Molecule Model

A Python implementations of the MolSSI QCSchema Molecule object. A “Molecule” many definitions of Molecule depending on the domain; this particular Molecule is an immutable 3D Cartesian representation with support for quantum chemistry constructs.

Creation

A Molecule can be created using the normal kwargs fashion as shown below:

>>> mol = qcel.models.Molecule(**{"symbols":["He"], "geometry": [0, 0, 0]})

In addition, there is the from_data attribute to create a molecule from standard strings:

>>> mol = qcel.models.Molecule.from_data("He 0 0 0")
>>> mol
<    Geometry (in Angstrom), charge = 0.0, multiplicity = 1:

       Center              X                  Y                   Z
    ------------   -----------------  -----------------  -----------------
    He                0.000000000000     0.000000000000     0.000000000000
>

Identifiers

A number of unique identifiers are automatically created for each molecule. Additional implementation such as InChI and SMILES are actively being looked into.

Molecular Hash

A molecule hash is automatically created to allow each molecule to be uniquely identified. The following keys are used to generate the hash:

  • symbols

  • masses (1.e-6 tolerance)

  • molecular_charge (1.e-4 tolerance)

  • molecular_multiplicity

  • real

  • geometry (1.e-8 tolerance)

  • fragments

  • fragment_charges (1.e-4 tolerance)

  • fragment_multiplicities

  • connectivity

Hashes can be acquired from any molecule object and a FractalServer automatically generates canonical hashes when a molecule is added to the database.

>>> mol = qcel.models.Molecule(**{"symbols": ["He", "He"], "geometry": [0, 0, -3, 0, 0, 3]})
>>> mol.get_hash()
'84872f975d19aafa62b188b40fbadaf26a3b1f84'

Molecular Formula

The molecular formula is also available sorted in alphabetical order with title case symbol names. Any symbol with a count of one does not have a number associated with it.

>>> mol.get_molecular_formula()
    'He2'

Fragments

A Molecule with fragments can be created either using the -- separators in the from_data function or by passing explicit fragments in the Molecule constructor:

>>> mol = qcel.models.Molecule.from_data(
>>>       """
>>>       Ne 0.000000 0.000000 0.000000
>>>       --
>>>       Ne 3.100000 0.000000 0.000000
>>>       """)

>>> mol = qcel.models.Molecule(
>>>       geometry=[0, 0, 0, 3.1, 0, 0],
>>>       symbols=["Ne", "Ne"],
>>>       fragments=[[0], [1]]
>>>       )

Fragments from a molecule containing fragment information can be aquired by:

>>> mol.get_fragment(0)
<    Geometry (in Angstrom), charge = 0.0, multiplicity = 1:

       Center              X                  Y                   Z
    ------------   -----------------  -----------------  -----------------
    Ne                0.000000000000     0.000000000000     0.000000000000
>

Obtaining fragments with ghost atoms is also supported:

>>> mol.get_fragment(0, 1)
<    Geometry (in Angstrom), charge = 0.0, multiplicity = 1:

       Center              X                  Y                   Z
    ------------   -----------------  -----------------  -----------------
    Ne                0.000000000000     0.000000000000     0.000000000000
    Ne      (Gh)      3.100000000572     0.000000000000     0.000000000000
>

Molecule Attributes

Below are the documentations for all attributes and initialization keywords for a Molecule object

class qcelemental.models.Molecule(orient=False, validate=None, **kwargs)[source]

The fundamental representation of a Molecule inside the QCArchive Ecosystem. This model contains data for atomic elements, coordinates, connectivity, charges, fragmentation, etc. The model also supports orientation and measurement utilities.

All Molecule objects are oriented via inertia tensor with the center-of-mass at (0,0,0) unless explicitly blocked.

All Molecule objects have coordinates truncated to 8 (GEOMETRY_NOISE) decimal places and mass and charge truncated to 6 (MASS_NOISE) and 4 (CHARGE_NOISE), respectively, unless explicitly blocked.

Parameters
  • schema_name (ConstrainedStrValue, Default: qcschema_molecule) – The QCSchema specification this model conforms to. Explicitly fixed as qcschema_molecule.

  • schema_version (int, Default: 2) – The version number of schema_name that this Molecule model conforms to.

  • validated (bool, Default: False) – A boolean indicator (for speed purposes) that the input Molecule data has been previously checked for schema (data layout and type) and physics (e.g., non-overlapping atoms, feasible multiplicity) compliance. This should be False in most cases. A True setting should only ever be set by the constructor for this class itself or other trusted sources such as a Fractal Server or previously serialized Molecules.

  • symbols (Array) – An ordered (nat,) array-like object of atomic elemental symbols of shape (nat,). The index of this attribute sets atomic order for all other per-atom setting like real and the first dimension of geometry. Ghost/Virtual atoms must have an entry in this array-like and are indicated by the matching the 0-indexed indices in real field.

  • geometry (Array) – An ordered (nat,3) array-like for XYZ atomic coordinates [a0]. Atom ordering is fixed; that is, a consumer who shuffles atoms must not reattach the input (pre-shuffling) molecule schema instance to any output (post-shuffling) per-atom results (e.g., gradient). Index of the first dimension matches the 0-indexed indices of all other per-atom settings like symbols and real. Can also accept array-likes which can be mapped to (nat,3) such as a 1-D list of length 3*nat, or the serialized version of the array in (3*nat,) shape; all forms will be reshaped to (nat,3) for this attribute.

  • name (str, Optional) – A common or human-readable name to assign to this molecule. Can be arbitrary.

  • identifiers (Identifiers, Optional) – An optional dictionary of additional identifiers by which this Molecule can be referenced, such as INCHI, canonical SMILES, etc. See the :class:Identifiers model for more details.

  • comment (str, Optional) – Additional comments for this Molecule. Intended for pure human/user consumption and clarity.

  • molecular_charge (float, Default: 0.0) – The net electrostatic charge of this Molecule.

  • molecular_multiplicity (int, Default: 1) – The total multiplicity of this Molecule.

  • masses (Array, Optional) – An ordered 1-D array-like object of atomic masses [u] of shape (nat,). Index order matches the 0-indexed indices of all other per-atom settings like symbols and real. If this is not provided, the mass of each atom is inferred from their most common isotope. If this is provided, it must be the same length as symbols but can accept None entries for standard masses to infer from the same index in the symbols field.

  • real (Array, Optional) – An ordered 1-D array-like object of shape (nat,) indicating if each atom is real (True) or ghost/virtual (False). Index matches the 0-indexed indices of all other per-atom settings like symbols and the first dimension of geometry. If this is not provided, all atoms are assumed to be real (True).If this is provided, the reality or ghostality of every atom must be specified.

  • atom_labels (Array, Optional) – Additional per-atom labels as a 1-D array-like of of strings of shape (nat,). Typical use is in model conversions, such as Elemental <-> Molpro and not typically something which should be user assigned. See the comments field for general human-consumable text to affix to the Molecule.

  • atomic_numbers (Array, Optional) – An optional ordered 1-D array-like object of atomic numbers of shape (nat,). Index matches the 0-indexed indices of all other per-atom settings like symbols and real. Values are inferred from the symbols list if not explicitly set.

  • mass_numbers (Array, Optional) – An optional ordered 1-D array-like object of atomic mass numbers of shape (nat). Index matches the 0-indexed indices of all other per-atom settings like symbols and real. Values are inferred from the most common isotopes of the symbols list if not explicitly set.

  • connectivity (List[Tuple[int, int, float]], Optional) – The connectivity information between each atom in the symbols array. Each entry in this list is a Tuple of (atom_index_A, atom_index_B, bond_order) where the atom_index matches the 0-indexed indices of all other per-atom settings like symbols and real.

  • fragments (List[Array], Optional) – An indication of which sets of atoms are fragments within the Molecule. This is a list of shape (nfr) of 1-D array-like objects of arbitrary length. Each entry in the list indicates a new fragment. The index of the list matches the 0-indexed indices of fragment_charges and fragment_multiplicities. The 1-D array-like objects are sets of atom indices indicating the atoms which compose the fragment. The atom indices match the 0-indexed indices of all other per-atom settings like symbols and real.

  • fragment_charges (List[float], Optional) – The total charge of each fragment in the fragments list of shape (nfr,). The index of this list matches the 0-index indices of fragment list. Will be filled in based on a set of rules if not provided (and fragments are specified).

  • fragment_multiplicities (List[int], Optional) – The multiplicity of each fragment in the fragments list of shape (nfr,). The index of this list matches the 0-index indices of fragment list. Will be filled in based on a set of rules if not provided (and fragments are specified).

  • fix_com (bool, Default: False) – An indicator which prevents pre-processing the Molecule object to translate the Center-of-Mass to (0,0,0) in euclidean coordinate space. Will result in a different geometry than the one provided if False.

  • fix_orientation (bool, Default: False) – An indicator which prevents pre-processes the Molecule object to orient via the inertia tensor.Will result in a different geometry than the one provided if False.

  • fix_symmetry (str, Optional) – Maximal point group symmetry which geometry should be treated. Lowercase.

  • provenance (Provenance, Default: {‘creator’: ‘QCElemental’, ‘version’: ‘v0.6.1+0.g444ac8d.dirty’, ‘routine’: ‘qcelemental.models.molecule’}) – The provenance information about how this Molecule (and its attributes) were generated, provided, and manipulated.

  • id (Any, Optional) – A unique identifier for this Molecule object. This field exists primarily for Databases (e.g. Fractal’s Server) to track and lookup this specific object and should virtually never need to be manually set.

  • extras (Dict[str, Any], Optional) – Extra information to associate with this Molecule.