qrunch.chemistry.ground_state_problem.builders.projective_embedding_ground_state_problem_builders

Classes for embedding systems of molecules in an environment consisting of the remaining molecule.

The embedding procedure consists of several elements:

The full molecule is solved using the given mean field solver.
The resulting orbitals are localized.
The localized orbitals are assigned to either the embedded or environment regions.
A projector onto the occupied environment states is build from the assigned orbitals.
Modified integrals are built for the embedded region including an effective repulsion from the environment electrons and a cost preventing the embedded electrons to occupy the same orbitals as the environment electrons.
The modified integrals are used to solve the embedded region using the given mean field solver resulting in canonical molecular orbitals for the embedded region alone.
The modified integrals are transformed into the basis of the new molecular orbitals.
The remaining energy contributions from the environment not included in the modified integrals are calculated.
The modified integrals and the energy contributions are returned.

Functions

persistence_checkpoints()

Define the persistence checkpoints used during the embedding process.

Classes

`PreliminaryRestrictedData`	Dataclass for preliminary data of a Projective-Embedding calculation.
`PreliminaryUnrestrictedData`	Dataclass for preliminary data of a Projective-Embedding calculation.
`ProjectiveEmbeddingGroundStateProblemBuilder`	A builder for the projective embedding ground state problem.
`ProjectiveEmbeddingRestrictedGroundStateProblemBuilder`	Class for embedding systems of molecules in an environment consisting of the remaining molecule.
`ProjectiveEmbeddingUnrestrictedGroundStateProblemBuilder`	Class for embedding systems of molecules in an environment consisting of the remaining molecule.

class PreliminaryRestrictedData

Bases: object

Dataclass for preliminary data of a Projective-Embedding calculation.

Parameters:

assignment_result – The orbital assignment results
local_molecular_orbitals – The local molecular orbitals

__init__(assignment_result: RestrictedOrbitalAssignmentResult, local_molecular_orbitals: RestrictedOccupiedMolecularOrbitals) → None

Parameters:

assignment_result (RestrictedOrbitalAssignmentResult)
local_molecular_orbitals (RestrictedOccupiedMolecularOrbitals)

Return type:

None

assignment_result: RestrictedOrbitalAssignmentResult

local_molecular_orbitals: RestrictedOccupiedMolecularOrbitals

class PreliminaryUnrestrictedData

Bases: object

Dataclass for preliminary data of a Projective-Embedding calculation.

Parameters:

assignment_result – The orbital assignment results
local_molecular_orbitals – The local molecular orbitals

__init__(assignment_result: UnrestrictedOrbitalAssignmentResult, local_molecular_orbitals: UnrestrictedOccupiedMolecularOrbitals) → None

Parameters:

assignment_result (UnrestrictedOrbitalAssignmentResult)
local_molecular_orbitals (UnrestrictedOccupiedMolecularOrbitals)

Return type:

None

assignment_result: UnrestrictedOrbitalAssignmentResult

local_molecular_orbitals: UnrestrictedOccupiedMolecularOrbitals

class ProjectiveEmbeddingGroundStateProblemBuilder

Bases: GroundStateProblemBuilder

A builder for the projective embedding ground state problem.

This builder uses a full system solver to find the orbitals for the whole system, and an embedded solver to find the orbitals for the embedded system. It also uses a localizer to localize orbitals before embedding, and an orbital assigner to assign localized orbitals to the embedded region.

__init__(full_system_solver: MeanFieldCalculator, embedded_orbital_calculator: MolecularOrbitalCalculator, localizer: OrbitalLocalizer, orbital_assigner: OrbitalAssigner, projector_builder: ManbysLevelShiftProjectorBuilder, data_persister_manager: DataPersisterManager | None = None, problem_modifiers: list[GroundStateProblemModifier] | None = None, cube_generator: ProjectiveEmbeddingCubeGenerator | None = None, repulsion_integral_builder: TwoBodyElectronRepulsionIntegralBuilderProtocol | None = None) → None

Initialize a projective-embedder.

Parameters:

full_system_solver (MeanFieldCalculator) – Mean field solver used to find orbitals for the whole system.
embedded_orbital_calculator (MolecularOrbitalCalculator) – Solver used to find orbitals for the embedded system.
localizer (OrbitalLocalizer) – Localizer used to localize orbitals before embedding.
orbital_assigner (OrbitalAssigner) – Orbital assigner used to assign localized orbitals to the embedded region.
projector_builder (ManbysLevelShiftProjectorBuilder) – Projector used separate the embedded and environment regions while solving.
data_persister_manager (DataPersisterManager | None) – Manager to handle saving and loading heavy full system calculations.
problem_modifiers (list[GroundStateProblemModifier] | None) – A list of problem modifiers
cube_generator (ProjectiveEmbeddingCubeGenerator | None) – An Optional Cube Generator
repulsion_integral_builder (TwoBodyElectronRepulsionIntegralBuilderProtocol | None) – The object that can build two electron repulsion integrals. TwoBodyElectronRepulsionIntegralBuilder is used as default.

Return type:

None

build_restricted(molecular_configuration: MolecularConfiguration) → RestrictedGroundStateProblem

Build the restricted ground state problem.

Parameters:: molecular_configuration (MolecularConfiguration)
Return type:: RestrictedGroundStateProblem

build_restricted_cube_files(molecular_configuration: MolecularConfiguration, post_fix: str | None = None) → None

Build cube files.

Parameters:

molecular_configuration (MolecularConfiguration) – Molecular configuration for the full molecule.
post_fix (str | None) – Optional string to append to the base file name before the suffix.

Return type:

None

build_unrestricted(molecular_configuration: MolecularConfiguration) → UnrestrictedGroundStateProblem

Build the unrestricted ground state problem.

Parameters:: molecular_configuration (MolecularConfiguration)
Return type:: UnrestrictedGroundStateProblem

build_unrestricted_cube_files(molecular_configuration: MolecularConfiguration, post_fix: str | None = None) → None

Build cube files.

Parameters:

molecular_configuration (MolecularConfiguration) – Molecular configuration for the full molecule.
post_fix (str | None) – Optional string to append to the base file name before the suffix.

Return type:

None

data_persister_manager() → DataPersisterManager | None

Return the data persister manager.

Return type:: DataPersisterManager | None

classmethod persistence_checkpoints() → list[str]

Define the persistence checkpoints used during the embedding process.

These checkpoints specify computational stages where intermediate results can be saved and loaded to optimize computations and ensure reproducibility.

Return type:: list[str]

class ProjectiveEmbeddingRestrictedGroundStateProblemBuilder

Bases: object

Class for embedding systems of molecules in an environment consisting of the remaining molecule.

This class uses the Projection-Based Wavefunction-in-DFT Embedding scheme https://doi.org/10.1021/ct300544e and https://doi.org/10.1021/acs.accounts.8b00672.

The embedding procedure consists of several elements:

The full molecule is solved using the given mean field solver.
The resulting orbitals are localized.
The localized orbitals are assigned to either the embedded or environment regions.
A projector onto the occupied environment states is build from the assigned orbitals.
Modified integrals are built for the embedded region including an effective repulsion from the environment electrons and a cost preventing the embedded electrons to occupy the same orbitals as the environment electrons.
The modified integrals are used to solve the embedded region using the given mean field solver resulting in canonical molecular orbitals for the embedded region alone.
The modified integrals are transformed into the basis of the new molecular orbitals.
The remaining energy contributions from the environment not included in the modified integrals are calculated.
The modified integrals and the energy contributions are returned.

__init__(full_system_solver: MeanFieldCalculator, embedded_orbital_calculator: MolecularOrbitalCalculator, localizer: OrbitalLocalizer, orbital_assigner: OrbitalAssigner, projector_builder: ManbysLevelShiftProjectorBuilder, data_persister_manager: DataPersisterManager | None = None, problem_modifiers: list[GroundStateProblemModifier] | None = None, cube_generator: ProjectiveEmbeddingCubeGenerator | None = None, repulsion_integral_builder: TwoBodyElectronRepulsionIntegralBuilderProtocol | None = None) → None

Initialize a restricted projective-embedder.

Parameters:

full_system_solver (MeanFieldCalculator) – Mean field solver used to find orbitals for the whole system.
embedded_orbital_calculator (MolecularOrbitalCalculator) – Solver used to find orbitals for the embedded system.
localizer (OrbitalLocalizer) – Localizer used to localize orbitals before embedding.
orbital_assigner (OrbitalAssigner) – Orbital assigner used to assign localized orbitals to the embedded region.
projector_builder (ManbysLevelShiftProjectorBuilder) – Projector used separate the embedded and environment regions while solving.
data_persister_manager (DataPersisterManager | None) – Manager to handle saving and loading heavy full system calculations.
problem_modifiers (list[GroundStateProblemModifier] | None) – A list of problem modifiers
cube_generator (ProjectiveEmbeddingCubeGenerator | None) – An Optional Cube Generator
repulsion_integral_builder (TwoBodyElectronRepulsionIntegralBuilderProtocol | None) – The object that can build two electron repulsion integrals. RestrictedTwoBodyElectronRepulsionIntegralBuilder is used as default.

Return type:

None

build(molecular_configuration: MolecularConfiguration) → RestrictedGroundStateProblem

Build embedded problem.

Parameters:: molecular_configuration (MolecularConfiguration) – Molecular configuration for the full molecule.
Return type:: RestrictedGroundStateProblem

build_cube_files(molecular_configuration: MolecularConfiguration, post_fix: str | None = None) → None

Build cube files.

Parameters:

molecular_configuration (MolecularConfiguration) – Molecular configuration for the full molecule.
post_fix (str | None) – Optional string to append to the base file name before the suffix.

Return type:

None

compute_preliminary_data(molecular_configuration: MolecularConfiguration) → PreliminaryRestrictedData

Compute preliminary data.

Parameters:: molecular_configuration (MolecularConfiguration) – Molecular configuration for the full molecule.
Return type:: PreliminaryRestrictedData

data_persister_manager() → DataPersisterManager | None

Return the data persister manager.

Return type:: DataPersisterManager | None

finalize_construction(molecular_configuration: MolecularConfiguration, preliminary_data: PreliminaryRestrictedData) → RestrictedGroundStateProblem

Perform the final constructions of the embedded problem.

Parameters:

molecular_configuration (MolecularConfiguration) – Molecular configuration for the full molecule.
preliminary_data (PreliminaryRestrictedData) – The preliminary_data.

Return type:

RestrictedGroundStateProblem

classmethod persistence_checkpoints() → list[str]

Define the persistence checkpoints used during the embedding process.

These checkpoints specify computational stages where intermediate results can be saved and loaded to optimize computations and ensure reproducibility.

Return type:: list[str]

class ProjectiveEmbeddingUnrestrictedGroundStateProblemBuilder

Bases: object

Class for embedding systems of molecules in an environment consisting of the remaining molecule.

The embedding procedure consists of several elements:

The full molecule is solved using the given mean field solver.
The resulting orbitals are localized.
The localized orbitals are assigned to either the embedded or environment regions.
A projector onto the occupied environment states is build from the assigned orbitals.
Modified integrals are built for the embedded region including an effective repulsion from the environment electrons and a cost preventing the embedded electrons to occupy the same orbitals as the environment electrons.
The modified integrals are used to solve the embedded region using the given mean field solver resulting in canonical molecular orbitals for the embedded region alone.
The modified integrals are transformed into the basis of the new molecular orbitals.
The remaining energy contributions from the environment not included in the modified integrals are calculated.
The modified integrals and the energy contributions are returned.

__init__(full_system_solver: MeanFieldCalculator, embedded_orbital_calculator: MolecularOrbitalCalculator, localizer: OrbitalLocalizer, orbital_assigner: OrbitalAssigner, projector_builder: ManbysLevelShiftProjectorBuilder, data_persister_manager: DataPersisterManager | None = None, problem_modifiers: list[GroundStateProblemModifier] | None = None, cube_generator: ProjectiveEmbeddingCubeGenerator | None = None, repulsion_integral_builder: TwoBodyElectronRepulsionIntegralBuilderProtocol | None = None) → None

Initialize an unrestricted projective-embedder.

Parameters:

full_system_solver (MeanFieldCalculator) – Mean field solver used to find orbitals for the whole system.
embedded_orbital_calculator (MolecularOrbitalCalculator) – Solver used to find orbitals for the embedded system.
localizer (OrbitalLocalizer) – Localizer used to localize orbitals before embedding.
orbital_assigner (OrbitalAssigner) – Orbital assigner used to assign localized orbitals to the embedded region.
projector_builder (ManbysLevelShiftProjectorBuilder) – Projector used separate the embedded and environment regions while solving.
data_persister_manager (DataPersisterManager | None) – Manager to handle saving and loading heavy full system calculations.
problem_modifiers (list[GroundStateProblemModifier] | None) – A list of problem modifiers
cube_generator (ProjectiveEmbeddingCubeGenerator | None) – An Optional Cube Generator
repulsion_integral_builder (TwoBodyElectronRepulsionIntegralBuilderProtocol | None) – The object that can build two electron repulsion integrals. TwoBodyElectronRepulsionIntegralBuilder is used as default.

Return type:

None

build(molecular_configuration: MolecularConfiguration) → UnrestrictedGroundStateProblem

Build embedded problem.

Parameters:: molecular_configuration (MolecularConfiguration) – Molecular configuration for the full molecule.
Return type:: UnrestrictedGroundStateProblem

build_cube_files(molecular_configuration: MolecularConfiguration, post_fix: str | None = None) → None

Build cube files.

Parameters:

molecular_configuration (MolecularConfiguration) – Molecular configuration for the full molecule.
post_fix (str | None) – Optional string to append to the base file name before the suffix.

Return type:

None

compute_preliminary_data(molecular_configuration: MolecularConfiguration) → PreliminaryUnrestrictedData

Compute preliminary data.

Parameters:: molecular_configuration (MolecularConfiguration) – Molecular configuration for the full molecule.
Return type:: PreliminaryUnrestrictedData

data_persister_manager() → DataPersisterManager | None

Return the data persister manager.

Return type:: DataPersisterManager | None

finalize_construction(molecular_configuration: MolecularConfiguration, preliminary_data: PreliminaryUnrestrictedData) → UnrestrictedGroundStateProblem

Perform the final constructions of the embedded problem.

Parameters:

molecular_configuration (MolecularConfiguration) – Molecular configuration for the full molecule.
preliminary_data (PreliminaryUnrestrictedData) – The preliminary_data.

Return type:

UnrestrictedGroundStateProblem

classmethod persistence_checkpoints() → list[str]

Define the persistence checkpoints used during the embedding process.

These checkpoints specify computational stages where intermediate results can be saved and loaded to optimize computations and ensure reproducibility.

Return type:: list[str]

persistence_checkpoints() → list[str]

Define the persistence checkpoints used during the embedding process.

These checkpoints specify computational stages where intermediate results can be saved and loaded to optimize computations and ensure reproducibility.

Return type:: list[str]