API

MOPAC’s application programming interface (API) is intended to streamline access and improve performance for the most commonly used features, while also providing access to MOPAC’s conventional file-based operations.

The Python API is located in the api.py module of mopactools, which can be imported as:

from mopactools import api

Conventional MOPAC calculations using an input file can then be run by using the function:

mopactools.api.from_file(input_path)

Run a MOPAC calculation from an input file that is equivalent to running MOPAC on the command line.

For example, an input file at the path dir/name.mop should generate an ouput file at the path dir/name.out. MOPAC also accepts input files with the .dat extension or no file extension, and it can also use the input block at the bottom of an archive file (.arc) that was generated by a previous MOPAC calculation if a .arc file is given as an input file. In addition to a primary output file (.out), MOPAC may generate other outputs such as an archive file (.arc) and a machine-readable output data file (.aux) that can be requested using the AUX keyword.

Parameters

input_pathpath-like

The path to a MOPAC input file.

Returns

statusbool

Truth value indicating whether or not an error occured during the MOPAC calculation.

The rest of the API functionality is presently limited to the most commonly used features in MOPAC, which is the calculation of an electronic ground state, with an option to relax the atomic coordinates to their local energy minimum, and a further option to calculate vibrational properties at that relaxed geometry. These features can be run using either the conventional MOPAC solver or the linear-scaling MOZYME solver. The MOZYME solver is faster for larger systems, but only works under a narrower set of conditions. Specifically, the MOZYME solver only works for closed-shell systems with a covalent and/or ionic bonding structure that can be inferred from the geometry. Otherwise, MOZYME will fail and report an error.

This functionality is accessed through the function:

mopactools.api.from_data(system, state, relax=False, vibe=False)

Run a MOPAC calculation defined by the input data.

Parameters

systemMopacSystem

The description of the atomistic system to be calculated.

stateMopacState or MozymeState

The electronic ground state that the calculation is initialized to. The type is used to determine whether to run a MOPAC or MOZYME calculation.

relaxbool, optional

Relax the positions of the atoms into a local energy minimum.

vibebool, optional

Perform a vibrational calculation on a geometry that is in a local energy minimum.

Returns

propertiesMopacProperties

The physical properties calculated by MOPAC, with vibrational frequencies, properties.freq, and displacement vectors, properties.disp, set to None unless vibe is True.

The Python data layout follows the underlying Fortran (with C bindings) data layout. There is a MopacSystem object for the atomistic system data and computational options that define the calculation, a MopacState or MozymeState object that describes the electronic ground state at the beginning and end of the calculation, and a MopacProperties object that stores the important physical properties that were evaluated during the calculation. The MopacSystem object is strictly an input that is not altered by the calculation, while the MopacState and MozymeState objects act as both inputs and outputs, so the input object is altered by the function call. The initial value of MopacState or MozymeState is used as the initial guess for the self-consistent field (SCF) cycle, and the final value is the converged ground state at the end of the SCF cycle. An uninitialized MopacState or MozymeState instance correspond to the default guesses for the electronic ground state (an atomic guess for MOPAC and a Lewis-bonded guess for MOZYME). The MopacProperties object is strictly an output, therefore it is returned by the API call rather than specified as a function argument.

Note

The relaxed geometry of a system is stored in MopacProperties.coord_update rather than MopacSystem.coord because MopacSystem is not altered by calls to api.from_data. The user has to update the geometry themselves if they want it to be used in subsequent calculations.

The specification of this API data structures is as follows:

class mopactools.api.MopacSystem(c_system=None)

Information defining a MOPAC calculation of an atomistic system

Attributes

natomint

The number of atoms in the system.

natom_moveint

The number of atoms in the system that are allowed to move. The first natom_move atoms in the list can move, and the last natom-natom_move atoms cannot.

chargeint

The total charge on the system.

spinint

The excess electronic spin on the system. For example, spin=0 is a singlet and spin=1 is a triplet for an even number of electrons, and spin=0 is a doublet for an odd number of electrons.

model{“PM7”, “PM6-D3H4”, “PM6-ORG”, “PM6”, “AM1”, “RM1”} or int

The semiempirical model used for the calculation, or the corresponding integer value in the base API layer.

epsilonfloat

The dielectric constant of the implicit solvent that the atomistic system is embedded in. There is no implicit solvent if epsilon=1.0, the dielectric constant of empty vacuum.

atomndarray of ints, or list of strs or ints

An array containing the atomic numbers of the atoms being simulated. This can also be specified as a list of atomic numbers and/or element symbols, which will be converted into an array when MopacSystem is attached to the MOPAC library.

coordndarray

An array containing the Cartesian coordinates of atoms in xyz order and Angstrom units.

nlatticeint

The number of lattice/translation vectors that define periodic boundary conditions.

nlattice_moveint

The number of lattice/translation vectors that are allowed to move. The first nlattice_move vectors can move, and the last nlattice-nlattice_move vectors cannot.

pressurefloat

The external pressure applied to the system in units of Gigapascals (GPa).

latticendarray

An array contains the Cartesian coordinates of lattice vectors in xyz order and Angstrom units.

tolerancefloat

The relative numerical tolerances of the MOPAC calculation, with tolerance=1.0 as default. The default is appropriate for most calculations, and this is only intended to test convergence.

max_timeint

The maximum run time that a MOPAC calculation is allowed to use in seconds.

Methods

attach()

Attach to a c_mopac_system instance that uses Python memory.

class mopactools.api.MopacState(c_state=None)

Electronic ground state in a conventional MOPAC calculation

Attributes

mpackint

Size of the packed density matrix. An uninitialized MOPAC ground state is denoted by mpack=0.

uhfbool

Flag specifying if the ground state uses spin-unrestricted electronic orbitals.

pandarray

Electronic density matrix for the alpha electrons in a packed lower-triangle format.

pbndarray

If bool=True, electronic density matrix for the beta electrons in a packed lower-triangle format.

Methods

attach()

Attach to a c_mopac_state instance and move memory into MOPAC.

update()

Update the Python data to be consistent with the MOPAC data.

detach()

Detach from a c_mopac_state instance and move memory into Python.

class mopactools.api.MozymeState(c_state=None)

Electronic ground state in a linear-scaling MOZYME calculation

Attributes

numatint

Number of “real” atoms with active electrons. An uninitialized MOZYME ground state is denoted by numat=0.

nbondsndarray of ints

Number of Lewis bonds for each real atom.

ibondsndarray of ints

List of Lewis-bonded real atoms for each real atom.

iorbsndarray of ints

Number of orbitals for each real atom.

noccupiedint

Number of occupied local molecular orbitals (LMOs).

ncfndarray of ints

Number of atoms in each occupied LMO.

nvirtualint

Number of virtual LMOs.

ncendarray of ints

Number of atoms in each virtual LMO.

icoccndarray of ints

1-based index of each real atom in each occupied LMO.

icvirndarray of ints

1-based index of each real atom in each virtual LMO.

coccndarray

orbital coefficients of each real atom in each occupied LMO.

cvirndarray

orbital coefficients of each real atom in each virtual LMO.

Methods

attach()

Attach to a c_mozyme_state instance and move memory into MOPAC.

update()

Update the Python data to be consistent with the MOPAC data.

detach()

Detach from a c_mozyme_state instance and move memory into Python.

class mopactools.api.MopacProperties(c_properties=None, system=None)

Properties generated by a MOPAC calculation

Attributes

heatfloat

The heat of formation of the system in units of kcal/mol.

dipolendarray

The dipole vector of the system in units of Debye.

chargendarray

The partial charge on each atom in the system.

coord_updatendarray

The updated Cartesian coordinates of the moveable atoms in xyz format and Angstrom units.

coord_derivndarray

The heat-of-formation gradients of the moveable atoms in xyz format and kcal/mol/Angstrom units.

freqndarray

The viibrational frequencies of the normal modes of the moveable atoms in units of 1/cm.

dispndarray

The displacement vectors of the normal modes of the moveable atoms in xyz format.

bond_ordercsc_matrix

The bond-order matrix with diagonal entries corresponding to the valence of atoms.

lattice_updatendarray

The updated Cartesian coordinates of the moveable lattice vectors in xyz format and Angstrom units.

lattice_derivndarray

The heat-of-formation gradients of the moveable lattice vectors in xyz format and kcal/mol/Angstrom units.

stressndarray

The stress tensor in Voigt form (xx, yy, zz, yz, xz, xy) and Gigapascal units.

Methods

detach()

Detach from a c_mopac_properties instance and move memory into Python.

Finally, version information about the MOPAC shared library is provided by the module variable:

mopactools.api.VERSION

Semantic version number of the MOPAC shared library

Warning

None of the MOPAC API functionality is thread-safe. Typical usage of Python occurs in a single thread, so this is not relevant to normal operations. However, Python is slowly expanding its multi-threading support, so this may eventually be a problem. Making MOPAC itself thread-safe is not a realistic possibility without completely rewriting it, but the Python API wrapper could be made thread-safe if each thread loads a separate instance of the MOPAC shared library.