morfeus.xtb module

xtb interface code.

class morfeus.xtb.XTB(elements, coordinates, method=2, charge=0, n_unpaired=None, solvent=None, electronic_temperature=None, n_processes=None, env_variables=None, run_path=None)[source]

Bases: object

Calculate electronic properties with the xtb program.

Parameters:

  • elements (Iterable[int] | Iterable[str]) – Elements as atomic symbols or numbers

  • coordinates (ArrayLike2D) – Coordinates (Å)

  • method (int | str) – Method to use in xtb. Currently works with: - 2: GFN2-xTB (default) - 1: GFN1-xTB - ptb: PTB

  • charge (int) – Molecular charge

  • n_unpaired (int | None) – Number of unpaired electrons

  • solvent (str | None) – Solvent. Uses the ALPB solvation model

  • electronic_temperature (int | None) – Electronic temperature (K)

  • n_processes (int | None) – Number of parallel processes in xtb. If not provided, runs on 1 thread.

  • env_variables (dict[str, str] | None) – Optional dictionary to set environment variables for xtb execution

  • run_path (Path | str | None) – Folder path to run xTB calculation. If not provided, runs in a temporary folder

get_atom_dipole_moments(unit='au')[source]

Return atomic dipole moments.

Parameters:

unit (str) – ‘au’ or ‘debye’

Returns:

Atomic dipole moments (a.u. or debye)

Raises:

ValueError – If given unit is not supported

Return type:

dict[int, float]

get_atom_dipoles()[source]

Return atomic dipole vectors (a.u.).

Raises:

ValueError – If the chosen method is GFN1-xTB (does not support atomic dipoles)

Returns:

Atomic dipole vectors (a.u.)

Return type:

dict[int, Any]

get_atom_polarizabilities()[source]

Return atomic polarizabilities.

Raises:

ValueError – If the chosen method is not GFN2-xTB (necessary for polarizability calculations)

Returns:

Atomic polarizabilities

Return type:

dict[int, float]

get_atomic_h_bond_corrections(unit='Eh')[source]

Calculate atomic hydrogen bonding corrections to the solvation free energy.

Caveat: Due to the limited print precision of the H-bond terms outputted by xtb, the atomic energy corrections returned here have an error of max ± (atomic charge)^2 * 0.0005 Eh

Parameters:

unit (str) – ‘Eh’, ‘eV’, ‘kcal/mol’ or kJ/mol’

Returns:

Atomic hydrogen bonding corrections to the solvation free energy (Eh, eV, kcal/mol or kJ/mol)

Raises:

  • ValueError – If no solvent is specified (necessary for solvation calculations)

  • ValueError – If the specified solvent is not polar (necessary for atomic hydrogen bonding contributions)

  • ValueError – If given unit is not supported

Return type:

dict[int, float]

get_bond_order(i, j)[source]

Return bond order between two atoms.

Parameters:

  • i (int) – Index of atom 1 (1-indexed)

  • j (int) – Index of atom 2 (1-indexed)

Returns:

Bond order between atoms i and j

Raises:

ValueError – If no bond exists between the given atoms.

Return type:

float

get_bond_orders()[source]

Return bond orders.

Return type:

dict[tuple[int, int], float]

get_charges(model='Mulliken')[source]

Return atomic charges.

Parameters:

model (str) – Charge model to use. - ‘Mulliken’ - ‘CM5’: only available with GFN1-xTB

Raises:

ValueError – If given charge model is not available with the chosen xtb method.

Returns:

Atomic charges (1-indexed)

Return type:

dict[int, float]

get_chemical_potential(corrected=True)[source]

Calculate chemical potential.

Parameters:

corrected (bool) – Whether to apply empirical correction term

Returns:

Chemical potential (eV)

Return type:

float

get_covcn()[source]

Return atomic covalent coordination numbers.

Raises:

ValueError – If the chosen method is not GFN2-xTB (necessary for covCN calculations)

Returns:

Atomic covalent coordination numbers

Return type:

dict[int, float]

get_d_pop()[source]

Return atomic population partitioned to the d shell from Mulliken population analysis.

Raises:

ValueError – If the chosen method is not GFN1-xTB (necessary for population calculations)

Returns:

Atomic d shell populations

Return type:

dict[int, float]

get_dipole()[source]

Return molecular dipole vector (a.u.).

Return type:

Any

get_dipole_moment(unit='au')[source]

Return molecular dipole moment.

Parameters:

unit (str) – ‘au’ or ‘debye’

Returns:

Molecular dipole moment (a.u. or debye)

Raises:

ValueError – If given unit is not supported

Return type:

float

get_ea(corrected=True)[source]

Return electron affinity.

Parameters:

corrected (bool) – Whether to apply empirical correction term

Returns:

Electron affinity (eV)

Return type:

float

get_electronegativity(corrected=True)[source]

Calculate electronegativity.

Parameters:

corrected (bool) – Whether to apply empirical correction term

Returns:

Electronegativity (eV)

Return type:

float

get_energy()[source]

Return total energy (Eh).

Return type:

float

get_fermi_level()[source]

Return Fermi level (eV).

Return type:

float

get_fod_population()[source]

Return atomic fractional occupation number weighted density population.

The FOD calculation is performed by default with an electronic temperature of 5000 K.

Returns:

Atomic FOD populations

Return type:

dict[int, float]

get_fukui(variety, corrected=True)[source]

Calculate Fukui coefficients.

Parameters:

  • variety (str) – Type of Fukui coefficient:’nucleophilicity’ = ‘minus’, ‘electrophilicity’ = ‘plus’, ‘radical’, ‘dual’, ‘local_nucleophilicity’ or ‘local_electrophilicity’. Note: ‘nucleophilicity’ and ‘electrophilicity’ are synonym for respectively ‘minus’ and ‘plus’.

  • corrected (bool) – Whether to apply empirical correction term to the inonization potential and electron affinity (only applicable for local electrophilicity calculation)

Returns:

Atomic Fukui coefficients

Return type:

fukui

Raises:

ValueError – When variety does not exist

get_global_descriptor(variety, corrected=True)[source]

Calculate global reactivity descriptors.

Parameters:

  • corrected (bool) – Whether to apply empirical correction term

  • variety (str) – Type of descriptor: ‘electrophilicity’, ‘nucleophilicity’, ‘electrofugality’ or ‘nucleofugality’

Returns:

Global reactivity descriptor (eV)

Return type:

descriptor

Raises:

ValueError – When variety does not exist

get_hardness()[source]

Calculate hardness (eV).

Return type:

float

get_homo(unit='Eh')[source]

Return HOMO energy.

Parameters:

unit (str) – ‘Eh’, ‘eV’, ‘kcal/mol’ or kJ/mol’

Returns:

HOMO energy (Eh, eV, kcal/mol or kJ/mol)

Raises:

ValueError – If given unit is not supported

Return type:

float

get_homo_lumo_gap(unit='eV')[source]

Return HOMO-LUMO gap.

Parameters:

unit (str) – ‘Eh’, ‘eV’, ‘kcal/mol’ or kJ/mol’

Returns:

HOMO-LUMO gap (Eh, eV, kcal/mol or kJ/mol)

Raises:

ValueError – If given unit is not supported

Return type:

float

get_ip(corrected=True)[source]

Return ionization potential.

Parameters:

corrected (bool) – Whether to apply empirical correction term

Returns:

Ionization potential (eV)

Return type:

float

get_lumo(unit='Eh')[source]

Return LUMO energy.

Parameters:

unit (str) – ‘Eh’, ‘eV’, ‘kcal/mol’ or kJ/mol’

Returns:

LUMO energy (Eh, eV, kcal/mol or kJ/mol)

Raises:

ValueError – If given unit is not supported

Return type:

float

get_molecular_polarizability()[source]

Return molecular polarizability.

Raises:

ValueError – If the chosen method is not GFN2-xTB (necessary for polarizability calculations)

Returns:

Molecular polarizability

Return type:

float

get_nfod()[source]

Return NFOD descriptor.

NFOD is the integration over all space of the fractional occupation number weighted density (FOD). The FOD calculation is performed by default with an electronic temperature of 5000 K.

Returns:

NFOD descriptor

Return type:

float

get_p_pop()[source]

Return atomic population partitioned to the p shell from Mulliken population analysis.

Raises:

ValueError – If the chosen method is not GFN1-xTB (necessary for population calculations)

Returns:

Atomic p shell populations

Return type:

dict[int, float]

get_s_pop()[source]

Return atomic population partitioned to the s shell from Mulliken population analysis.

Raises:

ValueError – If the chosen method is not GFN1-xTB (necessary for population calculations)

Returns:

Atomic s shell populations

Return type:

dict[int, float]

get_softness()[source]

Calculate softness (eV).

Return type:

float

get_solvation_energy(unit='Eh')[source]

Return solvation free energy.

Parameters:

unit (str) – ‘Eh’, ‘eV’, ‘kcal/mol’ or kJ/mol’

Returns:

Solvation free energy (Eh, eV, kcal/mol or kJ/mol)

Raises:

  • ValueError – If no solvent is specified (necessary for solvation calculations)

  • ValueError – If given unit is not supported

Return type:

float

get_solvation_h_bond_correction(unit='Eh')[source]

Return hydrogen bonding correction to the solvation free energy.

The hydrogen bonding correction is 0.0 for non-polar solvents.

Parameters:

unit (str) – ‘Eh’, ‘eV’, ‘kcal/mol’ or kJ/mol’

Returns:

Hydrogen bonding correction to the solvation free energy (Eh, eV, kcal/mol or kJ/mol)

Raises:

  • ValueError – If no solvent is specified (necessary for solvation calculations)

  • ValueError – If given unit is not supported

Return type:

float

class morfeus.xtb.XTBResults(charges=None, charges_cm5=None, bond_orders=None, homo=None, lumo=None, gap=None, atom_dipole_vect=None, dipole_vect=None, dipole_moment=None, atom_polarizabilities=None, mol_polarizability=None, total_energy=None, fermi_level=None, s_pop=None, p_pop=None, d_pop=None, covcn=None, g_solv=None, g_solv_hb=None, atom_hb_terms=None, fod_pop=None, ip=None, ea=None, fukui_plus=None, fukui_minus=None, fukui_radical=None)[source]

Bases: object

Stores xTB descriptors.

Parameters:

  • charges (list[float] | None)

  • charges_cm5 (list[float] | None)

  • bond_orders (list[tuple[int, int, float]] | None)

  • homo (dict[str, float] | None)

  • lumo (dict[str, float] | None)

  • gap (float | None)

  • atom_dipole_vect (Any | None)

  • dipole_vect (Any | None)

  • dipole_moment (float | None)

  • atom_polarizabilities (list[float] | None)

  • mol_polarizability (float | None)

  • total_energy (float | None)

  • fermi_level (float | None)

  • s_pop (list[float] | None)

  • p_pop (list[float] | None)

  • d_pop (list[float] | None)

  • covcn (list[float] | None)

  • g_solv (float | None)

  • g_solv_hb (float | None)

  • atom_hb_terms (list[float] | None)

  • fod_pop (list[float] | None)

  • ip (float | None)

  • ea (float | None)

  • fukui_plus (list[float] | None)

  • fukui_minus (list[float] | None)

  • fukui_radical (list[float] | None)

morfeus.xtb.cli(file)[source]

CLI for XTB.

Parameters:

file (str) – Geometry file

Returns:

Partially instantiated class

Return type:

Any