atomic_system

A module containing the AtomicSystem class

Summary

Classes:

AtomicSystem

A class for storing atomic systems.

Reference

Bases: _PropertiesMixin, _StandardPropertiesMixin, _PositionsMixin

A class for storing atomic systems.

It contains the standard properties of an atomic system (i.e. positions, velocities, forces, charges, topology and cell). The AtomicSystem class can be used as a container for the standard properties of any molecular/atomic system.

Notes

An atomic system does not have to containing any positions, velocities, forces and so forth. The only requirement is that the number of atoms in the topology is equal to the number of entries in the positions, velocities, forces and charges arrays. If e.g. only a system containing information of the velocities is needed, the positions, forces and charges arrays can be left empty (i.e. np.zeros((0, 3)) and np.zeros(0)). The same goes for the other properties. An empty cell can be created with Cell() and represents a system without periodic boundary conditions. (For more information see the documentation of Cell). As the topology is can be really and complex and most of the cases really specific to the system, here no further information is given. (For more information see the documentation of Topology). Furthermore for this reason if no specialization of the topology is needed, the atomic system can be initialized with only a list of atoms (see examples, and the documentation of Atom).

Inherits from the Mixins: _PropertiesMixin, _StandardPropertiesMixin, _IndexingMixin, _PositionsMixin

The _StandardPropertiesMixin contains the standard properties of an atomic

system (i.e. standard getter and setter methods). - The _PropertiesMixin contains special properties derived from the standard properties - The _PositionsMixin contains methods for computing properties based on the positions of the atoms

Examples

>>> import numpy as np
>>> from PQAnalysis.core import Atom
>>> from PQAnalysis.atomic_system import AtomicSystem

>>> atoms = [Atom('C1', use_guess_element=False), Atom('C2', use_guess_element=False)]
>>> AtomicSystem(atoms=atoms, pos=np.array([[0, 0, 0], [1, 0, 0]]))
AtomicSystem(topology=(Topology with 2 atoms...), cell=(Cell()))

>>> AtomicSystem()
AtomicSystem(topology=(Topology with 0 atoms...), cell=(Cell()))

>>> AtomicSystem(topology=Topology(atoms=[Atom('C'), Atom('C')]))
AtomicSystem(topology=(Topology with 2 atoms...), cell=(Cell()))

For the initialization of an AtomicSystem all parameters are optional. If no value is given for a parameter, the default value is used which is an empty list for atoms, an empty numpy.ndarray for pos, vel, forces and charges, a Topology() object for topology and a Cell() object for cell.

If the shapes or lengths of the given parameters are not consistent, this will only raise an error when a property or method is called that requires the given parameter. This is done to allow for the creation of an AtomicSystem with only a subset of the properties.

One important restriction is that atoms and topology are mutually exclusive, i.e. if atoms is given, topology cannot be given and vice versa (this is because the topology is derived from the atoms - if given).

Parameters:

atoms (Atoms, optional) – A list of Atom objects, by default []
pos (Np2DNumberArray, optional) – A 2d numpy.ndarray containing the positions of the atoms, by default np.zeros((0, 3)).
vel (Np2DNumberArray, optional) – A 2d numpy.ndarray containing the velocities of the atoms, by default np.zeros((0, 3)).
forces (Np2DNumberArray, optional) – A 2d numpy.ndarray containing the forces on the atoms, by default np.zeros((0, 3)).
charges (Np1DNumberArray, optional) – A 1d numpy.ndarray containing the charges of the atoms, by default np.zeros(0).
topology (Topology, optional) – The topology of the system, by default Topology()
energy (float, optional) – The energy of the system, by default None
virial (Np3x3NumberArray, optional) – The virial of the system, by default None
stress (Np3x3NumberArray, optional) – The stress of the system, by default None
cell (Cell, optional) – The unit cell of the system. Defaults to a Cell with no periodic boundary conditions, by default Cell()

Raises:

ValueError – If both atoms and topology are given.

__eq__( other: Any, ) → Bool[source]

Checks whether the AtomicSystem is equal to another AtomicSystem.

Parameters:: other (AtomicSystem) – The other AtomicSystem to compare to.
Returns:: Whether the AtomicSystem is equal to the other AtomicSystem.
Return type:: bool

__getitem__( key: Atom | int | slice | Np1DIntArray, ) → AtomicSystem[source]

Returns a new AtomicSystem with the given key.

Examples

>>> import numpy as np
>>> from PQAnalysis.core import Atom, Residue
>>> from PQAnalysis.atomic_system import AtomicSystem

>>> atoms = [Atom('C'), Atom('C')]
>>> pos = np.array([[0, 0, 0], [1, 0, 0]])
>>> system = AtomicSystem(atoms=atoms, pos=pos)
>>> system[0]
AtomicSystem(topology=(Topology with 1 atoms...), cell=(Cell()))

>>> system[0] == AtomicSystem(atoms=[Atom('C')], pos=np.array([[0, 0, 0]]))
True

>>> system[0:2]
AtomicSystem(topology=(Topology with 2 atoms...), cell=(Cell()))

>>> atoms = [Atom('C'), Atom('C')]
>>> pos = np.array([[0, 0, 0], [1, 0, 0]])
>>> system[0:2] == AtomicSystem(atoms=atoms, pos=pos)
True

>>> system[np.array([0, 1])]
AtomicSystem(topology=(Topology with 2 atoms ...), cell=(Cell()))

>>> atoms = [Atom('C'), Atom('C')]
>>> pos = np.array([[0, 0, 0], [1, 0, 0]])
>>> system[np.array([0, 1])] == AtomicSystem(atoms=atoms, pos=pos)
True

Parameters:: key (Atom | int | slice | Np1DIntArray) – The key to get the new AtomicSystem with.
Returns:: The new AtomicSystem with the given key.
Return type:: AtomicSystem

__repr__() → str[source]

Returns the string representation of the AtomicSystem.

Returns:: The string representation of the AtomicSystem.
Return type:: str

__str__() → str[source]

Returns the string representation of the AtomicSystem.

Returns:: The string representation of the AtomicSystem.
Return type:: str

center( position: Np1DNumberArray, image: bool = True, ) → None

Center the positions of the system to a given position.

Parameters:

position (Np1DIntArray) – The position to recenter the system to.
image (bool, optional) – If the system should be imaged back into the cell, by default True

compute_com_atomic_system( group=None, ) → AtomicSystem[source]

Computes a new AtomicSystem with the center of mass of the system or groups of atoms.

Parameters:: group (int, optional) – group of atoms to compute the center of mass of, by default None (all atoms)
Returns:: A new AtomicSystem with the center of mass of the system or groups of atoms.
Return type:: AtomicSystem
Raises:: AtomicSystemError – If the number of atoms in the selection is not a multiple of group.

copy() → AtomicSystem[source]

Returns a copy of the AtomicSystem.

Returns:: A copy of the AtomicSystem.
Return type:: AtomicSystem

fit_atomic_system( system: AtomicSystem, number_of_additions: PositiveInt = 1, max_iterations: PositiveInt = 100, distance_cutoff: PositiveReal = 1.0, max_displacement: PositiveReal | Np1DNumberArray = 0.1, rotation_angle_step: PositiveInt = 10, ) → list[AtomicSystem] | AtomicSystem[source]

Fit the positions of the system to the positions of another system.

Parameters:

system (AtomicSystem) – The system that should be fitted into the positions of the AtomicSystem.
number_of_additions (PositiveInt, optional) – The number of times the system should be fitted into the positions of the AtomicSystem, by default 1
max_iterations (PositiveInt, optional) – The maximum number of iterations to try to fit the system into the positions of the AtomicSystem, by default 100
distance_cutoff (PositiveReal, optional) – The distance cutoff for the fitting, by default 1.0
max_displacement (PositiveReal | Np1DNumberArray, optional) – The maximum displacement percentage for the fitting, by default 0.1
rotation_angle_step (PositiveInt, optional) – The angle step for the rotation of the system, by default 10
displacement (First a random center of mass is chosen and a random)
possible (is applied to the system. Then the system is rotated in all)
the (ways and the distances between the atoms are checked. If)
cutoff (distances are larger than the distance)
fitted. (the system is)

Returns:

The fitted AtomicSystem(s). If number_of_additions is 1, a single AtomicSystem is returned, otherwise a list of AtomicSystems is returned.

Return type:

List[AtomicSystem] | AtomicSystem

Raises:

AtomicSystemError – If the AtomicSystem has a vacuum cell.
ValueError – If the maximum displacement percentage is negative.
AtomicSystemError – If the system could not be fitted into the positions of the AtomicSystem within the maximum number of iterations.

image() → None: Images the positions of the system back into the cell.

isclose( other: Any, rtol: PositiveReal = 1e-09, atol: PositiveReal = 0.0, ) → Bool[source]

Checks whether the AtomicSystem is close to another AtomicSystem.

Parameters:

other (AtomicSystem) – The other AtomicSystem to compare to.
rtol (PositiveReal, optional) – The relative tolerance, by default 1e-9
atol (PositiveReal, optional) – The absolute tolerance, by default 0.0

Returns:

Whether the AtomicSystem is close to the other AtomicSystem.

Return type:

bool

nearest_neighbours( n: PositiveInt = 1, selection: SelectionCompatible = None, use_full_atom_info: bool = False, ) → tuple[Np2DIntArray, Np2DNumberArray]

Returns the n nearest neighbours of the given atoms in the system.

If no selection of target atoms is given, the n nearest neighbours of all atoms are returned. With the parameter ‘n’ the number of nearest neighbours can be specified.

Examples

>>> import numpy as np
>>> from PQAnalysis.atomic_system import AtomicSystem
>>> from PQAnalysis.core import Atom

>>> pos = np.array([[0, 0, 0], [0.5, 0.5, 0.5], [1, 1, 1]])
>>> atoms = [Atom('H'), Atom('H'), Atom('H')]
>>> system = AtomicSystem(atoms=atoms, pos=pos)

>>> system.nearest_neighbours()
(array([[1], [0], [1]]), array([[0.8660254], [0.8660254], [0.8660254]]))

>>> system.nearest_neighbours(n=2)
(array([[1, 2],
       [0, 2],
       [1, 0]]), array([[0.8660254 , 1.73205081],
       [0.8660254 , 0.8660254 ],
       [0.8660254 , 1.73205081]]))

>>> system.nearest_neighbours(selection=np.array([0]))
(array([[1]]), array([[0.8660254]]))

Parameters:

n (PositiveInt, optional) – The number of nearest neighbours to return, by default 1
selection (SelectionCompatible, optional) – Selection is either a selection object or any object that can be initialized via ‘Selection(selection)’, default None (all atoms)
use_full_atom_info (bool, optional) – If the full atom object should be used to match the atoms or only the element type, by default False

Returns:

The n nearest neighbours of the given atoms in the system. The first array contains the indices of the nearest neighbours and the second array contains the distances to the nearest neighbours.

Return type:

Tuple[Np2DIntArray, Np2DNumberArray]

set_charges_no_checks( charges: Np1DNumberArray, ) → None

Set the charges of the atoms in the system without any checks.

Parameters:: charges (Np1DNumberArray) – The charges of the atoms in the system.

set_forces_no_checks( forces: Np2DNumberArray, ) → None

Set the forces acting on the atoms in the system without any checks.

Parameters:: forces (Np2DNumberArray) – The forces acting on the atoms in the system.

set_pos_no_checks( pos: Np2DNumberArray, ) → None

Set the positions of the atoms in the system without any checks.

Parameters:: pos (Np2DNumberArray) – The positions of the atoms in the system.

set_vel_no_checks( vel: Np2DNumberArray, ) → None

Set the velocities of the atoms in the system without any checks.

Parameters:: vel (Np2DNumberArray) – The velocities of the atoms in the system.

property atomic_masses: Np1DNumberArray

The atomic masses of the atoms in the system.

Type:: Np1DNumberArray

property atoms: Atoms

The atoms in the system.

Type:: Atoms

property build_custom_element: CustomElement

The custom element of the atoms in the system.

Type:: CustomElement

property cell: Cell

The unit cell of the system.

Type:: Cell

property center_of_mass: Np1DNumberArray

The center of mass of the system.

Type:: Np1DNumberArray

property center_of_mass_residues: AtomicSystem

Computes the center of mass of the residues in the system.

Returns:

AtomicSystem – The center of mass of the residues in the system.
Raises
——-
AtomicSystemError – If the number of residues in the system is not a multiple of the number of atoms.
PQNotImplementedError – if system has forces, velocities or charges.
TODO
—–
Include also center of mass velocities, forces and so on…

property charges: Np1DNumberArray

The charges of the atoms in the system.

In order to set the charges of the atoms in the system, the number of atoms in the system has to be equal to the number of charges.

Type:: Np1DNumberArray

property combined_name: str

The combined name of the atoms in the system.

Type:: str

property energy: Real | None

The energy of the system.

Type:: float

fitting_logger = <CustomLogger PQAnalysis.atomic_system.atomic_system.fit_atomic_system (INFO)>

property forces: Np2DNumberArray

The forces acting on the atoms in the system.

In order to set the forces acting on the atoms in the system, the number of atoms in the system has to be equal to the number of forces.

Type:: Np2DNumberArray

handler = <StreamHandler <stderr> (INFO)>

property has_charges: bool

A boolean indicating if the system has charges for all atoms.

Type:: bool

property has_energy: bool

A boolean indicating if the system has an energy.

Type:: bool

property has_forces: bool

A boolean indicating if the system has forces for all atoms.

Type:: bool

property has_pos: bool

A boolean indicating if the system has positions for all atoms.

Type:: bool

property has_stress: bool

A boolean indicating if the system has a stress tensor.

Type:: bool

property has_vel: bool

A boolean indicating if the system has velocities for all atoms.

Type:: bool

property has_virial: bool

A boolean indicating if the system has a virial tensor.

Type:: bool

logger = <CustomLogger PQAnalysis.AtomicSystem (INFO)>

property mass: Real

The total mass of the system.

Type:: Real

property n_atoms: int

The number of atoms in the system.

Raises:: AtomicSystemError – If the number of atoms in the topology, positions, velocities, forces and charges are not equal (if they are not 0).
Type:: int

property pbc: bool

Whether the system has periodic boundary conditions.

Type:: bool

property pos: Np2DNumberArray

The positions of the atoms in the system.

In order to set the positions of the atoms in the system, the number of atoms in the system has to be equal to the number of positions.

Type:: Np2DNumberArray

property stress: Np2x2NumberArray | None

The stress tensor of the system.

Type:: Np2DNumberArray

property topology: Topology

The topology of the system.

In order to set the topology of the system, the number of atoms in the topology has to be equal to the number of atoms in the system.

Type:: Topology

property unique_element_names: list[str]

The unique element names of the atoms in the system.

Type:: List[str]

property vel: Np2DNumberArray

The velocities of the atoms in the system.

In order to set the velocities of the atoms in the system, the number of atoms in the system has to be equal to the number of velocities.

Type:: Np2DNumberArray

property virial: Np2x2NumberArray | None

The virial tensor of the system.

Type:: Np2DNumberArray