pylammpsmpi package

Subpackages

• pylammpsmpi.mpi package
  • Submodules
    • pylammpsmpi.mpi.lmpmpi module
      • command()
      • commands_list()
      • commands_string()
      • create_atoms()
      • extract_atom()
      • extract_box()
      • extract_compute()
      • extract_fix()
      • extract_global()
      • extract_setting()
      • extract_variable()
      • find_compute_neighlist()
      • find_fix_neighlist()
      • find_pair_neighlist()
      • gather_atoms()
      • gather_atoms_concat()
      • gather_atoms_subset()
      • get_file()
      • get_natoms()
      • get_neighlist()
      • get_neighlist_element_neighbors()
      • get_neighlist_size()
      • get_thermo()
      • get_version()
      • has_exceptions()
      • has_ffmpeg_support()
      • has_gzip_support()
      • has_jpeg_support()
      • has_png_support()
      • installed_packages()
      • reset_box()
      • scatter_atoms()
      • scatter_atoms_subset()
      • select_cmd()
      • set_fix_external_callback()
      • set_variable()
  • Module contents
• pylammpsmpi.wrapper package
  • Submodules
    • pylammpsmpi.wrapper.ase module
      • LammpsASELibrary
      • cell_is_skewed()
      • get_fixed_atom_boolean_vector()
      • get_lammps_indicies_from_ase_indices()
      • get_lammps_indicies_from_ase_structure()
      • get_species_indices_dict()
      • get_species_symbols()
      • get_structure_indices()
      • set_selective_dynamics()
    • pylammpsmpi.wrapper.base module
      • LammpsBase
      • get_result()
    • pylammpsmpi.wrapper.concurrent module
      • LammpsConcurrent
      • call_function_lmp()
      • init_function()
      • shutdown_lmp()
      • start_lmp()
    • pylammpsmpi.wrapper.extended module
      • LammpsLibrary
  • Module contents

Module contents

class pylammpsmpi.LammpsASELibrary(working_directory: str | None = None, hostname_localhost: bool | None = None, cores: int = 1, comm: object | None = None, logger: object | None = None, log_file: str | None = None, library: Any = None, disable_log_file: bool = True, executor: BaseExecutor | None = None)

Bases: object

A class that provides an interface to interact with LAMMPS using ASE.

Parameters:

• working_directory (str, optional) – The working directory. Defaults to None.

• cores (int, optional) – The number of cores to use. Defaults to 1.

• comm (object, optional) – The MPI communicator. Defaults to None.

• logger (object, optional) – The logger object. Defaults to None.

• log_file (str, optional) – The log file path. Defaults to None.

• library (object, optional) – The LAMMPS library object. Defaults to None.

• disable_log_file (bool, optional) – Whether to disable the log file. Defaults to True.

• executor – Executor to use for parallel execution (default: None)

close()

interactive_cells_getter() → ndarray

Get the cell vectors from the interactive library.

Returns:

The cell vectors.

Return type:

np.ndarray

interactive_cells_setter(cell: ndarray) → None

Set the cell vectors in the interactive library.

Parameters:

cell (np.ndarray) – The cell vectors.

interactive_energy_pot_getter() → float

Get the potential energy from the interactive library.

Returns:

The potential energy.

Return type:

float

interactive_energy_tot_getter() → float

Get the total energy from the interactive library.

Returns:

The total energy.

Return type:

float

interactive_forces_getter() → ndarray

Get the forces on atoms from the interactive library.

Returns:

The forces on atoms.

Return type:

np.ndarray

interactive_indices_getter() → ndarray

Get the indices of atoms from the interactive library.

Returns:

The indices of atoms.

Return type:

np.ndarray

interactive_indices_setter(indices, el_eam_lst)

interactive_lib_command(command: str) → None

Execute a LAMMPS command using the interactive library.

Parameters:

command (str) – The LAMMPS command to execute.

interactive_positions_getter() → ndarray

Get the positions of atoms from the interactive library.

Returns:

The positions of atoms.

Return type:

np.ndarray

interactive_positions_setter(positions: list[list[float]]) → None

Set the positions of atoms in the interactive library.

Parameters:

positions (List[List[float]]) – The positions of atoms.

interactive_pressures_getter()

interactive_steps_getter() → int

Get the number of steps from the interactive library.

Returns:

The number of steps.

Return type:

int

interactive_stress_getter(enable_stress_computation=True)

This gives back an Nx3x3 array of stress/atom defined in http://lammps.sandia.gov/doc/compute_stress_atom.html Keep in mind that it is stress*volume in eV. Further discussion can be found on the website above.

Returns:

Nx3x3 np array of stress/atom

Return type:

numpy.array

interactive_structure_setter(structure: Atoms, units: str, dimension: int, boundary: str, atom_style: str, el_eam_lst: list[str], calc_md: bool = True) → None

Set the structure in the interactive library.

Parameters:

• structure (ase.Atoms) – The structure.

• units (str) – The units of the simulation.

• dimension (int) – The dimension of the simulation.

• boundary (str) – The boundary conditions.

• atom_style (str) – The atom style.

• el_eam_lst (List[str]) – The list of element symbols.

• calc_md (bool, optional) – Whether to calculate molecular dynamics. Defaults to True.

interactive_temperatures_getter() → float

Get the temperature from the interactive library.

Returns:

The temperature.

Return type:

float

interactive_velocities_getter()

interactive_volume_getter() → float

Get the volume of the system from the interactive library.

Returns:

The volume of the system.

Return type:

float

set_fix_external_callback(fix_id, callback, caller=None)

class pylammpsmpi.LammpsBase(cores: int = 8, oversubscribe: bool = False, working_directory: str = '.', hostname_localhost: bool | None = None, cmdargs: list[Any] | None = None, executor: BaseExecutor | None = None)

Bases: LammpsConcurrent

command(cmd)

Send a command to the lammps object

Parameters:

cmd (string, list of strings) – command to be sent

Return type:

None

create_atoms(n: int, id: list[int], type: list[int], x: list[float], v: list[float] | None = None, image: list[int] | None = None, shrinkexceed: bool = False) → None

Create atoms on all procs

Parameters: n : int

number of atoms

idlist of ints, optional

ids of N atoms that need to be created if not specified, ids from 1 to N are assigned

typelist of atom types, optional

type of N atoms, if not specified, all atoms are assigned as type 1

x: list of positions

list of the type [posx, posy, posz] for N atoms

v: list of velocities

list of the type [vx, vy, vz] for N atoms

image: list of ints, optional

if not specified a list of 0s will be used.

shrinkexceed: bool, optional

default False

Returns: None

extract_atom(name: str) → list[int] | list[float]

Extract a property of the atoms

Parameters: name : str

the property of atom to be extracted

Returns: val : list of int or float

If the requested name has multiple dimensions, output will be a multi-dimensional list.

extract_box() → list[float | list[float] | list[int]]

Get the simulation box

Returns: box : list

list containing the simulation box information [boxlo, boxhi, xy, yz, xz, periodicity, box_change] where boxlo and boxhi are lower and upper bounds of the box in three dimensions, xy, yz, xz are the box tilts, periodicity is an array which shows if the box is periodic in three dimensions, and box_change is a list of booleans indicating if the box dimensions have changed

extract_compute(id, style, type, length=0, width=0)

Extract compute value from the lammps library

Parameters:

• id (string) – id of the compute

• style ({0, 1}) – 0 - global data 1 - per atom data

• type ({0, 1, 2}) – 0 - scalar 1 - vector 2 - array

• length (int, optional. Default 0) – if style is 0 and type is 1 or 2, then length is the length of vector.

• width (int, optional. Default 0) – if type is 2, then width is the number of elements in each element along length.

Returns:

data computed by the fix depending on the chosen inputs

Return type:

val

extract_fix(*args) → int | float | list[int | float]

Extract a fix value

Parameters: *args: tuple

arguments to specify the fix value to extract

Returns: value: int, float, or list of int or float

extracted fix value corresponding to the requested dimensions

extract_global(name: str) → int | float | str

Extract value of global simulation parameters

Parameters: name : str

name of the global parameter to extract

Returns: value: int, float, or str

extracted value of the global parameter

extract_setting(*args) → int | float | str

Extract a setting value

Parameters: *args: tuple

arguments to specify the setting to extract

Returns: value: int, float, or str

extracted setting value

extract_variable(*args) → int | float | list[int | float]

Extract the value of a variable

Parameters: *args: tuple

arguments to specify the variable to extract

Returns: data: int, float, or list of int or float

value of the variable depending on the requested dimension

file(inputfile: str) → None

Read script from an input file

Parameters: inputfile: str

name of inputfile

Returns: None

find_compute_neighlist(*args)

Find neighbor list index of compute neighbor list :param computeid: name of compute :type computeid: string :param request: index of neighbor list request, in case there are more than one, defaults to 0 :type request: int, optional :return: neighbor list index if found, otherwise -1 :rtype: int

find_fix_neighlist(*args)

Find neighbor list index of fix neighbor list :param fixid: name of fix :type fixid: string :param request: index of neighbor list request, in case there are more than one, defaults to 0 :type request: int, optional :return: neighbor list index if found, otherwise -1 :rtype: int

find_pair_neighlist(*args) → int

Find neighbor list index of pair style neighbor list Try finding pair instance that matches style. If exact is set, the pair must match style exactly. If exact is 0, style must only be contained. If pair is of style pair/hybrid, style is instead matched the nsub-th hybrid sub-style. Once the pair instance has been identified, multiple neighbor list requests may be found. Every neighbor list is uniquely identified by its request index. Thus, providing this request index ensures that the correct neighbor list index is returned. :param style: name of pair style that should be searched for :type style: string :param exact: controls whether style should match exactly or only must be contained in pair style name, defaults to True :type exact: bool, optional :param nsub: match nsub-th hybrid sub-style, defaults to 0 :type nsub: int, optional :param request: index of neighbor list request, in case there are more than one, defaults to 0 :type request: int, optional :return: neighbor list index if found, otherwise -1 :rtype: int

gather_atoms(*args, concat=False, ids=None)

Gather atom properties

Parameters:

• name ({'x', 'mass', 'id', 'type', 'mask', 'v', 'f',) – ‘molecule’, ‘q’, ‘mu’, ‘omega’, ‘angmom’, ‘torque’, ‘radius’} the property of atom to be extracted

• concat (bool, optional. Default False) – If True, gather information from all processors, but not sorted according to Atom ids

• ids (list, optional. Default None) – If a list of ids are provided, the required information for only those atoms are returned

Returns:

val – If the requested name has multiple dimensions, output will be a multi-dimensional array.

Return type:

array of length n_atoms sorted by atom ids

Notes

This method gathers information from all processors.

See also

extract_atoms

generate_atoms(ids: list[int] | None = None, type: list[int] | None = None, x: list[float] | None = None, v: list[float] | None = None, image: list[int] | None = None, shrinkexceed: bool = False) → None

Create atoms on all procs

Parameters: ids : list of ints, optional

ids of N atoms that need to be created if not specified, ids from 1 to N are assigned

typelist of atom types, optional

type of N atoms, if not specified, all atoms are assigned as type 1

x: list of positions

list of the type [posx, posy, posz] for N atoms

v: list of velocities

list of the type [vx, vy, vz] for N atoms

image: list of ints, optional

if not specified a list of 0s will be used.

shrinkexceed: bool, optional

default False

Returns: None

get_natoms() → int

Get the number of atoms

Returns: natoms : int

number of atoms

get_neighlist(*args)

Returns an instance of NeighList which wraps access to the neighbor list with the given index :param idx: index of neighbor list :type idx: int :return: an instance of NeighList wrapping access to neighbor list data :rtype: NeighList

get_neighlist_element_neighbors(*args)

get_neighlist_size(*args)

Return the number of elements in neighbor list with the given index :param idx: neighbor list index :type idx: int :return: number of elements in neighbor list with index idx :rtype: int

get_thermo(*args)

Return current value of thermo keyword

Parameters:

name (string) – name of the thermo keyword

Returns:

value of the thermo keyword

Return type:

val

property has_exceptions: bool

Return whether the LAMMPS shared library was compiled with C++ exceptions handling enabled

property has_ffmpeg_support: bool

property has_gzip_support: bool

Return whether the Lammps shared library has gzip support.

Returns:

has_gzip_support – A future object representing whether the Lammps library has gzip support.

Return type:

Future

property has_jpeg_support: bool

Return whether the Lammps shared library has JPEG support.

Returns:

has_jpeg_support – A future object representing whether the Lammps library has JPEG support.

Return type:

Future

property has_png_support: bool

Return whether the Lammps shared library has PNG support.

Returns:

has_png_support – A future object representing whether the Lammps library has PNG support.

Return type:

Future

property installed_packages: list[str]

property natoms: int

Get the number of atoms

Returns: natoms : int

number of atoms

reset_box(*args) → None

Reset the simulation box

Parameters: *args: tuple

arguments to specify the new box dimensions

Returns: None

scatter_atoms(*args, ids=None)

Scatter atoms for the lammps library

Parameters:

*args

set_fix_external_callback(*args) → None

Follows the signature of LAMMPS’s set_fix_external_callback(fix_id, callback, caller=None). The caller argument is a list of inputs to the callback function, including class instances and, importantly, the LammpsLibrary instance itself. Since LAMMPS’s set_fix_external_callback allows passing to itself a self-reference, we want to keep this feature. Because the LAMMPS instance is unavailable at this stage, we insert a placeholder in its position, which will later be replaced with the actual LAMMPS instance.

set_variable(*args) → int

Set the value of a string style variable

Parameters: *args: tuple

arguments to specify the variable and its value

Returns: flag : int

0 if successful, -1 otherwise

property version: str

Get the version of lammps

Returns: version: str

version string of lammps

class pylammpsmpi.LammpsConcurrent(cores: int = 8, oversubscribe: bool = False, working_directory: str = '.', hostname_localhost: bool | None = None, cmdargs: list[Any] | None = None, executor: BaseExecutor | None = None)

Bases: object

close()

Close the current lammps object

Parameters:

None

Return type:

None

command(cmd)

Send a command to the lammps object

Parameters:

cmd (string, list of strings) – command to be sent

Return type:

None

create_atoms(n, id, type, x, v=None, image=None, shrinkexceed=False) → Future

Create atoms on all processors.

Parameters:

• n (int) – Number of atoms.

• id (list of ints, optional) – IDs of N atoms that need to be created.

• type (list of atom types, optional) – Type of N atoms.

• x (list of positions) – List of positions for N atoms.

• v (list of velocities, optional) – List of velocities for N atoms.

• image (list of ints, optional) – List of image flags for N atoms.

• shrinkexceed (bool, optional) – Whether to shrink the box if the atoms exceed the box boundaries.

Return type:

None

extract_atom(name: str) → Future

Extract a property of the atoms.

Parameters:

name (str) – The property of the atom to be extracted.

Returns:

val – A future object representing the extracted property of the atoms.

Return type:

Future

extract_box() → Future

Get the simulation box.

Returns:

box – A future object representing the simulation box.

Return type:

Future

extract_compute(id, style, type, length=0, width=0)

Extract compute value from the lammps library

Parameters:

• id (string) – id of the compute

• style ({0, 1}) – 0 - global data 1 - per atom data

• type ({0, 1, 2}) – 0 - scalar 1 - vector 2 - array

• length (int, optional. Default 0) – if style is 0 and type is 1 or 2, then length is the length of vector.

• width (int, optional. Default 0) – if type is 2, then width is the number of elements in each element along length.

Returns:

data computed by the fix depending on the chosen inputs

Return type:

val

extract_fix(*args) → Future

Extract a fix value.

Parameters:

args (tuple) – Variable number of arguments specifying the fix value to extract.

Returns:

value – A future object representing the extracted fix value.

Return type:

Future

extract_global(name: str) → Future

Extract value of global simulation parameters.

Parameters:

name (str) – Name of the global simulation parameter.

Returns:

value – A future object representing the value of the requested global parameter.

Return type:

Future

extract_setting(*args)

extract_variable(*args) → Future

Extract the value of a variable.

Parameters:

args (tuple) – Variable number of arguments specifying the variable to extract.

Returns:

data – A future object representing the value of the variable.

Return type:

Future

file(inputfile: str) → Future

Read script from an input file.

Parameters:

inputfile (str) – Name of the input file.

Return type:

None

find_compute_neighlist(*args)

Find neighbor list index of compute neighbor list :param computeid: name of compute :type computeid: string :param request: index of neighbor list request, in case there are more than one, defaults to 0 :type request: int, optional :return: neighbor list index if found, otherwise -1 :rtype: int

find_fix_neighlist(*args)

Find neighbor list index of fix neighbor list :param fixid: name of fix :type fixid: string :param request: index of neighbor list request, in case there are more than one, defaults to 0 :type request: int, optional :return: neighbor list index if found, otherwise -1 :rtype: int

find_pair_neighlist(*args)

Find neighbor list index of pair style neighbor list Try finding pair instance that matches style. If exact is set, the pair must match style exactly. If exact is 0, style must only be contained. If pair is of style pair/hybrid, style is instead matched the nsub-th hybrid sub-style. Once the pair instance has been identified, multiple neighbor list requests may be found. Every neighbor list is uniquely identified by its request index. Thus, providing this request index ensures that the correct neighbor list index is returned. :param style: name of pair style that should be searched for :type style: string :param exact: controls whether style should match exactly or only must be contained in pair style name, defaults to True :type exact: bool, optional :param nsub: match nsub-th hybrid sub-style, defaults to 0 :type nsub: int, optional :param request: index of neighbor list request, in case there are more than one, defaults to 0 :type request: int, optional :return: neighbor list index if found, otherwise -1 :rtype: int

gather_atoms(*args, concat=False, ids=None)

Gather atom properties

Parameters:

• name ({'x', 'mass', 'id', 'type', 'mask', 'v', 'f',) – ‘molecule’, ‘q’, ‘mu’, ‘omega’, ‘angmom’, ‘torque’, ‘radius’} the property of atom to be extracted

• concat (bool, optional. Default False) – If True, gather information from all processors, but not sorted according to Atom ids

• ids (list, optional. Default None) – If a list of ids are provided, the required information for only those atoms are returned

Returns:

val – If the requested name has multiple dimensions, output will be a multi-dimensional array.

Return type:

array of length n_atoms sorted by atom ids

Notes

This method gathers information from all processors.

See also

extract_atoms

generate_atoms(ids=None, type=None, x=None, v=None, image=None, shrinkexceed=False) → Future

Create atoms on all processors.

Parameters:

• ids (list of ints, optional) – IDs of N atoms that need to be created.

• type (list of atom types, optional) – Type of N atoms.

• x (list of positions) – List of positions for N atoms.

• v (list of velocities, optional) – List of velocities for N atoms.

• image (list of ints, optional) – List of image flags for N atoms.

• shrinkexceed (bool, optional) – Whether to shrink the box if the atoms exceed the box boundaries.

Return type:

None

get_natoms() → Future

Get the number of atoms.

Returns:

natoms – A future object representing the number of atoms.

Return type:

Future

get_neighlist(*args)

Returns an instance of NeighList which wraps access to the neighbor list with the given index :param idx: index of neighbor list :type idx: int :return: an instance of NeighList wrapping access to neighbor list data :rtype: NeighList

get_neighlist_element_neighbors(*args)

get_neighlist_size(*args)

Return the number of elements in neighbor list with the given index :param idx: neighbor list index :type idx: int :return: number of elements in neighbor list with index idx :rtype: int

get_thermo(*args)

Return current value of thermo keyword

Parameters:

name (string) – name of the thermo keyword

Returns:

value of the thermo keyword

Return type:

val

property has_exceptions: Future

Return whether the Lammps shared library was compiled with C++ exceptions handling enabled.

Returns:

has_exceptions – A future object representing whether the Lammps library has exceptions handling enabled.

Return type:

Future

property has_ffmpeg_support

property has_gzip_support: Future

Return whether the Lammps shared library has gzip support.

Returns:

has_gzip_support – A future object representing whether the Lammps library has gzip support.

Return type:

Future

property has_jpeg_support: Future

Return whether the Lammps shared library has JPEG support.

Returns:

has_jpeg_support – A future object representing whether the Lammps library has JPEG support.

Return type:

Future

property has_png_support: Future

Return whether the Lammps shared library has PNG support.

Returns:

has_png_support – A future object representing whether the Lammps library has PNG support.

Return type:

Future

property installed_packages

property natoms: Future

Get the number of atoms.

Returns:

natoms – A future object representing the number of atoms.

Return type:

Future

reset_box(*args) → Future

Reset the simulation box.

Parameters:

args (tuple) – Variable number of arguments specifying the box parameters.

Return type:

None

scatter_atoms(*args, ids=None)

Scatter atoms for the lammps library

Parameters:

*args

set_fix_external_callback(*args)

Follows the signature of LAMMPS’s set_fix_external_callback(fix_id, callback, caller=None). The caller argument is a list of inputs to the callback function, including class instances and, importantly, the LammpsLibrary instance itself. Since LAMMPS’s set_fix_external_callback allows passing to itself a self-reference, we want to keep this feature. Because the LAMMPS instance is unavailable at this stage, we insert a placeholder in its position, which will later be replaced with the actual LAMMPS instance.

set_variable(*args) → Future

Set the value of a string style variable.

Parameters:

args (tuple) – Variable number of arguments specifying the variable name and value.

Returns:

flag – A future object representing the success flag (0 if successful, -1 otherwise).

Return type:

Future

property version: Future

Get the version of Lammps.

Returns:

version – A future object representing the version string of Lammps.

Return type:

Future

class pylammpsmpi.LammpsLibrary(cores: int = 1, oversubscribe: bool = False, working_directory: str = '.', hostname_localhost: bool | None = None, client: Any = None, cmdargs: list[str] | None = None, executor: BaseExecutor | None = None)

Bases: object

Top level class which manages the lammps library provided by LammpsBase

Parameters:

• cores (int) – Number of CPU cores to use for Lammps simulation (default: 1)

• oversubscribe (bool) – Whether to oversubscribe CPU cores (default: False)

• working_directory (str) – Path to the working directory (default: “.”)

• client – Client object for distributed computing (default: None)

• cmdargs – Additional command line arguments for Lammps (default: None)

• executor – Executor to use for parallel execution (default: None)

close() → None

Close the Lammps simulation

pylammpsmpi.init_function()