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')[source]
Bases:
object
- property basis_atoms
- property basis_info
- 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()[source]
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:
- 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,
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:
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)[source]
_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()[source]
Re-orders atoms to push those in embedding region 1 to the beginning :return:
- run(ev_corr_scf=False)[source]
Actually performed a given simulation run for the calculator. Must be separated for indidividual system calls.
- property truncate
asiembedding.basis_info module
- class asiembedding.basis_info.Basis_info[source]
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()[source]
_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)[source]
Bases:
ABC
- calc_subsys_pop(overlap_matrix, density_matrix)[source]
- 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
- property scf_methods
- select_atoms_basis_truncation(thresh)[source]
_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)[source]
Initialises the AtomsEmbed methods for a given method
- set_truncation_defaults(truncated_atom_list)[source]
_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)[source]
Bases:
EmbeddingBase
- calculate_levelshift_projector()[source]
_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()[source]
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).
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.)
…
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.
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.
TODO: REF
asiembedding.parallel_utils module
Module contents
- class asiembedding.AtomsEmbed(atoms, initial_calc, embed_mask, no_scf=False, ghosts=0, outdir='asi.calc')[source]
Bases:
object
- property basis_atoms
- property basis_info
- 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()[source]
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:
- 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,
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:
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)[source]
_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()[source]
Re-orders atoms to push those in embedding region 1 to the beginning :return:
- run(ev_corr_scf=False)[source]
Actually performed a given simulation run for the calculator. Must be separated for indidividual system calls.
- property truncate
- 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)[source]
Bases:
EmbeddingBase
- calculate_levelshift_projector()[source]
_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()[source]
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).
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.)
…
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.
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.
TODO: REF