pyiron_atomistics.lammps.control.LammpsControl

class pyiron_atomistics.lammps.control.LammpsControl(input_file_name=None, **qwargs)

Bases: GenericParameters

__init__(input_file_name=None, **qwargs)

Methods

__init__([input_file_name])
calc_md([temperature, pressure, ...])	Set an MD calculation within LAMMPS.
calc_minimize([ionic_energy_tolerance, ...])	Sets parameters required for minimization.
calc_static()
calc_vcsgc(mu, ordered_element_list[, ...])	Run variance-constrained semi-grand-canonical MD/MC for a binary system.
clear_all()	Clears all fields in the object
define_blocks(block_dict)	Define a block section within the GenericParameters
energy_kin_per_atom()	Enable the output of per atom kinetic energies.
energy_pot_per_atom()	Enable the output of per atom potential energies.
fix_move_linear_by_id(ids, velocity)	Displace atoms at each timestep.
fix_setforce_by_id(ids, force)	Set the force on a collection of atoms to a specified value.
from_dict(obj_dict[, version])	Populate the object from the serialized object.
from_hdf(hdf[, group_name])	Restore the GenericParameters from an HDF5 file
generate_seed_from_job([job_name, seed])	Generate a unique seed from the job name.
get(parameter_name[, default_value])	Get the value of a specific parameter from GenericParameters - if the parameter is not available return default_value if that is set.
get_attribute(attribute_name)	Get the value of a specific parameter from GenericParameters
get_pandas()	Output the GenericParameters object as Pandas Dataframe for human readability.
get_string_lst()	Get list of strings from GenericParameters to write to input file
instantiate(obj_dict[, version])	Create a blank instance of this class.
keys()	Return keys of GenericParameters object
load_default([file_content])	Load defaults resets the dataset in the background to be empty
load_string(input_str)	Load a multi line string to overwrite the current parameter settings
measure_mean_value(key[, every, repeat, ...])	param key: property to take an average value of (e.g. 'energy_pot' v.i.)
modify([separator, append_if_not_present])	Modify values for existing parameters.
pressure_to_lammps(pressure, rotation_matrix)	Convert a singular value, list of values, or combination of values to the appropriate six elements for Lammps pxx, pyy, pzz, pxy, pxz, and pyz pressure tensor representation.
read_input(file_name[, ignore_trigger])	Read input file and store the data in GenericParameters - this overwrites the current parameter settings
remove_keys(key_list)	Remove a list of keys from the GenericParameters
set([separator])	Set the value of multiple parameters or create new parameter key, if they do not exist already.
set_dict(dictionary)	Set a dictionary of key value pairs
set_initial_velocity(temperature[, seed, ...])	Create initial velocities via velocity all create.
set_value(line, val)	Set the value of a parameter in a specific line
to_dict()	Reduce the object to a dictionary.
to_hdf(hdf[, group_name])	Store the GenericParameters in an HDF5 file
write_file(file_name[, cwd])	Write GenericParameters to input file

Attributes

comment_char	Get the separator that characterizes comment
dataset
end_value_char	Get the special character at the end of every line
file_name	Get the file name of the input file
multi_word_separator	Get the multi word separator to have multi word keys
replace_char_dict	Get the dictionary to replace certain character combinations
separator_char	Get the separator that characterizes the split between key and value
table_name	Get the name of the input table inside the HDF5 file
val_only	Get the boolean option to switch from a key value list to an value only input file

calc_md(temperature=None, pressure=None, n_ionic_steps=1000, time_step=1.0, n_print=100, temperature_damping_timescale=100.0, pressure_damping_timescale=1000.0, seed=None, tloop=None, initial_temperature=None, langevin=False, delta_temp=None, delta_press=None, job_name='', rotation_matrix=None)

Set an MD calculation within LAMMPS. Nosé Hoover is used by default.

Parameters:

• temperature (None/float/list) – Target temperature value(-s). If set to None, an NVE calculation is performed. It is required when the pressure is set or langevin is set It can be a list of temperature values, containing the initial target temperature and the final target temperature (in between the target value is varied linearly).

• pressure (None/float/numpy.ndarray/list) – Target pressure. If set to None, an NVE or an NVT calculation is performed. If set to a scalar, the shear of the cell and the ratio of the x, y, and z components is kept constant, while an isotropic, hydrostatic pressure is applied. A list of up to length 6 can be given to specify xx, yy, zz, xy, xz, and yz components of the pressure tensor, respectively. These values can mix floats and None to allow only certain degrees of cell freedom to change. (Default is None, run isochorically.)

• n_ionic_steps (int) – Number of ionic steps

• time_step (float) – Step size in fs between two steps.

• n_print (int) – Print frequency

• temperature_damping_timescale (float) – The time associated with the thermostat adjusting the temperature. (In fs. After rescaling to appropriate time units, is equivalent to Lammps’ Tdamp.)

• pressure_damping_timescale (float) – The time associated with the barostat adjusting the temperature. (In fs. After rescaling to appropriate time units, is equivalent to Lammps’ Pdamp.)

• seed (int) – Seed for the random number generation used for the intiial velocity creation and langevin dynamics - otherwise ignored. If not specified, the seed is created via job name

• tloop

• initial_temperature (None/float) – Initial temperature according to which the initial velocity field is created. If None, the initial temperature will be twice the target temperature (which would go immediately down to the target temperature as described in equipartition theorem). If 0, the velocity field is not initialized (in which case the initial velocity given in structure will be used). If any other number is given, this value is going to be used for the initial temperature.

• langevin (bool) – (True or False) Activate Langevin dynamics

• delta_temp (float) – Thermostat timescale, but in your Lammps time units, whatever those are. (DEPRECATED.)

• delta_press (float) – Barostat timescale, but in your Lammps time units, whatever those are. (DEPRECATED.)

• job_name (str) – Job name of the job to generate a unique random seed.

• rotation_matrix (numpy.ndarray) – The rotation matrix from the pyiron to Lammps coordinate frame.

calc_minimize(ionic_energy_tolerance=0.0, ionic_force_tolerance=0.0001, max_iter=100000, pressure=None, n_print=100, style='cg', rotation_matrix=None)

Sets parameters required for minimization.

Parameters:

• ionic_energy_tolerance (float) – If the magnitude of difference between energies of two consecutive steps is lower than or equal to ionic_energy_tolerance, the minimisation terminates. (Default is 0.0 eV.)

• ionic_force_tolerance (float) – If the magnitude of the global force vector at a step is lower than or equal to ionic_force_tolerance, the minimisation terminates. (Default is 1e-4 eV/angstrom.)

• e_tol (float) – Same as ionic_energy_tolerance (deprecated)

• f_tol (float) – Same as ionic_force_tolerance (deprecated)

• max_iter (int) – Maximum number of minimisation steps to carry out. If the minimisation converges before max_iter steps, terminate at the converged step. If the minimisation does not converge up to max_iter steps, terminate at the max_iter step. (Default is 100000.)

• pressure (None/float/numpy.ndarray/list) – Target pressure. If set to None, an isochoric (constant V) calculation is performed. If set to a scalar, the shear of the cell and the ratio of the x, y, and z components is kept constant, while an isotropic, hydrostatic pressure is applied. A list of up to length 6 can be given to specify xx, yy, zz, xy, xz, and yz components of the pressure tensor, respectively. These values can mix floats and None to allow only certain degrees of cell freedom to change. (Default is None, run isochorically.)

• n_print (int) – Write (dump or print) to the output file every n steps (Default: 100)

• style ('cg'/'sd'/other values from Lammps docs) – The style of the numeric minimization, either conjugate gradient, steepest descent, or other keys permissible from the Lammps docs on ‘min_style’. (Default is ‘cg’ – conjugate gradient.)

• rotation_matrix (numpy.ndarray) – The rotation matrix from the pyiron to Lammps coordinate frame.

calc_vcsgc(mu, ordered_element_list, target_concentration=None, kappa=1000.0, mc_step_interval=100, swap_fraction=0.1, temperature_mc=None, window_size=None, window_moves=None, temperature=None, pressure=None, n_ionic_steps=1000, time_step=1.0, n_print=100, temperature_damping_timescale=100.0, pressure_damping_timescale=1000.0, seed=None, initial_temperature=None, langevin=False, job_name='', rotation_matrix=None)

Run variance-constrained semi-grand-canonical MD/MC for a binary system. In addition to VC-SGC arguments, all arguments for a regular MD calculation are also accepted.

https://vcsgc-lammps.materialsmodeling.org

Note

For easy visualization later (with get_structure), it is highly recommended that the initial structure contain at least one atom of each species.

Warning

Assumes the units are metal, otherwise units for the constraints may be off.

Parameters:

• mu (dict) – A dictionary of chemical potentials, one for each element the potential treats, where the dictionary keys are just the chemical symbol. Note that only the relative chemical potentials are used here, such that the swap acceptance probability is influenced by the chemical potential difference between the two species (a more negative value increases the odds of swapping to that element.)

• ordered_element_list (list) – A list of the chemical species symbols in the order they appear in the definition of the potential in the Lammps’ input file.

• target_concentration – A dictionary of target simulation domain concentrations for each species in the potential. Dictionary keys should be the chemical symbol of the corresponding species, and the sum of all concentrations must be 1. (Default is None, which runs regular semi-grand-canonical MD/MC without any variance constraint.)

• kappa – Variance constraint for the MC. Larger value means a tighter adherence to the target concentrations. (Default is 1000.)

• mc_step_interval (int) – How many steps of MD between each set of MC moves. (Default is 100.) Must divide the number of ionic steps evenly.

• swap_fraction (float) – The fraction of atoms whose species is swapped at each MC phase. (Default is 0.1.)

• temperature_mc (float) – The temperature for accepting MC steps. (Default is None, which uses the MD temperature.)

• window_size (float) – The size of the sampling window for parallel calculations as a fraction of something unspecified in the VC-SGC docs, but it must lie between 0.5 and 1. (Default is None, window is determined automatically.)

• window_moves (int) – The number of times the sampling window is moved during one MC cycle. (Default is None, number of moves is determined automatically.)

• rotation_matrix (numpy.ndarray) – The rotation matrix from the pyiron to Lammps coordinate frame.

clear_all() → None

Clears all fields in the object

property comment_char: str | None

Get the separator that characterizes comment

Returns:

comment character

Return type:

str

define_blocks(block_dict: Dict[str, List[str]]) → None

Define a block section within the GenericParameters

Parameters:

block_dict (dict) – dictionary to define the block

property end_value_char: str | None

Get the special character at the end of every line

Returns:

end of line character

Return type:

str

energy_kin_per_atom()

Enable the output of per atom kinetic energies. This will add an additional key ‘energy_kin_per_atom’ to the HDF output.

energy_pot_per_atom()

Enable the output of per atom potential energies. This will add an additional key ‘energy_pot_per_atom’ to the HDF output.

property file_name: str | None

Get the file name of the input file

Returns:

file name

Return type:

str

fix_move_linear_by_id(ids, velocity)

Displace atoms at each timestep. Creates a new group with a unique name based off the hash of the ids.

Parameters:

• ids (list/numpy.ndarray) – Integer ids of the atoms to move in the job’s structure.

• velocity (list/numpy.ndarray/tuple) – The velocity in x-y-z-direction for the group. None arguments are converted to Lammps ‘NULL’ values and the velocity in this direction is left unchanged.

Warning: This fix does not exclude these atoms from [other fixes](https://lammps.sandia.gov/doc/fix_move.html).

You may wish to combine this call with selective_dynamics on your corresponding structure. Future developers can find a more complete discussion [here](pyiron/pyiron#1212) when further modifying this capability. Further, it will malfunction if the Lammps coordinate frame and pyiron coordinate frame differ.

fix_setforce_by_id(ids, force)

Set the force on a collection of atoms to a specified value.

ids (list/numpy.ndarray): Integer ids of the atoms to move in the job’s structure. force (list/numpy.ndarray/tuple): The force in x-y-z-direction for the group. None arguments are

converted to Lammps ‘NULL’ values and the force in this direction is left unchanged.

Warning: This fix will malfunction (silently) if the Lammps coordinate frame and pyiron coordinate frame differ.

from_dict(obj_dict: dict, version: str = None)

Populate the object from the serialized object.

Parameters:

• obj_dict (dict) – data previously returned from to_dict()

• version (str) – version tag written together with the data

from_hdf(hdf, group_name: str | None = None) → None

Restore the GenericParameters from an HDF5 file

Parameters:

• hdf (ProjectHDFio) – HDF5 group object

• group_name (str) – HDF5 subgroup name - optional

static generate_seed_from_job(job_name='', seed=0)

Generate a unique seed from the job name.

Parameters:

• job_name (str) – job_name of the current job to generate the seed

• seed (int) – integer to access part of the seed

Returns:

random seed generated based on the hash

Return type:

int

get(parameter_name: str, default_value: str | None = None) → str | None

Get the value of a specific parameter from GenericParameters - if the parameter is not available return default_value if that is set.

Parameters:

• parameter_name (str) – parameter key

• default_value (str) – default value to return is the parameter is not set

Returns:

value of the parameter

Return type:

str

get_attribute(attribute_name: str) → str | None

Get the value of a specific parameter from GenericParameters

Parameters:

attribute_name (str) – parameter key

Returns:

value of the parameter

Return type:

str

get_pandas() → DataFrame

Output the GenericParameters object as Pandas Dataframe for human readability.

Returns:

Pandas Dataframe of the GenericParameters object

Return type:

pandas.DataFrame

get_string_lst() → List[str]

Get list of strings from GenericParameters to write to input file

Returns:

List of strings representing the GenericParameters object

Return type:

List[str]

classmethod instantiate(obj_dict: dict, version: str = None) → Self

Create a blank instance of this class.

This can be used when some values are already necessary for the objects __init__.

Parameters:

• obj_dict (dict) – data previously returned from to_dict()

• version (str) – version tag written together with the data

Returns:

a blank instance of the object that is sufficiently initialized to call _from_dict() on it

Return type:

object

keys() → List[str]

Return keys of GenericParameters object

load_default(file_content=None)

Load defaults resets the dataset in the background to be empty

load_string(input_str: str) → None

Load a multi line string to overwrite the current parameter settings

Parameters:

input_str (str) – multi line string

measure_mean_value(key, every=1, repeat=None, name=None, atom=False)

Parameters:

• key (str) – property to take an average value of (e.g. ‘energy_pot’ v.i.)

• every (int) – number of steps there should be between two measurements

• repeat (int) – number of measurements for each output (default: n_print/every)

• name (str) – name to give in the output string (ignored if a pyiron predefined tag is used)

Comments:

Currently available keys: ‘energy_pot’, ‘energy_tot’, ‘temperature’, ‘volume’,

‘pressures’, ‘positions’, ‘forces, ‘velocities’

Future keys: ‘cells’

modify(separator: str | None = None, append_if_not_present: bool = False, **modify_dict: str | bool) → None

Modify values for existing parameters. The command is called as modify(param1=val1, param2=val2, …)

Parameters:

• separator (str) – needed if the parameter name contains special characters such as par: use then as input: modify(separator=”:”, par=val) - optional

• append_if_not_present (bool) – do not raise an exception but append the parameter in practice use set(par=val) - default=False

• **modify_dict (dict) – dictionary of parameter names and values

property multi_word_separator: str | None

Get the multi word separator to have multi word keys

Returns:

multi word separator

Return type:

str

pressure_to_lammps(pressure, rotation_matrix)

Convert a singular value, list of values, or combination of values to the appropriate six elements for Lammps pxx, pyy, pzz, pxy, pxz, and pyz pressure tensor representation.

Lammps handles complex cells in a particular way, namely by using an upper triangular cell. This means we may need to convert our pressure tensor to a new coordinate frame. We also handle that transformation here.

In case of a single pressure value, it is again returned as a single pressure value, to be used with the “iso” option (i.e., coupled deformation in x, y, and z).

Finally, we also ensure that the units are converted from pyiron’s GPa to whatever Lammps needs.

Parameters:

• pressure (float/list/tuple/numpy.ndarray) – The pressure(s) to convert.

• rotation_matrix (numpy.ndarray) – The 3x3 matrix rotating from the pyiron to Lammps coordinate frame.

Returns:

pxx, pyy, pzz, pxy, pxz, and pyz to be passed to Lammps.

or

(float): a single, isotropic pressure to be used with the “iso” option

Return type:

(list)

read_input(file_name: str, ignore_trigger: str | None = None) → None

Read input file and store the data in GenericParameters - this overwrites the current parameter settings

Parameters:

• file_name (str) – absolute path to the input file

• ignore_trigger (str) – trigger for lines to be ignored

remove_keys(key_list: List[str]) → None

Remove a list of keys from the GenericParameters

Parameters:

key_list (list) – list of keys to be removed

property replace_char_dict: Dict[str, str] | None

Get the dictionary to replace certain character combinations

Returns:

character replace dictionary

Return type:

dict

property separator_char: str | None

Get the separator that characterizes the split between key and value

Returns:

separator character

Return type:

str

set(separator: str | None = None, **set_dict: str | bool) → None

Set the value of multiple parameters or create new parameter key, if they do not exist already.

Parameters:

• separator (float/int/str) – separator string - optional

• **set_dict (dict) – dictionary containing the parameter keys and their corresponding values to be set

set_dict(dictionary: Dict[str, str | bool]) → None

Set a dictionary of key value pairs

Parameters:

dictionary (dict) – dictionary of key value pairs

set_initial_velocity(temperature, seed=None, gaussian=False, append_value=False, zero_lin_momentum=True, zero_rot_momentum=True, job_name='')

Create initial velocities via velocity all create. More information can be found on LAMMPS website: https://lammps.sandia.gov/doc/velocity.html

Parameters:

• temperature – (int or float)

• seed – (int) Seed for the initial random number generator

• gaussian – (True/False) Create velocity according to the Gaussian distribution (otherwise uniform)

• append_value – (True/False) Add the velocity values to the current velocities (probably not functional now)

• zero_lin_momentum – (True/False) Cancel the total linear momentum

• zero_rot_momentum – (True/False) Cancel the total angular momentum

• job_name – (str) job name to generate seed

set_value(line: int, val: str | bytes) → None

Set the value of a parameter in a specific line

Parameters:

• line (float/int/str) – line number - starting with 0

• val (str/bytes) – value to be set

property table_name: str | None

Get the name of the input table inside the HDF5 file

Returns:

table name

Return type:

str

to_dict() → dict

Reduce the object to a dictionary.

Returns:

serialized state of this object

Return type:

dict

to_hdf(hdf, group_name: str | None = None) → None

Store the GenericParameters in an HDF5 file

Parameters:

• hdf (ProjectHDFio) – HDF5 group object

• group_name (str) – HDF5 subgroup name - optional

property val_only: bool | None

Get the boolean option to switch from a key value list to an value only input file

Returns:

[True/False]

Return type:

bool

write_file(file_name: str, cwd: str | None = None) → None

Write GenericParameters to input file

Parameters:

• file_name (str) – name of the file, either absolute (then cwd must be None) or relative

• cwd (str) – path name (default: None)