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
- 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_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
- 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.
- 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.
- 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_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_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.