Nodes

The core functionality of mlipx is based on ZnTrack nodes. Each Node is documented in the following section.

LoadDataFile

mlipx.LoadDataFile(*, name: str | None = None, always_changed: bool = False, path: str | Path, start: int = 0, stop: int | None = None, step: int = 1) → None

Load a trajectory file.

Entry point of trajectory data for the use in other nodes.

Parameters:

• path (str | pathlib.Path) – Path to the trajectory file.

• start (int, default=0) – Index of the first frame to load.

• stop (int, default=None) – Index of the last frame to load.

• step (int, default=1) – Step size between frames.

mlipx.frames

Loaded frames.

Type:

list[ase.Atoms]

LangevinConfig

mlipx.LangevinConfig(timestep: float, temperature: float, friction: float) → None

Configure a Langevin thermostat for molecular dynamics.

Parameters:

• timestep (float) – Time step for the molecular dynamics simulation in fs.

• temperature (float) – Temperature of the thermostat.

• friction (float) – Friction coefficient of the thermostat.

ApplyCalculator

mlipx.ApplyCalculator(*, name: str | None = None, always_changed: bool = False, data: list[Atoms], model: NodeWithCalculator | None, frames_path: Path = PosixPath('$nwd$/frames.h5')) → None

Apply a calculator to a list of atoms objects and store the results in a H5MD file.

Parameters:

• data (list[ase.Atoms]) – List of atoms objects to calculate.

• model (NodeWithCalculator, optional) – Node providing the calculator object to apply to the data.

EvaluateCalculatorResults

mlipx.EvaluateCalculatorResults(*, name: str | None = None, always_changed: bool = False, data: list[Atoms]) → None

Evaluate the results of a calculator.

Parameters:

data (list[ase.Atoms]) – List of atoms objects.

CompareCalculatorResults

mlipx.CompareCalculatorResults(*, name: str | None = None, always_changed: bool = False, data: EvaluateCalculatorResults, reference: EvaluateCalculatorResults) → None

CompareCalculatorResults is a node that compares the results of two calculators. It calculates the RMSE between the two calculators and adjusts plots accordingly. It calculates the error between the two calculators and saves the min/max values.

Parameters:

• data (EvaluateCalculatorResults) – The results of the first calculator.

• reference (EvaluateCalculatorResults) – The results of the second calculator. The results of the first calculator will be compared to these results.

CompareFormationEnergy

mlipx.CompareFormationEnergy(*, name: str | None = None, always_changed: bool = False, data: mlipx.nodes.formation_energy.CalculateFormationEnergy, reference: mlipx.nodes.formation_energy.CalculateFormationEnergy)

CalculateFormationEnergy

mlipx.CalculateFormationEnergy(*, name: str | None = None, always_changed: bool = False, data: list[Atoms], model: NodeWithCalculator | None = None) → None

Calculate formation energy.

Parameters:

data (list[ase.Atoms]) – ASE atoms object with appropriate tags in info

MaximumForceObserver

mlipx.MaximumForceObserver(f_max: float) → None

Evaluate if the maximum force on a single atom exceeds a threshold.

Parameters:

f_max (float) – Maximum allowed force norm on a single atom

Example

>>> import zntrack, mlipx
>>> project = zntrack.Project()
>>> observer = mlipx.MaximumForceObserver(f_max=0.1)
>>> with project:
...     md = mlipx.MolecularDynamics(
...         observers=[observer],
...         **kwargs
...     )
>>> project.build()

TemperatureRampModifier

mlipx.TemperatureRampModifier(end_temperature: float, total_steps: int, start_temperature: float | None = None, interval: int = 1) → None

Ramp the temperature from start_temperature to temperature.

mlipx.start_temperature

temperature to start from, if None, the temperature of the thermostat is used.

Type:

float, optional

mlipx.end_temperature

temperature to ramp to.

Type:

float

mlipx.interval

interval in which the temperature is changed.

Type:

int, default 1

mlipx.total_steps

total number of steps in the simulation.

Type:

int

References

Code taken from ipsuite/calculators/ase_md.py

MolecularDynamics

mlipx.MolecularDynamics(*, name: str | None = None, always_changed: bool = False, model: NodeWithCalculator, thermostat: NodeWithMolecularDynamics, data: list[Atoms], data_id: int = -1, steps: int = 100, observers: list[DynamicsObserver] = None, modifiers: list[DynamicsModifier] = None, frames_path: Path = PosixPath('$nwd$/frames.xyz')) → None

Run molecular dynamics simulation.

Parameters:

• model (NodeWithCalculator) – Node providing the calculator object for the simulation.

• thermostat (LangevinConfig) – Node providing the thermostat object for the simulation.

• data (list[ase.Atoms]) – Initial configurations for the simulation.

• data_id (int, default=-1) – Index of the initial configuration to use.

• steps (int, default=100) – Number of steps to run the simulation.

HomonuclearDiatomics

mlipx.HomonuclearDiatomics(*, name: str | None = None, always_changed: bool = False, model: NodeWithCalculator, elements: list[str] = ('H', 'He', 'Li'), data: list[Atoms] | None = None, n_points: int = 100, min_distance: float = 0.5, max_distance: float = 2.0, eq_distance: Literal['covalent-radiuis'] | float = 'covalent-radiuis', model_outs: Path = PosixPath('$nwd$/model_outs')) → None

Compute energy-bondlength curves for homonuclear diatomic molecules.

Parameters:

• elements (list[str]) – List of elements to consider. For example, [“H”, “He”, “Li”].

• model (NodeWithCalculator) – Node providing the calculator object for the energy calculations.

• n_points (int, default=100) – Number of points to sample for the bond length between min_distance and max_distance.

• min_distance (float, default=0.5) – Minimum bond length to consider in Angstrom.

• max_distance (float, default=2.0) – Maximum bond length to consider in Angstrom.

• data (list[ase.Atoms]|None) – Optional list of ase.Atoms. Diatomics for each element in this list will be added to elements.

• model_outs – Path to store the outputs of the model. Some models, like DFT calculators, generate files that will be stored in this path.

mlipx.frames

List of frames with the bond length varied.

Type:

list[ase.Atoms]

mlipx.results

DataFrame with the energy values for each bond length.

Type:

pd.DataFrame

NEBinterpolate

mlipx.NEBinterpolate(*, name: str | None = None, always_changed: bool = False, data: list[Atoms], n_images: int = 5, mic: bool = False, add_constraints: bool = True, frames_path: Path = PosixPath('$nwd$/initial_frames.xyz')) → None

Interpolates between two or three images to create a NEB path.

Parameters:

• data (list[ase.Atoms]) – List of atoms objects.

• n_images (int) – Number of images to interpolate.

• mic (bool) – Whether to use the minimum image convention.

• add_constraints (bool) – Whether to copy constraints from initial image to all the interpolated images

• frames_path (pathlib.Path) – Path to save the interpolated frames.

NEBs

mlipx.NEBs(*, name: str | None = None, always_changed: bool = False, data: list[Atoms], model: NodeWithCalculator, relax: bool = True, optimizer: Optimizer = 'FIRE', fmax: float = 0.09, n_steps: int = 500, frames_path: Path = PosixPath('$nwd$/frames.xyz'), trajectory_path: Path = PosixPath('$nwd$/neb_trajectory.traj')) → None

Runs NEB calculation on a list of images.

Parameters:

• data (list[ase.Atoms]) – List of atoms objects.

• model (NodeWithCalculator) – Node with a calculator.

• relax (bool) – Whether to relax the initial and final images.

• optimizer (Optimizer) – ASE optimizer to use.

• fmax (float) – Maximum force allowed.

• n_steps (int) – Maximum number of steps allowed.

• frames_path (pathlib.Path) – Path to save the final frames.

• trajectory_path (pathlib.Path) – Path to save the neb trajectory file.

mlipx.results

DataFrame with the data_id and potential energy of the NEB calculation

Type:

pd.DataFrame

VibrationalAnalysis

mlipx.VibrationalAnalysis(*, name: str | None = None, always_changed: bool = False, data: list[Atoms], model: NodeWithCalculator, displacement: float = 0.01, nfree: int = 4, temperature: float = 298.15, lower_freq_threshold: float = 12.0, frames_path: Path = PosixPath('$nwd$/frames.xyz'), modes_path: Path = PosixPath('$nwd$/modes.xyz'), modes_cache: Path = PosixPath('$nwd$/modes'), vib_cache: Path = PosixPath('$nwd$/vib'), free_indices: list[int] = None, system: Literal['molecule'] | Literal['other'] | Literal['linear-molecule'] | Literal['isolated-atom'] | None = None, calc_type: Literal['ts'] | Literal['relax'] | None = None) → None

Vibrational Analysis Node This node performs vibrational analysis on the provided images.

Parameters:

• data (list[ase.Atoms]) – List of images to perform vibrational analysis on.

• model (NodeWithCalculator) – Model node with calculator to perform vibrational analysis.

• displacement (float) – Displacement for vibrational analysis.

• nfree (int) – Number of free atoms.

• lower_freq_threshold (float) – Lower frequency threshold.

• frames_path (pathlib.Path) – Path to save frames.

• modes_path (pathlib.Path) – Path to save vibrational modes.

• modes_cache (pathlib.Path) – Path to save modes cache.

• vib_cache (pathlib.Path) – Path to save vibrational cache.

mlipx.results

Results of vibrational analysis.

Type:

pd.DataFrame

PhaseDiagram

mlipx.PhaseDiagram(*, name: str | None = None, always_changed: bool = False, model: NodeWithCalculator, data: list[Atoms], chemsys: list[str] = None, data_ids: list[int] = None, geo_opt: bool = False, fmax: float = 0.05, frames_path: str = PosixPath('$nwd$/frames.xyz')) → None

Compute the phase diagram for a given set of structures.

Parameters:

• data (list[ase.Atoms]) – List of structures to evaluate.

• model (NodeWithCalculator) – Node providing the calculator object for the energy calculations.

• chemsys (list[str], defaeult=None) – The set of chemical symbols to construct phase diagram.

• data_ids (list[int], default=None) – Index of the structure to evaluate.

• geo_opt (bool, default=False) – Whether to perform geometry optimization before calculating the formation energy of each structure.

• fmax (float, default=0.05) – The maximum force stopping rule for geometry optimizations.

mlipx.results

DataFrame with the data_id, potential energy and formation energy.

Type:

pd.DataFrame

mlipx.plots

Dictionary with the phase diagram (and formation energy plot).

Type:

dict[str, go.Figure]

PourbaixDiagram

mlipx.PourbaixDiagram(*, name: str | None = None, always_changed: bool = False, model: NodeWithCalculator, data: list[Atoms], pH: float, V: float, use_gibbs: bool = False, data_ids: list[int] = None, geo_opt: bool = False, fmax: float = 0.05, frames_path: str = PosixPath('$nwd$/frames.xyz')) → None

Compute the Pourbaix diagram for a given set of structures.

Parameters:

• data (list[ase.Atoms]) – List of structures to evaluate.

• model (NodeWithCalculator) – Node providing the calculator object for the energy calculations.

• pH (float) – pH where the Pourbaix stability is evaluated ,

• V (float) – Electrode potential where the Pourbaix stability is evaluated.

• use_gibbs (bool, default=False) – Set to 300 (for 300 Kelvin) to use a machine learning model to estimate solid free energy from DFT energy (see GibbsComputedStructureEntry). This can slightly improve the accuracy of the Pourbaix diagram in some cases. Default: None. Note that temperatures other than 300K are not permitted here, because MaterialsProjectAqueousCompatibility corrections, used in Pourbaix diagram construction, are calculated based on 300 K data.

• data_ids (list[int], default=None) – Index of the structure to evaluate.

• geo_opt (bool, default=False) – Whether to perform geometry optimization before calculating the Pourbaix decomposition energy of each structure.

• fmax (float, default=0.05) – The maximum force stopping rule for geometry optimizations.

mlipx.results

DataFrame with the data_id, potential energy and Pourbaix decomposition energy.

Type:

pd.DataFrame

mlipx.plots

Dictionary with the phase diagram (and Pourbaix decomposition energy plot).

Type:

dict[str, go.Figure]

StructureOptimization

mlipx.StructureOptimization(*, name: str | None = None, always_changed: bool = False, data: list[Atoms], data_id: int = -1, optimizer: Optimizer = 'LBFGS', model: NodeWithCalculator, fmax: float = 0.05, steps: int = 100000000, frames_path: Path = PosixPath('$nwd$/frames.traj')) → None

Structure optimization Node.

Relax the geometry for the selected ase.Atoms.

Parameters:

• data (list[ase.Atoms]) – Atoms to relax.

• data_id (int, default=-1) – The index of the ase.Atoms in data to optimize.

• optimizer (Optimizer) – Optimizer to use.

• model (NodeWithCalculator) – Model to use.

• fmax (float) – Maximum force to reach before stopping.

• steps (int) – Maximum number of steps for each optimization.

• plots (pd.DataFrame) – Resulting energy and fmax for each step.

• trajectory_path (str) – Output directory for the optimization trajectories.

Smiles2Conformers

mlipx.Smiles2Conformers(*, name: str | None = None, always_changed: bool = False, smiles: str, num_confs: int, random_seed: int = 42, max_attempts: int = 1000, frames_path: Path = PosixPath('$nwd$/frames.xyz')) → None

Create conformers from a SMILES string.

Parameters:

• smiles (str) – The SMILES string.

• num_confs (int) – The number of conformers to generate.

• random_seed (int) – The random seed.

• max_attempts (int) – The maximum number of attempts.

BuildBox

mlipx.BuildBox(*, name: str | None = None, always_changed: bool = False, data: list[list[Atoms]], counts: list[int], density: float = 1000, frames_path: Path = PosixPath('$nwd$/frames.xyz')) → None

Build a box from a list of atoms.

Parameters:

• data (list[list[ase.Atoms]]) – A list of lists of ASE Atoms objects representing the molecules to be packed.

• counts (list[int]) – A list of integers representing the number of each type of molecule.

• density (float) – The target density of the packed system in kg/m^3

EnergyVolumeCurve

mlipx.EnergyVolumeCurve(*, name: str | None = None, always_changed: bool = False, model: NodeWithCalculator, data: list[Atoms], data_id: int = -1, n_points: int = 50, start: float = 0.75, stop: float = 2.0, frames_path: str = PosixPath('$nwd$/frames.xyz')) → None

Compute the energy-volume curve for a given structure.

Parameters:

• data (list[ase.Atoms]) – List of structures to evaluate.

• model (NodeWithCalculator) – Node providing the calculator object for the energy calculations.

• data_id (int, default=-1) – Index of the structure to evaluate.

• n_points (int, default=50) – Number of points to sample for the volume scaling.

• start (float, default=0.75) – Initial scaling factor from the original cell.

• stop (float, default=2.0) – Final scaling factor from the original cell.

mlipx.results

DataFrame with the volume, energy, and scaling factor.

Type:

pd.DataFrame

FilterAtoms

mlipx.FilterAtoms(*, name: str | None = None, always_changed: bool = False, data: list[Atoms], elements: list[str], filtering_type: FilteringType = 'inclusive', frames_path: Path = PosixPath('$nwd$/frames.xyz')) → None

ZnTrack node that filters a list of atomic configurations

based on specified elements and filtering type.

mlipx.data

List of atomic configurations to filter.

Type:

list[ase.Atoms]

mlipx.elements

List of elements to use as the filtering subset.

Type:

list[str]

mlipx.filtering_type

Type of filtering to apply (INCLUSIVE, EXCLUSIVE, or COMBINATIONS).

Type:

FilteringType

mlipx.frames_path

Path to store filtered atomic configuration frames.

Type:

pathlib.Path

mlipx.run()

Filters atomic configurations and writes the results to frames_path.

mlipx.frames() → list[ase.Atoms]

Loads filtered atomic configurations from frames_path.

RotationalInvariance

mlipx.RotationalInvariance(*, name: str | None = None, always_changed: bool = False, model: NodeWithCalculator, data: list[Atoms], data_id: int = -1, n_points: int = 50, frames_path: Path = PosixPath('$nwd$/frames.xyz')) → None

Test rotational invariance by random rotation of the box.

TranslationalInvariance

mlipx.TranslationalInvariance(*, name: str | None = None, always_changed: bool = False, model: NodeWithCalculator, data: list[Atoms], data_id: int = -1, n_points: int = 50, frames_path: Path = PosixPath('$nwd$/frames.xyz')) → None

Test translational invariance by random box translocation.

PermutationInvariance

mlipx.PermutationInvariance(*, name: str | None = None, always_changed: bool = False, model: NodeWithCalculator, data: list[Atoms], data_id: int = -1, n_points: int = 50, frames_path: Path = PosixPath('$nwd$/frames.xyz')) → None

Test permutation invariance by permutation of atoms of the same species.

RelaxAdsorptionConfigs

mlipx.RelaxAdsorptionConfigs(*, name: str | None = None, always_changed: bool = False, slabs: list[Atoms], adsorbates: list[Atoms], height: float = 2.1, position: str = 'all', mol_index: int = 0, slab_id: int = -1, adsorbate_id: int = -1, optimizer: str = 'LBFGS', model: NodeWithCalculator, steps: int = 300, fmax: float = 0.05, frames_path: Path = PosixPath('$nwd$/frames.traj'), relax_path: Path = PosixPath('$nwd$/relax')) → None

Add an adsorbate to a surface.

Parameters:

• slab (ase.Atoms) – The surface onto which the adsorbate should be added.

• adsorbate (union(str, ase.Atoms)) – The adsorbate. Must be one of the following three types: A string containing the chemical symbol for a single atom. An atom object. An atoms object (for a molecular adsorbate).

• height (float) – Height above the surface.

• position (str) – The x-y position of the adsorbate, either as a tuple of two numbers or as a keyword (if the surface is produced by one of the functions in ase.build).

• mol_index (int) – (default: 0): If the adsorbate is a molecule, index of the atom to be positioned above the location specified by the position argument.

BuildASEslab

mlipx.BuildASEslab(*, name: str | None = None, always_changed: bool = False, crystal: Literal['fcc111', 'fcc211', 'bcc110', 'bcc111', 'hcp0001', 'diamond111'], symbol: str, size: tuple, a: float = None, c: float = False, vacuum: float = 10, orthogonal: bool = True, periodic: bool = True, frames_path: Path = PosixPath('$nwd$/frames.traj')) → None

Create slab (ase.Atoms). As implemented in ase.build. Options are: fcc111, fcc211, bcc110, bcc111, hcp0001, diamond111

Parameters:

• crystal (str) – A choice between a few options (fcc111, fcc211, bcc110, bcc111 , hcp0001. diamond111)

• symbol (str) – Atoms symbol.

• size (tuple) – A tuple giving the system size in units of the minimal unit cell.

• a (float) – (optional) The lattice constant. If specified, it overrides the experimental lattice constant of the element. Must be specified if setting up a crystal structure different from the one found in nature.

• c (float) –

  (optional) Extra HCP lattice constant. If specified, it overrides

  the experimental lattice constant of the element.

• vacuum (float) – The thickness of the vacuum layer.

• orthogonal (bool) –

  If specified and true, forces the creation of a unit cell with orthogonal

  basis vectors.

• periodic (bool) –

  If true, sets boundary conditions and cell constantly with the corresponding

  bulk structure.

COSplitting

mlipx.COSplitting(*, name: str | None = None, always_changed: bool = False, data: list[Atoms], model: NodeWithCalculator, miller: list[int] = None, supercell: list[int] = None, layers: int = 8, vacuum: float = 10.0, grid_step: float = 3.0, freeze_ratio: float = 0.5, node_path: Path = PosixPath('$nwd$/outputs'), frames_path: str = PosixPath('$nwd$/frames.xyz')) → None

CO Splitting Node This node performs CO splitting analysis on the provided bulk structures.

Parameters:

• data (list[ase.Atoms]) – List of images to perform CO splitting analysis on.

• model (NodeWithCalculator) – Model node with calculator to perform CO splitting analysis.

• miller (list[int], default=[2,1,1]) – Miller index of the surface to be generated.

• supercell (list[int], default=[2,2,1]) – Supercell in a list format.

• layers (int, default=8) – Number of layers.

• vacuum (float, default=10.0) – Vacuum size in Angst.

• grid_step (float, default=0.3) – Step size of the grid for the placement of intermediates.

• freeze_ratio (float, default=0.5) – Ratio of bottom layers to be frozen for relaxations.

• frames_path (pathlib.Path) – Path to save frames.

• node_path (pathlib.Path) – Path to save additional information such as cache and heatmaps.

mlipx.results

Results of CO splitting analysis.

Type:

pd.DataFrame