stko.XTBEnergy

class stko.XTBEnergy(xtb_path, gfn_version=2, output_dir=None, num_cores=1, calculate_free_energy=False, calculate_ip_and_ea=False, electronic_temperature=300, solvent_model='gbsa', solvent=None, solvent_grid='normal', charge=0, num_unpaired_electrons=0, unlimited_memory=False, write_sasa_info=False)[source]

Bases: object

Uses GFN-xTB to calculate energy and other properties.

By default, get_results() will extract other properties of the stk.Molecule passed to calculate(), which will be saved in the attributes of stko.XTBResults.

See also

Parameters:

  • xtb_path (Path | str) – The path to the xTB executable.

  • gfn_version (int) – Parameterization of GFN to use in xTB. For details see https://xtb-docs.readthedocs.io/en/latest/basics.html.

  • output_dir (Path | str | None) – The name of the directory into which files generated during the calculation are written, if None then uuid.uuid4() is used.

  • num_cores (int) – The number of cores xTB should use.

  • calculate_free_energy (bool) – Whether to calculate the total free energy and vibrational frequencies. Setting this to True can drastically increase calculation time and memory requirements.

  • calculate_ip_and_ea (bool) – Whether to calculate the vertical ionisation potential and vertical electron affinity. Equivalent to –vipea flag in command-line interface.

  • electronic_temperature (float) – Electronic temperature in Kelvin.

  • solvent_model (str) – Solvent model to use out of older gbsa and newer alpb. gbsa is default for backwards compatability, but alpb is recommended. For details see https://xtb-docs.readthedocs.io/en/latest/gbsa.html.

  • solvent (str | None) – Solvent to use in GBSA implicit solvation method. For details see https://xtb-docs.readthedocs.io/en/latest/gbsa.html.

  • solvent_grid (str) – Grid level to use in SASA calculations for GBSA implicit solvent. Can be one of 'normal', 'tight', 'verytight' or 'extreme'. For details see https://xtb-docs.readthedocs.io/en/latest/gbsa.html.

  • charge (int) – Formal molecular charge.

  • num_unpaired_electrons (int) – Number of unpaired electrons.

  • unlimited_memory (bool) – If True energy() will be run without constraints on the stack size. If memory issues are encountered, this should be True, however this may raise issues on clusters.

  • write_sasa_info (bool) – If True, the detailed info input will request gbsa=True and output SASA information from xtb. Requires a solvent model to be used.

Notes

When running calculate(), this calculator changes the present working directory with os.chdir(). The original working directory will be restored even if an error is raised, so unless multi-threading is being used this implementation detail should not matter.

If multi-threading is being used an error could occur if two different threads need to know about the current working directory as stko.XTBEnergy can change it from under them.

Note that this does not have any impact on multi-processing, which should always be safe.

We thank Andrew Tarzia and Alejandro Santana-Bonilla for their contributions to this code.

Examples

import stk
import stko

bb1 = stk.BuildingBlock('NCCNCCN', [stk.PrimaryAminoFactory()])
bb2 = stk.BuildingBlock('O=CCCC=O', [stk.AldehydeFactory()])
polymer = stk.ConstructedMolecule(
    stk.polymer.Linear(
        building_blocks=(bb1, bb2),
        repeating_unit="AB",
        orientations=[0, 0],
        num_repeating_units=1
    )
)

# Optimize the constructed molecule so that it has a
# reasonable structure.
opt = stko.OptimizerSequence(
    stko.UFF(),
    stko.XTB(xtb_path='/opt/gfnxtb/xtb', unlimited_memory=True)
)
polymer = opt.optimize(polymer)

# Calculate energy using GFN-xTB.
xtb = stko.XTBEnergy(
    xtb_path='/opt/gfnxtb/xtb',
    unlimited_memory=True
)

xtb_results = xtb.get_results(polymer)

# Extract properties from the energy calculator for a given
# molecule.
total_energy = xtb_results.get_total_energy()
homo_lumo_gap = xtb_results.get_homo_lumo_gap()
fermi_levels = xtb_results.get_fermi_level()
homo_lumo_orbitals = xtb_results.get_homo_lumo_orbitals()
full_dipole_moments = xtb_results.get_full_dipole_moments()

If calculate_free_energy is True, xTB performs a numerical Hessian calculation and calculates the total free energy and vibrational frequencies of a molecule. It is recommended that a well optimized structure be used as input for these calculations

# Optimize the constructed molecule so that it has a
# reasonable structure.
optimizer = stko.OptimizerSequence(
    stko.ETKDG(),
    stko.XTB(
        xtb_path='/opt/gfnxtb/xtb',
        unlimited_memory=True,
        opt_level='verytight'
    )
)
polymer = optimizer.optimize(polymer)

# Calculate energy using GFN-xTB.
xtb = stko.XTBEnergy(
    xtb_path='/opt/gfnxtb/xtb',
    unlimited_memory=True,
    calculate_free_energy=True
)

xtb_results = xtb.get_results(polymer)

# Extract properties from the energy calculator for a given
# molecule.
total_free_energy = xtb_results.get_total_free_energy()
total_frequencies = xtb_results.get_frequencies()

If calculate_ip_and_ea is True, xTB performs multiple single- point-energy calculations to calculate the vertical electron affinity and ionisation potential. It is recommended that a well optimized structure be used as input for these calculations

# Optimize the constructed molecule so that it has a
# reasonable structure.
optimizer = stko.OptimizerSequence(
    stko.ETKDG(),
    stko.XTB(
        xtb_path='/opt/gfnxtb/xtb',
        unlimited_memory=True,
        opt_level='verytight'
    )
)
polymer = optimizer.optimize(polymer)

# Calculate energy using GFN-xTB.
xtb = stko.XTBEnergy(
    xtb_path='/opt/gfnxtb/xtb',
    unlimited_memory=True,
    calculate_ip_and_ea=True,
)

xtb_results = xtb.get_results(polymer)

# Extract properties from the energy calculator for a given
# molecule.
ip = xtb_results.get_ionisation_potential()
ea = xtb_results.get_electron_affinity()

Methods

calculate

get_energy

Calculate the energy of mol.

get_results

Calculate the xTB properties of mol.
calculate(mol)[source]
Parameters:

mol (Molecule)

Return type:

Generator

get_energy(mol)[source]

Calculate the energy of mol.

Parameters:

mol (Molecule) – The stk.Molecule whose energy is to be calculated.

Returns:

The energy.

Return type:

float

get_results(mol)[source]

Calculate the xTB properties of mol.

Parameters:

mol (Molecule) – The stk.Molecule whose energy is to be calculated.

Returns:

The properties, with units, from xTB calculations.

Return type:

XTBResults