pyCADD.Density package

Submodules

pyCADD.Density.base module

High-level Gaussian quantum chemistry calculation interface.

This module provides the Gauss class which serves as a high-level interface for running Gaussian quantum chemistry calculations including geometry optimization, single-point energy calculations, and RESP/RESP2 charge calculations.

class pyCADD.Density.base.Gauss[source]

Bases: object

High-level interface for Gaussian quantum chemistry calculations.

This class provides methods for running various types of Gaussian calculations including geometry optimization, single-point energy calculations, and RESP charge calculations. It automatically manages input file generation, job execution, and output file handling.

gauss

Path to the Gaussian executable (g16).

Type:

str

Example

>>> gauss = Gauss()
>>> opt_file = gauss.calc_opt("molecule.sdf", charge=0, multiplicity=1)
>>> resp_file = gauss.calc_resp("molecule.sdf", charge=0)
__init__() → None[source]

Initializes the Gauss calculator by locating the Gaussian executable.

Raises:

FileNotFoundError – If the g16 executable is not found in the system PATH.

static change_atom_type(mol2_block: str, atom_type: str = 'gaff2', dumpto: str = None) → str[source]
run(gau_input: str, job_name: str = None, dumpto: str = None) → str[source]

Executes a Gaussian calculation with the provided input.

Runs a Gaussian calculation by writing the input to a file and executing the Gaussian program. The calculation can be run in a temporary directory or a specified output directory.

Parameters:

  • gau_input (str) – Complete Gaussian input file content as a string.

  • job_name (str, optional) – Base name for input and output files. Defaults to “gauss_job”.

  • dumpto (str, optional) – Directory path where calculation files should be saved. If None, uses a temporary directory that is automatically cleaned up.

Returns:

Content of the Gaussian output file.

Return type:

str

Raises:

  • RuntimeError – If the Gaussian calculation fails.

  • FileNotFoundError – If the Gaussian executable is not found.

Note

When dumpto is None, all calculation files are created in a temporary directory and only the output content is returned. When dumpto is specified, all files are preserved in that directory.

static convert_to_mol2_block(structure_file: str | File) → str[source]

Converts a molecular structure file to MOL2 format.

Uses OpenBabel to convert various molecular file formats (SDF, PDB, XYZ, etc.) to MOL2 format and returns the content as a string.

Parameters:

structure_file (str | File) – Path to the input molecular structure file or File object.

Returns:

Complete MOL2 format content of the converted structure.

Return type:

str

Raises:

  • RuntimeError – If OpenBabel conversion fails.

  • FileNotFoundError – If the input structure file doesn’t exist.

Note

The conversion is performed in a temporary directory and only the MOL2 content is returned. Supported input formats include most common molecular file types recognized by OpenBabel.

static get_resp_mol2_block(gout_file: str | File) → str[source]

Extracts RESP charges from Gaussian output and generates MOL2 format.

Uses AmberTools antechamber to extract RESP (Restrained Electrostatic Potential) charges from a Gaussian output file and create a MOL2 format structure with the calculated charges.

Parameters:

gout_file (str | File) – Path to Gaussian output file (.out) containing ESP calculation results or File object.

Returns:

Complete MOL2 format content with RESP charges assigned to atoms.

Return type:

str

Raises:

  • RuntimeError – If antechamber processing fails or if the Gaussian output doesn’t contain the required ESP information.

  • FileNotFoundError – If the Gaussian output file doesn’t exist.

Note

The input Gaussian calculation must have been performed with ESP calculation keywords (e.g., “pop=MK IOp(6/33=2,6/42=6)”) to generate the electrostatic potential data required for RESP charge fitting.

static get_resp2_mol2_block(gas_mol2_block: str, solvent_mol2_block: str, delta: float = 0.5) → str[source]

Generates RESP2 charges by interpolating between gas and solvent RESP charges.

Calculates RESP2 charges using the formula: RESP2 = (1-δ) × RESP_gas + δ × RESP_solvent where δ (delta) is the interpolation parameter.

Parameters:

  • gas_mol2_block (str) – MOL2 format string containing gas-phase RESP charges.

  • solvent_mol2_block (str) – MOL2 format string containing solvent-phase RESP charges.

  • delta (float, optional) – Interpolation parameter (0.0 = pure gas, 1.0 = pure solvent). Defaults to 0.5 for equal weighting.

Returns:

MOL2 format string with interpolated RESP2 charges.

Return type:

str

Raises:

  • ValueError – If the number of atoms in gas and solvent MOL2 blocks don’t match.

  • IndexError – If either MOL2 block has incomplete atomic information.

Note

Both input MOL2 blocks must represent the same molecular structure with identical atom ordering. The RESP2 method provides charges that balance gas-phase and solution-phase electrostatic properties.

calc_opt(structure_file: str | File, charge: int, multiplicity: int = 1, dft: str = 'B3LYP', basis_set: str = '6-31g*', solvent: str = 'water', loose: bool = True, dispersion_correct: bool = False, td: bool = False, freq: bool = False, mem_use: str = '4GB', cpu_num: int = 4, save_dir: str = None) → File[source]

Performs geometry optimization calculation using Gaussian.

Executes a complete geometry optimization calculation with customizable DFT method, basis set, and optimization parameters. The optimized structure is saved to an output file.

Parameters:

  • structure_file (str | File) – Path to the input molecular structure file or File object.

  • charge (int) – Molecular charge (required parameter).

  • multiplicity (int, optional) – Spin multiplicity. Defaults to 1.

  • dft (str, optional) – DFT functional name. Defaults to “B3LYP”.

  • basis_set (str, optional) – Basis set specification. Defaults to “6-31g*”.

  • solvent (str, optional) – Solvent for implicit solvation model. Defaults to “water”.

  • loose (bool, optional) – Whether to use loose convergence criteria for faster optimization. Defaults to True.

  • dispersion_correct (bool, optional) – Whether to apply dispersion correction (GD3BJ). Defaults to False.

  • td (bool, optional) – Whether to perform time-dependent DFT optimization. Defaults to False.

  • freq (bool, optional) – Whether to calculate vibrational frequencies after optimization. Defaults to False.

  • mem_use (str, optional) – Memory allocation string. Defaults to “4GB”.

  • cpu_num (int, optional) – Number of processors to use. Defaults to 4.

  • save_dir (str, optional) – Directory to save calculation result files. If None, saves in current directory.

Returns:

Generated Gaussian output file containing optimization results.

Return type:

File

Raises:

  • RuntimeError – If the Gaussian optimization calculation fails.

  • FileNotFoundError – If the input structure file doesn’t exist.

Note

The output file is named “{structure_prefix}_opt.out” and contains the complete optimization trajectory and final optimized geometry.

calc_energy(structure_file: str | File, charge: int, multiplicity: int = 1, dft: str = 'B3LYP', basis_set: str = '6-31g*', solvent: str = 'water', dispersion_correct: bool = False, td: bool = False, esp_calculate: bool = False, mem_use: str = '4GB', cpu_num: int = 4, save_dir: str = None) → File[source]

Performs single-point energy calculation using Gaussian.

Calculates the electronic energy of a molecular structure without geometry optimization. Can include electrostatic potential calculation for RESP charge fitting and time-dependent DFT for excited states.

Parameters:

  • structure_file (str | File) – Path to the input molecular structure file or File object.

  • charge (int) – Molecular charge (required parameter).

  • multiplicity (int, optional) – Spin multiplicity. Defaults to 1.

  • dft (str, optional) – DFT functional name. Defaults to “B3LYP”.

  • basis_set (str, optional) – Basis set specification. Defaults to “6-31g*”.

  • solvent (str, optional) – Solvent for implicit solvation model. Defaults to “water”. Set to None for gas-phase calculation.

  • dispersion_correct (bool, optional) – Whether to apply dispersion correction (GD3BJ). Defaults to False.

  • td (bool, optional) – Whether to perform time-dependent DFT calculation. Defaults to False.

  • esp_calculate (bool, optional) – Whether to calculate electrostatic potential for RESP charge fitting. Defaults to False.

  • mem_use (str, optional) – Memory allocation string. Defaults to “4GB”.

  • cpu_num (int, optional) – Number of processors to use. Defaults to 4.

  • save_dir (str, optional) – Directory to save calculation result files. If None, saves in current directory.

Returns:

Path to the generated Gaussian output file containing energy results.

Return type:

File

Raises:

  • RuntimeError – If the Gaussian energy calculation fails.

  • FileNotFoundError – If the input structure file doesn’t exist.

Note

Output file naming follows the pattern “{structure_prefix}_{solvent}_energy.out” or “{structure_prefix}_gas_energy.out” for gas-phase calculations. When esp_calculate=True, the output contains ESP data suitable for RESP fitting.

calc_resp(structure_file: str | File, charge: int, multiplicity: int = 1, dft: str = 'B3LYP', basis_set: str = '6-31g*', solvent: str = 'water', mem_use: str = '4GB', cpu_num: int = 4, atom_type: str = 'gaff2', save_dir: str = None) → File[source]

Performs complete RESP charge calculation workflow.

Executes a full RESP (Restrained Electrostatic Potential) charge calculation workflow including geometry optimization and single-point energy calculation with ESP analysis. The resulting charges are merged back into the original molecular structure format.

Parameters:

  • structure_file (str | File) – Path to the input molecular structure file or File object.

  • charge (int) – Molecular charge (required parameter).

  • multiplicity (int, optional) – Spin multiplicity. Defaults to 1.

  • dft (str, optional) – DFT functional name. Defaults to “B3LYP”.

  • basis_set (str, optional) – Basis set specification. Defaults to “6-31g*”.

  • solvent (str, optional) – Solvent for implicit solvation model. Defaults to “water”.

  • mem_use (str, optional) – Memory allocation string. Defaults to “4GB”.

  • cpu_num (int, optional) – Number of processors to use. Defaults to 4.

  • atom_type (str, optional) – Atom type to assign using antechamber. Defaults to “gaff2”. None for no change.

  • save_dir (str, optional) – Directory to save calculation result files. If None, saves in current directory.

Returns:

Path to the generated MOL2 file with RESP charges assigned to atoms.

Return type:

File

Raises:

  • RuntimeError – If any step of the RESP calculation workflow fails.

  • FileNotFoundError – If the input structure file doesn’t exist.

Note

The complete workflow includes:

  1. Geometry optimization with loose convergence

  2. Single-point energy calculation with ESP analysis

  3. RESP charge fitting using antechamber

  4. Merging charges back into original molecular structure

Output file is named “{structure_prefix}_resp.mol2”.

calc_resp2(structure_file: str | File, charge: int, multiplicity: int = 1, dft: str = 'B3LYP', basis_set: str = '6-31g*', solvent: str = 'water', mem_use: str = '4GB', cpu_num: int = 4, delta: float = 0.5, atom_type: str = 'gaff2', save_dir: str = None) → File[source]

Performs complete RESP2 charge calculation workflow.

Executes a full RESP2 charge calculation workflow that combines gas-phase and solvent-phase RESP charges using interpolation. This method provides charges that balance gas-phase and solution-phase electrostatic properties.

Parameters:

  • structure_file (str | File) – Path to the input molecular structure file or File object.

  • charge (int) – Molecular charge (required parameter).

  • multiplicity (int, optional) – Spin multiplicity. Defaults to 1.

  • dft (str, optional) – DFT functional name. Defaults to “B3LYP”.

  • basis_set (str, optional) – Basis set specification. Defaults to “6-31g*”.

  • solvent (str, optional) – Solvent for implicit solvation model. Defaults to “water”.

  • mem_use (str, optional) – Memory allocation string. Defaults to “4GB”.

  • cpu_num (int, optional) – Number of processors to use. Defaults to 4.

  • delta (float, optional) – Interpolation parameter for RESP2 charge calculation. 0.0 = pure gas-phase, 1.0 = pure solvent-phase. Defaults to 0.5.

  • atom_type (str, optional) – Atom type to assign using antechamber. Defaults to “gaff2”. None for no change.

  • save_dir (str, optional) – Directory to save calculation result files. If None, saves in current directory.

Returns:

Path to the generated MOL2 file with RESP2 charges assigned to atoms.

Return type:

File

Raises:

  • RuntimeError – If any step of the RESP2 calculation workflow fails.

  • FileNotFoundError – If the input structure file doesn’t exist.

  • ValueError – If gas and solvent calculations produce inconsistent atom counts.

Note

The complete workflow includes:

  1. Geometry optimization with loose convergence

  2. Gas-phase single-point energy calculation with ESP analysis

  3. Solvent-phase single-point energy calculation with ESP analysis

  4. RESP charge fitting for both phases using antechamber

  5. Interpolation of charges using RESP2 formula: (1-δ)*RESP_gas + δ*RESP_solvent

Output files include individual gas/solvent RESP files and final RESP2 file.

pyCADD.Density.cli module

pyCADD.Density.core module

Core utilities for Gaussian quantum chemistry calculations and molecular density analysis.

This module provides core functions for generating Gaussian input files, processing molecular structures, and handling charge calculations for quantum chemistry workflows.

pyCADD.Density.core.generate_gauss_input(structure_file: str | File, keyword: str, chk_file: str = None, title: str = None, charge: int = 0, multiplicity: int = 1, mem_use: str = '4GB', cpu_num: int = 4)[source]

Generates a Gaussian input file from a molecular structure.

Creates a Gaussian input (.gjf) file by combining molecular geometry from OpenBabel with specified quantum chemistry parameters.

Parameters:

  • structure_file (str | File) – Path to the input molecular structure file or File object.

  • keyword (str) – Gaussian calculation keywords (e.g., “# opt B3LYP/6-31G*”).

  • chk_file (str, optional) – Name of the checkpoint file. Defaults to structure_file prefix + “.chk”.

  • title (str, optional) – Title for the calculation. Defaults to structure_file prefix + “ Gaussian Input”.

  • charge (int, optional) – Molecular charge. Defaults to 0.

  • multiplicity (int, optional) – Spin multiplicity. Defaults to 1.

  • mem_use (str, optional) – Memory allocation string. Defaults to “4GB”.

  • cpu_num (int, optional) – Number of processors to use. Defaults to 4.

Returns:

Content of the generated Gaussian input file.

Return type:

str

Raises:

  • FileNotFoundError – If the structure file doesn’t exist.

  • RuntimeError – If OpenBabel conversion fails.

pyCADD.Density.core.generate_opt_input(structure_file: str | File, charge: int, multiplicity: int = 1, dft: str = 'B3LYP', basis_set: str = '6-31g*', solvent: str = 'water', loose: bool = True, dispersion_correct: bool = True, td: bool = False, freq: bool = False, mem_use: str = '4GB', cpu_num: int = 4)[source]

Generates Gaussian input for geometry optimization calculations.

Creates a Gaussian input file optimized for geometry optimization with customizable DFT method, basis set, and calculation options.

Parameters:

  • structure_file (str | File) – Path to the input molecular structure file or File object.

  • charge (int) – Molecular charge (required parameter).

  • multiplicity (int, optional) – Spin multiplicity. Defaults to 1.

  • dft (str, optional) – DFT functional name. Defaults to “B3LYP”.

  • basis_set (str, optional) – Basis set specification. Defaults to “6-31g*”.

  • solvent (str, optional) – Solvent for implicit solvation model. Defaults to “water”.

  • loose (bool, optional) – Whether to use loose convergence criteria. Defaults to True.

  • dispersion_correct (bool, optional) – Whether to apply dispersion correction (GD3BJ). Defaults to True.

  • td (bool, optional) – Whether to perform time-dependent DFT calculation. Defaults to False.

  • freq (bool, optional) – Whether to calculate vibrational frequencies. Defaults to False.

  • mem_use (str, optional) – Memory allocation string. Defaults to “4GB”.

  • cpu_num (int, optional) – Number of processors to use. Defaults to 4.

Returns:

Content of the generated Gaussian optimization input file.

Return type:

str

Note

The checkpoint file is automatically named as “{structure_prefix}_opt.chk” or “{structure_prefix}_opt_td.chk” if TD-DFT is enabled.

pyCADD.Density.core.generate_energy_input(structure_file: str | File, charge: int, multiplicity: int, dft: str = 'B3LYP', basis_set: str = '6-31g*', solvent: str = 'water', dispersion_correct: bool = True, td: bool = False, esp_calculate: bool = False, mem_use: str = '4GB', cpu_num: int = 4)[source]

Generates Gaussian input for single-point energy calculations.

Creates a Gaussian input file for single-point energy calculations with options for electrostatic potential (ESP) calculation and TD-DFT.

Parameters:

  • structure_file (str | File) – Path to the input molecular structure file or File object.

  • charge (int) – Molecular charge (required parameter).

  • multiplicity (int) – Spin multiplicity (required parameter).

  • dft (str, optional) – DFT functional name. Defaults to “B3LYP”.

  • basis_set (str, optional) – Basis set specification. Defaults to “6-31g*”.

  • solvent (str, optional) – Solvent for implicit solvation model. Defaults to “water”.

  • dispersion_correct (bool, optional) – Whether to apply dispersion correction (GD3BJ). Defaults to True.

  • td (bool, optional) – Whether to perform time-dependent DFT calculation. Defaults to False.

  • esp_calculate (bool, optional) – Whether to calculate electrostatic potential for RESP charges. Defaults to False.

  • mem_use (str, optional) – Memory allocation string. Defaults to “4GB”.

  • cpu_num (int, optional) – Number of processors to use. Defaults to 4.

Returns:

Content of the generated Gaussian single-point energy input file.

Return type:

str

Note

When esp_calculate is True, the calculation includes “pop=MK IOp(6/33=2,6/42=6)” keywords for Merz-Kollman population analysis suitable for RESP charge fitting.

pyCADD.Density.core.generate_fchk(chk_file_path: str | File)[source]

Converts a Gaussian checkpoint file to formatted checkpoint file.

Uses the Gaussian formchk utility to convert a binary checkpoint (.chk) file to a formatted checkpoint (.fchk) file that can be read by other programs.

Parameters:

chk_file_path (str | File) – Path to the Gaussian checkpoint file or File object.

Returns:

Path to the generated formatted checkpoint file (.fchk).

Return type:

str

Raises:

  • RuntimeError – If the formchk command fails.

  • FileNotFoundError – If the checkpoint file doesn’t exist.

Note

The output .fchk file is created in the same directory as the input .chk file with the same base name but .fchk extension.

pyCADD.Density.core.merge_mol2_charge(charge_mol2_block: str, origin_mol2_block: str) → str[source]

Merges partial charges from one MOL2 block into another MOL2 block.

Extracts partial charges from the charge_mol2_block and applies them to the corresponding atoms in the origin_mol2_block, preserving the original structure and connectivity while updating the charges.

Parameters:

  • charge_mol2_block (str) – MOL2 format string containing the source charges.

  • origin_mol2_block (str) – MOL2 format string to receive the new charges.

Returns:

Modified MOL2 format string with charges from charge_mol2_block

applied to the structure from origin_mol2_block.

Return type:

str

Raises:

  • IndexError – If the number of atoms differs between the two MOL2 blocks.

  • ValueError – If either MOL2 block has invalid format.

Note

Both MOL2 blocks must have the same number of atoms with complete atomic information for proper charge transfer.

Module contents