ppap4lmp documentation

Introduction

This project is named ppap4lmp, which stands for PostProcess and Analysis Program for LAMMPS.

GitHub repository is here.

Installation

Via Conda.

# shell
conda install -c irista56 ppap4lmp

For more details, please see GitHub repository.

Features

• Implemented by C++, Used from Python.
• Data stored in JSON structure.
• Extensible without editing existing codes.

Schematic Sequence Diagram

sequenceDiagram participant user as User (Python) participant ele as Element participant upd as Updater's subclass participant pro as Processor's subclass participant inv as Invoker's subclass user ->> upd : create Starter (Uptater for initialization) upd -->> user : object user ->> ele : create with the Starter object note over ele,upd : UpdatePair (pair of Element and Updater) is stored in the Element object. ele -->> user : object loop additional properties user ->> upd : create Adder (Uptater for adding new properties) upd -->> user : object user ->> ele : append the Adder object note over ele,upd : UpdatePair (pair of Element and Updater) is stored the Element object. end user ->> pro : create with Generator objects note over pro : Store the Generator objects pro -->> user : object user ->> inv : execute with Processor objects loop over Generator objects inv ->> pro : run pro ->> ele : execute updating process note over ele,upd : Chain of UpdatePair objects is executed one by one (the Element objects updates their data using the paired Updater objects). ele -->> pro : updated data can be accessed note over pro : Run analysis process for each Generator object using the data. end pro -->> user : get results

Acknowledgement

This project would not be possible without the following great open-source projects.

• pybind11
• nlohmann/json
• Eigen

Class accessible from Python

Element

Element inherits Generator class and contains data element (or entity) as a Json object.

Constructor of Element class is hidden from Python. A Python-side function create provides functionality to create an Element object taking a Starter's subclass object as its parameter.

Python-side functions

Name	C++	Description	Parameters	Return
create	Lambda function defined in pybind::py_element	Factory function for Element class.	upd An object of Starter's subclass, which sets some properties to empty Element::data of the created Element object. Note that upd can be an Element or Json object: StaCopy and StaCustom are implicitly used for Element and Json, respectively.	An object of Element class.

Python-side methods of Element

Name	C++	Description	Parameters	Return
append_updater	Element::append_updater	Append an Updater object to this Element object: the only way to extend an updating process associated with this object.	upd An Adder or Filter object to be paired with this Element object as an UpdatePair object, which is appended to a sequence of UpdatePair objects describing the updating process of this object.	This Element object.
get_data	Element::get_data_py	Get a reference to #data of this object.	None.	A Json object (complex of dictionary and list).
get_keys	Element::get_keys_py	Get keys of the data of this object.	None.	Set of strings.
get_1d_int	Element::get_1d_int_py	Get integer values stored in Element::data of this object as a one-dimensional Numpy-Array.	key A string key specifying a property.	One-dimensional Numpy-Array of which elements are integers.
get_1d_float	Element::get_1d_float_py	Get float values stored in Element::data of this object as a one-dimensional Numpy-Array.	key A string key specifying a property.	One-dimensional Numpy-Array of which elements are floats.
get_2d_int	Element::get_2d_int_py	Get integer values stored in Element::data of this object as a two-dimensional Numpy-Array.	*args An ordered list of keys specifying properties (Python's variable number arguments).	Two-dimensional Numpy-Array of which elements are integers.
get_2d_float	Element::get_2d_float_py	Get float values stored in Element::data of this object as a two-dimensional Numpy-Array.	*args An ordered list of keys specifying properties (Python's variable number arguments).	Tow-dimensional Numpy-Array of which elements are floats.

Starter

Starter sets some properties to an empty Element object.

StaBeads

StaBeads sets properties for beads using mapping (coarse-graining) scheme for each molecule.

Python-side constructor of StaBeads

C++	Description		Parameters
StaBeads::StaBeads	Constructor of StaBeads class for molecules all of whose type property are 1, or molecules all of which do not have the property. Property to be added id : integer mol : integer atom-ids : array of integers type : integer (optional) atom-weights : array of floats (optional)		el_mols A molecular Element object consisting of beads for which an Element object is created with this constructed object. Required property atom-ids : array of integers scheme List of Json (complex of dictionary and list) objects. Each Json object corresponds to each bead in a molecule, and contains three items: indices-in-mol is an array of zero-based index of atoms in the molecule, type is type of the bead, and weights is an array of floats for weighting factors of atoms.
StaBeads::StaBeads	Constructor of StaBeads class for multiple molecular types. Property to be added id : integer mol : integer atom-ids : array of integers type : integer (optional) atom-weights : array of floats (optional)		el_mols A molecular Element object consisting of beads for which an Element object is created with this constructed object. Required property atom-ids : array of integers schemes Dictionary from molecular type to list of Json (complex of dictionary and list) objects. Each Json object corresponds to each bead in a molecule of that type, and contains three items: indices-in-mol is an array of zero-based index of atoms in the molecule, type is type of the bead, and weights is an array of floats for weighting factors of atoms.

Usage example of the constructor for beads consisting of five atoms in a molecule; the molecule consists of four beads, and all the beads are type 1.

# python

atoms = create(StaDumpAtoms("path/to/dump", 0))
molecules = create(StaMolecules(atoms))

my_beads = StaBeads(
  molecules,
  [
    {"type": 1, "indices-in-mol": [0, 1, 2, 3, 4]},
    {"type": 1, "indices-in-mol": [5, 6, 7, 8, 9]},
    {"type": 1, "indices-in-mol": [10, 11, 12, 13, 14]},
    {"type": 1, "indices-in-mol": [15, 16, 17, 18, 19]}
  ]
)

beads = create(my_beads)

Usage example of the constructor; some beads belong to molecules whose type is 1 and the others belong to molecules whose type is 2. The number of molecules is 100; molecules with odd id are type 1 and the others are type 2. All the beads for molecular type 1 consist of five atoms and their types are 1. All the beads for molecular type 2 consist of four atoms and their types are 2.

# python

atoms = create(StaDumpAtoms("path/to/dump", 0))
molecules = create(StaMolecules(atoms))

map_from_id_to_type = {
  i + 1 : i%2 + 1 for i in range(100)
}

molecules.append_updater(
  AddMap("id", "type", map_from_id_to_type))

my_beads = StaBeads(
  molecules,
  {
    1: [
      {"type": 1, "indices-in-mol": [0, 1, 2, 3, 4]},
      {"type": 1, "indices-in-mol": [5, 6, 7, 8, 9]},
      {"type": 1, "indices-in-mol": [10, 11, 12, 13, 14]},
      {"type": 1, "indices-in-mol": [15, 16, 17, 18, 19]}
    ],
    2: [
      {"type": 2, "indices-in-mol": [0, 1, 2, 3]},
      {"type": 2, "indices-in-mol": [4, 5, 6, 7]},
      {"type": 2, "indices-in-mol": [8, 9, 10, 11]},
      {"type": 2, "indices-in-mol": [12, 13, 14, 15]}
    ]
  }
)

beads = create(my_beads)

StaCopy

StaCopy copies Element::data of an existing Element object and sets it to a new Element object.

Python-side constructor of StaCopy

C++	Description		Parameters
StaCopy::StaCopy	Constructor of StaCopy class.		elem An Element object to be copied.

StaCustom

StaCustom sets an user-defined Json object to a new Element object as its Element::data.

Python-side constructor of StaCustom

C++	Description		Parameters
StaCustom::StaCustom	Constructor of StaCustom class.		json_ A Json (complex of dictionary and list) object to be set as Element::data.

StaDumpAtoms

StaDumpAtoms reads a Lammps' dump file and sets properties for atoms.

Python-side constructor of StaDumpAtoms

C++	Description		Parameters
StaDumpAtoms::StaDump	Constructor of StaDumpAtoms class. Property to be added Keys to be set are names of dumped Lammps' atom property. In a Lammps' dump file, the names are printed in a line beginning with ITEM: ATOMS.		filepath_ A path to a Lammps' dump file to be read. timestep_ A timestep of simulation to be read.

Usage example of the constructor for a sequence of Lammps' dump files.

# python

atoms_traj = [
  create(StaDumpAtoms("path/to/dump", i))
  for i in range(0, 1000000, 1000)]

StaDumpBox

StaDumpBox reads a Lammps' dump file and sets properties for simulation box.

Python-side constructor of StaDumpBox

C++	Description		Parameters
StaDumpBox::StaDump	Constructor of StaDumpBox class. Property to be added pbc_x : boolean pbc_y : boolean pbc_z : boolean lo_x : float lo_y : float lo_z : float hi_x : float hi_y : float hi_z : float		filepath_ A path to a Lammps' dump file to be read. timestep_ A timestep of simulation to be read.

Usage example of the constructor for a sequence of Lammps' dump files.

# python

atoms_traj = [
  create(StaDumpBox("path/to/dump", i))
  for i in range(0, 1000000, 1000)]

StaMolecules

StaMolecules sets properties for molecules using atoms forming the molecules.

Python-side constructor of StaMolecules

C++	Description		Parameters
StaMolecules::StaMolecules	Constructor of StaMolecules class. Property to be added id : integer atom-ids : array of integers		el_atoms An Element object for atoms forming molecules to be created. Required property id : integer mol : integer

Usage example of the constructor for a trajectory of typed molecules. The number of molecules is 100; molecules with odd id are type 1 and the others are type 2.

# python

atoms_traj = [
  create(StaDumpAtoms("path/to/dump", i))
  for i in range(0, 1000000, 1000))
]

map_from_id_to_type = {
  i + 1 : i%2 + 1 for i in range(100)
}

molecules_traj = [
  create(StaMolecules(atoms))
    .append_updater(AddMap("id", "type", map_from_id_to_type))
  for atoms in atoms_traj
]

Adder

Adder adds new properties to a non-empty Element object.

AddBondAngle

AddBondAngle adds angle property to bond-angles, each of them is defined by three consecutive atoms.

Python-side constructor of AddBondAngle

C++	Description		Parameters
AddBondAngle::AddBondAngle	Constructor of AddBondAngle class. Property to be added angle : float Required property atom1-id : integer atom2-id : integer atom3-id : integer		elem An Element object containing atoms data. Required property id : integer xu : float yu : float zu : float

Usage example of the constructor to add angle property to an Element object for bond-angles.

# python

atoms = create(StaDumpAtoms("path/to/dump", 0))
angles = create(StaCustom([...]))

angles.append_updater(AddBondAngle(atoms))

AddBondLength

AddBondLength adds length property to bonds, each of them connects two atoms.

Python-side constructor of AddBondLength

C++	Description		Parameters
AddBondLength::AddBondLength	Constructor of AddBondLength class. Property to be added length : float Required property atom1-id : integer atom2-id : integer		elem An Element object containing atoms data. Required property id : integer xu : float yu : float zu : float

Usage example of the constructor to add length property to an Element object for bonds.

# python

atoms = create(StaDumpAtoms("path/to/dump", 0))
bonds = create(StaCustom([...]))

bonds.append_updater(AddBondLength(atoms))

AddChildIDs

AddChildIDs adds id property of a child Element object to a parent Element object.

Python-side constructor of AddChildIDs

C++	Description		Parameters
AddChildIDs::AddChildIDs	Constructor of AddChildIDs class. Property to be added [child_name]-ids : array of integers Required property id : integer		elem A child Element object. Required property id : integer [key_for_parent_id] : integer child_name_ A string for naming the child object. key_for_parent_id_ A string for key in the child object corresponding to id of parent object.

Usage example of the constructor to add bead-ids property to an Element object for molecules.

# python

atoms = create(StaDumpAtoms("path/to/dump", 0))
molecules = create(StaMolecules(atoms))
beads = create(StaBeads(molecules, mapping))

molecules.append_updater(AddChildIDs(beads, "bead", "mol"))

AddChildPositions

AddChildPositions adds relative positions of a child Element object to a parent Element object.

Python-side constructor of AddChildPositions

C++	Description		Parameters
AddChildPositions::AddChildPositions	Constructor of AddChildPositions class. Property to be added [child_name]-xs : array of floats [child_name]-ys : array of floats [child_name]-zs : array of floats Required property [child_name]-ids : array of integers xu : float yu : float zu : float		elem A child Element object. Required property id : integer xu : float yu : float zu : float child_name_ A string for naming the child object.

AddCoMPosition

AddCoMPosition adds center of mass to an Element object as its unwrapped position.

Python-side constructor of AddCoMPosition

C++	Description		Parameters
AddCoMPosition::AddCoMPosition	Constructor of AddCoMPosition class. Property to be added mass : float xu : float yu : float zu : float Required property atom-ids : array of integers atom-weights : array of floats (optional)		elem A child Element object. Required property id : integer mass : float xu : float yu : float zu : float

Usage example of the constructor to add xu, yu and zu property to an Element object for molecules.

# python

atoms = create(StaDumpAtoms("path/to/dump", 0))
molecules = create(StaMolecules(atoms))

molecules.append_updater(AddCoMPosition(atoms))

AddDihedralAngle

AddDihedralAngle adds dihedral-angle property to dehedrals, each of them is defined by four consecutive atoms.

Python-side constructor of AddDihedralAngle

C++	Description		Parameters
AddDihedralAngle::AddDihedralAngle	Constructor of AddDihedralAngle class. Property to be added dihedral-angle : float Required property atom1-id : integer atom2-id : integer atom3-id : integer atom4-id : integer		elem An Element object containing atoms data. Required property id : integer xu : float yu : float zu : float

Usage example of the constructor to add dihedral-angle property to an Element object for dihedrals.

# python

atoms = create(StaDumpAtoms("path/to/dump", 0))
dihedrals = create(StaCustom([...]))

dihedrals.append_updater(AddDihedralAngle(atoms))

AddGyrationRadius

AddGyrationRadius adds gyration radius to an Element object.

Python-side constructor of AddGyrationRadius

C++	Description		Parameters
AddGyrationRadius::Updater	Constructor of AddGyrationRadius class. Property to be added Rg^2 : float Rg^2(y+z) : float Rg^2(z+x) : float Rg^2(x+y) : float Rg^2(x) : float Rg^2(y) : float Rg^2(z) : float Rg : float (optional) Rg(y+z) : float (optional) Rg(z+x) : float (optional) Rg(x+y) : float (optional) Rg(x) : float (optional) Rg(y) : float (optional) Rg(z) : float (optional) Required property mass : float I_xx : float I_yy : float I_zz : float		None.

Usage example of the constructor to add square of gyration radius to an Element object for molecules.

# python

atoms = create(StaDumpAtoms("path/to/dump", 0))
molecules = create(StaMolecules(atoms))

molecules.append_updater(AddCoMPosition(atoms))
molecules.append_updater(AddInertiaMoment(atoms))
molecules.append_updater(AddGyrationRadius())

Python-side methods of AddGyrationRadius

Name	C++	Description	Parameters	Return
with_sqrted	AddGyrationRadius::with_sqrted	Enable to compute gyration radius (by default, only square of gyration radius is computed).	add_sqrted_ A boolean, whether gyration radius is computed or not (default is true).	This AddGyrationRadius object.

AddInertiaMoment

AddInertiaMoment adds inertia moment to an Element object.

Python-side constructor of AddInertiaMoment

C++	Description		Parameters
AddInertiaMoment::AddInertiaMoment	Constructor of AddInertiaMoment class. Property to be added I_xx : float I_yy : float I_zz : float I_xy : float I_xz : float I_yz : float Required property atom-ids : array of integers xu : float yu : float zu : float atom-weights : array of floats (optional)		elem A child Element object. Required property id : int mass : float xu : float yu : float zu : float

Usage example of the constructor to add elements of inertia moment to an Element object for molecules.

# python

atoms = create(StaDumpAtoms("path/to/dump", 0))
molecules = create(StaMolecules(atoms))

molecules.append_updater(AddCoMPosition(atoms))
molecules.append_updater(AddInertiaMoment(atoms))

AddMap

AddMap adds a new property by mapping from an existing property.

Python-side constructor of AddMap

C++	Description		Parameters
AddMap::AddMap	Constructor of AddMap class. Property to be added [key_new] : any type Required property [key_ref] : any type (but, in most cases, integer or strings)		key_ref_ A string key for a reference property: an existing property to be used as domain of mapping. key_new_ A string key for a new property to be added. Values for the new property are determined by mapping. mapping_ Dictionary defining a mapping from values for the reference property to values for the new property. Keys of the dictionary corresponds to domain of the mapping, and values of the dictionary corresponds to codomain of the mapping. Note that the keys must cover all values of the reference property in an Element object where the constructed object is appended to.

Usage example of the constructor for mapping from atomic-number to mass.

# python

my_mapping = AddMap(
  "atomic-number", "mass",
  {
    6: 12.011,
    8: 15.999,
    9: 18.998
  }
)

Python-side methods of AddMap

Name	C++	Description	Parameters	Return
overwrite	AddMap::overwrite	Allow overwriting an existing property by a new property with the same name.	do_overwrite_ A boolean, whether an existing property can be overwritten by a new property (default is true).	This AddMap object.

AddMolecularOrientation

AddMolecularOrientation adds molecular orientation (order parameter) to an Element object.

Python-side constructor of AddMolecularOrientation

C++	Description		Parameters
AddMolecularOrientation::Updater	Constructor of AddMolecularOrientation class. Property to be added I_values : array of floats (eigenvalues of inertia moment) I_vectors : array of arrays of floats (eigenvectors of inertia moment) S_x : float S_y : float S_z : float Required property I_xx : float I_yy : float I_zz : float I_xy : float I_xz : float I_yz : float		None.

Usage example of the constructor to add molecular orientation to an Element object for molecules.

# python

atoms = create(StaDumpAtoms("path/to/dump", 0))
molecules = create(StaMolecules(atoms))

molecules.append_updater(AddCoMPosition(atoms))
molecules.append_updater(AddInertiaMoment(atoms))
molecules.append_updater(AddMolecularOrientation())

AddRename

AddRename renames an existing property.

Python-side constructor of AddRename

C++	Description		Parameters
AddRename::AddRename	Constructor of AddRename class.		key_old_ A string key for an existing property to be renamed. key_new_ A string key by which the old key for the existing property is renamed.

Python-side methods of AddRename

Name	C++	Description	Parameters	Return
overwrite	AddRename::overwrite	Allow overwriting an existing property by a renamed property with the same name.	do_overwrite_ A boolean, whether an existing property can be overwritten by a renamed property (default is true).	This AddRename object.

AddSpecialBonds

AddSpecialBonds adds special bonds.

Python-side constructor of AddSpecialBonds

C++	Description		Parameters
AddSpecialBonds::AddSpecialBonds	Constructor of AddSpecialBonds class for molecules all of whose type property are 1, or molecules all of which do not have the property. Property to be added special-bonds : array of integers		el_mols A molecular Element object consisting of an atomic (or bead) Element object where the constructed object is appended to. Required property atom-ids : array of integers scheme List of lists of zero-based indices of atoms in a molecule. The first list corresponds atoms in a molecule, and the second lists corresponds special bonds of each atom.
AddSpecialBonds::AddSpecialBonds	Constructor of AddSpecialBonds class for multiple molecular types. Property to be added special-bonds : array of integers		el_mols A molecular Element object consisting of an atomic (or bead) Element object where the constructed object is appended to. Required property atom-ids : array of integers type_to_scheme Dictionary from molecular type to list of lists of zero-based indices of atoms in a molecule. The first list corresponds atoms in a molecule, and the second lists corresponds special bonds of each atom.

Usage example of the constructor for molecules consisting of linearly connected four atoms. Bond-length and bond-angle potentials are considered.

# python

atoms = create(StaDumpAtoms("path/to/dump", 0))
molecules = create(StaMolecules(atoms))

my_sbonds = AddSpecialBonds(
  molecules,
  [
    [1, 2],
    [0, 2, 3],
    [0, 1, 3],
    [1, 2]
  ]
)

atoms.append_updater(my_sbonds)

Usage example of the constructor for two types of molecule: the first one consists of linearly connected four atoms, and the second one consists of linearly connected five atoms. Bond-length and bond-angle potentials are considered.

# python

atoms = create(StaDumpAtoms("path/to/dump", 0))
molecules = create(StaMolecules(atoms))

my_sbonds = AddSpecialBonds(
  molecules,
  {
    1: [
      [1, 2],
      [0, 2, 3],
      [0, 1, 3],
      [1, 2]
    ],
    2: [
      [1, 2],
      [0, 2, 3],
      [0, 1, 3, 4],
      [1, 2, 4],
      [2, 3]
    ]
  }
)

atoms.append_updater(my_sbonds)

AddWrappedPosition

AddWrappedPosition adds wrapped positions for an Element object.

Python-side constructor of AddWrappedPosition

C++	Description		Parameters
AddWrappedPosition::AddWrappedPosition	Constructor of AddWrappedPosition class. Property to be added x : float y : float z : float Required property xu : float yu : float zu : float		elem An Element object for a simulation box. Required property lo_x : float lo_y : float lo_z : float hi_x : float hi_y : float hi_z : float

Filter

Filter removes elements from array Element::data if the elements fail user-defined criteria.

FilComparison

FilComparison applies a filter defined by comparison operators.

Python-side constructor of FilComparison

C++	Description		Parameters
FilComparison::FilComparison	Constructor of FilComparison class with one criterion.		compare_expr_ A three-elements tuple consisting of a string key, comparison operator and right side value of an inequality (or equation). Note that an Element object, where the constructed object is appended to, must has a property corresponding to the first element of this parameter (string key).
FilComparison::FilComparison	Constructor of FilComparison class with multiple criteria.		compare_expr_list_ List of three-elements tuples consisting of a string key, comparison operator and right side value of an inequality (or equation). Note that an Element object, where the constructed object is appended to, must has properties corresponding to the first elements of this parameter (string key).

Usage example of the constructor for a filter removing atoms whose xu property is less than 10.0.

# python

atoms = create(StaDumpAtoms("path/to/dump", 0))
atoms.append_updater(FilComparison(("xu", ">=", 10.0)))

Usage example of the constructor for a filter removing atoms except for those of which xu property is greater than 10.0 and less than 20.0, and charge property is equal to -1.0.

# python

atoms = create(StaDumpAtoms("path/to/dump", 0))
atoms.append_updater(FilComparison([
  ("xu", ">", 10.0),
  ("xu", "<", 20.0),
  ("charge", "==", -1.0)
]))

FilSet

FilSet applies a filter defined by sets of acceptable values.

Python-side constructor of FilSet

C++	Description		Parameters
FilSet::FilSet	Constructor of FilSet class.		acceptable_value_sets_ Dictionary from a string key for property to acceptable values of that property. Note that an Element object, where the constructed object is appended to, must has properties corresponding to keys in this parameter.

Usage example of the constructor for a filter removing atoms whose type property is not 1, 2, or 3.

# python

atoms = create(StaDumpAtoms("path/to/dump", 0))
atoms.append_updater(FilSet({"type": {1, 2, 3}}))

Usage example of the constructor for a filter removing atoms except for those of which type property is 1, 2, or 3, and id property is a multiple of 3 less than 1000.

# python

atoms = create(StaDumpAtoms("path/to/dump", 0))
atoms.append_updater(FilSet({
  "type": {1, 2, 3},
  "id": set(range(3, 1000, 3))
}))

Processor

Processor analyzes data contained in one or more Generator objects.

ProData

ProData copies Element::data from Element objects.

Python-side constructor of ProData

C++	Description		Parameters
ProData::ProData	Constructor of ProData class for one Element object.		elem An Element object to be copied.
ProData::ProData	Constructor of ProData class for a sequence of Element objects.		elems List of Element objects to be copied.

Python-side methods of ProData

Name	C++	Description	Parameters	Return
select	ProData::select	Specify string keys for properties to be copied.	*args An ordered list of string keys for properties to be copied (Python's variable number arguments).	None.
get_results	ProData::get_results	Get list of Json objects consisting of all or some properties of Element objects stored in this object.	None.	List of Json objects (complex of dictionary and list).

ProDistanceInMolecule

ProDistanceInMolecule computes atom-to-atom distance in each molecule (also computes square of the distance).

Python-side constructor of ProDistanceInMolecule

C++	Description		Parameters
ProDistanceInMolecule::ProDistanceInMolecule	Constructor of ProDistanceInMolecule class for a snapshot of simulation.		mols An Element object for molecules. Required property id : integer atom-ids : array of integers atoms An Element object for atoms. Required property id : integer xu : float yu : float zu : float
ProDistanceInMolecule::ProDistanceInMolecule	Constructor of ProDistanceInMolecule class for multiple snapshots of simulation.		pairs List of pairs of two Element objects: the first object is for molecules and the second object is for atoms. If each Element object has an array data, all the array should have the same length. Required property (first) atom-ids : array of integers Required property (second) id : integer xu : float yu : float zu : float

Python-side methods of ProDistanceInMolecule

Name	C++	Description	Parameters	Return
set_indices	ProDistanceInMolecule::set_indices	Specify two atoms in a molecule by zero-based index. Distance between the two atoms is computed for each molecule.	index1_in_mol_ A zero-based index in a molecule specifying a target atom. index2_in_mol_ A zero-based index in a molecule specifying the other target atom.	None.
set_moltype	ProDistanceInMolecule::set_moltype	Specify a molecular type. Only molecules whose type property is the specified type are analyzed. If molecules have no type property, you do not need to use this method.	target_moltype_ An integer for molecular type.	None.
get_distance_array	ProDistanceInMolecule::get_distance_array	Get computed distances between two atoms in each molecule as a two-dimensional array: each row corresponds to each snapshot of a simulation and each column corresponds to each molecule.	None.	Two-dimensional Numpy-Array.
get_distance2_array	ProDistanceInMolecule::get_distance2_array	Get computed squared distances between two atoms in each molecule as a two-dimensional array: each row corresponds to each snapshot of a simulation and each column corresponds to each molecule.	None.	Two-dimensional Numpy-Array.

Usage example of ProDistanceInMolecule class for a trajectory of molecules without type property. Distance between the 0 th atom and 100 th atom is computed.

# python

atoms_traj = [
  create(StaDumpAtoms("path/to/dump", i))
  for i in range(0, 1000000, 1000))
]

molecules_traj = [
  create(StaMolecules(atoms)) for atoms in atoms_traj
]

pro = ProDistanceInMolecule(list(zip(atoms_traj, molecules_traj)))
pro.set_indices(0, 100)

execute_omp(pro)

average_r2 = pro.get_distance2_array().mean()

ProMeanSquareDisplacement

ProMeanSquareDisplacement computes mean square displacement (MSD).

Python-side constructor of ProMeanSquareDisplacement

C++	Description		Parameters
ProMeanSquareDisplacement::ProMeanSquareDisplacement	Constructor of ProMeanSquareDisplacement class.		elems List of Element objects for atoms, beads, molecules... If each Element object has an array data, all the array should have the same length. Required property id : integer xu : float yu : float zu : float mass : float (for drift correction)

Python-side methods of ProMeanSquareDisplacement

Name	C++	Description	Parameters	Return
set_dimension	ProMeanSquareDisplacement::set_dimension	Specify dimensions to be considered. By default, the mean square displacement is computed in three dimensions. To compute the mean square displacement in xy place, for example, the third parameter of this method must be set to false.	include_x A boolean, whether component in the x direction is included in squared displacement. include_y A boolean, whether component in the y direction is included in squared displacement. include_z A boolean, whether component in the z direction is included in squared displacement.	None.
without_drift_correction	ProMeanSquareDisplacement::without_drift_correction	Disable to correct a drift of center of mass of the simulation system.	without_drift_correction_ Whether disable the drift correction or not (default is true).	None.
get_displacement2_array	ProMeanSquareDisplacement::get_displacement2_array	Get computed time series of squared displacements from initial position for each target as a two-dimensional array: each row corresponds to each snapshot of the simulation and each column corresponds to each target.	None.	Two-dimensional Numpy-Array.
get_mean_square_displacement	ProMeanSquareDisplacement::get_mean_square_displacement	Get time series of the mean square displacement as a one-dimensional array. Each element of the array corresponds to each snapshot of the simulation.	None.	One-dimensional Numpy-Array.

Usage example of ProMeanSquareDisplacement class for three-dimensional mean square displacement.

# python

atoms_traj = [
  create(StaDumpAtoms("path/to/dump", i))
  for i in range(0, 1000000, 1000))
]

molecules_traj = [
  create(StaMolecules(atoms))
    .append_updater(AddCoMPosition(atoms))
  for atoms in atoms_traj
]

pro = ProMeanSquareDisplacement(molecules_traj)

execute_omp(pro)

msd = pro.get_distance2_array().mean()

ProRadialDistributionFunction

ProRadialDistributionFunction computes radial distribution function (RDF).

Python-side constructor of ProRadialDistributionFunction

C++	Description		Parameters
ProRadialDistributionFunction::ProRadialDistributionFunction	Constructor of ProRadialDistributionFunction class for a snapshot of simulation.		targets An Element object for particles (can be atoms, beads, molecules...). Required property id : integer x : float y : float z : float special-bonds : array of integers (optional) box An Element object for a simulation box. Required property lo_x : float lo_y : float lo_z : float hi_x : float hi_y : float hi_z : float
ProRadialDistributionFunction::ProRadialDistributionFunction	Constructor of ProThicknessProfile class for multiple snapshots of simulation.		pairs List of pairs of two Element objects: the first object is for particles and the second object is for a simulation box. If each Element object has an array data, all the array should have the same length. Required property (first) id : integer x : float y : float z : float special-bonds : array of integers (optional) Required property (second) lo_x : float lo_y : float lo_z : float hi_x : float hi_y : float hi_z : float

Python-side methods of ProRadialDistributionFunction

Name	C++	Description	Parameters	Return
set_bin	ProRadialDistributionFunction::set_bin	Set width and number of bins in the distance axis. Each bin is a spherical shell of which center is positioned at a reference particle.	bin_width_ Width of a bin. n_bins_ Number of bins.	None.
bin_from_r_to_r_plus_dr	ProRadialDistributionFunction::bin_from_r_to_r_plus_dr	By default, the bins are [0, 0.5*dr), [0.5*dr, 1.5*dr), ... . If this method is called without a parameter, the bins are set as [0, dr), [dr, 2*dr), ... .	bin_from_r_ A boolean, whether to use bin of which inner radius is r and outer radius is r+dr (default is true).	None.
beyond_half_box_length	ProRadialDistributionFunction::beyond_half_box_length	Use a sample including particles of which distance from a reference particle are larger than half the simulation box length.	beyond_half_ A boolean, whether to use particles beyond half the simulation box from a reference particle (default is true).	None.
get_r_axis	ProRadialDistributionFunction::get_r_axis	Get a one-dimensional array of distance, [0, dr, 2*dr, ... ], where dr is width of a bin.	None.	One-dimensional Numpy-Array.
get_rdf	ProRadialDistributionFunction::get_rdf	Get the radial distribution function as a one-dimensional array.	None.	One-dimensional Numpy-Array.
get_rdf_traj	ProRadialDistributionFunction::get_rdf_traj	Get a sequence of radial distribution functions as list of one-dimensional arrays.	None.	List of one-dimensional Numpy-Arrays.

Usage example of ProRadialDistributionFunction class for computing radial distribution function of atoms with the following two conditions. Linearly connected four atoms form a molecule. Each atom has next two atoms in the same molecule as special bonds.

# python

atoms_traj = [
  create(StaDumpAtoms("path/to/dump", i))
  for i in range(0, 1000000, 1000))
]

for atoms in atoms_traj:
  atoms.append_updater(AddSpecialBonds(
    create(StaMolecules(atoms)),
    [[1, 2], [0, 2, 3], [0, 1, 3], [1, 2]]
  ))

box_traj = [
  create(StaDumpBox("path/to/dump", i))
  for i in range(0, 1000000, 1000))
]

for atoms, box in zip(atoms_traj, box_traj):
  atoms.append_updater(AddWrappedPosition(box))

pro = ProRadialDistributionFunction(list(zip(atoms_traj, box_traj)))
pro.set_bin(0.1, 200)

execute_omp(pro)

rdf = pro.get_rdf()

ProRadialDistributionFunctionWithDeformation

ProRadialDistributionFunctionWithDeformation computes radial distribution function (RDF) taking deformation of particles into consideration.

Python-side constructor of ProRadialDistributionFunctionWithDeformation

C++	Description		Parameters
ProRadialDistributionFunctionWithDeformation::ProRadialDistributionFunction	Constructor of ProRadialDistributionFunctionWithDeformation class for a snapshot of simulation.		targets An Element object for particles (can be atoms, beads, molecules...). Required property id : integer x : float y : float z : float mass : float I_xx : float I_yy : float I_zz : float I_xy : float I_xz : float I_yz : float special-bonds : array of integers (optional) box An Element object for a simulation box. Required property lo_x : float lo_y : float lo_z : float hi_x : float hi_y : float hi_z : float
ProRadialDistributionFunctionWithDeformation::ProRadialDistributionFunction	Constructor of ProRadialDistributionFunctionWithDeformation class for multiple snapshots of simulation.		pairs List of pairs of two Element objects: the first object is for particles and the second object is for a simulation box. If each Element object has an array data, all the array should have the same length. Required property (first) id : integer x : float y : float z : float mass : float I_xx : float I_yy : float I_zz : float I_xy : float I_xz : float I_yz : float special-bonds : array of integers (optional) Required property (second) lo_x : float lo_y : float lo_z : float hi_x : float hi_y : float hi_z : float

Python-side methods of ProRadialDistributionFunctionWithDeformation

Name	C++	Description	Parameters	Return
set_bin	ProRadialDistributionFunctionWithDeformation::set_bin	Set width and number of bins in the distance axis. Each bin is a spherical shell of which center is positioned at a reference particle.	bin_width_ Width of a bin. n_bins_ Number of bins.	None.
set_margin	ProRadialDistributionFunctionWithDeformation::set_margin	Set margin for distance from a reference particle: this program uses a sample including particles of which distance from a reference particle are less than the maximum distance in a domain, where the radial distribution function is computed, plus* the margin.	margin_ Consider particles up to the maximum distance in the domain plus* this value.	None.
bin_from_r_to_r_plus_dr	ProRadialDistributionFunctionWithDeformation::bin_from_r_to_r_plus_dr	By default, the bins are [0, 0.5*dr), [0.5*dr, 1.5*dr), ... . If this method is called without a parameter, the bins are set as [0, dr), [dr, 2*dr), ... .	bin_from_r_ A boolean, whether to use bin of which inner radius is r and outer radius is r+dr (default is true).	None.
beyond_half_box_length	ProRadialDistributionFunctionWithDeformation::beyond_half_box_length	Use a sample including particles of which distance from a reference particle are larger than half the simulation box length.	beyond_half_ A boolean, whether to use particles beyond half the simulation box from a reference particle (default is true).	None.
get_r_axis	ProRadialDistributionFunctionWithDeformation::get_r_axis	Get a one-dimensional array of distance, [0, dr, 2*dr, ... ], where dr is width of a bin.	A.	One-dimensional Numpy-Array.
get_rdf	ProRadialDistributionFunctionWithDeformation::get_rdf	Get the radial distribution function as a one-dimensional array.	None.	One-dimensional Numpy-Array.
get_rdf_traj	ProRadialDistributionFunctionWithDeformation::get_rdf_traj	Get a sequence of radial distribution functions as list of one-dimensional arrays.	None.	List of one-dimensional Numpy-Arrays.
get_gyration_radius	ProRadialDistributionFunctionWithDeformation::get_gyration_radius	Get averaged gyration radius as function of distance from a reference particle. The returned value is dictionary of which keys are isotropic, parallel and perpendicular, and corresponding values are functions for general gyration radius, gyration radius in the particle-to-particle axis and gyration radius around the particle-to-particle axis, respectively.	None.	Dictionary from string keys to one-dimensional Numpy-Arrays.
get_gyration_radius_traj	ProRadialDistributionFunctionWithDeformation::get_gyration_radius_traj	Get list of temporary gyration radius as function of distance from a reference particle. The returned value is dictionary of which keys are isotropic, parallel and perpendicular, and corresponding values are lists of functions for general gyration radius, gyration radius in* the particle-to-particle axis and gyration radius around* the particle-to-particle axis, respectively. Each element of the lists corresponds to each snapshot of the simulation.	None.	Dictionary from string keys to lists of one-dimensional Numpy-Arrays.
get_squared_gyration_radius	ProRadialDistributionFunctionWithDeformation::get_squared_gyration_radius	Get averaged square of gyration radius as function of distance from a reference particle. The returned value is dictionary of which keys are isotropic, parallel and perpendicular, and corresponding values are function for general gyration radius, gyration radius in* the particle-to-particle axis and gyration radius around* the particle-to-particle axis, respectively.	None.	Dictionary from string keys to one-dimensional Numpy-Arrays.
get_squared_gyration_radius_traj	ProRadialDistributionFunctionWithDeformation::get_squared_gyration_radius_traj	Get list of temporary square of gyration radius as function of distance from a reference particle. The returned value is dictionary of which keys are isotropic, parallel and perpendicular, and corresponding values are lists of functions for general gyration radius, gyration radius in* the particle-to-particle axis and gyration radius around* the particle-to-particle axis, respectively. Each element of the lists corresponds to each snapshot of the simulation.	None.	Dictionary from string keys to lists of one-dimensional Numpy-Arrays.

Usage example of ProRadialDistributionFunctionWithDeformation class for computing radial distribution function of beads.

# python

ProRDFWD = ProRadialDistributionFunctionWithDeformation

n_samples = 1000
interval = 1000

atoms_traj = [create(
  StaDumpAtoms("/path/to/dump", i))
  for i in range(0, n_samples*interval+1, interval)
]
box_traj = [create(
  StaDumpBox("/path/to/dump", i))
  for i in range(0, n_samples*interval+1, interval)
]

mols_traj = [create(StaMolecules(atoms)) for atoms in atoms_traj]

mappings = [
  [0, 1, 2, 12, 13, 14, 15, 16, 17, 18],
  [3, 4, 5, 19, 20, 21, 22, 23, 24],
  [6, 7, 8, 25, 26, 27, 28, 29, 30],
  [9, 10, 11, 31, 32, 33, 34, 35, 36, 37]
]

abst_beads = [
  {"type": 1, "indices-in-mol": mapping}
  for i, mapping in enumerate(mappings)
]

abst_special_bonds = [[1,2], [0,2,3], [0,1,3], [1,2]]


beads_traj = [
  create(StaBeads(mols, abst_beads))
    .append_updater(AddCoMPosition(atoms))
    .append_updater(AddInertiaMoment(atoms))
    .append_updater(AddWrappedPosition(box))
  for atoms, box, mols in zip(atoms_traj, box_traj, mols_traj)
]


for beads, mols in zip(beads_traj, mols_traj):

  mols.append_updater(AddChildIDs(beads, "bead", "mol"))
  mols.append_updater(AddRename("bead-ids", "atom-ids").overwrite())

  beads.append_updater(AddSpecialBonds(mols, abst_special_bonds))

pro = ProRDFWD(list(zip(beads_traj, box_traj)))

pro.set_bin(0.1, 200)
pro.set_margin(2.0)

execute_omp(pro)

print(pro.get_rdf())

ProThicknessProfile

ProThicknessProfile computes thickness profile of a film consisting of particles (can be atoms, beads, molecules...).

Python-side constructor of ProThicknessProfile

C++	Description		Parameters
ProThicknessProfile::ProThicknessProfile	Constructor of ProThicknessProfile class for a snapshot of simulation.		atoms An Element object for particles (can be atoms, beads, molecules...) forming a film. Required property x : float y : float z : float radius : float box An Element object for a simulation box. Required property lo_x : float lo_y : float hi_x : float hi_y : float
ProThicknessProfile::ProThicknessProfile	Constructor of ProThicknessProfile class for multiple snapshots of simulation.		pairs List of pairs of two Element objects: the first object is for particles forming a film and the second object is for a simulation box. If each Element object has an array data, all the array should have the same length. Required property (first) x : float y : float z : float radius : float Required property (second) lo_x : float lo_y : float hi_x : float hi_y : float

Python-side methods of ProThicknessProfile

Name	C++	Description	Parameters	Return
set_grid	ProThicknessProfile::set_grid	Specify the number of grids in the x and y directions.	nx_ The number of grids in the x direction. ny_ The number of grids in the y direction.	None.
set_offset	ProThicknessProfile::set_offset	Specify the offset for thickness (height).	offset_ Film thickness is calculated after subtracting this value from z coordinate of particles.	None.
shift_half_delta	ProThicknessProfile::shift_half_delta	Increment coordinates of the grid points by half the grid width. By default, grids in the x direction are set as x_0, x_0+dx, x_0+2*dx, ... , where x_0 is the minimum x coordinate in the simulation box and dx is the grid width. If this method is called without a parameter, the grids are set as x_0+0.5*dx, x_0+1.5*dx, x_0+2.5*dx, ... .	shift_half_ A boolean, whether to shift the grid points or not (default is true).	None.
get_conditions	ProThicknessProfile::get_conditions	Get computation conditions (origin of computed area, grid width and the number of grads) used by this object as list of dictionary.	None.	List of dictionary.
get_profiles	ProThicknessProfile::get_profiles	Get a sequence of two-dimensional profile of film thickness as list of two-dimensional arrays. Row and column of each array is for the x and y direction, respectively.	None.	List of two-dimensional Numpy-Array.

Usage example of ProThicknessProfile class for computing a time series of thickness profile of a film consisting of atoms of which radius is 2.16 and type property is 1.

# python

atoms_traj = [
  create(StaDumpAtoms("path/to/dump", i))
    .append_updater(AddMap("type", "radius", {1: 2.16}))
  for i in range(0, 1000000, 1000))
]

box_traj = [
  create(StaDumpBox("path/to/dump", i))
  for i in range(0, 1000000, 1000))
]

for atoms, box in zip(atoms_traj, box_traj):
  atoms.append_updater(AddWrappedPosition(box))

pro = ProThicknessProfile(list(zip(atoms_traj, box_traj)))
pro.set_grid(100, 100)

execute_omp(pro)

profiles = pro.get_profiles()

ProTimeCorrelationInMolecule

ProTimeCorrelationInMolecule computes time correlation function of atom-to-atom vector in each molecule.

Python-side constructor of ProTimeCorrelationInMolecule

C++	Description		Parameters
ProTimeCorrelationInMolecule::ProTimeCorrelationInMolecule	Constructor of ProTimeCorrelationInMolecule class.		pairs List of pairs of two Element objects: the first object is for molecules and the second object is for atoms. If each Element object has an array data, all the array should have the same length. Required property (first) id : integer atom-ids : array of integers Required property (second) id : integer xu : float yu : float zu : float

Python-side methods of ProTimeCorrelationInMolecule

Name	C++	Description	Parameters	Return
set_indices	ProTimeCorrelationInMolecule::set_indices	Specify two atoms in a molecule by zero-based index. Time correlation function of a vector between the two atoms is computed for each molecule.	index1_in_mol_ A zero-based index in a molecule specifying a target atom. index2_in_mol_ A zero-based index in a molecule specifying the other target atom.	None.
set_moltype	ProTimeCorrelationInMolecule::set_moltype	Specify a molecular type. Only molecules whose type property is the specified type are analyzed. If molecules have no type property, you do not need to use this method.	target_moltype_ An integer for molecular type.	None.
get_coefficients_array	ProTimeCorrelationInMolecule::get_coefficients_array	Get a two-dimensional array containing computed time correlation coefficients of vectors connecting two atoms in the same molecule: each column is a time correlation function of atom-to-atom vector in each molecule.	None.	Two-dimensional Numpy-Array.
get_time_correlation	ProTimeCorrelationInMolecule::get_time_correlation	Get an averaged time correlation function of atom-to-atom vector; each pair of atoms is in the same molecule.	None.	One-dimensional Numpy-Array.

Usage example of ProTimeCorrelationInMolecule class for a trajectory of molecules without type property. Time correlation function for a vector between the 0 th atom and 100 th atom is computed.

# python

atoms_traj = [
  create(StaDumpAtoms("path/to/dump", i))
  for i in range(0, 1000000, 1000))
]

molecules_traj = [
  create(StaMolecules(atoms)) for atoms in atoms_traj
]

pro = ProTimeCorrelationInMolecule(list(zip(atoms_traj, molecules_traj)))
pro.set_indices(0, 100)

execute_omp(pro)

tcf = pro.get_time_correlation()

ProValueArray

ProValueArray makes one or more arrays consisting of values for property in a sequence of Element objects.

Python-side constructor of ProValueArray

C++	Description		Parameters
ProValueArray::ProValueArray	Constructor of ProValueArray class for one Element object.		elem An Element object.
ProValueArray::ProValueArray	Constructor of ProValueArray class for a sequence of Element objects.		elems List of Element objects. If each Element object has an array data, all the array should have the same length.

Python-side methods of ProValueArray

Name	C++	Description	Parameters	Return
select	ProValueArray::select	Specify string keys for properties. To use this object, at least one key must be specified. Note that new keys overwrite old keys.	*args An ordered list of string keys for properties (Python's variable number arguments). Be sure that all Element objects stored in this object has the keys.	None.
get_results	ProValueArray::get_results	Get dictionary from keys for property to two-dimensional arrays of values for the property. Each row of the array corresponds to each snapshot of a simulation, and each column of the array corresponds to each element in array Element objects (for example, each atom in Element objects for atoms).	None.	Dictionary from string key to two-dimensional Numpy-Array.

Usage example of ProValueArray class for computing an averaged radius of gyration of molecules.

# python

atoms_traj = [
  create(StaDumpAtoms("path/to/dump", i))
  for i in range(0, 1000000, 1000))
]

molecules_traj = [
  create(StaMolecules(atoms))
    .append_updater(AddCoMPosition(atoms))
    .append_updater(AddInertiaMoment(atoms))
    .append_updater(AddGyrationRadius())
   for atoms in atoms_traj
]

pro = ProValueArray(molecules_traj)
pro.select("Rg^2")

execute_omp(pro)

Rg = sqrt(pro.get_results()["Rg^2"].mean())

Invoker

Invoker executes analysis programmed in one or more Processor objects.

InvOMP

InvOMP is an Invoker's subclass using OpenMP to execute a computationally expensive part of analysis.

Constructor of InvOMP class is hidden from Python. A Python-side function execute_omp provides functionality to create an InvOMP object and execute analysis using it.

Python-side functions

Name	C++	Description	Parameters	Return
execute_omp	pybind::execute_omp	Create and use an InvOMP object to conduct analysis programmed in a Processor's subclass object.	proc A Processor object to be executed.	None.
execute_omp	pybind::execute_omp	Create and use an InvOMP object to conduct analysis programmed in Processor's subclass objects.	procs List of Processor objects to be executed.	None.

Utilities

Python-side utility functions

Name	C++	Description	Parameters	Return
log_switch	utils::log_switch	Switch on/off logging.	input A boolean, whether take log or not.	None.

Properties To Be Added

Class	Property Names
StaBeads	atom-ids, atom-weights, id, mol, type
StaCopy
StaCustom
StaDumpAtoms	ITEM: ATOMS — in Lammps DUMP file
StaDumpBox	hi_x, hi_y, hi_z, lo_x, lo_y, lo_z, pbc_x, pbc_y, pbc_z
StaMolecules	atom-ids, id
AddBondAngle	angle
AddBondLength	length
AddChildIDs	[child_name]-ids
AddChildPositions	[child_name]-xs, [child_name]-ys, [child_name]-zs
AddCoMPosition	mass, xu, yu, zu
AddDihedralAngle	dihedral-angle
AddGyrationRadius	Rg(x), Rg(x+y), Rg(y), Rg(y+z), Rg(z), Rg(z+x), Rg, Rg^2(x), Rg^2(x+y), Rg^2(y), Rg^2(y+z), Rg^2(z), Rg^2(z+x), Rg^2
AddInertiaMoment	I_xx, I_xy, I_xz, I_yy, I_yz, I_zz
AddMap	[key_new]
AddMolecularOrientation	I_values, I_vectors, S_x, S_y, S_z
AddRename
AddSpecialBonds	special-bonds
AddWrappedPosition	x, y, z

---

Author

Takayuki Kobayashi

Copyright

MIT License

Date

2018