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

class spycci.core.dependency_finder.DependencySpec(name: str, version_marker: str | None = None, token_index: int | None = None, versions_map: Dict[str, List[str]] | None = None, critical: bool = True)
Parameters:

  • name (str)

  • version_marker (str | None)

  • token_index (int | None)

  • versions_map (Dict[str, List[str]] | None)

  • critical (bool)

class spycci.core.dependency_finder.EngineFinder(specs)

The EngineFinder class provides a general interface for locating software dependencies, checking their versions and the availablility of auxiliary tools and softwares.

Parameters:

specs (List[EngineSpec]) – List of EngineSpec objects defining supported programs and their dependencies.

locate(path, version=None)

Locates an executable and validate its version and dependencies.

Parameters:

  • path (str) – The name or the expected path of the program to locate.

  • version (Optional[str]) – A version specifier string (e.g., ‘>=1.0,<2.0’). If None, no version is enforced.

Returns:

The full path to the located executable.

Return type:

str

Raises:

RuntimeError – Exception raised if the program is not found, version check fails, or a critical dependency is missing.

class spycci.core.dependency_finder.EngineSpec(name: str, version_marker: Optional[str] = None, token_index: Optional[int] = None, dependencies: List[spycci.core.dependency_finder.DependencySpec] = <factory>)
Parameters:

  • name (str)

  • version_marker (str | None)

  • token_index (int | None)

  • dependencies (List[DependencySpec])

class spycci.core.dependency_finder.ProgramSpec(name: str, version_marker: str | None = None, token_index: int | None = None)
Parameters:

  • name (str)

  • version_marker (str | None)

  • token_index (int | None)

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_smiles(smiles, force_uff=False, default_mmffvariant='MMFF94', use_small_ring_torsions=True, use_macrocycle_torsions=True, maxiter=500, random_seed=-1)

The function returns a fully initialized MolecularGeometry object from the given SMILES string. The returned geometry is generated by embedding the molecule in 3D using the ETKDGv3 algorithm, followed by energy minimization using MMFF or UFF force fields, depending on availability and user preference. The operations are carried out using the tools defined in the RDKit package.

Parameters:

  • smiles (str) – A valid SMILES string representing the molecular structure to be converted into 3D coordinates.

  • force_uff (bool) – If True, the geometry optimization will use the UFF force field even when MMFF parameters are available. This can be useful when consistency across a dataset using UFF is desired. (default: False)

  • default_mmffvariant (str,) – Specifies the MMFF variant to use when MMFF is selected. Valid options are “MMFF94” or “MMFF94s”. “MMFF94s” is generally recommended for more accurate static geometries.

  • use_small_ring_torsions (bool) – If True, enables special torsional sampling for small rings during 3D embedding. Recommended when working with strained ring systems (e.g., cyclopropanes, aziridines). (default: True)

  • use_macrocycle_torsions (bool) – If True, enables special torsional treatment of macrocycles during embedding. Recommended for cyclic peptides or large ring systems (≥12 atoms). (default: True)

  • maxiter (int) – The maximum number of iterations allowed for the force field optimization step. (default=500)

  • random_seed (int) – If set to a positive integer, this value is used to seed the random number generator for the 3D embedding algorithm. This will ensure reproducible conformations for the same input SMILES. This keyword is mainly used for testing. (default: -1)

Returns:

A MolecularGeometry object containing atomic symbols and optimized 3D coordinates derived from the input SMILES string.

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 vibrational 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. 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.

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

property free_energy_correction: float

The free energy correction G-E(el) as the difference between the Gibbs free energy and the electronic energy (in Hartree).

Returns:

The free energy correction 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 as the sum of Electronic energy and free energy correction

Returns:

The Gibbs 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_vibrational: str

The level of theory adopted for the vibrational calculations

Returns:

The string encoding the vibrational 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: pKa

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_free_energy_correction(value, vibrational_engine)

Sets the free energy correction G-E(el) of the system.

Parameters:

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

  • vibrational_engine (Union[Engine, str]) – The engine used in the calculation.

Return type:

None

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, vibrational_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.

  • vibrational_engine (Union[Engine, str]) – The engine used in the vibrational calculation. (optional)

Return type:

None

set_vibrational_data(value, vibrational_engine)

Sets condensed Fukui values computed from the Hirshfeld charges.

Parameters:

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

  • vibrational_engine (Union[Engine, str]) – The engine used in the vibrational 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

The pKa property

class spycci.core.properties.pKa

The pKa class organizes all the pKa values computed for a given System using different schemes. All the stored data are accessible as read-only properties (no setter is provided). To set the pKa values, dedicated set function are provided (e.g. set_direct). The class also exposes the free_energies attribute where all the free energy values used in the calculations are stored.

Properties

direct: float

The pKa value computed using the direct scheme.

oxonium: float

The pKa value computed using the oxonium scheme.

oxonium_cosmors: float

The pKa value computed using the COSMO-RS model to compute the solvation energies in the oxonium scheme

level_of_theory_cosmors: str

The level of theory used to run the COSMO-RS calculations

property direct: float | None

The pKa value computed using the direct scheme. According to the direct scheme, the pKa is computed from the standard thermodynamic dissociation reaction:

The scheme is semi-empiric: the Gibbs free energies of HA and A⁻ are computed in acqueous solvent while the proton free energy, together with the RTln(24.46), is assumed to be -270.29 kcal/mol at 298.15K.

Returns:

The pKa value as a float value, if available, else None.

Return type:

Union[float, None]

classmethod from_dict(data)

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

Parameters:

data (dict) – The dictionary containing the class attributes

Returns:

The fully initialized pKa object

Return type:

pKa

is_set()

Returns True if at least one value of the class has been set, False otherwise.

Returns:

The set status of the pKa class object.

Return type:

bool

property level_of_theory_cosmors: str | None

The level of theory used in the COSMO-RS calculations.

Returns:

The string encoding the level of theory.

Return type:

Union[str, None]

property oxonium: float | None

The pKa value computed using the oxonium scheme. According to the oxonium scheme, the pKa is computed from the standard thermodynamic dissociation reaction:

\(HA + H_2O \rightarrow H_3O^{+} + A^{-}\)

The scheme is fully computational: all species involved (HA, A⁻, H₂O, H₃O⁺) must have their free energies computed in aqueous solvent. The water concentration is taken as 55.34 mol/L (i.e., 997 g/L at 25°C / 18.01528 g/mol).

Returns:

The pKa value.

Return type:

Union[float, None]

property oxonium_cosmors: float | None

The pKa value computed using the oxonium scheme and the COSMO-RS solvation energies. This variant of the oxonium scheme uses solvation free energies from a COSMO-RS calculation instead of implicit solvent methods. The thermodynamic cycle remains:

\(HA + H_2O \rightarrow H_3O^{+} + A^{-}\)

The scheme is fully computational: all species involved (HA, A⁻, H₂O, H₃O⁺) must have their free energies computed according to an hybrid scheme. Firstly the free energy in vacumm is computed for all species (using the solvent equilibium geometyr). Then, the solvation correction for the water solvent is then taken from the OpenCOSMO-RS model. The water concentration is taken as 55.34 mol/L (i.e., 997 g/L at 25°C / 18.01528 g/mol).

Returns:

The pKa value.

Return type:

Union[float, None]

set_direct(pka)

Sets the pKa computed using the direct scheme.

Parameters:

pka (float) – The computed pKa value.

Return type:

None

set_oxonium(pka)

Sets the pKa computed using the oxonium scheme.

Parameters:

pka (float) – The computed pKa value.

Return type:

None

set_oxonium_cormors(pka, engine)

Sets the pKa computed using the oxonium scheme using the solvation energies computing the COSMO-RS method.

Parameters:

  • pka (float) – The computed pKa value.

  • engine (Engine) – The engine used in the COSMO-RS calculations.

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