spycci.core module

The spycci.core.base sub-module

class spycci.core.base.Engine(method)

Simple base class for the definition of a software engine. The class sets the level_of_theory and method attributes.

Parameters:

method (str) – The string indicating the method to be used in the calculation.

The spycci.core.dependency_finder sub-module

spycci.core.dependency_finder.locate_crest(version=None)

Locates the path to the ‘crest’ executable from the system PATH. If specified, checks that the correct version of crest is loaded.

Parameters:

version (str) – The string defining the desired version of crest. If set to None (default) all versions of crest are accepted.

Returns:

The path to the crest executable file.

Return type:

str

spycci.core.dependency_finder.locate_dftbparamdir()

Locates the path to the DFTBPLUS_PARAM_DIR environment variable.

Returns:

The path to the DFTBPLUS_PARAM_DIR environment variable.

Return type:

str

spycci.core.dependency_finder.locate_dftbplus(version=None)

Locates the path to the ‘dftb+’ executable from the system PATH. If specified, checks that the correct version of dftb+ is loaded.

Parameters:

version (str) – The string defining the desired version of dftb+. If set to None (default) all versions of dftb+ are accepted.

Returns:

The path to the dftb+ executable file.

Return type:

str

spycci.core.dependency_finder.locate_executable(name)

Locates a given executable in the system PATH. If the program is found the path is returned, else an exception is raised.

Parameters:

name (str) – The name of the program to locate.

Raises:

RuntimeError – Exception raised if the program is not found in the system path.

Returns:

The path to the requested program.

Return type:

str

spycci.core.dependency_finder.locate_orca(version=None, get_folder=False)

Locates the path to the ‘orca’ executable from the system PATH. If the executable is located checks that the correct version of OpenMPI is exported (explicit reference to the static builds). If specified, checks that the correct version of orca is loaded.

Parameters:

  • version (str) – The string defining the desired version of orca. If set to None (default) all versions of orca are accepted.

  • get_folder (bool) – If set to True will return the path of the folder containing the orca executable instead of the default path to the executable itself. Equivalent to applying an rstrip(‘/orca’) to the executable path

Returns:

The path to the orca executable file.

Return type:

str

spycci.core.dependency_finder.locate_vmd()

Locate the path to the ‘vmd’ folder from the system PATH.

Returns:

The path to the vmd base folder (the one containing the bin and lib subfolders)

Return type:

str

spycci.core.dependency_finder.locate_xtb(version=None)

Locates the path to the ‘xtb’ executable from the system PATH. If specified, checks that the correct version of xtb is loaded.

Parameters:

version (str) – The string defining the desired version of xtb. If set to None (default) all versions of xtb are accepted.

Returns:

The path to the xtb executable file.

Return type:

str

The spycci.core.geometry sub-module

class spycci.core.geometry.MolecularGeometry

The MolecularGeometry class implements all the functions required to operate on the geometric properties of a given molecule or molecular aggregate.

level_of_theory_geometry

The level of theory at which the geometry has been obtained.

Type:

str

append(atom, coordinates)

The append function allows the user to add the position of a new atom belonging to the molecule.

Parameters:

  • atom (str) – The symbol of the atom

  • coordinates (Union[List[float], np.ndarray]) – The list or numpy array of 3 floating point values indicating the cartesian position of the atom in the tridimensional space

Raises:

ValueError – Exception raised if the atom does not represent a valid element or if the coordinates vector does not match the requirements

Return type:

None

property atomcount: int

The number of atoms in the molecule

Returns:

The number of atoms in the molecule

Return type:

int

property atomic_numbers: List[int]

The ordered list of the atomic numbers of each atom in the molecule

Returns:

The list of integers atomic numbers associated with each atom in the molecule

Return type:

List[int]

property atoms: List[str]

The list of atoms/elements in the molecule

Returns:

The list of strings representing, in order, the symbols of the atoms in the molecule

Return type:

List[str]

buried_volume_fraction(site, radius=3.5, density=0.001, include_hydrogens=True, excluded_atoms=None, radii=None, radii_type='bondi', radii_scale=1.17)

Computes the buried volume fraction around a given site. The functions adopts the implementation provided in the morfeus python package (https://kjelljorner.github.io/morfeus/buried_volume.html).

Parameters:

  • site (int) – The index (starting the numeration from zero) of the reactive atom around which the buried volume must be computed

  • radius (float) – The radius (in Angstrom) of the sphere in which the buried volume should be computed

  • density (float) – The volume (in Angstrom^3) per point in the sphere used in the calculation

  • include_hydrogens (bool) – If set to True (default) will consider the hydrogen atoms in the calculation

  • excluded_atoms (List[int]) – The list of indices (starting the numeration from zero) of the atom that should be excluded from the compuitation of the buried volume (default: None)

  • radii (List[float]) – The custom list of atomic radii to be used in the computation (default: None). If set to a value different from None, will override the radii_type and radii_scale options.

  • radii_type (str) – Type of radii to use in the calculation. The available options are alvarez, bondi, crc or truhlar.

  • radii_scale (float) – Scaling factor for the selected radii_type

Raises:

ValueError – Exception raised if either the index of the selected atoms are out of bounds or if the radii type does not match any of the presets.

Returns:

The fraction of buried volume of the sphere (between 0 and 1)

Return type:

float

property coordinates: List[ndarray]

The list of coordinates of the atoms in the molecule

Returns:

The list of numpy arrays representing, in order, the 3D position of each atom in the molecule

Return type:

List[np.ndarray]

classmethod from_dict(data)

Construct a MolecularGeometry object from the data encoded in a dictionary.

Parameters:

data (dict) – The dictionary containing the class attributes

Returns:

The fully initialized MolecularGeometry object

Return type:

MolecularGeometry

classmethod from_xyz(path)

The functions returns a fully initialized MolecularGeometry class containing the coordinates indicated in the .xyz file located in the indicated path.

Parameters:

path (str) – A string indicating the path to a valid .xyz file

Returns:

The MolecularGeometry object containing the coordinates encoded in the .xyz file

Return type:

MolecularGeometry

load_xyz(path)

Imports the coordinates of the molecule from a path pointing to a valid .xyz file

Parameters:

path (str) – The path to the .xyz from which the coordinates must be loaded

Raises:

  • ValueError – Exception raised if the path given does not point to a valid file

  • RuntimeError – Exception raised if an error occurs while loading the data from the file

Return type:

None

property mass: float

The mass of the molecule in atomic mass units computed using the average atomic weights.

Returns:

The molecular mass in atomic mass units.

Return type:

float

to_dict()

Generates a dictionary representation of the class. The obtained dictionary can be saved and used to re-load the object using the built-in from_dict class method.

Returns:

The dictionary listing, with human friendly names, the attributes of the class

Return type:

dict

write_xyz(path, comment='')

Exports the coordinates to a .xyz file located at a given path

Parameters:

  • path (str) – A valid path in which the .xyz file must be saved

  • comment (str) – An optional comment that can be saved in the .xyz file

Return type:

None

The spycci.core.properties sub-module

class spycci.core.properties.Properties

Class containing the properties associated to a system when a given electronic and vibronic level of theory are considered. The class automatically stores the level of theory associated to the coputed properties and checks, whenever a new property is set, that a given input data is compatible with the current used level of theory. In normal conditions (strict mode) if a mismatch between levels of theory is detected all the properties related to the old level of theory are cleaned and a warning is raised. If the strict mode is disables (by setting compechem.config.STRICT_MODE to False) the level of theory is set to Undefined and all the properties are kept.

property condensed_fukui_hirshfeld: Dict[str, List[float]]

The condensed Fukui values computed from the Hirshfeld charges.

Returns:

The dictionaty containing the list of condensed Fukui values computed for each atom in the system starting from the values of the Hirshfeld charges. The functions are stored in the dictionary according to the f+, f- and f0 keys.

Return type:

Dict[str, List[float]]

property condensed_fukui_mulliken: Dict[str, List[float]]

The condensed Fukui values computed from the Mulliken charges.

Returns:

The dictionaty containing the list of condensed Fukui values computed for each atom in the system starting from the values of the Mulliken charges. The functions are stored in the dictionary according to the f+, f- and f0 keys.

Return type:

Dict[str, List[float]]

property electronic_energy: float

The electronic energy of the system in Hartree.

Returns:

The electronic energy of the system in Hartree.

Return type:

float

classmethod from_dict(data)

Construct a Properties object from the data encoded in a dictionary.

Parameters:

data (dict) – The dictionary containing the class attributes

Returns:

The fully initialized Properties object

Return type:

Properties

property gibbs_free_energy: float

The Gibbs free energy of the system in Hartree.

Returns:

The Gibbs free energy of the system in Hartree.

Return type:

float

property helmholtz_free_energy: float

The Helmholtz free energy of the system in Hartree.

Returns:

The Helmholtz free energy of the system in Hartree.

Return type:

float

property hirshfeld_charges: List[float]

The Hirshfeld charges of the system.

Returns:

The list of Hirshfeld charges associated to each atom in the system.

Return type:

List[float]

property hirshfeld_spin_populations: List[float]

The Hirshfeld spin populations of the system.

Returns:

The list of Hirshfeld spin populations associated to each atom in the system.

Return type:

List[float]

property level_of_theory_electronic: str

The level of theory adopted for the electronic structure calculations

Returns:

The string encoding the electronic level of theory

Return type:

str

property level_of_theory_vibronic: str

The level of theory adopted for the vibronic calculations

Returns:

The string encoding the vibronic level of theory

Return type:

str

property mulliken_charges: List[float]

The Mulliken charges of the system.

Returns:

The list of Mulliken charges associated to each atom in the system.

Return type:

List[float]

property mulliken_spin_populations: List[float]

The Mulliken spin populations of the system.

Returns:

The list of Mulliken spin populations associated to each atom in the system.

Return type:

List[float]

property pka: float

The pKa of the system.

Returns:

The pKa the system.

Return type:

float

set_condensed_fukui_hirshfeld(value, electronic_engine)

Sets condensed Fukui values computed from the Hirshfeld charges.

Parameters:

  • Dict[str – The dictionaty containing the list of condensed Fukui values computed for each atom in the system starting from the values of the Hirshfeld charges. The functions are stored in the dictionary according to the f+, f- and f0 keys.

  • List[float]] – The dictionaty containing the list of condensed Fukui values computed for each atom in the system starting from the values of the Hirshfeld charges. The functions are stored in the dictionary according to the f+, f- and f0 keys.

  • electronic_engine (Union(Engine, str)) – The engine used in the electronic calculation.

  • value (Dict[str, List[float]]) –

Return type:

None

set_condensed_fukui_mulliken(value, electronic_engine)

Sets condensed Fukui values computed from the Mulliken charges.

Parameters:

  • Dict[str – The dictionaty containing the list of condensed Fukui values computed for each atom in the system starting from the values of the Mulliken charges. The functions are stored in the dictionary according to the f+, f- and f0 keys.

  • List[float]] – The dictionaty containing the list of condensed Fukui values computed for each atom in the system starting from the values of the Mulliken charges. The functions are stored in the dictionary according to the f+, f- and f0 keys.

  • electronic_engine (Union(Engine, str)) – The engine used in the electronic calculation.

  • value (Dict[str, List[float]]) –

Return type:

None

set_electronic_energy(value, electronic_engine)

Sets the electronic energy of the system.

Parameters:

  • value (float) – The electronic energy of the system in Hartree.

  • electronic_engine (Union(Engine, str)) – The engine used in the calculation.

Return type:

None

set_gibbs_free_energy(value, electronic_engine, vibronic_engine)

Sets the Gibbs free energy of the system.

Parameters:

  • value (float) – The Gibbs free energy of the system in Hartree.

  • electronic_engine (Union(Engine, str)) – The engine used in the electronic calculation.

  • vibronic_engine (Union(Engine, str)) – The engine used in the vibronic calculation.

Return type:

float

set_helmholtz_free_energy(value, electronic_engine, vibronic_engine)

Sets the Helmholtz free energy of the system.

Parameters:

  • value (float) – The Helmholtz free energy of the system in Hartree.

  • electronic_engine (Union(Engine, str)) – The engine used in the electronic calculation.

  • vibronic_engine (Union(Engine, str)) – The engine used in the vibronic calculation.

Return type:

float

set_hirshfeld_charges(value, electronic_engine)

Sets the Hirshfeld charges of the system.

Parameters:

  • value (float) – The list of Hirshfeld charges associated to each atom of the system.

  • electronic_engine (Union(Engine, str)) – The engine used in the electronic calculation.

Return type:

None

set_hirshfeld_spin_populations(value, electronic_engine)

Sets the Hirshfeld spin populations of the system.

Parameters:

  • value (float) – The list of Hirshfeld spin populations associated to each atom of the system.

  • electronic_engine (Union(Engine, str)) – The engine used in the electronic calculation.

Return type:

None

set_mulliken_charges(value, electronic_engine)

Sets the Mulliken charges of the system.

Parameters:

  • value (float) – The list of Mulliken charges associated to each atom of the system.

  • electronic_engine (Union(Engine, str)) – The engine used in the electronic calculation.

Return type:

None

set_mulliken_spin_populations(value, electronic_engine)

Sets the Mulliken spin populations of the system.

Parameters:

  • value (float) – The list of Mulliken spin populations associated to each atom of the system.

  • electronic_engine (Union(Engine, str)) – The engine used in the electronic calculation.

Return type:

None

set_pka(value, electronic_engine, vibronic_engine=None)

Sets the pKa of the system.

Parameters:

  • value (float) – The pKa of the system.

  • electronic_engine (Union(Engine, str)) – The engine used in the electronic calculation.

  • vibronic_engine (Union(Engine, str)) – The engine used in the vibronic calculation. (optional)

Return type:

float

set_vibrational_data(value, vibronic_engine)

Sets condensed Fukui values computed from the Hirshfeld charges.

Parameters:

  • value (VibrationalData) – The class encoding all the vibrational data associated to the molecule

  • vibronic_engine (Union(Engine, str)) – The engine used in the vibronic calculation.

Return type:

None

set_vibronic_energy(value, vibronic_engine)

Sets the vibronic energy of the system.

Parameters:

  • value (float) – The vibronic energy of the system in Hartree.

  • vibronic_engine (Union(Engine, str)) – The engine used in the calculation.

Return type:

None

to_dict()

Generates a dictionary representation of the class. The obtained dictionary can be saved and used to re-load the object using the built-in from_dict class method.

Returns:

The dictionary listing, with human friendly names, the attributes of the class

Return type:

dict

property vibrational_data: VibrationalData

Returns the class containing all the available vibrational data about the molecule

Returns:

The class containing all the available vibrational data

Return type:

VibrationalData

property vibronic_energy: float

The vibronic energy of the system in Hartree.

Returns:

The vibronic energy of the system in Hartree.

Return type:

float