This package contains general functions and the most basic data containers such as Atom, Molecule and System. Plus some utility functions to create and edit common Systems.
Create an Atom instance. Atom is a generic container for particle data.
See also
Parameters
- type: str
- Atomic symbol
- r: {np.ndarray [3], list [3]}
- Atomic coordinates in nm
- export: dict, optional
- Additional export information.
Example
>>> Atom('H', [0.0, 0.0, 0.0])
In this example we’re attaching additional data to the Atom instance. The chemlab.io.GroIO can use this information when exporting in the gro format.
>>> Atom('H', [0.0, 0.0, 0.0], {'groname': 'HW1'})
Type : | str |
---|
The atomic symbol e.g. Ar, H, O.
Type : | np.ndarray(3) of floats |
---|
Atomic position in nm.
Type : | float |
---|
Mass in atomic mass units.
Type : | dict |
---|
Dictionary containing additional information when importing data from various formats.
See also
chemlab.io.gro.GroIO
Type : | tuple |
---|
This is a class attribute. The list of attributes that constitute the Atom. This is used to iterate over the Atom attributes at runtime.
Return a copy of the original Atom.
Create an Atom instance from a set of fields. This is a slightly faster way to initialize an Atom.
Example
>>> Atom.from_fields(type='Ar',
r_array=np.array([0.0, 0.0, 0.0]),
mass=39.948,
export={})
Molecule is a data container for a set of N Atoms.
See also
Parameters
Type : | np.ndarray((N,3), dtype=float) |
---|---|
Derived from: | Atom |
An array with the coordinates of each Atom.
Type : | np.ndarray(N, dtype=str) |
---|---|
Derived from: | Atom |
An array containing the chemical symbols of the constituent atoms.
Type : | np.ndarray(N, dtype=float) |
---|---|
Derived from: | Atom |
Array of masses.
Type : | np.ndarray(N, dtype=object) array of dicts |
---|---|
Derived from: | Atom |
Array of Atom.export dicts.
Type : | int |
---|
Number of atoms present in the molecule.
Type : | dict |
---|
Export information for the whole Molecule.
Type : | float |
---|
Mass of the whole molecule in amu.
Type : | float |
---|
Type : | float |
---|
Type : | str |
---|
The brute formula of the Molecule. i.e. "H2O"
Return a copy of the molecule instance
Create a Molecule from a set of Atom-derived arrays. Please refer to the Molecule Atom Derived Attributes. Only r_array and type_array are absolutely required, the others are optional.
>>> Molecule.from_arrays(r_array=np.array([[0.0, 0.0, 0.0],
[1.0, 0.0, 0.0],
[0.0, 1.0, 0.0]]),
type_array=np.array(['O', 'H', 'H']))
molecule(H2O)
Initializing a molecule in this way can be much faster than the default initialization method.
Translate the molecule to a new position r.
A data structure containing information of a set of N Molecules and NA Atoms.
Parameters
The System class has attributes derived both from the Molecule and the Atom class.
Type : | np.ndarray((NA, 3), dtype=float) |
---|---|
Derived from: | Atom |
Atomic coordinates.
Type : | np.ndarray(NA, dtype=float) |
---|---|
Derived from: | Atom |
Atomic masses.
Type : | np.ndarray(NA, dtype=object) array of str |
---|---|
Derived from: | Atom |
Array of all the atomic symbols. It can be used to select certain atoms in a system.
Example
Suppose you have a box of water defined by the System s, to select all oxygen atoms you can use the numpy selection rules:
>>> oxygens = s.type_array == 'O'
# oxygens is an array of booleans of length NA where
# each True corresponds to an oxygen atom i.e:
# [True, False, False, True, False, False]
You can use the oxygen array to access other properties:
>>> o_coordinates = s.r_array[oxygens]
>>> o_indices = np.arange(s.n_atoms)[oxygens]
Type : | np.ndarray(NA, dtype=object) array of dict |
---|---|
Derived from: | Atom |
Type : | np.ndarray(N, dtype=object) array of dict |
---|---|
Derived from: | Molecule |
Export information relative to the molecule.
Type : | np.ndarray((3,3), dtype=float) or None |
---|
Those are the three vectors that define of the periodic box of the system.
Example
To define an orthorombic box of size 3, 4, 5 nm:
>>> np.array([[3.0, 0.0, 0.0], # Vector a
[0.0, 4.0, 0.0], # Vector b
[0.0, 0.0, 5.0]]) # Vector c
Type : | float or None |
---|
Defines the size of the periodic box. Boxes defined with boxsize are cubic. Changes in boxsize are reflected in box.
Type : | int |
---|
Number of molecules.
Type : | int |
---|
Number of atoms.
Type : | np.ndarray(N, dtype=int) |
---|
Gives the starting index for each molecule in the atomic arrays. For example, in a System comprised of 3 water molecules:
>>> s.mol_indices
[0, 3, 6]
>>> s.type_array[0:3]
['O', 'H', 'H']
This array is used internally to retrieve all the Molecule derived data. Do not modify unless you know what you’re doing.
Type : | np.ndarray(N, dtype=int) |
---|
Contains the number of atoms present in each molecule
Add the molecule mol to a System initialized through System.empty.
Initialize an empty System containing n_mol Molecules and n_atoms Atoms. The molecules can be added by using the method add().
Example
How to initialize a system of 3 water molecules:
s = System.empty(3, 9)
for i in range(3):
s.add(water)
Initialize a System from its constituent arrays. It is the fastest way to initialize a System, well suited for reading one or more big System from data files.
Parameters
The following parameters are required:
To further speed up the initialization process you optionally pass the other derived arrays:
Example
Our classic example of 3 water molecules:
r_array = np.random.random((3, 9))
type_array = ['O', 'H', 'H', 'O', 'H', 'H', 'O', 'H', 'H']
mol_indices = [0, 3, 6]
System.from_arrays(r_array=r_array, type_array=type_array,
mol_indices=mol_indices)
Get the Molecule instance corresponding to the molecule at index.
This method is useful to use Molecule properties that are generated each time, such as Molecule.formula and Molecule.center_of_mass
Given the indices over molecules, return the indices over atoms.
Sort the molecules in the system according to their brute formula.
Create a system from the orig system by picking the molecules specified in selection.
Parameters
Example
In this example we can see how to select the molecules whose center of mass that is in the region of space x > 0.1:
s = System(...) # It is a set of 10 water molecules
select = []
for i range(s.n_mol):
if s.get_molecule(i).center_of_mass[0] > 0.1:
select.append(i)
subs = subsystem_from_molecules(s, np.ndarray(select))
Note
The API for operating on molecules is not yet fully developed. In the future there will be smarter ways to filter molecule attributes instead of looping and using System.get_molecule.
Generate a subsystem containing the atoms specified by selection. If an atom belongs to a molecule, the whole molecule is selected.
Example
This function can be useful when selecting a part of a system based on positions. For example, in this snippet you can see how to select the part of the system (a set of molecules) whose x coordinates is bigger than 1.0 nm:
s = System(...)
subs = subsystem_from_atoms(s.r_array[0,:] > 1.0)
Parameters
Returns:
A new System instance.
Generate a system by overlapping sysa and sysb. Overlapping molecules are removed by cutting the molecules of sysa that are found inside the space defined by sysb.box_vectors.
Parameters
Build a crystal from atomic positions, space group and cell parameters.
Parameters
This function was taken and adapted from the spacegroup module found in ASE.
The module spacegroup module was originally developed by Jesper Frills.