psi4_utils¶

parametrizani.psi4_utils ¶

ParametrizANI - Psi4 Utilities¶

Optional Psi4-based functions for RESP charge calculation.

Requires: conda install -c conda-forge psi4 resp

These functions are optional and not required for the main ParametrizANI workflow. They provide higher-accuracy QM-based charges as an alternative to the default AM1-BCC charges from antechamber.

calculate_resp_charges ¶

calculate_resp_charges(mol_file: str, method: str = 'HF', basis: str = '6-31G*', charge: int = 0, multiplicity: int = 1, memory: str = '2 GB', n_threads: int = 2, resp_a: float = 0.0005, resp_b: float = 0.1, output_file: Optional[str] = None) -> Dict[str, Any]

Calculate RESP charges using Psi4.

Uses Psi4 to compute the electrostatic potential (ESP) and fits restrained electrostatic potential (RESP) charges. This provides higher-accuracy partial charges compared to AM1-BCC.

Parameters:

Name	Type	Description	Default
`mol_file`	`str`	Path to the molecule file (MOL, MOL2, SDF, or PDB format).	required
`method`	`str`	QM method for ESP calculation. Options: 'HF', 'B3LYP', 'MP2', 'wB97X-D'. Default: 'HF'.	`'HF'`
`basis`	`str`	Basis set. Options: '6-31G', 'cc-pVDZ', 'cc-pVTZ', etc. Default: '6-31G'.	`'6-31G*'`
`charge`	`int`	Net molecular charge. Default: 0.	`0`
`multiplicity`	`int`	Spin multiplicity. Default: 1 (singlet).	`1`
`memory`	`str`	Memory allocation for Psi4. Default: '2 GB'.	`'2 GB'`
`n_threads`	`int`	Number of CPU threads for Psi4. Default: 2.	`2`
`resp_a`	`float`	RESP restraint strength parameter a. Default: 0.0005.	`0.0005`
`resp_b`	`float`	RESP tightness parameter b. Default: 0.1.	`0.1`
`output_file`	`str`	Path to save charges. If None, saves to same directory as mol_file.	`None`

Returns:

Type	Description
`Dict[str, Any]`	Dictionary with: - 'charges': np.ndarray of RESP charges - 'atom_symbols': list of atom element symbols - 'output_file': path to saved charges file

Raises:

Type	Description
`ImportError`	If psi4 or resp packages are not installed.
`ValueError`	If molecule file cannot be read.

Examples:

>>> from parametrizani import calculate_resp_charges
>>> result = calculate_resp_charges('molecule.mol', method='HF', basis='6-31G*')
>>> print(result['charges'])
>>> print(f"Total charge: {sum(result['charges']):.4f}")

Usage Example¶

from parametrizani import calculate_resp_charges

# Calculate RESP charges using Psi4
result = calculate_resp_charges(
    'molecule.mol',
    method='HF',          # QM method for ESP calculation
    basis='6-31G*',       # Basis set
    charge=0,
    multiplicity=1,
    memory='2 GB',
    n_threads=2,
)

print(result['charges'])       # np.ndarray of RESP charges
print(result['atom_symbols'])  # ['C', 'C', 'O', 'H', ...]
print(result['output_file'])   # Path to saved charges file

Requirements¶

This module requires Psi4 and the resp package:

conda install -c conda-forge psi4 resp -y

These are optional dependencies — they are NOT required for the main ParametrizANI workflow.

Supported Methods¶

Method	Description	Speed
`HF`	Hartree-Fock	Fast (standard for RESP)
`B3LYP`	B3LYP DFT functional	Medium
`MP2`	Møller-Plesset 2nd order perturbation theory	Slow (higher accuracy)
`wB97X-D`	Range-separated hybrid with dispersion	Medium
`PBE0`	PBE0 hybrid functional	Medium
`M06-2X`	M06-2X functional	Medium

Recommendation: Use HF for standard RESP charges (matches the original Bayly et al. 1993 protocol and the AMBER force field convention). Use B3LYP or MP2 when higher accuracy is needed.

Supported Basis Sets¶

Basis	Description	Recommended for
`6-31G*`	Pople double-zeta + polarization	Standard RESP (default, recommended)
`6-31G**`	Adds polarization on H atoms	Slightly better H charges
`cc-pVDZ`	Correlation-consistent double-zeta	General use
`cc-pVTZ`	Correlation-consistent triple-zeta	Higher accuracy (slower)
`aug-cc-pVDZ`	Augmented double-zeta	Anions, lone pairs
`def2-SVP`	Karlsruhe split-valence polarized	Fast alternative
`def2-TZVP`	Karlsruhe triple-zeta valence polarized	High accuracy alternative

Recommendation: Use 6-31G* for standard RESP charges. This is the basis set used in the original RESP paper (Bayly et al. 1993) and provides the best compatibility with AMBER force fields.

RESP Parameters¶

Parameter	Description	Default
`resp_a`	Restraint strength (hyperbolic penalty)	0.0005
`resp_b`	Tightness of the hyperbolic penalty	0.1
`charge`	Net molecular charge	0
`multiplicity`	Spin multiplicity (1=singlet, 2=doublet, ...)	1
`memory`	Memory for Psi4 calculation	`'2 GB'`
`n_threads`	Number of CPU threads	2

Integration with GAFF2 Workflow¶

After computing RESP charges, pass the charges file to generate_amber():

from parametrizani import calculate_resp_charges, TopologyGenerator, ConformerGenerator

# 1. Generate conformer
gen = ConformerGenerator(smiles, 'smiles', './work')
conf = gen.run()

# 2. Calculate RESP charges with Psi4
resp_result = calculate_resp_charges(conf['mol_file'], method='HF', basis='6-31G*')
print(f"Charges: {resp_result['charges']}")
print(f"Saved to: {resp_result['output_file']}")

# 3. Generate topology using the Psi4 RESP charges
topo = TopologyGenerator('./work', force_field='gaff2')
amber_files = topo.generate_amber(
    conf['mol_file'],
    resp_charges_file=resp_result['output_file']  # Reads pre-computed Psi4 charges
)

The resp_charges_file parameter tells antechamber to read pre-computed charges from the file (-c rc -cf <file>) rather than trying to compute RESP charges internally (which would require Gaussian/GAMESS). This is the correct way to integrate Psi4 RESP charges into the AMBER topology generation pipeline.