Defining molecular systems#
When running computational chemistry numerical simulations, you need to define two things: the system under study, and the type of calculation to run on it. For the former, you can use the compechem.systems submodule.
The compechem.systems submodule contains the following classes, used to collect and store information about the system of interest:
System: generic system object, such as a single molecule.Ensemble: ensemble object, intended as a collection of closely relatedSystemobjects. For example, the ensemble of conformers generated by the corresponding CREST routine.
The individual classes can be imported as follows:
from compechem.systems import System
from compechem.systems import Ensemble
In this section of the user guide, we will show you how to define molecular systems using the aforementioned classes.
Single systems#
A System object is defined as a molecular system, containing one or more individual molecules, and is initialized by providing a molecular structure via a .xyz file:
from compechem.systems import System
my_mol = System("path/to/xyz/water.xyz")
Optionally, the following parameters can be provided (if not provided, some default values are set):
charge: total charge of the system. Default: 0spin: total spin multiplicity of the system (2S+1, where S is the total spin quantum number). Default: 1 (singlet)box_side: (for periodic systems only), length of the simulation box (in Å)
Example of a periodic system of side 18.27 Å containing a cation radical:
from compechem.systems import System
my_mol = System(
"path/to/xyz/water.xyz",
charge=1,
spin=2,
box_side=18.27,
)
To get a list of all the available properties, please refer to the API.
For a quick look at the main properties of a System, you can simply ask to print the corresponding variable:
print(my_system)
=========================================================
SYSTEM: water
=========================================================
Number of atoms: 3
Charge: 0
Spin multiplicity: 1
********************** GEOMETRY *************************
Total system mass: 18.0153 amu
----------------------------------------------
index atom x (Å) y (Å) z (Å)
----------------------------------------------
0 O 0.03595 2.78898 0.00000
1 H 1.00595 2.78898 0.00000
2 H -0.28738 2.19789 0.69783
----------------------------------------------
********************** PROPERTIES *************************
Geometry level of theory: None
Electronic level of theory: None
Vibronic level of theory: None
Electronic energy: None Eh
Vibronic energy: None Eh
Helmholtz free energy: None Eh
Gibbs free energy: None Eh
pKa: None
Ensembles#
An Ensemble object is defined as a collection of related Systems, for example the collection of lowest-energy conformers generated by CREST. To initialise an Ensemble object you need to provide an iterable (such as a list) yielding System objects:
from compechem.systems import System
from compechem.systems import Ensemble
my_mol1 = System("path/to/xyz/my_mol1.xyz")
my_mol2 = System("path/to/xyz/my_mol2.xyz")
my_mol3 = System("path/to/xyz/my_mol3.xyz")
my_list = [my_mol1, my_mol2, my_mol3]
my_ens = Ensemble(my_list)
To get a list of all the available properties, please refer to the API.
Saving/Loading System objects#
It is possible to save/load System objects to/from .json files. To save a System object, dumping all the information currently stored in it after the undergone calculations (structure, charge, spin multiplicity, energies, frequencies, etc…) use the system.save_json() function and specify the path where you want to store the file:
from compechem.systems import System
mol = System("water.xyz")
... calculations ...
mol.save_json("water.json")
Then, you can load a previously saved System by passing the .json file path instead of a .xyz file:
from compechem.systems import System
mol = System("water.json")
print(mol)
=========================================================
SYSTEM: water
=========================================================
Number of atoms: 3
Charge: 0
Spin multiplicity: 1
********************** GEOMETRY *************************
Total system mass: 18.0153 amu
----------------------------------------------
index atom x (Å) y (Å) z (Å)
----------------------------------------------
0 O 0.00000 -0.37937 0.00000
1 H 0.77221 0.18968 -0.00000
2 H -0.77221 0.18969 0.00000
----------------------------------------------
********************** PROPERTIES *************************
Geometry level of theory: XtbInput || method: gfn2 | solvent: None
Electronic level of theory: XtbInput || method: gfn2 | solvent: None
Vibronic level of theory: XtbInput || method: gfn2 | solvent: None
Electronic energy: -5.070544446692 Eh
Vibronic energy: 0.002508973529 Eh
Helmholtz free energy: None Eh
Gibbs free energy: -5.068035473164 Eh
pKa: None
MULLIKEN ANALYSIS
----------------------------------------------
index atom charge spin
----------------------------------------------
0 O -0.56500 0.00000
1 H 0.28200 0.00000
2 H 0.28200 0.00000