kinisi.parser

Parsers for kinisi. This module is responsible for reading in input files from pymatgen, MDAnalysis, and ase.

class kinisi.parser.Parser(coords, latt, time_step, step_skip, dt=None, specie_indices=None, drift_indices=None, masses=None, dimension='xyz')

Bases: object

The base class for object parsing. This is not normally used directly; the format-specific parsers (kinisi.ase.ASEParser, kinisi.mdanalysis.MDAnalysisParser and kinisi.pymatgen.PymatgenParser) read a trajectory and pass the result to this class.

Parameters:

• coords (VariableLikeType) – Fractional coordinates of all atoms, as a scipp array with dimensions of time, particle, and dimension.

• latt (VariableLikeType) – Lattice matrices for each frame, as a scipp array with dimensions of time, dimension1, and dimension2 and a unit of length.

• time_step (VariableLikeType) – The input simulation time step, i.e., the time step for the molecular dynamics integrator. This must be given as a scipp-type scalar, and its unit is used for the time interval values.

• step_skip (VariableLikeType) – Sampling frequency of the simulation trajectory, i.e., how many time steps exist between the output of the positions in the trajectory. Similar to the time_step, this parameter must be a scipp scalar. The units for this scalar should be dimensionless.

• dt (VariableLikeType) – Time intervals to calculate the displacements over. Optional, defaults to a scipp array ranging from the smallest interval (i.e., time_step * step_skip) to the full simulation length, with a step size the same as the smallest interval.

• specie_indices (VariableLikeType) – Indices of the atoms to calculate the diffusivity for, as a scipp array. A 1D array with dimension particle selects individual atoms. A 2D array with dimensions particle and atoms in particle groups atoms into molecules, and the centre of mass of each molecule is used.

• drift_indices (VariableLikeType) – Indices of the atoms used for drift correction (typically the framework). Optional, defaults to all atoms that are not in specie_indices.

• masses (VariableLikeType) – Masses used to weight the centre of mass of each molecule. Optional, defaults to None, in which case all atoms are weighted equally. If used, this should be a 1D scipp array with dimension atoms in particle.

• dimension (str) – Dimension/s to find the displacement along, this should be some subset of ‘xyz’ indicating the axes of interest. Optional, defaults to ‘xyz’.

create_integer_dt(coords, time_step, step_skip)

Create an integer time interval from the given time intervals (and if necessary the time interval object). Also checks that the time intervals provided in the dt parameter are a valid subset of the simulation time intervals.

Parameters:

• coords (VariableLikeType) – The fractional coordinates of the atoms in the trajectory. This should be a scipp array type object with dimensions of ‘particle’, ‘time’, and ‘dimension’.

• time_step (VariableLikeType) – The input simulation time step, i.e., the time step for the molecular dynamics integrator. This must be given as a scipp-type scalar, and its unit is used for the time interval values.

• step_skip (VariableLikeType) – Sampling frequency of the simulation trajectory, i.e., how many time steps exist between the output of the positions in the trajectory. Similar to the time_step, this parameter must be a scipp scalar. The units for this scalar should be dimensionless.

Raises:

ValueError – If the time intervals provided in the dt parameter are not a subset of the time intervals present in the simulation, based on the time_step and step_skip parameters and number of snapshots in the trajectory.

Return type:

VariableLikeType

Returns:

The integer time intervals as a scipp array with dimensions of ‘time interval’.

static orthorhombic_calculate_displacements(coords, lattice)

Calculate the absolute displacements of the atoms in the trajectory, when the cell is orthorhombic on all frames.

Parameters:

• coords (VariableLikeType) – The fractional coordinates of the atoms in the trajectory. This should be a scipp array type object with dimensions of ‘particle’, ‘time’, and ‘dimension’.

• lattice (VariableLikeType) – A series of matrices that describe the lattice in each step in the trajectory. A scipp array with dimensions of ‘time’, ‘dimension1’, and ‘dimension2’.

Return type:

VariableLikeType

Returns:

The absolute displacements of the atoms in the trajectory.

static non_orthorhombic_calculate_displacements(coords, lattice)

Calculate the absolute displacements of the atoms in the trajectory, when a non-orthorhombic cell is used.

This is done by finding the minimum cartesian displacement vector, from its 8 periodic images. This ensures that triclinic cells are treated correctly.

Parameters:

• coords (VariableLikeType) – The fractional coordinates of the atoms in the trajectory. This should be a scipp array type object with dimensions of ‘particle’, ‘time’, and ‘dimension’.

• lattice (VariableLikeType) – A series of matrices that describe the lattice in each step in the trajectory. A scipp array with dimensions of ‘time’, ‘row’, and ‘column’.

Return type:

VariableLikeType

Returns:

The absolute displacements of the atoms in the trajectory.

correct_drift(disp)

Perform drift correction, such that the displacement is calculated normalised to any framework drift.

Parameters:

disp (VariableLikeType) – Displacements for all atoms in the simulation. A scipp array with dimensions of obs, particle and dimension.

Return type:

VariableLikeType

Returns:

Displacements corrected to account for drift of a framework.

abstractmethod get_indices(structure, specie)

abstractmethod get_drift_indices(structure, specie_indices)

get_specie_and_drift_indices(specie, specie_indices, drift_indices, structure)

property coords

Coordinates of ‘atoms’, this may be the raw coordinates parsed or centres of mass/geometry.

property disp

Atom displacements, without drift correction.

kinisi.parser.get_molecules(coords, indices, masses)

Replace the atoms in each molecule with the molecule’s centre of mass, for use when specie_indices groups atoms into molecules. The atoms that are not in any molecule are kept, after the centres of mass, and are used for drift correction.

Parameters:

• coords (VariableLikeType) – Fractional coordinates for all atoms, with dimensions of time, particle, and dimension.

• indices (VariableLikeType) – Indices of the atoms in each molecule, with dimensions of particle and atoms in particle.

• masses (VariableLikeType) – Masses used to weight the centre of mass, with dimension atoms in particle. If None, all atoms are weighted equally.

Return type:

tuple[VariableLikeType, VariableLikeType, VariableLikeType]

Returns:

Tuple containing: the new fractional coordinates (centres of mass followed by the remaining atoms), the indices of the centres of mass, and the indices of the remaining atoms (used for drift correction).

kinisi.parser.is_subset_approx(B, A, tol=1e-09)

Check if all elements in B are approximately equal to any element in A within a tolerance. This is useful for comparing floating-point numbers where exact equality is not feasible.

Parameters:

• B (array) – The array to check if it is a subset of A.

• A (array) – The array to check against.

• tol (float) – The tolerance for comparison. Default is 1e-9.

Return type:

bool

Returns:

True if all elements in B are approximately equal to any element in A, False otherwise.

kinisi.parser.is_orthorhombic(latt)

Check if trajectory is always orthorhombic.

This function works by flattening each frames lattice vectors, then checking which are close to 0, and counting how many return True. If the cell is orthorhombic, only 3 elements, of 9, should be nonzero, leaving 6. Hence, count_nonzero should equal 6 on every element to return true. This does not measure lattice angles and so all vectors must be aligned with axes to return true.

Parameters:

latt (VariableLikeType) – a scipp array with dimensions time,`dimension1`, and dimension2.

Return type:

bool

Returns:

True if lattice vectors are orthorhombic for all trajectory frames.

The ASEParser class is a parser for ASE atoms object. It is used to extract the necessary data for diffusion analysis from ASE.

class kinisi.ase.ASEParser(atoms, specie, time_step, step_skip, dt=None, dimension='xyz', distance_unit=Unit(1e-10 * m), specie_indices=None, drift_indices=None, masses=None, progress=True)

Bases: Parser

Parser for a trajectory of ase.atoms.Atoms objects, such as an ase.io.trajectory.Trajectory.

Parameters:

• atoms (list[ase.atoms.Atoms]) – Atoms objects ordered in sequence of run.

• specie (Union[str, list, VariableLikeType]) – Specie to calculate diffusivity for as a String, list of strings, or scipp array of strings, e.g. 'Li'. Either this or specie_indices must be given, not both.

• time_step (VariableLikeType) – The input simulation time step, i.e., the time step for the molecular dynamics integrator. This must be given as a scipp-type scalar, and its unit is used for the time interval values.

• step_skip (VariableLikeType) – Sampling frequency of the simulation trajectory, i.e., how many time steps exist between the output of the positions in the trajectory. Similar to the time_step, this parameter must be a scipp scalar. The units for this scalar should be dimensionless.

• dt (VariableLikeType) – Time intervals to calculate the displacements over. Optional, defaults to a scipp array ranging from the smallest interval (i.e., time_step * step_skip) to the full simulation length, with a step size the same as the smallest interval.

• dimension (str) – Dimension/s to find the displacement along, this should be some subset of ‘xyz’ indicating the axes of interest. Optional, defaults to ‘xyz’.

• distance_unit (Unit) – The unit of distance used in the input structures. Optional, defaults to angstroms.

• specie_indices (VariableLikeType) – Indices of the atoms to calculate the diffusivity for, as a scipp array. A 1D array with dimension particle selects individual atoms. A 2D array with dimensions particle and atoms in particle groups atoms into molecules, and the centre of mass of each molecule is used. Optional, defaults to None, in which case specie is used.

• drift_indices (VariableLikeType) – Indices of the atoms used for drift correction, as a scipp array. Optional, defaults to all atoms that are not being analysed.

• masses (VariableLikeType) – Masses used to weight the centre of mass of each molecule, as a scipp array with dimension atoms in particle. Optional, defaults to None, in which case all atoms are weighted equally.

• progress (bool) – Whether to show a progress bar when reading in the structures. Optional, defaults to True.

get_structure_coords_latt(atoms, distance_unit, progress=True)

Obtain the initial structure, fractional coordinates, and lattice matrices from a list of ase.atoms.Atoms objects.

Parameters:

• atoms (list[ase.atoms.Atoms]) – Atoms objects ordered in sequence of run.

• distance_unit (Unit) – The unit of distance used in the input structures.

• progress (bool) – Print progress bars to screen. Optional, defaults to True.

Return type:

tuple[ase.atoms.Atoms, VariableLikeType, VariableLikeType]

Returns:

Tuple containing: initial structure, fractional coordinates for all atoms, and lattice descriptions.

get_indices(structure, specie)

Determine framework and non-framework indices for a ase compatible file.

Parameters:

• structure (ase.atoms.Atoms) – Initial structure.

• specie (Union[str, list, VariableLikeType]) – Specie to calculate diffusivity for as a String, list of strings, or scipp.Variable of strings.

Return type:

tuple[VariableLikeType, VariableLikeType]

Returns:

Tuple containing: indices for the atoms in the trajectory used in the calculation of the diffusion and indices of framework atoms.

get_drift_indices(structure, specie_indices)

Determine framework indices for an ase structure.

Parameters:

structure (ase.atoms.Atoms) – Initial structure.

Return type:

VariableLikeType

Returns:

Indices for the atoms in the trajectory used as framework atoms.

The MDAnalysisParser class is a parser for MDAnalysis universe object. It is used to extract the necessary data for diffusion analysis from an MDAnalysis universe.

class kinisi.mdanalysis.MDAnalysisParser(universe, specie, time_step, step_skip, dt=None, dimension='xyz', distance_unit=Unit(1e-10 * m), specie_indices=None, drift_indices=None, masses=None, progress=True)

Bases: Parser

Parser for an MDAnalysis.core.universe.Universe.

Parameters:

• universe (MDAnalysis.core.universe.Universe) – MDAnalysis universe to be parsed.

• specie (Union[str, list, VariableLikeType]) – Specie to calculate diffusivity for as a String, list of strings, or scipp array of strings, e.g. 'Li'. Either this or specie_indices must be given, not both.

• time_step (VariableLikeType) – The input simulation time step, i.e., the time step for the molecular dynamics integrator. This must be given as a scipp-type scalar, and its unit is used for the time interval values.

• step_skip (VariableLikeType) – Sampling frequency of the simulation trajectory, i.e., how many time steps exist between the output of the positions in the trajectory. Similar to the time_step, this parameter must be a scipp scalar. The units for this scalar should be dimensionless.

• dt (VariableLikeType) – Time intervals to calculate the displacements over. Optional, defaults to a scipp array ranging from the smallest interval (i.e., time_step * step_skip) to the full simulation length, with a step size the same as the smallest interval.

• dimension (str) – Dimension/s to find the displacement along, this should be some subset of ‘xyz’ indicating the axes of interest. Optional, defaults to ‘xyz’.

• distance_unit (Unit) – The unit of distance used in the input structures. Optional, defaults to angstroms.

• specie_indices (VariableLikeType) – Indices of the atoms to calculate the diffusivity for, as a scipp array. A 1D array with dimension particle selects individual atoms. A 2D array with dimensions particle and atoms in particle groups atoms into molecules, and the centre of mass of each molecule is used. Optional, defaults to None, in which case specie is used.

• drift_indices (VariableLikeType) – Indices of the atoms used for drift correction, as a scipp array. Optional, defaults to all atoms that are not being analysed.

• masses (VariableLikeType) – Masses used to weight the centre of mass of each molecule, as a scipp array with dimension atoms in particle. Optional, defaults to None, in which case all atoms are weighted equally.

• progress (bool) – Whether to show a progress bar when reading in the structures. Optional, defaults to True.

get_structure_coords_latt(universe, distance_unit, progress=True)

Obtain the initial structure, coordinates, and lattice parameters from an MDAnalysis.Universe object.

Parameters:

• universe (MDAnalysis.core.universe.Universe) – MDAnalysis universe object.

• distance_unit (VariableLikeType) – The unit of distance used in the input structures.

• progress (bool) – Whether to show a progress bar when reading in the structures.

Return type:

tuple[MDAnalysis.core.universe.Universe, VariableLikeType, VariableLikeType]

Returns:

A tuple of: the initial structure (as a MDAnalysis.core.universe.Universe.atoms), coordinates (as a scipp array with dimensions of time, particle, and dimension), and lattice parameters (as a scipp array with dimensions time, dimension1, and dimension2).

get_indices(structure, specie)

Determine framework and non-framework indices for an MDAnalysis compatible file.

Parameters:

• structure (MDAnalysis.universe.Universe.atoms) – Initial structure.

• specie (Union[str, list, VariableLikeType]) – Specie to calculate diffusivity for as a String, list of strings, or scipp.Variable of strings.

Return type:

tuple[VariableLikeType, VariableLikeType]

Returns:

Tuple containing indices for the atoms in the trajectory used in the calculation of the diffusion and indices of framework atoms.

get_drift_indices(structure, specie_indices)

Determine framework indices for an MDAnalysis structure.

Parameters:

structure (MDAnalysis.universe.Universe.atoms) – Initial structure.

Return type:

VariableLikeType

Returns:

Indices for the atoms in the trajectory used as framework atoms.

The PymatgenParser class is a parser for pymatgen structures for kinisi. It is used to extract the necessary data for diffusion analysis from a list of pymatgen structures.

class kinisi.pymatgen.PymatgenParser(structures, specie, time_step, step_skip, dt=None, dimension='xyz', distance_unit=Unit(1e-10 * m), specie_indices=None, drift_indices=None, masses=None, progress=True)

Bases: Parser

Parser for a list of pymatgen.core.structure.Structure objects.

Parameters:

• structures (list[pymatgen.core.structure.Structure]) – Structures ordered in sequence of run.

• specie (Union[str, list, VariableLikeType]) – Specie to calculate diffusivity for as a String, list of strings, or scipp array of strings, e.g. 'Li'. Either this or specie_indices must be given, not both.

• time_step (VariableLikeType) – The input simulation time step, i.e., the time step for the molecular dynamics integrator. This must be given as a scipp-type scalar, and its unit is used for the time interval values.

• step_skip (VariableLikeType) – Sampling frequency of the simulation trajectory, i.e., how many time steps exist between the output of the positions in the trajectory. Similar to the time_step, this parameter must be a scipp scalar. The units for this scalar should be dimensionless.

• dt (VariableLikeType) – Time intervals to calculate the displacements over. Optional, defaults to a scipp array ranging from the smallest interval (i.e., time_step * step_skip) to the full simulation length, with a step size the same as the smallest interval.

• dimension (str) – Dimension/s to find the displacement along, this should be some subset of ‘xyz’ indicating the axes of interest. Optional, defaults to ‘xyz’.

• distance_unit (Unit) – The unit of distance used in the input structures. Optional, defaults to angstroms.

• specie_indices (VariableLikeType) – Indices of the atoms to calculate the diffusivity for, as a scipp array. A 1D array with dimension particle selects individual atoms. A 2D array with dimensions particle and atoms in particle groups atoms into molecules, and the centre of mass of each molecule is used. Optional, defaults to None, in which case specie is used.

• drift_indices (VariableLikeType) – Indices of the atoms used for drift correction, as a scipp array. Optional, defaults to all atoms that are not being analysed.

• masses (VariableLikeType) – Masses used to weight the centre of mass of each molecule, as a scipp array with dimension atoms in particle. Optional, defaults to None, in which case all atoms are weighted equally.

• progress (bool) – Whether to show a progress bar when reading in the structures. Optional, defaults to True.

get_structure_coords_latt(structures, distance_unit, progress=True)

Obtain the initial structure, coordinates, and lattice parameters from a list of pymatgen structures.

Parameters:

• structures (list[pymatgen.core.structure.Structure]) – Structures ordered in sequence of run.

• distance_unit (VariableLikeType) – The unit of distance used in the input structures.

• progress (bool) – Whether to show a progress bar when reading in the structures.

Return type:

tuple[pymatgen.core.structure.Structure, VariableLikeType, VariableLikeType]

Returns:

A tuple of the initial structure (as a pymatgen.core.structure.Structure), coordinates (as a scipp array with dimensions of time, particle, and dimension), and lattice parameters (as a scipp array with dimensions time, dimension1, and dimension2).

get_indices(structure, specie)

Determine the framework and mobile indices from a pymatgen structure.

Parameters:

• structure (pymatgen.core.structure.Structure) – The initial structure to determine the indices from.

• specie (Union[str, list, VariableLikeType]) – The specie to calculate the diffusivity for as a String, list of strings, or scipp.Variable of strings.

Return type:

tuple[VariableLikeType, VariableLikeType]

Returns:

A tuple of the indices for the specie of interest (mobile) and the drift (framework) indices.

get_drift_indices(structure, specie_indices)

Determine framework indices for an pymatgen structure.

Parameters:

structure (pymatgen.core.structure.Structure) – Initial structure.

Return type:

VariableLikeType

Returns:

Indices for the atoms in the trajectory used as framework atoms.