qrunch.chemistry.ground_state_problem.builders.tools.localization.orbital_assigners

Molecular orbital assignment utilities.

Functions

`suggest_assignment_tolerances_from_fractions`(...)	Suggest reasonable assignment_tolerance values from per-MO embedded fractions.
`to_assignment_threshold_enum`(value)	Coerce literal to AssignmentThreshold.

Classes

`AssignmentThreshold`	Enumerate data-driven threshold suggestion strategies.
`KMeans1DResult`	Represent 1D two-cluster k-means result.
`ProjectiveEmbeddingRegion`	The Projective-Embedding regions.
`RestrictedTotalWeightBasedOrbitalAssigner`	Assigns molecular orbitals to embedded and environment regions based on total AO contributions.
`TotalWeightBasedOrbitalAssigner`	Assigns molecular orbitals to embedded and environment regions based on total AO contributions.
`UnrestrictedTotalWeightBasedOrbitalAssigner`	Assigns molecular orbitals to embedded and environment regions based on total AO contributions.

class AssignmentThreshold

Bases: Enum

Enumerate data-driven threshold suggestion strategies.

KMEANS_MIDPOINT = 'kmeans_midpoint'

LARGEST_GAP_MIDPOINT = 'largest_gap_midpoint'

class KMeans1DResult

Bases: object

Represent 1D two-cluster k-means result.

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

Parameters:

low_center – The center of the low-value cluster.
high_center – The center of the high-value cluster.

__init__(low_center: float, high_center: float) → None

Parameters:

low_center (float)
high_center (float)

Return type:

None

high_center: float

low_center: float

midpoint() → float

Compute midpoint between cluster centers.

Return type:: float

class ProjectiveEmbeddingRegion

Bases: Enum

The Projective-Embedding regions.

EMBEDDED = 'Embedded'

ENVIRONMENT = 'Environment'

class RestrictedTotalWeightBasedOrbitalAssigner

Bases: object

Assigns molecular orbitals to embedded and environment regions based on total AO contributions.

__init__(assignment_tolerance: float | Literal['kmeans_midpoint', 'largest_gap_midpoint'] = 'kmeans_midpoint') → None

Initialize a total weight based molecular orbital assigner.

Parameters:

assignment_tolerance (float | Literal['kmeans_midpoint', 'largest_gap_midpoint']) –

Fractional threshold for assigning an MO to the embedded region.

If the fraction of AO weight in the embedded region > assignment_tolerance, the molecular orbital is assigned to embedded region.

Return type:

None

assign(molecular_configuration: MolecularConfiguration, local_occupied_molecular_orbitals: RestrictedOccupiedMolecularOrbitals) → RestrictedOrbitalAssignmentResult

Assign occupied molecular orbitals to embedded or environment regions.

Assigns occupied molecular orbitals to embedded or environment regions based on the total weights of their atomic orbital contributions.

Parameters:

molecular_configuration (MolecularConfiguration) – Molecular configuration containing information about atomic orbitals.
local_occupied_molecular_orbitals (RestrictedOccupiedMolecularOrbitals) – Localized occupied molecular orbitals (MOs). Shape: (number of AOs, number of occupied MOs).

Raises:

ValueError – If there are atomic orbitals not assigned to any region.

Return type:

RestrictedOrbitalAssignmentResult

class TotalWeightBasedOrbitalAssigner

Bases: OrbitalAssigner

Assigns molecular orbitals to embedded and environment regions based on total AO contributions.

__init__(assignment_tolerance: float | Literal['kmeans_midpoint', 'largest_gap_midpoint'] = 'kmeans_midpoint') → None

Initialize a total weight based molecular orbital assigner.

Parameters:

assignment_tolerance (float | Literal['kmeans_midpoint', 'largest_gap_midpoint']) –

Fractional threshold for assigning an MO to the embedded region.

If the fraction of AO weight in the embedded region > assignment_tolerance, the molecular orbital is assigned to embedded region.

Return type:

None

assign(molecular_configuration: MolecularConfiguration, local_occupied_molecular_orbitals: RestrictedOccupiedMolecularOrbitals) → RestrictedOrbitalAssignmentResult

assign(molecular_configuration: MolecularConfiguration, local_occupied_molecular_orbitals: UnrestrictedOccupiedMolecularOrbitals) → UnrestrictedOrbitalAssignmentResult

Assign occupied molecular orbitals to embedded or environment regions.

Assigns occupied molecular orbitals to embedded or environment regions based on the total weights of their atomic orbital contributions.

Parameters:

molecular_configuration (MolecularConfiguration) – Molecular configuration containing information about atomic orbitals.
local_occupied_molecular_orbitals (UnrestrictedOccupiedMolecularOrbitals | RestrictedOccupiedMolecularOrbitals) – Localized occupied molecular orbitals (MOs). Shape: (number of AOs, number of occupied MOs).

Raises:

ValueError – If there are atomic orbitals not assigned to any region.

Return type:

UnrestrictedOrbitalAssignmentResult | RestrictedOrbitalAssignmentResult

class UnrestrictedTotalWeightBasedOrbitalAssigner

Bases: object

Assigns molecular orbitals to embedded and environment regions based on total AO contributions.

__init__(assignment_tolerance: float | Literal['kmeans_midpoint', 'largest_gap_midpoint'] = 'kmeans_midpoint') → None

Initialize a total weight based molecular orbital assigner.

Parameters:

assignment_tolerance (float | Literal['kmeans_midpoint', 'largest_gap_midpoint']) –

Fractional threshold for assigning an MO to the embedded region.

If the fraction of AO weight in the embedded region > assignment_tolerance, the molecular orbital is assigned to embedded region.

Return type:

None

assign(molecular_configuration: MolecularConfiguration, local_occupied_molecular_orbitals: UnrestrictedOccupiedMolecularOrbitals) → UnrestrictedOrbitalAssignmentResult

Assign occupied molecular orbitals to embedded or environment regions.

Assigns occupied molecular orbitals to embedded or environment regions based on the total weights of their atomic orbital contributions.

Parameters:

molecular_configuration (MolecularConfiguration) – Molecular configuration containing information about atomic orbitals.
local_occupied_molecular_orbitals (UnrestrictedOccupiedMolecularOrbitals) – Localized occupied molecular orbitals (MOs). Shape: (number of AOs, number of occupied MOs).

Raises:

ValueError – If there are atomic orbitals not assigned to any region.

Return type:

UnrestrictedOrbitalAssignmentResult

suggest_assignment_tolerances_from_fractions(fractions: ndarray[Any, dtype[float64]]) → dict[str, float]

Suggest reasonable assignment_tolerance values from per-MO embedded fractions.

Parameters:: fractions (ndarray[Any, dtype[float64]]) – Array of embedded fractions in [0, 1] for occupied MOs.
Return type:: dict[str, float]

to_assignment_threshold_enum(value: Literal['kmeans_midpoint', 'largest_gap_midpoint']) → AssignmentThreshold | float

Coerce literal to AssignmentThreshold.

Parameters:: value (Literal['kmeans_midpoint', 'largest_gap_midpoint']) – Either an enum member or its underlying value string.
Raises:: ValueError – If value is a string and does not match any AssignmentThreshold member.
Return type:: AssignmentThreshold | float