spycci.systems sub-module

System class

class spycci.systems.System(name, geometry, charge=0, spin=1, box_side=None)

The System object describes a generic molecular system described at a given level of theory. A system is defined based on a molecular geometry, a charge, a spin multiplicity and, once a level of theory is selected, by a set of computed properties.

Parameters:

  • name (str) – The name of the system.

  • geometry (MolecularGeometry) – The MolecularGeometry object from which the System can be constructred.

  • charge (Optional[int]) – The total charge of the system. (Default: 0 neutral)

  • spin (Optional[int]) – The total spin multiplicity of the system. (Default: 1 singlet)

  • box_side (Optional[float]) – For periodic systems, defines the length (in Å) of the box side.

Raises:

TypeError – Exception raised if the geometry argument is not of the MolecularGeometry type.

classmethod from_json(path)

Construct a System object from the data encoded in a SPyCCI .json file.

Parameters:

path (str) – The path of the .json file.

Raises:

FileNotFoundError – Exception raised if the specified .json file cannot be found.

Return type:

System

classmethod from_smiles(name, smiles, charge=0, spin=1, box_side=None, 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 System object from the given SMILES string. The geometry of the molecule is generated in 3D using the ETKDGv3 algorithm, followed by force field optimization using either MMFF or UFF, depending on availability and user preference. The resulting system includes molecular geometry, total charge, spin multiplicity, and optional periodic boundary conditions. All operations are carried out using the tools defined in the RDKit package.

Parameters:

  • name (str) – The name assigned to the molecular system.

  • smiles (str) – A valid SMILES string representing the molecular structure to be converted into a full system.

  • charge (int) – The net formal charge of the system. (Default: 0)

  • spin (int) – The total spin multiplicity of the system. (Default: 1 singlet)

  • box_side (Optional[float]) – The length of the side of the simulation box (in Å) used to define periodic boundary conditions. If set to None, the system is treated as non-periodic. (default: None)

  • 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. (default: “MMFF94”)

  • 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)

Return type:

System

classmethod from_xyz(path, charge=0, spin=1, box_side=None)

Construct a System object from the geometry encoded in a .xyz file.

Parameters:

  • path (str) – The path of the .xyz file.

  • charge (Optional[int]) – The total charge of the system. (Default: 0 neutral)

  • spin (Optional[int]) – The total spin multiplicity of the system. (Default: 1 singlet)

  • box_side (Optional[float]) – For periodic systems, defines the length (in Å) of the box side.

Raises:

FileNotFoundError – Exception raised if the specified .xyz file cannot be found.

Return type:

System

property is_periodic: bool

Indicates if the system is periodic or not

Returns:

True if the system is periodic (the box_side is not None), False otherwise.

Return type:

bool

save_json(path)

Saves a JSON representation of the object that can be stored on disk and loaded (using the class constructor with the option SupportedTypes.JSON) at a later time to re-generate ad identical System object.

Parameters:

path (str) – The path to the .json file that must be created.

Return type:

None

write_gen(gen_file, box_side=None)

Writes the current geometry to a .gen file.

Parameters:

  • gen_file (str) – path to the output .gen file

  • box_side (float, optional) – for periodic systems, defines the length (in Å) of the box side

Ensemble class

class spycci.systems.Ensemble(systems)

Ensemble object, containing a series of System objects.

Parameters:

systems (List[System]) – The list of System objects to be included in the Ensemble.

name

Name of the system represented in the ensemble, taken from the first element of the ensemble

Type:

str

systems

The list of System objects in the Ensemble.

Type:

List[System]

properties

The property archive containing the average ensamble properties calculated at various levels of theory.

Type:

PropertiesArchive

add(systems)

Append more Systems to the ensemble

Parameters:

systems (List[System]) – The list of systems to be added to the ensamble

property atomcount: int

The number of atoms in the system

Returns:

The total number of atoms

Return type:

int

boltzmann_average(temperature=297.15)

Calculates the average free Helmholtz energy of the ensemble (in Hartree), weighted for each molecule by its Boltzmann factor.

Parameters:

temperature (float) – temperature at which to calculate the Boltzmann average, by default 297.15 K

Returns:

  • float – The total Helmholtz free energy of the ensemble.

  • NOTE (the vibrational contributions are included in the electronic component, which)

  • actually contains the TOTAL energy of the system. Maybe in the future I’ll think of

  • how to separate the two contributions - LB

Return type:

float