sponge.system.Molecule

class sponge.system.Molecule(atoms: Union[List[Union[str, int]], ndarray] = None, atom_name: Union[List[str], ndarray] = None, atom_type: Union[List[str], ndarray] = None, atom_mass: Union[Tensor, ndarray, List[float]] = None, atom_charge: Union[Tensor, ndarray, List[float]] = None, atomic_number: Union[Tensor, ndarray, List[float]] = None, bonds: Union[Tensor, ndarray, List[int]] = None, coordinate: Union[Tensor, ndarray, List[float]] = None, pbc_box: Union[Tensor, ndarray, List[float]] = None, template: Union[dict, str, List[Union[dict, str]]] = None, residue: Union[Residue, List[Residue]] = None, length_unit: str = None, **kwargs)[source]

Base class for molecular system, used as the "system module" in MindSPONGE. The Molecule Cell can represent a molecule or a system consisting of multiple molecules. The major components of the Molecule Cell is the Residue Cell. A Molecule Cell can contain multiple Residue Cells.

Parameters

atoms (Union[List[Union[str, int]], ndarray]) – Array of atoms. The data in array can be str of atom name or int of atomic number. Defulat: None
atom_name (Union[List[str], ndarray]) – Array of atom name with data type str. Defulat: None
atom_type (Union[List[str], ndarray]) – Array of atom type with data type str. Defulat: None
atom_mass (Union[Tensor, ndarray, List[float]]) – Array of atom mass of shape \((B, A)\) with data type float where B represents the batchsize, i.e. the number of walker in the system, A represents the number of atoms. Defulat: None
atom_charge (Union[Tensor, ndarray, List[float]]) – Array of atom charge of shape \((B, A)\) with data type float. Defulat: None
atomic_number (Union[Tensor, ndarray, List[float]]) – Array of atomic number of shape \((B, A)\) with data type int. Defulat: None
bond (Union[Tensor, ndarray, List[int]]) – Array of bond connection of shape \((B, b, 2)\) with data type int where b represents the number of bonds. Defulat: None
coordinate (Union[Tensor, ndarray, List[float]]) – Tensor of atomic coordinates \(R\) of shape \((B, A, D)\) with data type float where D represents the spatial dimension of the simulation system, usually is 3. Default: None
pbc_box (Union[Tensor, ndarray, List[float]]) – Tensor of box size \(\vec{L}\) of periodic boundary condition (PBC). The shape of tensor is \((B, D)\) and the data type is float. Default: None
template (Union[dict, str, List[Union[dict, str]]]) – Template for molecule. It can be a dict in MindSPONGE template format or a str for the filename of a MindSPONGE template file. If a str is given, it will first look for a file with the same name in the current directory. If the file does not exist, it will search in the built-in template directory of MindSPONGE (mindsponge.data.template). Default: None.
residue (Union[Residue, List[Residue]]) – Residue or a list of residues. If template is not None, only the residues in the template will be used. Default: None.
length_unit (str) – Length unit. If None is given, the global length units will be used. Default: None
kwargs (dict) – Other parameters for extension

Outputs:

coordinate, Tensor of shape (B, A, D). Data type is float.
pbc_box, Tensor of shape (B, D). Data type is float.

Supported Platforms:

Ascend GPU

Examples

>>> from sponge import Molecule
>>> system = Molecule(atoms=['O', 'H', 'H'],
...                   coordinate=[[0, 0, 0], [0.1, 0, 0], [-0.0333, 0.0943, 0]],
...                   bonds=[[[0, 1], [0, 2]]])
>>> print ('The number of atoms in the system is: ', system.num_atoms)
The number of atoms in the system is:  3
>>> print ('All the atom names in the system are: ', system.atom_name)
All the atom names in the system are:  [['O' 'H' 'H']]
>>> print ('The coordinates of atoms are: \n{}'.format(system.coordinate.asnumpy()))
The coordinates of atoms are:
[[[ 0.      0.      0.    ]
  [ 0.1     0.      0.    ]
  [-0.0333  0.0943  0.    ]]]
>>> system = Molecule(template='water.spce.yaml')
>>> print ('The number of atoms in the system is: ', system.num_atoms)
The number of atoms in the system is:  3
>>> print ('All the atom names in the system are: ', system.atom_name)
All the atom names in the system are:  [['O' 'H1' 'H2']]
>>> print ('The coordinates of atoms are: \n{}'.format(system.coordinate.asnumpy()))
The coordinates of atoms are:
[[[ 0.          0.          0.        ]
  [ 0.08164904  0.0577359   0.        ]
  [-0.08164904  0.0577359   0.        ]]]

add_residue(residue: Residue, coordinate: Tensor = None)[source]

Add residue to this molecule system.

Parameters

residue (class) – a Residue class of the residue added in the system.
coordinate (Tensor) – The coordinate of the input residue. Default: None.

append(system)[source]

Append a system to this molecule system.

Parameters: system (Molecule) – Another molecule system that will be added to this molecule system.

build_angle()[source]: build angles for the system

build_atom_charge()[source]: Build atom charge.

build_atom_type()[source]: Build atom type.

build_dihedrals()[source]: build dihedral angles for the system

build_h_bonds()[source]: build bonds with hydrogen atom.

build_improper()[source]: Build improper dihedral angles for the system

build_space(coordinate: Tensor, pbc_box: Tensor = None)[source]

Build coordinate and PBC box.

Parameters

coordinate (Tensor) – The initial coordinate of system. If it's None, the system will generate a random coordinate as its initial coordinate.
pbc_box (Tensor) – The initial pbc_box of the system. If it's None, the system won't use pbc_box. Default:None

build_system()[source]: Build the system by residues.

calc_colvar(colvar: Colvar)[source]

Calculate the value of specific collective variables in the system.

Parameters: colvar (Colvar) – Base class for generalized collective variables (CVs) \(s(R)\).
Returns: Tensor, the value of a collective variables \(s(R)\).

calc_image(shift: float = 0)[source]

Calculate the image of coordinate.

Parameters: shift (float) – Offset ratio \(c\) relative to box size \(\vec{L}\). Default: 0 .
Returns: Tensor, the image of coordinate.

convert_length_from(unit)[source]

Convert length from a specified units.

Parameters: unit (Union[str, Units, Length, float, int]) – Length unit.
Returns: float, length according to a specified units.

convert_length_to(unit)[source]

Convert length to a specified units.

Parameters: unit (Union[str, Units, Length, float, int]) – Length unit.
Returns: float, length according to a specified units.

coordinate_in_pbc(shift: float = 0)[source]

Get the coordinate in a whole PBC box.

Parameters: shift (float) – Offset ratio relative to box size. Default: 0
Returns: Tensor, the coordinate in the PBC box. Shape (B, …, D). Data type is float.

copy(shift: Tensor = None)[source]

Return a Molecule that copy the parameters of this molecule.

Parameters: shift (Tensor) – The displacement distance of the system. Default: None.
Returns: class, class Molecule that copy the parameters of this molecule.

fill_water(edge: float = None, gap: float = None, box: ndarray = None, pdb_out: str = None, template: str = None)[source]

The inner function in Molecule class to add water in a given box.

Parameters

edge (float) – The water edge around the system.
gap (float) – The minimum gap between system atoms and water atoms.
box (Tensor) – The pbc box we want, default to be None.
pdb_out (str) – The string format pdb file name to store the information of system after filling water.
template (str) – The supplemental template of the water molecules filled.

Returns

new_pbc_box(Tensor), this function will return a pbc_box after filling water.

get_atoms(atoms: Union[Tensor, Parameter, ndarray, str, list, tuple])[source]

Get atoms from the system.

Parameters: atoms (Union[Tensor, Parameter, ndarray, str, list, tuple]) – List of atoms.
Returns: class, atoms or groups of atoms.

get_coordinate(atoms: AtomsBase = None)[source]

Get Tensor of coordinate.

Parameters: atoms (class) – Base class for specific atoms group, used as the "atoms group module" in MindSPONGE. Default: None.
Returns: Tensor. Coordinate. Data type is float.

get_pbc_box()[source]

Get Tensor of PBC box.

Returns: Tensor, PBC box

get_volume()[source]

Get volume of system.

Returns: Tensor, the volume of the system. If pbc_box is not used, the volume is None.

property heavy_atom_mask

mask for heavy (non-hydrogen) atoms.

Returns: Tensor, mask for heavy atoms.

property length_unit

Length unit.

Returns: str, length unit.

move(shift: Tensor = None)[source]

Move the coordinate of the system.

Parameters: shift (Tensor) – The displacement distance of the system. Default: None.

property ndim

Ndim of atomic coordinate.

Returns: int, number of dims of atomic coordinate.

reduplicate(shift: Tensor)[source]

Duplicate the system to double of the origin size.

Parameters: shift (Tensor) – The distance moved from the origin system.

repeat_box(lattices: list)[source]

Repeat the system according to the lattices of PBC box.

Parameters: lattices (list) – Lattices of PBC box.

residue_bond(res_id: int)[source]

Get bond index of residue.

Parameters: res_id (int) – Residue index.
Returns: Tensor, the bond index of residue.

residue_coordinate(res_id: int)[source]

Get residue coordinate.

Parameters: res_id (int) – Residue index.
Returns: Tensor, residue coordinate in the system.

residue_head(res_id: int)[source]

Get head index of residue.

Parameters: res_id (int) – Residue index.
Returns: Tensor, the head index of residue.

residue_index(res_id: int)[source]

Get index of residue.

Parameters: res_id (int) – Residue index.
Returns: Tensor, the system index of the residue.

residue_tail(res_id: int)[source]

Get tail index of residue.

Parameters: res_id (int) – Residue index.
Returns: Tensor, the tail index of residue.

set_atom_charge(atom_charge: Tensor)[source]

set atom charge

Parameters: atom_charge (Tensor) – Atom charge.

set_bond_length(bond_length: Tensor)[source]

Set bond length.

Parameters: bond_length (Tensor) – Set the bond length of the system.

set_coordianate(coordinate: Tensor)[source]

Set the value of coordinate.

Parameters: coordinate (Tensor) – Coordinates used to set system coordinates.
Returns: Tensor, the coordinate of the system.

set_length_unit(unit)[source]

Set the length unit of system.

Parameters: unit (Union[str, Units, Length, float, int]) – Length unit.

set_pbc_box(pbc_box: Tensor = None)[source]

Set PBC box.

Parameters: pbc_box (Tensor) – Set the PBC box of the system. If it's None, the system won't use PBC box. Default: None.
Returns: Tensor, system PBC box.

set_pbc_grad(grad_box: bool)[source]

Set whether to calculate the gradient of PBC box.

Parameters: grad_box (bool) – Whether to calculate the gradient of PBC box.
Returns: bool, whether to calculate the gradient of PBC box.

property shape

Shape of atomic coordinate.

Returns: Tuple, atomic coordinate.

space_parameters()[source]

Get the parameter of space (coordinates and pbc box).

Returns: list[Tensor], coordinate and pbc_box. If pbc_box is not used, it will only return coordinate.

trainable_params(recurse=True)[source]

Trainable parameters.

Parameters: recurse (bool) – If true, yields parameters of this cell and all subcells. Otherwise, only yield parameters that are direct members of this cell. Default: True.
Returns: list, all trainable system parameters.

update_coordinate(coordinate: Tensor)[source]

Update the parameter of coordinate.

Parameters: coordinate (Tensor) – Coordinates used to update system coordinates.
Returns: Tensor, updated coordinate.

update_image(image: Tensor = None)[source]

Update the image of coordinate.

Parameters: image (Tensor) – The image of coordinate used to update the image of system coordinate. Default: None.
Returns: bool, whether successfully update the image of coordinate.

update_pbc_box(pbc_box: Tensor)[source]

Update PBC box

Parameters: pbc_box (Tensor) – PBC box used to update the system PBC box.
Returns: Tensor, updated system PBC box.