API Reference for exaPD

Core LAMMPS Job Infrastructure

lammpsJob

jobs.lammpsJob.hybridPair(pair0, pair1, lbd)[source]

Create a hybrid scaled pair style.

Parameters:

pair0 (lammpsPair) – First potential.
pair1 (lammpsPair) – Second potential.
lbd (float) – Mixing parameter (0 ≤ lbd ≤ 1).

Returns:

LAMMPS input script string.

Return type:

str

class jobs.lammpsJob.lammpsJob(directory, scriptFile=None, arch='gpu', depend=None, priority=1)[source]

Bases: object

Define a LAMMPS job with an input script and all necessary data files.

Parameters:

directory (str) – Directory where the job will be executed.
scriptFile (str, optional) – LAMMPS input script file.
arch (str, optional) – Architecture type (e.g., “gpu”, “cpu”). Default is “gpu”.
depend (list object, optional) – Dependency information for the job. depend[0]: pre-job directory. depend[1]: list of variable names to be set in LAMMPS script. depend[2]: corresponding list ofvariable names in pre-job output.
priority (int, optional) – Job priority: - 0: pre_job - 1: regular job - 2: dependent job

get_arch()[source]

Return the architecture type.

Returns:: Architecture identifier.
Return type:: str

get_depend()[source]

Return dependency information.

Returns:: Dependency list.
Return type:: list or None

get_dir()[source]

Return the job directory.

Returns:: Job directory path.
Return type:: str

get_script()[source]

Return the LAMMPS input script file.

Returns:: Input script filename.
Return type:: str or None

sample(varList=['PotEng'], logfile='log.lammps', skip=0.2)[source]

Sample averaged quantities from a LAMMPS log file.

Parameters:

varList (list of str, optional) – Names of variables to sample (e.g., “PotEng”, “Temp”).
logfile (str, optional) – Name of the LAMMPS log file.
skip (float, optional) – Fraction of initial data to discard as equilibration.

Returns:

Averaged values of the requested variables.

Return type:

numpy.ndarray

Notes

This method assumes standard LAMMPS thermo output format.

set_arch(arch)[source]

Set the architecture type.

Parameters:: arch (str) – Architecture identifier.

class jobs.lammpsJob.lammpsJobGroup(directory='./')[source]

Bases: object

Define a group of LAMMPS jobs to be launched simultaneously.

Parameters:: directory (str, optional) – Path to the group directory.

get_joblist()[source]

Return the list of LAMMPS jobs.

Returns:: Job list.
Return type:: list of lammpsJob

class jobs.lammpsJob.lammpsPair(pair_style, pair_coeff)[source]

Bases: object

Define an interatomic potential for LAMMPS.

Parameters:

pair_style (str) – LAMMPS pair_style command.
pair_coeff (str or list of str) – LAMMPS pair_coeff command(s).

class jobs.lammpsJob.lammpsPara(general)[source]

Bases: object

Define general LAMMPS parameters from a dictionary.

Parameters:: general (dict) – Dictionary containing LAMMPS parameters.

jobs.lammpsJob.pre_process(depend)[source]

Pre-process a dependent job by sampling parameters from a pre-job.

Parameters:: depend (list) – Dependency specification: - depend[0]: directory of the pre-job - depend[1]: variable names to be set - depend[2]: variables to sample
Returns:: Command-line arguments for LAMMPS variables.
Return type:: str

jobs.lammpsJob.reset_types(nab, natom)[source]

Reset atomic types based on desired composition.

Parameters:

nab (list of int) – Number of atoms of each type.
natom (int) – Total number of atoms.

Returns:

LAMMPS commands to reset atom types.

Return type:

str

Thermodynamic Integration & Free Energy

alchem

class jobs.alchem.alchem(data_in, dlbd, T, directory, ref_pair=None, nab=None, barostat='iso')[source]

Bases: lammpsJobGroup

Alchemical thermodynamic integration (TI) workflow using LAMMPS.

This class constructs and manages a set of LAMMPS jobs along an alchemical path that interpolates between a reference potential and a target potential using a coupling parameter $lambda$.

Parameters:

data_in (str) – Initial liquid structure file in LAMMPS data format.
dlbd (float) – Increment of the alchemical coupling parameter $lambda$.
T (float) – Temperature of the simulation.
directory (str) – Path to the job group directory.
ref_pair (lammpsPair, optional) – Reference pair potential for thermodynamic integration. If None, a UFM reference is used.
nab (list of int, optional) – Number of atoms of each type [n1, n2, …]. If provided, atomic types in data_in will be reassigned.
barostat (str, optional) – Barostat type for NPT simulations. If set to “none”, NVT simulations are used.

process(general)[source]

Post-process completed TI jobs and compute the free energy change.

Parameters:: general (lammpsPara) – General LAMMPS parameters.
Returns:: Gibbs free energy difference.
Return type:: float

setup(general, depend)[source]

Set up LAMMPS jobs along the alchemical path.

Parameters:

general (lammpsPara) – General LAMMPS parameters and potential definitions.
depend (list object) – Dependency specification for the jobs.

write_script(scriptFile, general, lbd)[source]

Write a LAMMPS input script for a given $lambda$ value.

Parameters:

scriptFile (str) – Path to the LAMMPS input script to be written.
general (lammpsPara) – General LAMMPS parameters.
lbd (float) – Alchemical coupling parameter λ.

einstein

class jobs.einstein.einstein(data_in, dlbd, T, directory='./')[source]

Bases: lammpsJobGroup

Frenkel–Ladd thermodynamic integration using an Einstein crystal reference.

This class implements the Frenkel–Ladd method to compute the absolute free energy of a solid by thermodynamic integration between the interacting system and an Einstein crystal.

Parameters:

data_in (str) – Initial structure file in LAMMPS data format.
dlbd (float) – Increment of the coupling parameter $lambda$.
T (float) – Temperature of the simulation.
directory (str, optional) – Path to the job group directory.

process(general, depend)[source]

Post-process completed jobs and compute the absolute free energy.

Parameters:

general (lammpsPara) – General LAMMPS parameters.
depend (list object) – Dependency specification used for MSD sampling.

Returns:

Absolute Helmholtz free energy per atom.

Return type:

float

setup(general, barostat, depend)[source]

Set up thermodynamic integration jobs for the Einstein crystal path.

Parameters:

general (lammpsPara) – General LAMMPS parameters.
barostat (str) – Barostat type (“iso”, “tri”, etc.).
depend (list object) – Dependency specification for the jobs.

write_script(scriptFile, general, lbd, barostat)[source]

Write a LAMMPS input script for a given $lambda value.

Parameters:

scriptFile (str) – Path to the LAMMPS input script to be written.
general (lammpsPara) – General LAMMPS parameters.
lbd (float) – Coupling parameter $lambda$.
barostat (str) – Barostat type.

tramp

class jobs.tramp.tramp(data_in, Tlist, directory, nab=None, barostat='iso')[source]

Bases: lammpsJobGroup

Temperature-ramping LAMMPS workflow for solid or liquid phases.

This class sets up a series of independent LAMMPS simulations at different temperatures to equilibrate a structure and extract thermodynamic quantities such as enthalpy and volume.

Parameters:

data_in (str) – Initial structure file in LAMMPS data format.
Tlist (list of float) – List of temperatures at which to equilibrate the system.
directory (str) – Path to the group directory where job subfolders are created.
nab (list of int, optional) – Number of atoms of each type [n1, n2, …]. If provided, atomic types in data_in will be reassigned accordingly.
barostat (str, optional) – Barostat type for NPT simulations. If set to “none”, the script still writes an npt fix line but without barostat coupling.

process()[source]

Post-process temperature-ramping simulations.

Returns:: Array of shape (N_T, 2) containing temperature and averaged enthalpy values [[T1, H1], [T2, H2], …].
Return type:: numpy.ndarray

setup(general, boxdims=False, msd=False)[source]

Set up temperature-ramping LAMMPS jobs.

Parameters:

general (lammpsPara) – General LAMMPS parameters (units, pair potential, neighbor settings, masses, timestep, thermo frequency, pressure, Tdamp/Pdamp, run length).
boxdims (bool, optional) – If True, output detailed box dimensions (xlo/xhi, etc.) instead of only volume. Default is False.
msd (bool, optional) – If True, compute mean-squared displacement (MSD) for each atomic species. Default is False.

write_script(scriptFile, general, T, boxdims, msd)[source]

Write a LAMMPS input script for equilibration at a single temperature.

Parameters:

scriptFile (str) – Output path for the LAMMPS input script.
general (lammpsPara) – General LAMMPS parameters and pair potential definition.
T (float) – Temperature at which the system is equilibrated.
boxdims (bool) – Whether to output detailed box dimensions.
msd (bool) – Whether to compute mean-squared displacement (MSD).

Hybrid Monte Carlo and Molecular Dynamics

sgmc

class jobs.sgmc.sgmc_simulator(data_in, Tlist, mu_list, directory, barostat='iso')[source]

Bases: lammpsJobGroup

Set up LAMMPS jobs for semi-grand canonical Monte Carlo (SGMC) simulations.

This class generates a grid of LAMMPS simulations over temperature and chemical potential difference (mu_B - mu_A) for solid solutions.

Parameters:

data_in (str) – Initial structure file in LAMMPS data format.
Tlist (list of float) – List of temperatures to run simulations at.
mu_list (list of float) – List of chemical potential differences (mu_B - mu_A).
directory (str) – Path to the group directory where job subfolders are created.
barostat (str, optional) – Barostat type for NPT. If “none”, the script attempts to run without barostat contribution in baro_style (though the current script still writes an npt fix line).

setup(general)[source]

Create job directories and LAMMPS input scripts for all (T, mu) points.

Parameters:: general (lammpsPara) – General LAMMPS parameters (units, pair potential, neighbor settings, masses, timestep, thermo frequency, pressure, Tdamp/Pdamp, run length).

write_script(scriptFile, general, T, mu)[source]

Write a LAMMPS input script for a given temperature and chemical potential.

Parameters:

scriptFile (str) – Output path for the LAMMPS input script.
general (lammpsPara) – General LAMMPS parameters and pair potential definition.
T (float) – Temperature for the simulation.
mu (float) – Chemical potential difference (mu_B - mu_A) used in the SGMC swap fix.

Notes

The script uses:

fix npt for temperature/pressure control (with barostat style determined by self._barostat), and
fix atom/swap ... semi-grand yes ... mu 0 {mu} to perform SGMC swaps between types 1 and 2.

Thermo output includes swap acceptance counters f_2[1], f_2[2] and the type populations c_typevec[1], c_typevec[2].

Solid Liquid Coexistence

sli

class jobs.sli.sli_simulator(data_in, Tlist, Tmelt, directory, replicate=2, orient='z', barostat='iso')[source]

Bases: lammpsJobGroup

Set up LAMMPS jobs for solid–liquid interface (SLI) simulations.

This workflow prepares and runs a sequence of MD stages to create a solid–liquid interface: 1) pre-equilibrate whole system at target temperature, 2) melt half of the simulation box by heating only the “liquid” region, 3) cool the melted region back to the target temperature, 4) re-equilibrate using a uniaxial barostat along the chosen orientation.

Parameters:

data_in (str) – Initial structure file in LAMMPS data format.
Tlist (list of float) – Temperatures to run the interface preparation/equilibration at.
Tmelt (float) – High temperature used to melt half of the box.
directory (str) – Path to the group directory where job subfolders are created.
replicate (int, optional) – Replication factor along the interface orientation direction. Default is 2.
orient ({"x", "y", "z"}, optional) – Direction along which the system is replicated and along which the liquid-half region is defined. Default is “z”.
barostat (str, optional) – Barostat style for the pre-equilibration stage. If “none”, the script writes an NPT fix with an empty barostat style string (current behavior). Default is “iso”.

setup(general)[source]

Create job directories and LAMMPS input scripts for all temperatures.

Parameters:: general (lammpsPara) – General LAMMPS parameters (units, pair potential, neighbor settings, masses, timestep, thermo frequency, pressure, Tdamp/Pdamp, run length).

write_script(scriptFile, general, T)[source]

Write a LAMMPS input script for solid–liquid interface preparation.

Parameters:

scriptFile (str) – Output path for the LAMMPS input script.
general (lammpsPara) – General LAMMPS parameters and pair potential definition.
T (float) – Target temperature for the interface simulation.

Notes

The script defines a liquid group as half of the simulation box along the chosen orientation (self._orient). It then runs several stages: - Pre-equilibrate (whole box) using NPT at temperature T. - Heat only the liquid group from T to Tmelt using NVT. - Cool the liquid group back from Tmelt to T using NVT. - Reset velocities. - Final relaxation using uniaxial NPT along self._orient.