DFT Architecture And Class Logic

Overview

The DFT workflow in dp5.dft is designed around one abstract base class and several concrete backend implementations:

dp5.dft.base_dft_method.BaseDFTMethod
dp5.dft.gaussian.DFTMethod
dp5.dft.nwchem.DFTMethod
dp5.dft.orca.DFTMethod

The module-level entrypoint dp5.dft.run_dft.dft_calculations() loads the backend selected in config and executes the requested DFT stages.

Class Inheritance

Inheritance structure:

BaseDFTMethod defines shared orchestration logic and abstract methods.
Each backend DFTMethod subclass implements engine-specific input writing, command format, and output parsing.

The following directives show the class hierarchy and inherited members:

class dp5.dft.base_dft_method.BaseDFTMethod(settings)

Bases: ABC

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.

class dp5.dft.gaussian.DFTMethod(settings)

Bases: BaseDFTMethod

Gaussian implementation of dp5.dft.base_dft_method.BaseDFTMethod.

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

e_options()

Build Gaussian route section for single-point energy jobs.

Returns:: Gaussian route section.
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]

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]]

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]

nmr_options()

Build Gaussian route section for NMR shielding jobs.

Returns:: Gaussian route section.
Return type:: str

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]

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").

class dp5.dft.nwchem.DFTMethod(settings)

Bases: BaseDFTMethod

NWChem implementation of dp5.dft.base_dft_method.BaseDFTMethod.

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

e_options()

Build NWChem task block for single-point energy.

Returns:: NWChem task block.
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]

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]]

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]

nmr_options()

Build NWChem task block for NMR shielding calculation.

Returns:: NWChem task block.
Return type:: str

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]

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.

class dp5.dft.orca.DFTMethod(settings)

Bases: BaseDFTMethod

ORCA implementation of dp5.dft.base_dft_method.BaseDFTMethod.

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]

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]]

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]

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.

Execution Flow

dp5.dft.run_dft.dft_calculations() imports the backend module named by config["method"] and instantiates DFTMethod(config).
Workflow flags (dft_opt, dft_energies, dft_nmr) control which stage methods are called.
Stage methods in BaseDFTMethod call BaseDFTMethod.get_files().
get_files either loads pre-run outputs or creates/runs missing jobs.
Each output is parsed through backend read_file() and mapped into DP5 molecule attributes.

Core Base Class Logic

The base class isolates common logic so backends only provide engine-specific behavior:

dp5.dft.base_dft_method.BaseDFTMethod.get_files() Selects between precomputed data and active execution.
dp5.dft.base_dft_method.BaseDFTMethod._get_files() Builds file stems per conformer, reuses valid outputs, and schedules missing calculations.
dp5.dft.base_dft_method.BaseDFTMethod._run_calcs() Runs backend commands and checks completion status.
dp5.dft.base_dft_method.BaseDFTMethod.opt() Enforces optimisation convergence before returning geometries.
dp5.dft.base_dft_method.BaseDFTMethod.energy() Collects single-point energies and associated coordinates.
dp5.dft.base_dft_method.BaseDFTMethod.nmr() Collects shielding tensors and labels in addition to energies.

Backend Responsibilities

Each backend subclass implements these abstract integration points:

dp5.dft.base_dft_method.BaseDFTMethod.write_file() Serialize one conformer and settings to an engine input file.
dp5.dft.base_dft_method.BaseDFTMethod.prepare_command() Return the shell command used to run one calculation.
dp5.dft.base_dft_method.BaseDFTMethod.read_file() Parse one output file and return the standard DP5 tuple contract.

This contract keeps downstream DP5 logic independent from the DFT engine in use.