lammps_engine

Facade for LAMMPS MD engine

This is a facade to PyLammps (added in 30th-Jul-2016 version), a convenience wrapper for the LAMMPS Python interface i.e. where Python is extended with LAMMPS.

Defining all interaction types requires that LAMMPS was built with the MOLECULE package.

Notes

When variables are either passed to or from PyLammps, the ctypes conversion can mean that they are unnecessarily cast, particularly from float to int. This can cause issues as LAMMPS requires certain variables, e.g. number of steps, to be int. Therefore it is always a good idea to be cast these variables when they are read from PyLammps e.g. int(lmp.variables['steps'].value).

A minor bug in LAMMPS (Dec 2018 version) means that nangletypes returned by PyLammps is incorrectly set to ndihedraltypes. This was corrected in Mar 2020 release.

class MDMC.MD.engine_facades.lammps_engine.LAMMPSEngine[source]

Facade for LAMMPS

One notable issue with creating the LAMMPS facade is that some pair_styles are combinations of both dispersion and coulombic interactions. For example, although LAMMPS has lj/cut, coul/cut, and coul/long, there is no lj/long pair_style; it only exists in combination with coul/long (i.e. lj/long/coul/long). This means that the facade has to not just parse each nonbonded interaction, but also has to determine if that pair_style should be combined with another pair_style (e.g. lj/long and coul/long have to be combined before passing to pair_style and pair_coeff). An additional complication of this is that when setting the coefficients (Parameters) of these interactions, they again have to be set together. So in theory a coulombic interaction needs to know the dispersion interaction it has been paired with an also pass those coefficients when calling pair_coeff. In practice a simplification can be made, at least in the case of currently implemented pair styles: As coulombic pair_styles do no take any coefficients, any coulombic pair_styles that comprise a combined pair_style can be ignored for the purposes of setting the coulombic pair_style; this can be taken care of when pair_coeff is called from the correspoding dispersion interaction, as this possesses the dispersion coefficients that also need to be passed when the coefficients of this pair style are set.

property barostat: str

Get or set the str which specifies the barostat

Returns:

The barostat name

Return type:

str

clear() → None[source]

Deletes all atoms of the MD engine, restores all settings to their default values, and frees all memory in LAMMPS.

convert_trajectory(start: int = 0, stop: int = None, step: int = 1, **settings: dict) → CompactTrajectory[source]

Converts between a LAMMPS trajectory dump and an MDMC CompactTrajectory

The LAMMPS dump must include at least id, atom_type, and xyz positions. The xyz positions must be consecutive and in that order. The same is true of the xyz components of the velocity, if they are provided.

Parameters:

  • start (int) – The index of the first trajectory, inclusive.

  • stop (int) – The index of the last trajectory, exclusive.

  • step (int) – The step size between trajectories.

  • **settings –

    scaled_positions (bool)

    If the trajectory_file has scaled positions

    atom_IDs (list)

    LAMMPS ID of the atoms which should be included. If not passed then all atoms are included in the converted trajectory.

Returns:

The MDMC CompactTrajectory corresponding to the LAMMPS trajectory_file.

Return type:

CompactTrajectory

Raises:

  • AssertionError – If universe is passed, and the number of atoms in the trajectory_file is not the same as in the universe.

  • TypeError – If trajectory_file describes a triclinic universe.

property ensemble: LAMMPSEnsemble

Get or set the ensemble object which applies a thermostat and/or barostat to LAMMPS

Returns:

The simulation thermodynamic ensemble

Return type:

LAMMPSEnsemble

eval(variable: str) → Any[source]

Evaluates some simulation variable.

minimize(n_steps: int, minimize_every: int = 10, output_log: str = None, work_dir: str = None, **settings: dict) → None[source]

Moves the atoms towards a potential energy minimum, by performing an MD simulation interrupted periodically by a structure relaxation. In the end, the configuration with the lowest potential energy reached during the run is kept.

Parameters:

  • n_steps (int) – Number of MD simulation steps

  • minimize_every (int, optional, default 10) – The structure relaxation will be performed every ‘minimize_every’ steps of the MD simulation

  • output_log (str, optional) – Not used in this facade

  • work_dir (str, optional) – Not used in this facade

  • **settings

  • etol (float, energy tolerance criteria for energy minimisation)

  • ftol (float, force tolerance criteria for force minimisation, active only if non-zero)

  • maxiter (int, maximum number of steps in a single structure relaxation)

  • maxeval (int, maximum number of force calculations in a single structure relaxation)

property pressure: float

Get or set the pressure of the simulation in atm

Returns:

Pressure in atm

Return type:

float

reset_config() → None[source]

Resets the configuration of the simulation to that in saved_config

run(n_steps: int, equilibration=False, output_log: str = None, work_dir: str = None, **settings: dict)[source]

Runs a simulation. Must follow a call to setup_universe() and setup_simulation().

Parameters:

  • n_steps (int) – Number of steps for the time integrator.

  • equilibration (bool) – If True, run is equilibration which does not store the trajectory. Otherwise run is prodution.

save_config() → None[source]

Sets self.saved_config to the current configuration

property saved_config: ndarray

Get the saved configuration of the atomic positions

Returns:

The configuration from the start of the run. Each row of the array corresponds to the LAMMPS atom ID - 1 (offset is due to array zero indexing) and the columns of the array are the x, y, z components of the position, the mass and the charge of each Atom.

Return type:

numpy.ndarray

setup_simulation(**settings: dict) → None[source]

Sets simulation parameters in LAMMPS, such as the thermodynamic variables, thermostat/barostat parameters and trajectory settings

Parameters:

**settings – Passed to LAMMPSSimulation

setup_universe(universe: Universe, **settings: dict) → None[source]

Creates the simulation box, the atomic configuration, and the topology in LAMMPS

Parameters:

  • universe (Universe) – The MDMC Universe which will be setup in LAMMPS.

  • **settings –

    atom_style (str)

    A LAMMPS atom_style str. The default setting of real will generally be appropriate.

property temperature: float

Get or set the temperature of the simulation in K

Returns:

Temperature in K

Return type:

float

property thermostat: str

Get or set the str which specifies the thermostat

Returns:

The thermostat name

Return type:

str

update_parameters() → None[source]

Updates the MDEngine force field Parameter objects from the Universe

class MDMC.MD.engine_facades.lammps_engine.LAMMPSEnsemble(lmp, temperature: float = None, pressure: float = None, thermostat: str = None, barostat: str = None, **settings: dict)[source]

A thermodynamic ensemble determined by applying a thermostat and/or barostat

Parameters:

  • lmp (PyLammps) – Set the lmp attribute to a PyLammps object.

  • temperature (float, optional) – Thermostat temperature. Default is None, which is only valid if a thermostat is also None.

  • pressure (float, optional) – Barostat pressure. Default is None, which is only valid if a barostat is also None.

  • thermostat (str) – Name of a thermostat to be applied.

  • barostat (str) – Name of a barostat to be applied.

  • **settings – time_step (float) t_damp (int) p_damp (int) t_window (float) t_fraction (float) rescale_step (int)

rescale_step

Number of steps between applying temperature rescaling. This only applies to rescale thermostats.

Type:

int

apply_ensemble_fixes() → None[source]

Passes the required LAMMPS fixes to apply a specific thermodynamic ensemble to the simulation

Removes all pre-existing thermostat and barostat fixes

property barostat: str

Get or set the str which specifies the barostat

Raises:

AttributeError – If self.pressure has not been set.

property pressure: float

Get or set the pressure of the simulation in atm

remove_ensemble_fixes() → None[source]

Removes all LAMMPS fixes relating to the ensemble i.e. removes all thermostats and barostats

This must be done before thermostat and barostat fixes are added, so that there is no conflict with existing thermostat and barostats fixes. It is also required for Shake and Rattle fixes which cannot be added after barostat fixes have been applied.

property t_fraction: float

Get or set the fraction by which the temperature is rescaled to the target temperature

This is required for the rescale thermostat.

Returns:

Fraction (i.e. between 0.0 and 1.0 inclusive) by which the temperature is rescaled

Return type:

float

Raises:

ValueError – If set to a value outside of 0.0 and 1.0 inclusive.

property t_window: float

Get or set the temperature range in K in which the temperature is not rescaled

This only applies to rescale thermostats.

Returns:

temperature range in K

Return type:

float

property temperature: float

Get or set the temperature of the simulation in K

property thermostat: str

Get or set the str which specifies the thermostat

Raises:

AttributeError – If self.temperature has not been set.

property time_step: float

Get or set the simulation time step in fs

Returns:

Simulation time step in fs

Return type:

float

class MDMC.MD.engine_facades.lammps_engine.LAMMPSSimulation(universe, traj_step: int, time_step: float = 1.0, lmp=None, **settings: dict)[source]

The attributes and methods related running a simulation in LAMMPS using a LAMMPSUniverse object

Parameters:

  • universe (Universe) – The MDMC Universe used to create the LAMMPSUniverse.

  • traj_step (int) – How many steps the simulation should take between dumping each CompactTrajectory frame

  • time_step (float, optional) – Simulation timestep in fs, default is 1.

  • lmp (PyLammps, optional) – Set the lmp attribute to a PyLammps object. Default is None, which results in a new PyLammps object being initialised.

  • **settings – temperature (float) skin (float) neighbor_steps (int) remove_linear_momentum (int) remove_angular_momentum (int) velocity_seed (int): The seed to be used by LAMMPS to create velocities.

universe

An MDMC Universe object.

Type:

Universe

traj_step

Number of simulation steps that elapse between the CompactTrajectory being stored.

Type:

int

ensemble

Simulation ensemble, which applies a thermostat and barostat.

Type:

LAMMPSEnsemble

property ang_momentum_steps: int

Get or set the number of steps between resetting the angular momentum

Returns:

Number of steps between the angular momentum being removed

Return type:

int

property barostat: str

Get or set the string which specifies the barostat

Returns:

The barostat name

Return type:

str

property lin_momentum_steps: int

Get or set the number of steps between resetting the linear momentum

Returns:

Number of steps between the linear momentum being removed

Return type:

int

property neighbor_steps: int

Get or set the number of steps between neighbor list updates

Returns:

Number of steps between neighbor list updates

Return type:

int

property pressure: float

Get or set the pressure of the simulation in atm

Returns:

Pressure in atm

Return type:

float

property skin: float

Get or set the skin distance in Ang

Returns:

The skin distance in Ang. This distance plus the force cutoff distance determines which atom pairs are stored in the neighbor list.

Return type:

float

property temperature: float

Get or set the temperature of the simulation in K

Returns:

Temperature in K

Return type:

float

property thermostat: str

Get or set the string which specifies the thermostat

Returns:

The thermostat name

Return type:

str

property time_step: float

Get or set the simulation time step in fs

Returns:

Simulation time step in fs

Return type:

float

class MDMC.MD.engine_facades.lammps_engine.LAMMPSUniverse(universe: Universe, lmp: PyLammps = None, **settings: dict)[source]

A class with what would be the equivalent in LAMMPS to the universe (i.e. the configuration and topology)

Parameters:

  • universe (Universe) – The MDMC Universe used to create the LAMMPSUniverse

  • lmp (PyLammps, optional) – Set the lmp attribute to a PyLammps object. Default is None, which results in a new PyLammps object being initialised.

  • **settings –

    atom_style (str)

    A LAMMPS atom_style string. The default setting of real will generally be appropriate.

    nonbonded_mix (str)

    The name of the formula which determines non-bonded mixing

universe

The MDMC Universe which has been converted to this LAMMPSUniverse.

Type:

Universe

atom_dict

A dict with {MDMC_atom: LAMMPS_atom_id}, where MDMC_atom is an MDMC Atom and LAMMPS_atom is the corresponding LAMMPS Atom.

Type:

dict

atom_types

A dict with {type_ID: MDMC_atom_group}, where the type_ID is a unique int and MDMC_atom_group is a list of Atom which are identical in terms of element and interactions.

Type:

dict

atom_type_properties

Each tuple is (symbol, mass) for all atom_types (ordered) by atom_type, where symbol is a str specifying the element of the atom_type and mass is a float specifying the mass of the atom_type.

Type:

list of tuples

bonds

All Bond interactions in the MDMC Universe.

Type:

list of Bonds

angles

All BondAngle interactions in the MDMC Universe.

Type:

list of BondAngles

couls

All Coulombic interactions in the MDMC Universe.

Type:

list of Coulombics

disps

All Dispersion interactions in the MDMC Universe.

Type:

list of Dispersions

bond_ID

A dict of {bond: ID pairs} relating each Bond to a LAMMPS ID.

Type:

dict

angle_ID

A dict of {angle: ID pairs} relating each BondAngle to a LAMMPS ID.

Type:

dict

proper_ID

A dict of {proper: ID pairs} relating each DihedralAngle (with improper == False) to a LAMMPS ID.

Type:

dict

improper_ID

A dict of {improper: ID pairs} relating each DihedralAngle (with improper == True) to a LAMMPS ID.

Type:

dict

apply_constraints() → None[source]

Adds a constraint fix to LAMMPS for all bonds and bond angles which are constrained

property nonbonded_mix: str

Get or set the formula used to calculate nonbonded interactions between different atom_types

Options are geometric, arithmetic and sixthpower, which are defined in the LAMMPS documentation.

Returns:

The name of the formula which determines non-bonded mixing

Return type:

str

Raises:

ValueError – str specifies an unsupported mix name

set_config(config: ndarray) → None[source]

Changes the positions of all of the atoms in the LAMMPS wrapper

Parameters:

config (numpy.ndarray) – The positions, mass and charge of the Atom objects, used to set the LAMMPS configuration. Each row of the array must correspond to the LAMMPS atom ID - 1 (offset is due to array zero indexing) and the columns of the array must be the x, y, z components of the position, the mass and the charge of each Atom.

Raises:

IndexError – If config does not contain the same number of atoms as LAMMPS possesses.

update_parameters() → None[source]

Updates the LAMMPS force field parameters from the MDMC universe

class MDMC.MD.engine_facades.lammps_engine.PyLammpsAttribute(lmp: PyLammps = None, atom_style: str = 'full')[source]

A class which has a PyLammps object as an attribute

It possesses attributes and methods relating to the PyLammps object

Parameters:

  • lmp (PyLammps, optional) – Set the lmp attribute to a PyLammps object. Default is None, which results in a new PyLammps object being initialised.

  • atom_style (str, optional) – The LAMMPS atom_style, which determines the properties that can be associated which the atoms (e.g. charge, bonds). Default is full.

lmp

The PyLammps object owned by this class

Type:

PyLammps

property dumps: list

Get the PyLammps wrapper list of dumps

Dumps are LAMMPS commands which write atom quantities to file for specified timesteps

property fix_names: list[str]

Get the names of the fixes applied in LAMMPS

Returns:

The names of the fixes

Return type:

list of str

property fix_styles: list[str]

Get the styles of the fixes applied in LAMMPS

Returns:

The styles of the fixes

Return type:

list of str

property fixes: list[dict]

Get the PyLammps wrapper list of fixes

Returns:

Each dict states the group, name and style of a LAMMPS ``fix` which is applied

Return type:

list of dict

property system_state: namedtuple

Get the PyLammps wrapper system state dict

Returns:

Contains the properties of the simulation box.

Return type:

System

MDMC.MD.engine_facades.lammps_engine.convert_unit(value: ndarray | float, unit: Unit = None, to_lammps: bool = True)[source]

Converts between MDMC units and LAMMPS real units

Parameters:

  • value (array_like or float_like) – The value of the physical property to be converted, in MDMC units. Must derive from either ndarray or float.

  • unit (Unit, optional) – The unit of the value. If None, the value must possess a unit attribute i.e. derive from UnitFloat or UnitArray. Default is None.

  • to_lammps (bool, optional) – If True the conversion is from MDMC units to LAMMPS units. Default is True.

Returns:

Value in LAMMPS units if to_lammps is True, otherwise value in MDMC units. Return type is same as value type.

Return type:

float or numpy.ndarray

MDMC.MD.engine_facades.lammps_engine.parse_all_nonbonded_styles(interactions: NonBondedInteraction) → dict[tuple, list[str]][source]

Converts all NonBondedInteractions to LAMMPS pair styles

This is required because LAMMPS frequently treats Coulombic and Disperion interactions together; these cases need to be dealt with to generate the correct input to LAMMPS pair_styles. For example, while the pair_styles buck, lj/cut, coul/cut and coul/long can all be passed separately, the dispersive and coulombic styles are combined (dispersive always preceding coulombic) as this is dealt with more efficiently in the LAMMPS engine. buck/long and lj/long only exist as part of other pair styles, such as buck/long/coul/long and lj/long/coul/long, so must be combined.

Parameters:

interactions (list of NonBondedInteractions) – NonBondedInteractions to be parsed into LAMMPS pair_styles.

Returns:

A dict with {pair_styles: pair_modifiers} where pair_styles is a tuple of all of the combined LAMMPS pair styles corresponding to interactions. Each tuple contains the combined pair_style as one element, and the cutoffs as the second element e.g. ('lj/cut/coul/cut', 5.0 10.0). If additional arguments are required when combining styles, they will be added and returned in the tuple as the third and middle element e.g. ('buck/long/coul/long', 'long long', '10.0'). pair_modifiers is a list of str for setting pair_modify for the corresponding pair_style.

Return type:

dict

Raises:

  • ValueError – If Dispersion and Coulombic interactions have different long range cutoff, which is not implemented in LAMMPS.

  • ValueError – If long range Dispersion not defined in conjunction with a long range Coulombic.

MDMC.MD.engine_facades.lammps_engine.parse_bonded_coefficients(interaction: BondedInteraction) → list[str][source]

Orders MDMC Parameter objects for input to LAMMPS bond_coeff and angle_coeff

Parameters:

interaction (BondedInteraction) – BondedInteraction where its style and parameters will be parsed.

Returns:

Style and parameters converted to the input format for LAMMPS bond_coeff and angle_coeff

Return type:

list of str

Raises:

NotImplementedError – If interaction has a function that has not been implemented in the LAMMPS facade.

MDMC.MD.engine_facades.lammps_engine.parse_bonded_styles(interaction: BondedInteraction) → str[source]

Converts MDMC InteractionFunction names for BondedInteractions to LAMMP bond styles

Parameters:

interaction (BondedInteraction) – BondedInteraction to be parsed into LAMMPS bond style.

Returns:

LAMMPS bond style corresponding to interaction

Return type:

str

Raises:

NotImplementedError – If interaction has a function that has not been implemented in the LAMMPS facade.

MDMC.MD.engine_facades.lammps_engine.parse_constraint(constraint_algorithm: ConstraintAlgorithm, bonds: list[Bond] = None, bond_ID_dict: dict = None, angles: list[BondAngle] = None, angle_ID_dict: dict = None) → list[source]

Converts an MDMC ConstraintAlgorithm for input to LAMMPS fix

At least one of bonds and angles must be passed.

Parameters:

  • constraint_algorithm (ConstraintAlgorithm) – An object that derives from ConstraintAlgorithm to be parsed.

  • bonds (list of Bonds, optional) – Constrained Bond interactions.

  • bond_ID_dict (dict, optional) – dict with {bond: ID pairs} relating each Bond object to a LAMMPS ID.

  • angles (list of BondAngles, optional) – Constrained BondAngle interactions.

  • angle_ID_dict (dict, optional) – dict with {angle: ID pairs} relating each BondAngle object to a LAMMPS ID.

Returns:

Input parameters for LAMMPS fix, not including the first two terms (fix ID, group-ID). The output list has a maximum length of 7, where the last four entries are optional but a minimum of two is required:

[algorithm name, accuracy, max iterations, 'b', bond IDs,
 'a', angle IDs]

Return type:

list

Raises:

  • TypeError – If there is not at least one constrained Interaction passed.

  • NotImplementedError – If constraint_algorithm not been implemented in the LAMMPS facade.

MDMC.MD.engine_facades.lammps_engine.parse_dispersion_coefficients(interactions: list[NonBondedInteraction], nonbonded_styles: list[tuple] = None) → list[str][source]

Orders MDMC Parameter objects for input to LAMMPS pair_coeff

Parameters:

  • interactions (list of NonBondedInteraction) – NonBondedInteractions where their style and parameters will be parsed.

  • nonbonded_styles (list of tuple) – The parsed NonBondedInteractions, where the combined pair_styles have been created by the parse_all_nonbonded_styles function. If None (default), the interactions are parsed manually.

Returns:

Each element is a partial pair_coeff command, containing a pair_style, the ordered Dispersion Parameter objects converted to the correct input format for LAMMPS pair_coeff, and the cutoff. For example, if interactions contains a Buckingham with Parameter A, B, C = 4.184, 1.0, 4.184, and cutoff = 20.0, and a Coulombic with a cutoff of 10.0, the str element of the list will be:

'buck/coul/cut 1.0 1.0 1.0 20.0 10.0'

Return type:

list of str

Raises:

  • NotImplementedError – If interaction has a function that has not been implemented in the LAMMPS facade.

  • ValueError – If the LAMMPS Buckingham parameter rho is less than or equal to zero.

MDMC.MD.engine_facades.lammps_engine.parse_kspace_solver(solver: KSpaceSolver) → list[source]

Converts an MDMC KSpaceSolver for input to LAMMPS kspace_style

Parameters:

solver (KSpaceSolver) – A KSpaceSolver to be parsed.

Returns:

Style and parameters for input to LAMMPS kspace_style

Return type:

list

Raises:

NotImplementedError – If solver type has has not been implemented in the LAMMPS facade.

MDMC.MD.engine_facades.lammps_engine.parse_nonbonded_modifications(interaction: Interaction) → list[str][source]

Parses MDMC Interaction attributes into list that can be used with LAMMPS pair_modify command

MDMC.MD.engine_facades.lammps_engine.interaction

The Interaction for which the attributes are parsed

Type:

Interaction

Returns:

A list of str which are a valid pair_modify command, or an empty list if no Interaction attributes require setting pair_modify

Return type:

list

MDMC.MD.engine_facades.lammps_engine.parse_nonbonded_styles(interaction: NonBondedInteraction) → tuple[source]

Converts MDMC InteractionFunction names for NonBondedInteractions to LAMMPS pair styles

Parameters:

interaction (NonBondedInteraction) – NonBondedInteraction to be parsed into LAMMPS pair style.

Returns:

(styles, mods) where styles is a list of str of LAMMPS pair style corresponding to the interaction, and mods is a list of str of LAMMPS pair modifications corresponding to the interaction

Return type:

tuple

Raises:

NotImplementedError – If interaction has a function that has not been implemented in the LAMMPS facade.