DFT API Reference

This page documents callable interfaces in dp5.dft and links to the RST-style docstrings added to the implementation.

Dispatcher Functions

dp5.dft.run_dft.dft_calculations(mols, workflow, config)

Run DFT stages requested by the workflow and update molecule objects.

This function dynamically imports the configured backend module, instantiates its DFTMethod class, and then executes optimisation, single-point energy, and/or NMR stages depending on workflow flags.

Parameters:

  • mols (list) – Molecule objects handled by the molecules container.

  • workflow (dict) – Workflow control flags (for example dft_opt, dft_energies, dft_nmr).

  • config (dict) – DFT configuration subsection.

Returns:

Updated molecule list.

Return type:

list

Base Class

wrapper for DFT methods.

Should implement setup, running, and reading the calculations

class dp5.dft.base_dft_method.BaseDFTMethod(settings)

Abstract base class for all DFT backends used by DP5.

Concrete backends (for example Gaussian, ORCA, and NWChem) inherit from this class and implement file generation, command preparation, and output parsing for a specific quantum chemistry engine.

The class also provides the orchestration logic that is backend-agnostic: selecting files to run, reusing completed calculations, launching jobs, and collecting parsed optimisation/energy/NMR data.

atom_num_to_symbol(anum: int) → str

Convert atomic number to element symbol.

Parameters:

anum (int) – Atomic number (1-indexed).

Returns:

Element symbol.

Return type:

str

energy(mols)

Run/read single-point energy calculations.

Parameters:

mols (list) – Molecules to evaluate.

Returns:

Tuple of (atoms, conformers, energies) grouped by molecule.

Return type:

tuple[list, list, list]

gasConstant = 8.3145
get_files(mols, calc_type)

Return completed calculation files for the requested calculation.

If self.dft_complete is set, pre-existing files are loaded from disk. Otherwise new calculations are prepared and executed.

Parameters:

  • mols (list) – Molecules with conformer geometries.

  • calc_type (str) – Calculation type label.

Returns:

Output file stems grouped per molecule.

Return type:

list[list[pathlib.Path]]

hartree_to_kJ = 2625.49962955401
is_completed(file)

Check whether a calculation terminated normally.

Parameters:

file (pathlib.Path) – Output file path.

Returns:

True if calculation completion flag is found.

Return type:

bool

is_converged(file)

Check whether an optimisation is marked as converged.

Parameters:

file (pathlib.Path) – Output file path.

Returns:

True if optimisation converged.

Return type:

bool

nmr(mols)

Run/read NMR shielding calculations.

Parameters:

mols (list) – Molecules to evaluate.

Returns:

Tuple of (atoms, conformers, energies, shieldings, shielding_labels) grouped by molecule.

Return type:

tuple[list, list, list, list, list]

opt(mols)

Run/read geometry optimisation results.

Parameters:

mols (list) – Molecules to optimise.

Returns:

Tuple of (atoms, conformers, energies) grouped by molecule, where conformers and energies correspond to converged optimisation outputs.

Return type:

tuple[list, list, list]

abstract prepare_command(file)

Build a shell command to run one calculation.

Concrete subclasses can override this to handle engine-specific command syntax.

Parameters:

file (pathlib.Path) – File stem without extension.

Returns:

Shell command string.

Return type:

str

abstract read_file(file)

Reads output file. Inspired by cclib parser

Returns:

  • atoms

  • coordinates

  • energies

  • shieldings

  • shielding labels

  • if calculation terminated normally

  • if optimisation has converged

temperature = 298.15
abstract write_file(filename, coordinates, atoms, charge, calc_type)

Write an engine-specific input file for one conformer.

Parameters:

  • filename (pathlib.Path) – File stem without extension.

  • coordinates (list) – Cartesian coordinates for one conformer.

  • atoms (list[str]) – Element symbols matching coordinates.

  • charge (int | float) – Molecular charge to use for the job.

  • calc_type (str) – Calculation type label.

Concrete Backends

Gaussian

class dp5.dft.gaussian.DFTMethod(settings)

Gaussian implementation of dp5.dft.base_dft_method.BaseDFTMethod.

e_options()

Build Gaussian route section for single-point energy jobs.

Returns:

Gaussian route section.

Return type:

str

nmr_options()

Build Gaussian route section for NMR shielding jobs.

Returns:

Gaussian route section.

Return type:

str

opt_options()

Build Gaussian route section for geometry optimisation jobs.

Returns:

Gaussian route section.

Return type:

str

prepare_command(file)

Prepare Gaussian execution command using input redirection.

Parameters:

file (pathlib.Path) – Input/output file stem.

Returns:

Shell command string.

Return type:

str

read_file(file)

Parse Gaussian output into DP5-standard result fields.

Parameters:

file (pathlib.Path) – Gaussian output path.

Returns:

(atoms, coordinates, energy, shieldings, shielding_labels, completed, opt_converged).

Return type:

tuple

write_file(filename, coordinates, atoms, charge, type)

Write a Gaussian .com input file for one conformer.

Parameters:

  • filename (pathlib.Path) – Output file stem.

  • coordinates (list) – Cartesian coordinates.

  • atoms (list[str]) – Element symbols.

  • charge (int | float) – Molecular charge.

  • type (str) – Calculation type ("opt", "e", "nmr").

NWChem

class dp5.dft.nwchem.DFTMethod(settings)

NWChem implementation of dp5.dft.base_dft_method.BaseDFTMethod.

e_options()

Build NWChem task block for single-point energy.

Returns:

NWChem task block.

Return type:

str

functional_dict = {'b3lyp': 'b3lyp', 'm062x': 'm06-2x', 'mpw1pw91': 'mpw91 perdew91'}
nmr_options()

Build NWChem task block for NMR shielding calculation.

Returns:

NWChem task block.

Return type:

str

opt_options()

Build NWChem task block for geometry optimisation.

Returns:

NWChem task block.

Return type:

str

prepare_command(file)

Build a shell command to run one calculation.

Concrete subclasses can override this to handle engine-specific command syntax.

Parameters:

file (pathlib.Path) – File stem without extension.

Returns:

Shell command string.

Return type:

str

read_file(file)

Parse NWChem output into DP5-standard result fields.

Parameters:

file (pathlib.Path) – NWChem output path.

Returns:

(atoms, coordinates, energy, shieldings, shielding_labels, completed, opt_converged).

Return type:

tuple

write_file(filename, coordinates, atoms, charge, calc_type)

Write an NWChem .nw input file for one conformer.

Parameters:

  • filename (pathlib.Path) – Output file stem.

  • coordinates (list) – Cartesian coordinates.

  • atoms (list[str]) – Element symbols.

  • charge (int | float) – Molecular charge.

  • calc_type (str) – Calculation type.

ORCA

class dp5.dft.orca.DFTMethod(settings)

ORCA implementation of dp5.dft.base_dft_method.BaseDFTMethod.

basis_dict = {'def2tzvp': 'def2-tzvp'}
functional_dict = {'b3lyp': 'functional b3lyp_g', 'm062x': 'functional m062x', 'mpw1pw91': 'exchange gga_x_mpw91\n  correlation gga_c_pw91'}
prepare_command(file)

Build a shell command to run one calculation.

Concrete subclasses can override this to handle engine-specific command syntax.

Parameters:

file (pathlib.Path) – File stem without extension.

Returns:

Shell command string.

Return type:

str

read_file(file)

Parse ORCA output into DP5-standard result fields.

Parameters:

file (pathlib.Path) – ORCA output path.

Returns:

(atoms, coordinates, energy, shieldings, shielding_labels, completed, converged).

Return type:

tuple

write_file(filename, coordinates, atoms, charge, calc_type)

Write an ORCA .inp input file for one conformer.

Parameters:

  • filename (pathlib.Path) – Output file stem.

  • coordinates (list) – Cartesian coordinates.

  • atoms (list[str]) – Element symbols.

  • charge (int | float) – Molecular charge.

  • calc_type (str) – Calculation type.