ASI Embedding Package — asiembedding 00.00.01 documentation

# 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