kinisi.parser#

Parser functions, including implementation for pymatgen compatible VASP files and MDAnalysis compatible trajectories.

This parser borrows heavily from the pymatgen.analysis.diffusion_analyzer.DiffusionAnalyzer class, originally authored by Will Richards (wrichard@mit.edu) and Shyue Ping Ong. We include this statement to note that we make no claim to authorship of that code and make no attack on the original authors.

In fact, we love pymatgen!

class kinisi.parser.Parser(disp, indices, drift_indices, time_step, step_skip, min_dt=None, max_dt=None, n_steps=100, spacing='linear', sampling='multi-origin', memory_limit=8.0, progress=True)#

Bases: object

The base class for parsing.

Parameters:

  • disp (ndarray) – Displacements of atoms with the shape [site, time step, axis].

  • indices (ndarray) – Indices for the atoms in the trajectory used in the diffusion calculation.

  • drift_indices (ndarray) – Indices for the atoms in the trajectory that should not be used in the diffusion calculation, instead being used to correct for framework drift.

  • time_step (float) – Time step, in picoseconds, between steps in trajectory.

  • step_skip (int) – Sampling freqency of the trajectory (time_step is multiplied by this number to get the real time between output from the simulation file).

  • min_dt (float) – Minimum time interval to be evaluated, in the simulation units. Optional, defaults to the produce of time_step and step_skip.

  • max_dt (float) – Maximum time interval to be evaluated, in the simulation units. Optional, defaults to the length of the simulation.

  • n_steps (int) – Number of steps to be used in the time interval function. Optional, defaults to 100 unless this is fewer than the total number of steps in the trajectory when it defaults to this number.

  • spacing (str) – The spacing of the steps that define the time interval, can be either 'linear' or 'logarithmic'. If 'logarithmic' the number of steps will be less than or equal to that in the n_steps argument, such that all values are unique. Optional, defaults to linear.

  • sampling (str) – The ways that the time-windows are sampled. The options are 'single-origin' or 'multi-origin' with the former resulting in only one observation per atom per time-window and the latter giving the maximum number of trajectories. Optional, defaults to 'multi-origin'.

  • memory_limit (float) – Upper limit in the amount of computer memory that the displacements can occupy in gigabytes (GB). Optional, defaults to 8..

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

property volume: float#
Returns:

Volume of system, in cubic angstrom.

static get_disp(coords, latt, progress=True)#

Calculate displacements with support for NPT simualtions, using the TOR scheme outlined in doi: 10.1021/acs.jctc.3c00308. Issues a warning about non-orthorhombic cells.

Parameters:

  • coords (List[ndarray]) – Fractional coordinates for all atoms.

  • latt (List[ndarray]) – Lattice descriptions.

Return type:

ndarray

Returns:

Numpy array of with shape [site, time step, axis] describing displacements.

static correct_drift(drift_indices, disp)#

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

Parameters:

  • drift_indices (ndarray) – Indices for the atoms in the trajectory that should not be used in the diffusion calculation.

  • disp (ndarray) – Numpy array of with shape [site, time step, axis] that describes the displacements.

Return type:

ndarray

Returns:

Displacements corrected to account for drift of a framework.

get_time_intervals(n_steps, spacing)#

Calculate the smoothed time intervals to be used.

Parameters:

  • n_steps (int) – Number of time steps.

  • step_spacing

Return type:

ndarray

Returns:

Smoothed time intervals.

get_disps(time_intervals, drift_corrected, progress=True)#

Calculate the displacement at each time interval.

Parameters:

  • time_intervals (ndarray) – Smoothed time intervals.

  • drift_corrected (ndarray) – Drift of framework corrected disp.

  • progress (bool) – Print progress bars to screen. Defaults to True.

Return type:

Tuple[ndarray, List[ndarray], ndarray]

Returns:

Tuple containing: time step intervals and raw displacement.

class kinisi.parser.ASEParser(atoms, specie, time_step, step_skip, sub_sample_traj=1, min_dt=None, max_dt=None, n_steps=100, spacing='linear', sampling='multi-origin', memory_limit=8.0, progress=True, specie_indices=None, masses=None, framework_indices=None)#

Bases: Parser

A parser for ASE Atoms objects

Parameters:

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

  • specie (str) – symbol to calculate diffusivity for as a String, e.g. 'Li'.

  • time_step (float) – Time step, in picoseconds, between steps in trajectory.

  • step_skip (int) – Sampling frequency of the trajectory (time_step is multiplied by this number to get the real time between output from the simulation file).

  • sub_sample_traj (int) – Multiple of the time_step to sub sample at. Optional, defaults to 1 where all timesteps are used.

  • min_dt (float) – Minimum time interval to be evaluated, in the simulation units. Optional, defaults to the produce of time_step and step_skip.

  • max_dt (float) – Maximum time interval to be evaluated, in the simulation units. Optional, defaults to the length of the simulation.

  • n_steps (int) – Number of steps to be used in the time interval function. Optional, defaults to 100 unless this is fewer than the total number of steps in the trajectory when it defaults to this number.

  • spacing (str) – The spacing of the steps that define the time interval, can be either 'linear' or 'logarithmic'. If 'logarithmic' the number of steps will be less than or equal to that in the n_steps argument, such that all values are unique. Optional, defaults to linear.

  • sampling (str) – The ways that the time-windows are sampled. The options are 'single-origin' or 'multi-origin' with the former resulting in only one observation per atom per time-window and the latter giving the maximum number of origins without sampling overlapping trajectories. Optional, defaults to 'multi-origin'.

  • memory_limit (float) – Upper limit in the amount of computer memory that the displacements can occupy in gigabytes (GB). Optional, defaults to 8..

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

  • specie_indices (List[int]) – Optional, list of indices to calculate diffusivity for as a list of indices. Specie must be set to None for this to function. Molecules can be specificed as a list of lists of indices. The inner lists must all be on the same length.

  • masses (List[float]) – Optional, list of masses associated with the indices in specie_indices. Must be same shape as specie_indices.

  • framework_indices (List[int]) – Optional, list of framework indices to be used to correct framework drift. If an empty list is passed no drift correction will be performed.

static get_structure_coords_latt(atoms, sub_sample_traj=1, progress=True)#

Obtain the initial structure and displacement from a list of :py:class`pymatgen.core.structure.Structure`.

Parameters:

  • structures – Structures ordered in sequence of run.

  • sub_sample_traj (int) – Multiple of the time_step to sub sample at. Optional, default is 1.

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

Return type:

Tuple[ase.atoms.Atoms, List[ndarray], List[ndarray]]

Returns:

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

static get_indices(structure, specie, framework_indices)#

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

Parameters:

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

  • specie (str) – Specie to calculate diffusivity for as a String, e.g. 'Li'.

  • framework_indices (List[int]) – Indices of framework to be used in drift correction. If set to None will return all indices that are not in indices.

Return type:

Tuple[ndarray, ndarray]

Returns:

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

class kinisi.parser.PymatgenParser(structures, specie, time_step, step_skip, sub_sample_traj=1, min_dt=None, max_dt=None, n_steps=100, spacing='linear', sampling='multi-origin', memory_limit=8.0, progress=True, specie_indices=None, masses=None, framework_indices=None)#

Bases: Parser

A parser for pymatgen structures.

Parameters:

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

  • specie (Union[pymatgen.core.periodic_table.Element, pymatgen.core.periodic_table.Specie]) – Specie to calculate diffusivity for as a String, e.g. 'Li'.

  • time_step (float) – Time step, in femtoseconds, between steps in trajectory.

  • step_skip (int) – Sampling freqency of the trajectory (time_step is multiplied by this number to get the real time between output from the simulation file).

  • sub_sample_traj (int) – Multiple of the time_step to sub sample at. Optional, defaults to 1 where all timesteps are used.

  • min_dt (float) – Minimum time interval to be evaluated, in the simulation units. Optional, defaults to the produce of time_step and step_skip.

  • max_dt (float) – Maximum time interval to be evaluated, in the simulation units. Optional, defaults to the length of the simulation.

  • n_steps (int) – Number of steps to be used in the time interval function. Optional, defaults to 100 unless this is fewer than the total number of steps in the trajectory when it defaults to this number.

  • spacing (str) – The spacing of the steps that define the time interval, can be either 'linear' or 'logarithmic'. If 'logarithmic' the number of steps will be less than or equal to that in the n_steps argument, such that all values are unique. Optional, defaults to linear.

  • sampling (str) – The ways that the time-windows are sampled. The options are 'single-origin' or 'multi-origin' with the former resulting in only one observation per atom per time-window and the latter giving the maximum number of origins without sampling overlapping trajectories. Optional, defaults to 'multi-origin'.

  • memory_limit (float) – Upper limit in the amount of computer memory that the displacements can occupy in gigabytes (GB). Optional, defaults to 8..

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

  • specie_indices (List[int]) – Optional, list of indices to calculate diffusivity for as a list of indices. Specie must be set to None for this to function. Molecules can be specificed as a list of lists of indices. The inner lists must all be on the same length.

  • masses (List[float]) – Optional, list of masses associated with the indices in specie_indices. Must be same shape as specie_indices.

  • framework_indices (List[int]) – Optional, list of framework indices to be used to correct framework drift. If an empty list is passed no drift correction will be performed.

static get_structure_coords_latt(structures, sub_sample_traj=1, progress=True)#

Obtain the initial structure and displacement from a list of :py:class`pymatgen.core.structure.Structure`.

Parameters:

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

  • sub_sample_traj (int) – Multiple of the time_step to sub sample at. Optional, default is 1.

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

Return type:

Tuple[pymatgen.core.structure.Structure, List[ndarray], List[ndarray]]

Returns:

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

static get_indices(structure, specie, framework_indices)#

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

Parameters:

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

  • specie (Union[pymatgen.core.periodic_table.Element, pymatgen.core.periodic_table.Specie, pymatgen.core.periodic_table.Species, List[pymatgen.core.periodic_table.Element], List[pymatgen.core.periodic_table.Specie], List[pymatgen.core.periodic_table.Species]]) – Specie to calculate diffusivity for as a String, e.g. 'Li'.

  • framework_indices (List[int]) – Indices of framework to be used in drift correction. If set to None will return all indices that are not in indices.

Return type:

Tuple[ndarray, ndarray]

Returns:

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

class kinisi.parser.MDAnalysisParser(universe, specie, time_step, step_skip, sub_sample_atoms=1, sub_sample_traj=1, min_dt=None, max_dt=None, n_steps=100, spacing='linear', sampling='multi-origin', memory_limit=8.0, progress=True, specie_indices=None, masses=None, framework_indices=None)#

Bases: Parser

A parser that consumes an MDAnalysis.Universe object.

Parameters:

  • universe (MDAnalysis.core.universe.Universe) – The MDAnalysis object of interest.

  • specie (str) – Specie to calculate diffusivity for as a String, e.g. 'Li'.

  • time_step (float) – Time step, in picoseconds, between steps in trajectory.

  • step_skip (int) – Sampling freqency of the trajectory (time_step is multiplied by this number to get the real time between output from the simulation file).

  • sub_sample_atoms (int) – The sampling rate to sample the atoms in the system. Optional, defaults to 1 where all atoms are used.

  • sub_sample_traj (int) – Multiple of the time_step to sub sample at. Optional, defaults to 1 where all timesteps are used.

  • min_dt (float) – Minimum time interval to be evaluated, in the simulation units. Optional, defaults to the produce of time_step and step_skip.

  • max_dt (float) – Maximum time interval to be evaluated, in the simulation units. Optional, defaults to the length of the simulation.

  • n_steps (int) – Number of steps to be used in the time interval function. Optional, defaults to 100 unless this is fewer than the total number of steps in the trajectory when it defaults to this number.

  • spacing (str) – The spacing of the steps that define the time interval, can be either 'linear' or 'logarithmic'. If 'logarithmic' the number of steps will be less than or equal to that in the n_steps argument, such that all values are unique. Optional, defaults to linear.

  • sampling (str) – The ways that the time-windows are sampled. The options are 'single-origin' or 'multi-origin' with the former resulting in only one observation per atom per time-window and the latter giving the maximum number of origins without sampling overlapping trajectories. Optional, defaults to 'multi-origin'.

  • memory_limit (float) – Upper limit in the amount of computer memory that the displacements can occupy in gigabytes (GB). Optional, defaults to 8..

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

  • specie_indices (List[int]) – Optional, list of indices to calculate diffusivity for as a list of indices. Specie must be set to None for this to function. Molecules can be specificed as a list of lists of indices. The inner lists must all be on the same length.

  • masses (List[float]) – Optional, list of masses associated with the indices in specie_indices. Must be same shape as specie_indices.

  • framework_indices (List[int]) – Optional, list of framework indices to be used to correct framework drift. If an empty list is passed no drift correction will be performed.

static get_structure_coords_latt(universe, sub_sample_atoms=1, sub_sample_traj=1, progress=True)#

Obtain the initial structure and displacement from a MDAnalysis.universe.Universe file.

Parameters:

  • universe (MDAnalysis.core.universe.Universe) – Universe for analysis.

  • sub_sample_atoms (int) – Frequency to sub sample the number of atoms. Optional, default is 1.

  • sub_sample_traj (int) – Multiple of the time_step to sub sample at. Optional, default is 1.

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

Return type:

Tuple[MDAnalysis.core.groups.AtomGroup, List[ndarray], List[ndarray], float]

Returns:

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

static get_indices(structure, specie, framework_indices)#

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

Parameters:

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

  • specie (str) – Specie to calculate diffusivity for as a String, e.g. 'Li'.

  • framework_indices (List[int]) – Indices of framework to be used in drift correction. If set to None will return all indices that are not specie.

Return type:

Tuple[ndarray, ndarray]

Returns:

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