External API Objects

class psi4.driver.qcdb.Molecule(molinit=None, dtype=None, geom=None, elea=None, elez=None, elem=None, mass=None, real=None, elbl=None, name=None, units='Angstrom', input_units_to_au=None, fix_com=None, fix_orientation=None, fix_symmetry=None, fragment_separators=None, fragment_charges=None, fragment_multiplicities=None, molecular_charge=None, molecular_multiplicity=None, comment=None, provenance=None, connectivity=None, enable_qm=True, enable_efp=True, missing_enabled_return_qm='none', missing_enabled_return_efp='none', missing_enabled_return='error', tooclose=0.1, zero_ghost_fragments=False, nonphysical=False, mtol=0.001, verbose=1)

Class to store the elements, coordinates, fragmentation pattern, charge, multiplicity of a molecule. Largely replicates psi4’s libmints Molecule class, developed by Justin M. Turney and Andy M. Simmonett with incremental improvements by other psi4 developers. Major

This class extends qcdb.LibmintsMolecule and occasionally psi4.core.Molecule itself.

class qcelemental.datum.Datum(label, units, data, *, comment=None, doi=None, glossary=None, numeric=True)

Facilitates the storage of quantum chemical results by labeling them with basic metadata.

Parameters

• label (str) –

• units (str) –

• data (Any) –

• comment (str) –

• doi (Optional[str]) –

• glossary (str) –

• numeric (bool) –

Return type

None

label

Official label for data, often qcvar. May contain spaces.

Type

str

units

ASCII, LaTeX-like representation of units, without square brackets.

Type

str

data

Value for label.

Type

float or decimal.Decimal or numpy.ndarray

comment

Additional notes.

Type

str

doi

Literature citation or definition DOI link.

Type

str

glossary

Extended description or definition.

Type

str

numeric

Whether data is numeric. Pass True to disable validating data as float/Decimal/np.ndarray.

Type

bool

class qcelemental.models.types.Array

qcelemental.molutil.B787(cgeom, rgeom, cuniq, runiq, do_plot=False, verbose=1, atoms_map=False, run_resorting=False, mols_align=False, run_to_completion=False, algorithm='hungarian_uno', uno_cutoff=0.001, run_mirror=False)

Use Kabsch algorithm to find best alignment of geometry cgeom onto rgeom while sampling atom mappings restricted by runiq and cuniq.

Parameters

• rgeom (ndarray) – (nat, 3) array of reference/target/unchanged geometry. Assumed [a0] for RMSD purposes.

• cgeom (ndarray) – (nat, 3) array of concern/changeable geometry. Assumed [a0] for RMSD purposes. Must have same nat, units, and atom content as rgeom.

• runiq (ndarray) – (nat,) array of str indicating which rows (atoms) in rgeom are shuffleable without changing the molecule. Generally hashes of element symbol and mass are used, but could be as simple as [‘C’, ‘H’, ‘H’, ‘D’, ‘H’] for monodeuterated methane.

• cuniq (ndarray) – (nat,) array of str indicating which rows (atoms) in cgeom are shuffleable. See runiq for more details. Strings and count in cuniq must match runiq. That is, sorted(cuniq) == sorted(runiq).

• do_plot (bool) – Pops up a mpl plot showing before, after, and ref geometries.

• verbose (int) – Quantity of printing. 0 to silence.

• atoms_map (bool) – Whether atom1 of rgeom already corresponds to atom1 of cgeom and so on. If True, no resorting will be run, parameters runiq and cuniq may be passed as None, and much time will be saved.

• run_resorting (bool) – Run the resorting machinery even if unnecessary because atoms_map=True.

• mols_align (Union[bool, float]) – Whether ref_mol and concern_mol have identical geometries by eye (barring orientation or atom mapping) and expected final RMSD = 0. If True, procedure is truncated when RMSD condition met, saving time. If float, convcrit at which search for minimium truncates.

• run_to_completion (bool) – Run reorderings to completion (past RMSD = 0) even if unnecessary because mols_align=True. Used to test worst-case timings.

• algorithm (str) – {‘hungarian_uno’, ‘permutative’} When atoms_map=False, screening algorithm for plausible atom mappings. permutative suitable only for small systems.

• uno_cutoff (float) – TODO

• run_mirror (bool) – Run alternate geometries potentially allowing best match to rgeom from mirror image of cgeom. Only run if system confirmed to be nonsuperimposable upon mirror reflection.

Returns

First item is RMSD [A] between rgeom and the optimally aligned geometry computed. Second item is a AlignmentMill with fields (shift, rotation, atommap, mirror) that prescribe the transformation from cgeom and the optimally aligned geometry.

Return type

float, tuple

qcelemental.molparse.from_arrays(*, geom=None, elea=None, elez=None, elem=None, mass=None, real=None, elbl=None, name=None, units='Angstrom', input_units_to_au=None, fix_com=None, fix_orientation=None, fix_symmetry=None, fragment_separators=None, fragment_charges=None, fragment_multiplicities=None, molecular_charge=None, molecular_multiplicity=None, comment=None, provenance=None, connectivity=None, fragment_files=None, hint_types=None, geom_hints=None, geom_unsettled=None, variables=None, domain='qm', missing_enabled_return='error', np_out=True, speclabel=True, tooclose=0.1, zero_ghost_fragments=False, nonphysical=False, mtol=0.001, copy=True, verbose=1)

Compose a Molecule dict from unvalidated arrays and variables, returning dict.

See fields of Return molrec below. Required parameters (for QM XYZ) are geom and one of elem, elez, elbl (speclabel=True)

Parameters

• geom (Union[List[List[float]], numpy.ndarray]) – (nat, 3) or (3 * nat, ) ndarray or list o’lists of Cartesian coordinates.

• fragment_separators (Union[List[int], numpy.ndarray]) – (nfr - 1, ) list of atom indices at which to split geom into fragments.

• elbl (Union[List[str], numpy.ndarray]) – (nat, ) Label extending elem symbol, possibly conveying ghosting, isotope, mass, tagging information.

• tooclose (float) – Interatom distance (native geom units) nearer than which atoms not allowed.

• nonphysical (bool) – Do allow masses outside an element’s natural range to pass validation?

• speclabel (bool) – If True, interpret elbl as potentially full nucleus spec including ghosting, isotope, mass, tagging information, e.g., @13C_mine or He4@4.01. If False, interpret elbl as only the user/tagging extension to nucleus label, e.g. _mine or 4 in the previous examples.

• missing_enabled_return (str) – {‘minimal’, ‘none’, ‘error’} What to do when an enabled domain is of zero-length? Respectively, return a fully valid but empty molrec, return empty dictionary, or throw error.

• np_out (bool) – When True, fields geom, elea, elez, elem, mass, real, elbl will be ndarray. Use False to get a json-able version.

Returns

• molrec (dict) – Molecule dictionary spec follows. Its principles are

  (1) contents are fully validated and defaulted - no error checking necessary,

  (2) contents may be mildly redundant - atomic numbers and element symbols present,

  (3) big system, nat-length single-type arrays, not small system, nat-number heterogeneous objects,

  (4) some fields are optional (e.g., fix_symmetry) but largely self-describing so units or fix_com must be present.

  (5) apart from some mild optional fields, _all_ fields will be present (corollary of “fully validated and defaulted”) - no need to check for every key. in some cases like efp, keys will appear in blocks, so pre-handshake there will be a few hint keys and post-handshake they will be joined by full qm-like molrec.

  (6) molrec should be idempotent through this function (equiv to schema validator) but are not idempotent throughout its life. if fields permit, frame may be changed. Future? if fields permit, mol may be symmetrized. Coordinates and angles may change units or range if program returns them in only one form.

• name (str, optional) – Label for molecule; should be valid Python identifier.

• units ({‘Angstrom’, ‘Bohr’}) – Units for geom.

• input_units_to_au (float, optional) – If units=’Angstrom’, overrides consumer’s value for [A]–>[a0] conversion.

• fix_com (bool) – Whether translation of geom is allowed or disallowed.

• fix_orientation (bool) – Whether rotation of geom is allowed or disallowed.

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

• geom (ndarray of float) – (3 * nat, ) Cartesian coordinates in units.

• elea (ndarray of int) – (nat, ) Mass number for atoms, if known isotope, else -1.

• elez (ndarray of int) – (nat, ) Number of protons, nuclear charge for atoms.

• elem (ndarray of str) – (nat, ) Element symbol for atoms.

• mass (ndarray of float) – (nat, ) Atomic mass [u] for atoms.

• real (ndarray of bool) – (nat, ) Real/ghostedness for atoms.

• elbl (ndarray of str) – (nat, ) Label with any tagging information from element spec.

• fragment_separators (list of int) – (nfr - 1, ) list of atom indices at which to split geom into fragments.

• fragment_charges (list of float) – (nfr, ) list of charge allocated to each fragment.

• fragment_multiplicities (list of int) – (nfr, ) list of multiplicity allocated to each fragment.

• molecular_charge (float) – total charge on system.

• molecular_multiplicity (int) – total multiplicity on system.

• comment (str, optional) – Additional comment for molecule.

• provenance (dict of str) – Accumulated history of molecule, with fields “creator”, “version”, “routine”.

• connectivity (list of tuples of int, optional) – (nbond, 3) list of (0-indexed) (atomA, atomB, bond_order) (int, int, double) tuples

• EFP extension (this + units is minimal)

• fragment_files (list of str) – (nfr, ) lowercased names of efp meat fragment files.

• hint_types ({‘xyzabc’, ‘points’}) – (nfr, ) type of fragment orientation hint.

• geom_hints (list of lists of float) – (nfr, ) inner lists have length 6 (xyzabc; to orient the center) or 9 (points; to orient the first three atoms) of the EFP fragment.

• QMVZ extension (geom_unsettled replaces geom)

• geom_unsettled (list of lists of str) – (nat, ) all-string Cartesian and/or zmat anchor and value contents mixing anchors, values, and variables.

• variables (list of pairs) – (nvar, 2) pairs of variables (str) and values (float). May be incomplete.

Raises

qcelemental.ValidationError – For most anything wrong.

class qcelemental.ValidationError(msg)

Error called for problems with syntax input file. Prints error message msg to standard output stream.