exatomic.core.universe module

The Atomic Universe

The Universe object is a subclass of Container that stores data coming from computational chemistry experiments in a unified and systematic way. Data is organized into “frames”. A frame is an axis that can represent time (e.g. molecular dynamics simulations), step number (e.g. geometry optimization), or an arbitrary index (e.g. density functional theory exchange correlation functional).

class exatomic.core.universe.Meta(name, bases, clsdict)[source]

Bases: TypedMeta

atom: alias of Atom

frame: alias of Frame

atom_two: alias of AtomTwo

unit_atom: alias of UnitAtom

projected_atom: alias of ProjectedAtom

visual_atom: alias of VisualAtom

frequency: alias of Frequency

molecule: alias of Molecule

molecule_two: alias of MoleculeTwo

field: alias of AtomicField

orbital: alias of Orbital

momatrix: alias of MOMatrix

cart_momatrix: alias of MOMatrix

sphr_momatrix: alias of MOMatrix

excitation: alias of Excitation

overlap: alias of Overlap

density: alias of DensityMatrix

basis_set_order: alias of BasisSetOrder

cart_basis_set_order: alias of BasisSetOrder

sphr_basis_set_order: alias of BasisSetOrder

uncontracted_basis_set_order: alias of BasisSetOrder

basis_set: alias of BasisSet

basis_dims: alias of dict

basis_functions: alias of BasisFunctions

contribution: alias of DataFrame

multipole: alias of DataFrame

tensor: alias of Tensor

class exatomic.core.universe.Universe(**kwargs)[source]

Bases: Container

The atomic container is called a universe because it represents everything known about the atomistic simulation (whether quantum or classical). This includes data such as atomic coordinates, molecular orbital energies, as well as (classical phenomena) such as two body distances, etc.

frame

State variables:

Type:: Frame

atom

(Classical) atomic data (e.g. coordinates)

Type:: Atom

atom_two

Interatomic distances

Type:: AtomTwo

molecule

Molecule information

Type:: Molecule

orbital

Molecular orbital information

Type:: Orbital

momatrix

Molecular orbital coefficient matrix

Type:: MOMatrix

frequency

Vibrational modes and atom displacements

Type:: Frequency

excitation

Electronic excitation information

Type:: Excitation

basis_set

Basis set specification

Type:: BasisSet

overlap

The overlap matrix

Type:: Overlap

basis_functions

Basis function evaluation

Type:: BasisFunctions

field

Scalar fields (MOs, densities, etc.)

Type:: AtomicField

property current_momatrix

property current_basis_set_order

property periodic

property orthorhombic

classmethod from_cclib(ccobj)[source]

compute_frame()[source]: Compute a minmal frame table.

compute_unit_atom()[source]: Compute minimal image for periodic systems.

compute_visual_atom()[source]

compute_atom_two(*args, **kwargs)[source]

Compute interatomic two body properties (e.g. bonds).

Parameters:

mapper (dict) – Custom radii to use when determining bonds
bond_extra (float) – Extra additive factor to use when determining bonds

compute_bonds(*args, **kwargs)[source]: Updates bonds (and molecules).

See also

compute_bonds()

compute_bond_count()[source]: Compute bond counts and attach them to the Atom table.

compute_molecule()[source]: Compute the Molecule table.

compute_molecule_com()[source]

compute_atom_count()[source]: Compute number of atoms per frame.

compute_molecule_count()[source]: Compute number of molecules per frame.

compute_basis_dims()[source]: Compute basis dimensions.

compute_basis_functions(**kwargs)[source]

compute_uncontracted_basis_set_order()[source]: Compute an uncontracted basis set order.

enumerate_shells(frame=0)[source]

Extract minimal information from the universe to be used in numba-compiled numerical procedures.

pointers, atoms, shells = uni.enumerate_shells()

Parameters:: frame (int) – state of the universe (default 0)

add_field(field)[source]

Adds a field object to the universe.

# Assuming field[n] is of type AtomicField
uni.add_field(field)
uni.add_field([field1, field2])

Parameters:: field (iter, exatomic.core.field.AtomicField) – field(s) to add

Warning

Adding a large number of (high resolution) fields may impact performance.

add_molecular_orbitals(field_params=None, mocoefs=None, vector=None, frame=0, replace=False, inplace=True, verbose=True, irrep=None)[source]

Add molecular orbitals to universe.

uni.add_molecular_orbitals()                  # Default around (HOMO-5, LUMO+7)
uni.add_molecular_orbitals(vector=range(5))   # Specifies the first 5 MOs
uni.add_molecular_orbitals(                   # Higher resolution fields
    field_params={'rmin': -10,                # smallest value in 'x', 'y', 'z'
                  'rmax': 10,                 # largest value in 'x', 'y', 'z'
                  'nr': 100})                 # number of points between rmin and rmax
uni.field                                     # The field parameters
uni.field.field_values                        # The generated scalar fields

Parameters:

field_params (dict, pd.Series) – see exatomic.algorithms.orbital_util.make_fps()
mocoefs (str) – column in MOMatrix
vector (iter) – indices of orbitals to evaluate (0-based)
frame (int) – frame of atomic positions for the orbitals
replace (bool) – remove previous fields (default False)
inplace (bool) – add directly to uni or return AtomicField (default True)
verbose (bool) – print timing statistics (default True)
irrep (int) – irreducible representation

Warning

Default behavior just continually adds fields to the universe. This can affect performance if adding many fields. replace modifies this behavior.

Warning

Specifying very high resolution field parameters, e.g. ‘nr’ > 100 may slow things down and/or crash the kernel. Use with caution.

write_cube(file_name='output', field_number=0)[source]

Write to a file in cube format for a single 3D scalar field in universe object.

uni.add_molecular_orbitals()                  # Default around (HOMO-5, LUMO+7)
uni.write_cube('cubefile', 0)                    # write to cubefile.cube for HOMO-5

Parameters:

file_name (str) – name of the output file without file extension
field_number (int) – number of the single field starting with 0

Returns:

None

property atom

property atom_two

property basis_dims

property basis_functions

property basis_set

property basis_set_order

property cart_basis_set_order

property cart_momatrix

property contribution

property density

property excitation

property field

property frame

property frequency

property molecule

property molecule_two

property momatrix

property multipole

property orbital

property overlap

property projected_atom

property sphr_basis_set_order

property sphr_momatrix

property tensor

property uncontracted_basis_set_order

property unit_atom

property visual_atom

exatomic.core.universe.concat(name=None, description=None, meta=None, *universes)[source]: Warning

This function is not fully featured or tested yet!

exatomic.core.universe.basis_function_contributions(universe, mo, mocoefs='coef', tol=0.01, ao=None, frame=0)[source]

Provided a universe with momatrix and basis_set_order attributes, return the major basis function contributions of a particular molecular orbital.

# display the 16th orbital coefficients > abs(0.15)
basis_function_contributions(uni, 15, tol=0.15) # 0-based indexing!

Parameters:

(class (universe) – exatomic.core.universe.Universe): a universe
mo (int) – molecular orbital index
mocoefs (str) – column of interest in universe.momatrix
tol (float) – minimum value of coefficient by which to filter
frame (int) – frame of the universe (default is zero)

Returns:

joined (pd.DataFrame) – a join of momatrix and basis_set_order