Localizers

Localization is performed in two independent steps.

The occupied-occupied block of the molecular orbital matrix is localized first, before occupied environment orbitals are projected out.

After projection is performed, virtual orbitals can be localized using the embedded molecular orbitals.

Occupied

Init for Occupied Localizer classes.

class nbed.localizers.occupied.BOYSLocalizer(global_scf: SCF, n_active_atoms: int, occ_cutoff: float = 0.95, virt_cutoff: float = 0.95)

Bases: PySCFLocalizer

Object used to localise molecular orbitals (MOs) using BOYS localization.

Running localization returns active and environment systems.

Parameters:

• global_scf (gto.Mole) – PySCF molecule object

• n_active_atoms (int) – Number of active atoms

• localization_method (str) – String of orbital localization method (spade, pipekmezey, boys, ibo)

• occ_cutoff (float) – Threshold for selecting occupied active region (only requried if spade localization is NOT used)

• virt_cutoff (float) – Threshold for selecting unoccupied (virtual) active region (required for spade approach too!)

c_active

C matrix of localized occupied active MOs (columns define MOs)

Type:

np.array

c_enviro

C matrix of localized occupied ennironment MOs

Type:

np.array

c_loc_occ_and_virt

Full localized C_matrix (occpuied and virtual)

Type:

np.array

dm_active

active system density matrix

Type:

np.array

dm_enviro

environment system density matrix

Type:

np.array

active_occ_inds

1D array of active occupied MO indices

Type:

np.array

enviro_occ_inds

1D array of environment occupied MO indices

Type:

np.array

c_loc_occ

C matrix of localized occupied MOs

Type:

np.array

run()

Main function to run localization.

class nbed.localizers.occupied.IBOLocalizer(global_scf: SCF, n_active_atoms: int, occ_cutoff: float = 0.95, virt_cutoff: float = 0.95)

Bases: PySCFLocalizer

Object used to localise molecular orbitals (MOs) using IBO localization.

Running localization returns active and environment systems.

Parameters:

• global_scf (gto.Mole) – PySCF molecule object

• n_active_atoms (int) – Number of active atoms

• occ_cutoff (float) – Threshold for selecting occupied active region (only requried if spade localization is NOT used)

• virt_cutoff (float) – Threshold for selecting unoccupied (virtual) active region (required for spade approach too!)

c_active

C matrix of localized occupied active MOs (columns define MOs)

Type:

np.array

c_enviro

C matrix of localized occupied ennironment MOs

Type:

np.array

c_loc_occ_and_virt

Full localized C_matrix (occpuied and virtual)

Type:

np.array

dm_active

active system density matrix

Type:

np.array

dm_enviro

environment system density matrix

Type:

np.array

active_occ_inds

1D array of active occupied MO indices

Type:

np.array

enviro_occ_inds

1D array of environment occupied MO indices

Type:

np.array

c_loc_occ

C matrix of localized occupied MOs

Type:

np.array

run()

Main function to run localization.

class nbed.localizers.occupied.OccupiedLocalizer(global_scf: SCF, n_active_atoms: int, n_mo_overwrite: tuple[int | None, int | None] | None = None)

Bases: ABC

Object used to localise molecular orbitals (MOs) using different localization schemes.

Running localization returns active and environment systems.

Note: The major improvement of IBOs over PM orbitals is that they are based on IAO charges instead of the erratic Mulliken charges. As a result, IBOs are always well-defined. (Ref: J. Chem. Theory Comput. 2013, 9, 4834−4843)

Parameters:

• global_scf (gto.Mole) – PySCF molecule object

• n_active_atoms (int) – Number of active atoms

run()

Main function to run localization.

localize() → LocalizedSystem

Localise orbitals using SPADE.

Returns:

A dataclass describing the localization.

Return type:

LocalizedSystem

class nbed.localizers.occupied.PMLocalizer(global_scf: SCF, n_active_atoms: int, occ_cutoff: float = 0.95, virt_cutoff: float = 0.95)

Bases: PySCFLocalizer

Object used to localise molecular orbitals (MOs) using Pipek-Mezey localization.

Running localization returns active and environment systems.

Parameters:

• global_scf (gto.Mole) – PySCF molecule object

• n_active_atoms (int) – Number of active atoms

• occ_cutoff (float) – Threshold for selecting occupied active region (only requried if spade localization is NOT used)

• virt_cutoff (float) – Threshold for selecting unoccupied (virtual) active region (required for spade approach too!)

c_active

C matrix of localized occupied active MOs (columns define MOs)

Type:

np.array

c_enviro

C matrix of localized occupied ennironment MOs

Type:

np.array

c_loc_occ_and_virt

Full localized C_matrix (occpuied and virtual)

Type:

np.array

dm_active

active system density matrix

Type:

np.array

dm_enviro

environment system density matrix

Type:

np.array

active_occ_inds

1D array of active occupied MO indices

Type:

np.array

enviro_occ_inds

1D array of environment occupied MO indices

Type:

np.array

c_loc_occ

C matrix of localized occupied MOs

Type:

np.array

run()

Main function to run localization.

class nbed.localizers.occupied.SPADELocalizer(global_scf: SCF, n_active_atoms: int, max_shells: int = 4, n_mo_overwrite: tuple[int | None, int | None] | None = None)

Bases: OccupiedLocalizer

Object used to localise molecular orbitals (MOs) using SPADE Localization.

Running localization returns active and environment systems.

Parameters:

• global_scf (scf.hf.SCF) – PySCF method object.

• n_active_atoms (int) – Number of active atoms

c_active

C matrix of localized occupied active MOs (columns define MOs)

Type:

np.array

c_enviro

C matrix of localized occupied ennironment MOs

Type:

np.array

c_loc_occ_and_virt

Full localized C_matrix (occpuied and virtual)

Type:

np.array

dm_active

active system density matrix

Type:

np.array

dm_enviro

environment system density matrix

Type:

np.array

active_occ_inds

1D array of active occupied MO indices

Type:

np.array

enviro_occ_inds

1D array of environment occupied MO indices

Type:

np.array

c_loc_occ

C matrix of localized occupied MOs

Type:

np.array

run()

Main function to run localization.

Virtual

Init for Virtual Localizer classes.

class nbed.localizers.virtual.ConcentricLocalizer(embedded_scf: SCF, n_active_atoms: int, max_shells: int = 4)

Bases: VirtualLocalizer

Class to localize virtual orbitals using concentric localization.

max_shells

Maximum number of shells to localize.

Type:

int

_n_active_atoms

Number of active atoms in the system.

Type:

int

projected_overlap

Projected overlap matrix.

Type:

np.ndarray

overlap_two_basis

Overlap matrix between two basis sets.

Type:

np.ndarray

n_act_proj_aos

Number of active projected atomic orbitals.

Type:

int

shells

List of shell sizes.

Type:

list

singular_values

List of singular values from SVD.

Type:

list

localize_virtual(scf.hf.SCF)

Localize virtual orbitals using concentric localization.

_localize_virtual_spin(np.ndarray, np.ndarray, np.ndarray)

Run concentric localization for each spin separately.

localize_virtual() → SCF

Localise virtual (unoccupied) obitals using concentric localization.

[1] D. Claudino and N. J. Mayhall, “Simple and Efficient Truncation of Virtual Spaces in Embedded Wave Functions via Concentric Localization”, Journal of Chemical Theory and Computation, vol. 15, no. 11, pp. 6085-6096, Nov. 2019, doi: 10.1021/ACS.JCTC.9B00682.

Returns:

Fully Localized SCF object.

Return type:

scf.hf.SCF

class nbed.localizers.virtual.VirtualLocalizer(n_active_atoms: int)

Bases: ABC

Base class for virtual localizers.

Parameters:

• embedded_scf (scf.hf.SCF) – SCF object with occupied orbitals localized.

• n_active_atoms (int) – Number of active atoms in the system.

embedded_scf

SCF object with occupied orbitals localized.

Type:

scf.hf.SCF

n_active_atoms

Number of active atoms in the system.

Type:

int

abstract localize_virtual() → SCF

Localize virtual orbitals.

Returns:

Localized SCF object.

Return type:

gto.Mole

Localisation Data

Outputs from OccupiedLocalizer.localize are standardised as a dataclass, LocalizedSystem

Class defining the data output from Localizers.

class nbed.localizers.system.LocalizedSystem(active_occ_inds: ndarray, enviro_occ_inds: ndarray, c_loc_occ: ndarray, dm_active: ndarray, dm_enviro: ndarray, c_loc_virt: ndarray | None = None)

Bases: object

Required data from localized system.

active_occ_inds (np.array): 1D array of active occupied MO indices enviro_occ_inds (np.array): 1D array of environment occupied MO indices c_loc_occ (np.array): C matrix of localized occupied MOs dm_active (np.array): active system density matrix dm_enviro (np.array): environment system density matrix c_loc_virt (np.array | None): C matrix of localized virual MOs.

active_occ_inds: ndarray

c_loc_occ: ndarray

c_loc_virt: ndarray | None = None

dm_active: ndarray

dm_enviro: ndarray

dm_loc_occ: ndarray

enviro_occ_inds: ndarray

class nbed.localizers.system.RestrictedLS(active_occ_inds: ndarray[tuple[int], dtype[bool]], enviro_occ_inds: ndarray[tuple[int], dtype[bool]], c_loc_occ: OneSpinMatrix, dm_active: OneSpinMatrix, dm_enviro: OneSpinMatrix, c_loc_virt: OneSpinMatrix | None = None)

Bases: LocalizedSystem

Required data from localized system.

active_occ_inds (np.array): 1D array of active occupied MO indices enviro_occ_inds (np.array): 1D array of environment occupied MO indices c_active (np.array): C matrix of localized occupied active MOs (columns define MOs) c_enviro (np.array): C matrix of localized occupied ennironment MOs c_loc_occ (np.array): C matrix of localized occupied MOs c_loc_virt (np.array | None): C matrix of localized virual MOs. dm_active (np.array): active system density matrix dm_enviro (np.array): environment system density matrix

active_occ_inds: ndarray[tuple[int], dtype[bool]]

c_loc_occ: OneSpinMatrix

c_loc_virt: OneSpinMatrix | None = None

dm_active: OneSpinMatrix

dm_enviro: OneSpinMatrix

dm_loc_occ: OneSpinMatrix

enviro_occ_inds: ndarray[tuple[int], dtype[bool]]

class nbed.localizers.system.RestrictedOpenLS(active_occ_inds: ndarray[tuple[int, int], dtype[bool]], enviro_occ_inds: ndarray[tuple[int, int], dtype[bool]], c_loc_occ: OneSpinMatrix, dm_active: OneSpinMatrix, dm_enviro: OneSpinMatrix, c_loc_virt: OneSpinMatrix | None = None)

Bases: LocalizedSystem

Required data from localized system.

active_occ_inds (np.array): 1D array of active occupied MO indices enviro_occ_inds (np.array): 1D array of environment occupied MO indices c_active (np.array): C matrix of localized occupied active MOs (columns define MOs) c_enviro (np.array): C matrix of localized occupied ennironment MOs c_loc_occ (np.array): C matrix of localized occupied MOs c_loc_virt (np.array | None): C matrix of localized virual MOs. dm_active (np.array): active system density matrix dm_enviro (np.array): environment system density matrix

active_occ_inds: ndarray[tuple[int, int], dtype[bool]]

c_loc_occ: OneSpinMatrix

c_loc_virt: OneSpinMatrix | None = None

dm_active: OneSpinMatrix

dm_enviro: OneSpinMatrix

dm_loc_occ: OneSpinMatrix

enviro_occ_inds: ndarray[tuple[int, int], dtype[bool]]

class nbed.localizers.system.UnrestrictedLS(active_occ_inds: ndarray[tuple[int, int], dtype[bool]], enviro_occ_inds: ndarray[tuple[int, int], dtype[bool]], c_loc_occ: TwoSpinMatrix, dm_active: TwoSpinMatrix, dm_enviro: TwoSpinMatrix, c_loc_virt: TwoSpinMatrix | None = None)

Bases: LocalizedSystem

Required data from localized system.

active_occ_inds (np.array): 1D array of active occupied MO indices enviro_occ_inds (np.array): 1D array of environment occupied MO indices c_active (np.array): C matrix of localized occupied active MOs (columns define MOs) c_enviro (np.array): C matrix of localized occupied ennironment MOs c_loc_occ (np.array): C matrix of localized occupied MOs c_loc_virt (np.array | None): C matrix of localized virual MOs. dm_active (np.array): active system density matrix dm_enviro (np.array): environment system density matrix

active_occ_inds: ndarray[tuple[int, int], dtype[bool]]

c_loc_occ: TwoSpinMatrix

c_loc_virt: TwoSpinMatrix | None = None

dm_active: TwoSpinMatrix

dm_enviro: TwoSpinMatrix

dm_loc_occ: TwoSpinMatrix

enviro_occ_inds: ndarray[tuple[int, int], dtype[bool]]

static from_spin_components(alpha: RestrictedLS, beta: RestrictedLS) → UnrestrictedLS

Construct a spin-aware LocalizedSystem from two spinless ones.

Parameters:

• alpha (LocalizedSystem) – The localized alpha spins

• beta (LocalizedSystem) – The localized beta spins.

Returns:

A combined localized system with spins (alpha, beta).

Return type:

LocalizedSystem