qrunch.chemistry.molecular_orbital_calculators.electron_correlation.coupled_cluster

Restricted and unrestricted calculators for coupled cluster (CCSD) natural orbitals.

Module Attributes

DEFAULT_OPTIONS

The default options for the CCSD Calculator.

Classes

CCSDCalculator

A CCSD molecular orbital calculator.

CCSDCalculatorOptions

Options controlling CCSDCalculator.

RestrictedCCSDCalculator

A restricted coupled cluster singles and doubles (CCSD) molecular orbital calculator.

UnrestrictedCCSDCalculator

An unrestricted coupled cluster singles and doubles (CCSD) molecular orbital calculator.
class CCSDCalculator

Bases: MolecularOrbitalCalculator

A CCSD molecular orbital calculator.

Uses a Hartree-Fock solution as a starting point, runs CCSD, then computes natural orbitals from the CCSD one-particle reduced density matrix.

__init__(options: CCSDCalculatorOptions | None = None) → None

Initialize CCSD molecular orbital calculator.

Parameters:

options (CCSDCalculatorOptions | None) – Options for the CCSD calculator.

Return type:

None

solve_restricted(molecular_configuration: MolecularConfiguration, initial_guess: RestrictedDensityOperator | None = None, additional_potential: RestrictedElectronPotential | None = None) → RestrictedMolecularOrbitalCalculatorResult

Solve the restricted problem.

Parameters:
Return type:

RestrictedMolecularOrbitalCalculatorResult

solve_unrestricted(molecular_configuration: MolecularConfiguration, initial_guess: UnrestrictedDensityOperator | None = None, additional_potential: UnrestrictedElectronPotential | None = None) → UnrestrictedMolecularOrbitalCalculatorResult

Solve the unrestricted problem.

Parameters:
Return type:

UnrestrictedMolecularOrbitalCalculatorResult

class CCSDCalculatorOptions

Bases: DataclassPublicAPI

Options controlling CCSDCalculator.

All fields are immutable (frozen=True) so an instance can be safely reused.

Parameters:

  • convergence_tolerance – Energy convergence tolerance for the HF step. (default=1e-9)

  • convergence_tolerance_gradient – Gradient convergence tolerance for the HF step. (default=3.16227766016-05)

  • initial_guess – Initial guess method for the HF step. (default=”minao”)

  • max_iterations – Maximum number of SCF iterations for the HF step. (default=50)

  • level_shift – Energy level shift for the HF step. (default=0.0)

  • verbose – Verbosity level. (default=0)

  • get_number_of_electrons_from_initial_guess – If true, the number of electrons in the initial guess will always overwrite the number of electrons in the molecular configuration. (default=False)

  • frozen_core_approximation – If true, core (or inner) orbitals are kept frozen during the CCSD calculation. (default=False)

  • virtual_truncation_threshold – Threshold below which virtual natural orbitals are discarded. (default=1.0e-5)

  • frozen_virtual_threshold – Disregard virtual orbitals with HF orbital energies above this threshold. (default=100.0)

  • fallback_options – Fallback options in case default SCF settings fail to converge. (default=(“SOSCF”,))

  • do_density_fitting – Utilize density fitting for the HF step. (default=False)

  • degeneracy_threshold – Minimum allowed gap between any occupied and virtual orbital energy. If \(|\varepsilon_a - \varepsilon_i| <\) degeneracy_threshold for any occupied orbital i and virtual orbital a, the calculation raises a ValueError to avoid numerically unstable energy denominators. (default=0.02)

  • integral_direct – If true, use integral-direct CCSD which recomputes two-electron integrals on the fly instead of storing them on disk. Thus reducing disk usage at the cost of increased memory. (default=False)

  • break_spin_symmetry – If true, the UHF initial guess is constructed by mixing HOMO and LUMO orbitals from a preliminary RHF calculation, breaking alpha/beta symmetry. Only affects unrestricted calculations and is ignored when an explicit initial_guess is provided. (default=False)

  • stability_analysis – If true, a post-convergence UHF stability analysis is performed and the SCF is re-converged if an instability is detected. Only affects unrestricted calculations. (default=False)

  • max_stability_iterations – Maximum number of stability-check / re-convergence cycles when stability_analysis is enabled. (default=10)

__init__(*, convergence_tolerance: float = 1e-09, convergence_tolerance_gradient: float = 3.1622776601683795e-05, initial_guess: Literal['minao', 'atom', 'huckel', 'vsap', 'chk', '1e'] | str = 'minao', max_iterations: int = 50, level_shift: float = 0.0, verbose: int = 0, get_number_of_electrons_from_initial_guess: bool = False, frozen_core_approximation: bool = False, virtual_truncation_threshold: float = 1e-05, frozen_virtual_threshold: float = 100.0, fallback_options: tuple[Literal['SOSCF', 'LevelShift(0.1)']] = ('SOSCF',), do_density_fitting: bool = False, degeneracy_threshold: float = 0.02, integral_direct: bool = False, break_spin_symmetry: bool = False, stability_analysis: bool = False, max_stability_iterations: int = 10) → None
Parameters:

  • convergence_tolerance (float)

  • convergence_tolerance_gradient (float)

  • initial_guess (Literal['minao', 'atom', 'huckel', 'vsap', 'chk', '1e'] | str)

  • max_iterations (int)

  • level_shift (float)

  • verbose (int)

  • get_number_of_electrons_from_initial_guess (bool)

  • frozen_core_approximation (bool)

  • virtual_truncation_threshold (float)

  • frozen_virtual_threshold (float)

  • fallback_options (tuple[Literal['SOSCF', 'LevelShift(0.1)']])

  • do_density_fitting (bool)

  • degeneracy_threshold (float)

  • integral_direct (bool)

  • break_spin_symmetry (bool)

  • stability_analysis (bool)

  • max_stability_iterations (int)

Return type:

None

break_spin_symmetry: bool = False
convergence_tolerance: float = 1e-09
convergence_tolerance_gradient: float = 3.1622776601683795e-05
degeneracy_threshold: float = 0.02
do_density_fitting: bool = False
fallback_options: tuple[Literal['SOSCF', 'LevelShift(0.1)']] = ('SOSCF',)
frozen_core_approximation: bool = False
frozen_virtual_threshold: float = 100.0
get_number_of_electrons_from_initial_guess: bool = False
initial_guess: Literal['minao', 'atom', 'huckel', 'vsap', 'chk', '1e'] | str = 'minao'
integral_direct: bool = False
level_shift: float = 0.0
max_iterations: int = 50
max_stability_iterations: int = 10
stability_analysis: bool = False
verbose: int = 0
virtual_truncation_threshold: float = 1e-05
DEFAULT_OPTIONS = CCSDCalculatorOptions(convergence_tolerance=1e-09, convergence_tolerance_gradient=3.1622776601683795e-05, initial_guess='minao', max_iterations=50, level_shift=0.0, verbose=0, get_number_of_electrons_from_initial_guess=False, frozen_core_approximation=False, virtual_truncation_threshold=1e-05, frozen_virtual_threshold=100.0, fallback_options=('SOSCF',), do_density_fitting=False, degeneracy_threshold=0.02, integral_direct=False, break_spin_symmetry=False, stability_analysis=False, max_stability_iterations=10)

The default options for the CCSD Calculator.

class RestrictedCCSDCalculator

Bases: object

A restricted coupled cluster singles and doubles (CCSD) molecular orbital calculator.

Uses a Hartree-Fock solution as a starting point, runs CCSD, then computes natural orbitals from the CCSD one-particle reduced density matrix.

__init__(options: CCSDCalculatorOptions = CCSDCalculatorOptions(convergence_tolerance=1e-09, convergence_tolerance_gradient=3.1622776601683795e-05, initial_guess='minao', max_iterations=50, level_shift=0.0, verbose=0, get_number_of_electrons_from_initial_guess=False, frozen_core_approximation=False, virtual_truncation_threshold=1e-05, frozen_virtual_threshold=100.0, fallback_options=('SOSCF',), do_density_fitting=False, degeneracy_threshold=0.02, integral_direct=False, break_spin_symmetry=False, stability_analysis=False, max_stability_iterations=10)) → None

Initialize restricted CCSD molecular orbital calculator.

Parameters:

options (CCSDCalculatorOptions) – Options for the CCSD calculator.

Return type:

None

solve(molecular_configuration: MolecularConfiguration, initial_guess: RestrictedDensityOperator | None = None, additional_potential: RestrictedElectronPotential | None = None) → RestrictedMolecularOrbitalCalculatorResult

Run the restricted CCSD calculator.

Parameters:
Return type:

RestrictedMolecularOrbitalCalculatorResult

class UnrestrictedCCSDCalculator

Bases: object

An unrestricted coupled cluster singles and doubles (CCSD) molecular orbital calculator.

Uses an unrestricted Hartree-Fock solution as a starting point, runs UCCSD, then computes natural orbitals from the CCSD one-particle reduced density matrix.

__init__(options: CCSDCalculatorOptions = CCSDCalculatorOptions(convergence_tolerance=1e-09, convergence_tolerance_gradient=3.1622776601683795e-05, initial_guess='minao', max_iterations=50, level_shift=0.0, verbose=0, get_number_of_electrons_from_initial_guess=False, frozen_core_approximation=False, virtual_truncation_threshold=1e-05, frozen_virtual_threshold=100.0, fallback_options=('SOSCF',), do_density_fitting=False, degeneracy_threshold=0.02, integral_direct=False, break_spin_symmetry=False, stability_analysis=False, max_stability_iterations=10)) → None

Initialize unrestricted CCSD molecular orbital calculator.

Parameters:

options (CCSDCalculatorOptions) – Options for the CCSD calculator.

Return type:

None

solve(molecular_configuration: MolecularConfiguration, initial_guess: UnrestrictedDensityOperator | None = None, additional_potential: UnrestrictedElectronPotential | None = None) → UnrestrictedMolecularOrbitalCalculatorResult

Run the unrestricted CCSD calculator.

Parameters:
Return type:

UnrestrictedMolecularOrbitalCalculatorResult