ASI Embedding Package

Submodules

asiembedding.atoms_embedding_asi module

class asiembedding.atoms_embedding_asi.AtomsEmbed(atoms, initial_calc, embed_mask, no_scf=False, ghosts=0, outdir='asi.calc')

Bases: object

property basis_atoms

property basis_info

calc_initializer(asi)

property density_matrices_out

_summary_

Returns a list of all density matrices within the dictionary, self.atoms.calc.asi.dm_storage, which stores all the matrices return from the calculation via ASI Callbacks.

Returns:

with dimensions (nbasis,nbasis)

Return type:

list of np.ndarray

property density_matrix_in

_summary_

Defines the density matrix used as an input to construct the density upon the initialisation of a given calulation

Returns:

with dimensions (nbasis,nbasis)

Return type:

np.ndarray

extract_results()

Extracts results from the DFT code output file that are otherwise unavailable within the ASE framework. This may need a separate module if other calculators are implemented.

property fock_embedding_matrix

_summary_

Represents the Fock embedding matrix used to level-shift/orthogonalise the subsystem orbitals of the environment from the active system:

1. F^{A-in-B} = h^{core} + g^{hilev}[gamma^{A}]

   • v_{emb}[gamma^{A}, gamma^{B}] + P_{B}[1]

where gamma^{A} is the density matrix for the subystem, A},g[gamma] are the two-electron interaction terms, is the embedding potential matrix,

2. v_{emb} = g^{low}[gamma^{A} + gamma^{B}] - g^{low}[gamma^{A}]

and h_core are the one-electron components of the hamiltonian (kinetic energy and nuclear-electron interactions).

NOTE: For FHI-aims, (1) is not formally constructed fully on the wrapper level. Numerical stability in FHI-aims requires that the onsite potential per atom exactly cancel, precluding the clean separation of the nuclear-electron interactions from the total electrostatic matrix. As such, v_{emb} is constructed from all potential components.

Formally, this is exactly the same when the embedded Fock matrix is finally constructed in FHI-aims for the high-level calculation - components of F^{A-in-B} are calculated in this function are added to the Hamiltonian of FHI-aims before its entry into the eigensolver. As such, removing components of the nuclear-potential between atoms of A (included in g^{low}[gamma^{A}]) makes perfect sense, as they are are calculated natively within FHI-aims. For similar reasons, the kinetic energy componnts of h^{core} may be ignored.

The final term calculated in the wrapper is then:

2. F_{wrapper}^{A-in-B} = H_{emb}^{Tot, lolev}[gamma^{A} + gamma^{B}]

• H_{emb}^{Tot, lolev}[gamma^{A}] - t_k(gamma^{A} + gamma^{B}}

  • t_k(gamma^{A}) + P_{B}

Where t_k is the kinetic energy contribution to the Hamiltonian and H_{emb}^{Tot, lolev}[gamma] is the total hamiltonian derived from the density matrix, gamma at the low-level reference level of thoery.

[1] Lee, S. et al., Acc. Chem. Res. 2019, 52 (5), 1359–1368.

Input:

vemb, np.ndarray: Embedding potential of environment at calculation at

low level of theory (ie., first four terms of equation (2)). (nbasis,nbasis):

projection_matrix, np.ndarray: Projection matrix to level shift P_B

components of the environment upwards relative to the active subsystem (nbasis,nbasis)

Returns:

fock_embedding_matrix(nbasis,nbasis)

Return type:

fock_embedding_matrix, np.ndarray

full_mat_to_truncated(full_mat)

_summary_ Truncate a given matrix with atomic orbitals basis (n_basis x n_basis) dimensions (e.g., hamiltonian, overlap matrix, density matrices) to only atoms specified in atom_mask. Atoms specified in the active region by self.embed_mask are always honoured.

property hamiltonian_electrostatic

_summary_ Generates

property hamiltonian_kinetic

property hamiltonian_total

initial_embed_mask

Sets which layer/layers are set to be ghost atoms

property n_basis

property overlap

reorder_atoms_from_embed_mask()

Re-orders atoms to push those in embedding region 1 to the beginning :return:

run(ev_corr_scf=False)

Actually performed a given simulation run for the calculator. Must be separated for indidividual system calls.

property truncate

truncated_mat_to_full(trunc_mat)

_summary_ Expand a truncated matrix (dim: nbasis_active*nbasis_active) to the full supermolecular basis (dim: nbasis*nbasis).

asiembedding.atoms_embedding_asi.dm_saving_callback(aux, iK, iS, descr, data, matrix_descr_ptr)

asiembedding.atoms_embedding_asi.ham_saving_callback(aux, iK, iS, descr, data, matrix_descr_ptr)

asiembedding.basis_info module

class asiembedding.basis_info.Basis_info

Bases: object

_summary_ Contains the basis dimension information, which acts as a permanent store basis information which may dynamically change for each AtomsEmbed object

property active_atoms

property full_basis_atoms

property full_natoms

property full_nbasis

set_basis_atom_indexes()

_summary_ Sets the start and end index of the matrices with nbasis*nbasis or trunc_nbasis*trunc_nbasis dimensions for each atom block.

property trunc_basis_atoms

property trunc_natoms

property trunc_nbasis

asiembedding.embedding module

class asiembedding.embedding.EmbeddingBase(atoms, embed_mask, calc_base_ll=None, calc_base_hl=None)

Bases: ABC

calc_subsys_pop(overlap_matrix, density_matrix)

Summary

Calculates the overall electron population of a given subsystem through the following relation:

P_{pop} = tr[S^{AB}/gamma]

where S^{AB} is the overlap matrix for the supermolecular system and /gamma is the density matrix of a given subsystem.

Parameters:

• overlap_matrix (np.ndarray) – Supersystem overlap matrix in AO basis.

• density_matrix (np.ndarray) – Subsystem density matrix in AO basis,

Returns:

Overall electronic population of subsystem

Return type:

population (int)

property nlayers

abstract run()

property scf_methods

select_atoms_basis_truncation(thresh)

_summary_ Returns a list of corresponding atoms for which the total contribution of an atoms constituent basis functions to the total charge of subsystem A, q^{A}:

q^{A}_{/mu, /nu} = /gamma^{A}_{/mu, /nu} S_{/mu, /nu}

exceeds the threshold, thresh:

thresh < q_{/mu, /nu}

This is unfortunately just Mulliken analysis. :param thresh: _description_ :type thresh: float

Returns:

True/False mask for

Return type:

active_mask (list)

set_layer(atoms, layer_name, calc, embed_mask, ghosts=0, no_scf=False)

Initialises the AtomsEmbed methods for a given method

set_truncation_defaults(truncated_atom_list)

_summary_ Necessary to maintain consistency in values needed for matrix truncation /expansion between the AtomsEmbed objects (eg., self.basis_atoms, self.n_atoms). Failure to do so leads to unexpected behaviour. which :param truncated_atom_list: A boolean mask asserting which atoms :type truncated_atom_list: list

class asiembedding.embedding.ProjectionEmbedding(atoms, embed_mask, calc_base_ll, calc_base_hl, frag_charge=0, post_scf=None, mu_val=1000000.0, truncate_basis=False)

Bases: EmbeddingBase

calculate_huzinaga_projector()

calculate_levelshift_projector()

_summary_

Calculate the level-shift based projection operator from Manby et al.[1]:

P^{B} = /mu S^{AB} D^{B} S^{AB}

where S^{AB} is the overlap matrix for the supermolecular system, and the density matrix for subsystem B.

[1] Manby, F. R.; Stella, M.; Goodpaster, J. D.; Miller, T. F. I. A Simple, Exact Density-Functional-Theory Embedding Scheme. J. Chem. Theory Comput. 2012, 8 (8), 2564–2568.

run()

Summary The primary driver routine for performing QM-in-QM with a Projection-based embedding scheme. This scheme draws upon the work of Manby et al. [1, 2].

The embedding scheme uses the following total energy expression…

Importing and exporting of density matrices and hamiltonians is performed with the ASI package [3].

The workflow operates as follows: 1) Calculate the KS-DFT energy of the combined subsystems A+B. Localised

density matrices, /gamma^{A} and /gamma^{B}

2a) Extract the localised density matrices 2b) (Optional) Select atoms in subsystem B that contribute

significantly to subsystem A (threshold 0.5 |e|) via Mulliken analysis:

q^{A}_{/mu, /nu} = /gamma^{A}_{/mu, /nu} S_{/mu, /nu}

Basis functions of said atoms within calculations of the embedded subsystem will be included as ghost atoms. Other basis functions will be removed (i.e., associated atomic centers not included in the QM calculation, and associated rows and columns in intermediate hamiltonians and density matrices deleted).

2. Calculate the total energy for subsystem A with the density matrix, /gamma^{A}

(For users of LaTeX, I am aware that a forward slash is used in place of the traditional backward slash for mathematical symbols - unfortunately using backslashes in these comment blocks produces ugly warnings within the comment blocks.)

…

1. Manby, F. R.; Stella, M.; Goodpaster, J. D.; Miller, T. F. I. A Simple, Exact Density-Functional-Theory Embedding Scheme. J. Chem. Theory Comput. 2012, 8 (8), 2564–2568.

2. Lee, S. J. R.; Welborn, M.; Manby, F. R.; Miller, T. F. Projection-Based Wavefunction-in-DFT Embedding. Acc. Chem. Res. 2019, 52 (5), 1359–1368.

3. TODO: REF

asiembedding.parallel_utils module

asiembedding.parallel_utils.mpi_bcast_integer(val)

asiembedding.parallel_utils.mpi_bcast_matrix_storage(data_dict, nrows, ncols)

asiembedding.parallel_utils.root_print(*args, **kwargs)

Prints only from the root node

Module contents

class asiembedding.AtomsEmbed(atoms, initial_calc, embed_mask, no_scf=False, ghosts=0, outdir='asi.calc')

Bases: object

property basis_atoms

property basis_info

calc_initializer(asi)

property density_matrices_out

_summary_

Returns a list of all density matrices within the dictionary, self.atoms.calc.asi.dm_storage, which stores all the matrices return from the calculation via ASI Callbacks.

Returns:

with dimensions (nbasis,nbasis)

Return type:

list of np.ndarray

property density_matrix_in

_summary_

Defines the density matrix used as an input to construct the density upon the initialisation of a given calulation

Returns:

with dimensions (nbasis,nbasis)

Return type:

np.ndarray

extract_results()

Extracts results from the DFT code output file that are otherwise unavailable within the ASE framework. This may need a separate module if other calculators are implemented.

property fock_embedding_matrix

_summary_

Represents the Fock embedding matrix used to level-shift/orthogonalise the subsystem orbitals of the environment from the active system:

1. F^{A-in-B} = h^{core} + g^{hilev}[gamma^{A}]

   • v_{emb}[gamma^{A}, gamma^{B}] + P_{B}[1]

where gamma^{A} is the density matrix for the subystem, A},g[gamma] are the two-electron interaction terms, is the embedding potential matrix,

2. v_{emb} = g^{low}[gamma^{A} + gamma^{B}] - g^{low}[gamma^{A}]

and h_core are the one-electron components of the hamiltonian (kinetic energy and nuclear-electron interactions).

NOTE: For FHI-aims, (1) is not formally constructed fully on the wrapper level. Numerical stability in FHI-aims requires that the onsite potential per atom exactly cancel, precluding the clean separation of the nuclear-electron interactions from the total electrostatic matrix. As such, v_{emb} is constructed from all potential components.

Formally, this is exactly the same when the embedded Fock matrix is finally constructed in FHI-aims for the high-level calculation - components of F^{A-in-B} are calculated in this function are added to the Hamiltonian of FHI-aims before its entry into the eigensolver. As such, removing components of the nuclear-potential between atoms of A (included in g^{low}[gamma^{A}]) makes perfect sense, as they are are calculated natively within FHI-aims. For similar reasons, the kinetic energy componnts of h^{core} may be ignored.

The final term calculated in the wrapper is then:

2. F_{wrapper}^{A-in-B} = H_{emb}^{Tot, lolev}[gamma^{A} + gamma^{B}]

• H_{emb}^{Tot, lolev}[gamma^{A}] - t_k(gamma^{A} + gamma^{B}}

  • t_k(gamma^{A}) + P_{B}

Where t_k is the kinetic energy contribution to the Hamiltonian and H_{emb}^{Tot, lolev}[gamma] is the total hamiltonian derived from the density matrix, gamma at the low-level reference level of thoery.

[1] Lee, S. et al., Acc. Chem. Res. 2019, 52 (5), 1359–1368.

Input:

vemb, np.ndarray: Embedding potential of environment at calculation at

low level of theory (ie., first four terms of equation (2)). (nbasis,nbasis):

projection_matrix, np.ndarray: Projection matrix to level shift P_B

components of the environment upwards relative to the active subsystem (nbasis,nbasis)

Returns:

fock_embedding_matrix(nbasis,nbasis)

Return type:

fock_embedding_matrix, np.ndarray

full_mat_to_truncated(full_mat)

_summary_ Truncate a given matrix with atomic orbitals basis (n_basis x n_basis) dimensions (e.g., hamiltonian, overlap matrix, density matrices) to only atoms specified in atom_mask. Atoms specified in the active region by self.embed_mask are always honoured.

property hamiltonian_electrostatic

_summary_ Generates

property hamiltonian_kinetic

property hamiltonian_total

initial_embed_mask

Sets which layer/layers are set to be ghost atoms

property n_basis

property overlap

reorder_atoms_from_embed_mask()

Re-orders atoms to push those in embedding region 1 to the beginning :return:

run(ev_corr_scf=False)

Actually performed a given simulation run for the calculator. Must be separated for indidividual system calls.

property truncate

truncated_mat_to_full(trunc_mat)

_summary_ Expand a truncated matrix (dim: nbasis_active*nbasis_active) to the full supermolecular basis (dim: nbasis*nbasis).

class asiembedding.ProjectionEmbedding(atoms, embed_mask, calc_base_ll, calc_base_hl, frag_charge=0, post_scf=None, mu_val=1000000.0, truncate_basis=False)

Bases: EmbeddingBase

calculate_huzinaga_projector()

calculate_levelshift_projector()

_summary_

Calculate the level-shift based projection operator from Manby et al.[1]:

P^{B} = /mu S^{AB} D^{B} S^{AB}

where S^{AB} is the overlap matrix for the supermolecular system, and the density matrix for subsystem B.

[1] Manby, F. R.; Stella, M.; Goodpaster, J. D.; Miller, T. F. I. A Simple, Exact Density-Functional-Theory Embedding Scheme. J. Chem. Theory Comput. 2012, 8 (8), 2564–2568.

run()

Summary The primary driver routine for performing QM-in-QM with a Projection-based embedding scheme. This scheme draws upon the work of Manby et al. [1, 2].

The embedding scheme uses the following total energy expression…

Importing and exporting of density matrices and hamiltonians is performed with the ASI package [3].

The workflow operates as follows: 1) Calculate the KS-DFT energy of the combined subsystems A+B. Localised

density matrices, /gamma^{A} and /gamma^{B}

2a) Extract the localised density matrices 2b) (Optional) Select atoms in subsystem B that contribute

significantly to subsystem A (threshold 0.5 |e|) via Mulliken analysis:

q^{A}_{/mu, /nu} = /gamma^{A}_{/mu, /nu} S_{/mu, /nu}

Basis functions of said atoms within calculations of the embedded subsystem will be included as ghost atoms. Other basis functions will be removed (i.e., associated atomic centers not included in the QM calculation, and associated rows and columns in intermediate hamiltonians and density matrices deleted).

2. Calculate the total energy for subsystem A with the density matrix, /gamma^{A}

(For users of LaTeX, I am aware that a forward slash is used in place of the traditional backward slash for mathematical symbols - unfortunately using backslashes in these comment blocks produces ugly warnings within the comment blocks.)

…

1. Manby, F. R.; Stella, M.; Goodpaster, J. D.; Miller, T. F. I. A Simple, Exact Density-Functional-Theory Embedding Scheme. J. Chem. Theory Comput. 2012, 8 (8), 2564–2568.

2. Lee, S. J. R.; Welborn, M.; Manby, F. R.; Miller, T. F. Projection-Based Wavefunction-in-DFT Embedding. Acc. Chem. Res. 2019, 52 (5), 1359–1368.

3. TODO: REF