afqmctools.wavefunction package#

Submodules#

afqmctools.wavefunction.common module#

afqmctools.wavefunction.common.check_orthonormality(wfn, nelec, wfn_type='collinear')#

Check orthonormality of wavefunction columns.

Parameters:

  • wfn (ndarray (1, n, m)) – Wavefunction array with shape (1, n_orbitals, n_electrons).

  • nelec (tuple or int) – Number of electrons. For collinear: (n_up, n_down), for noncollinear/closed: int.

  • wfn_type (str, optional) – Type of wavefunction: ‘noncollinear’, ‘collinear’, or ‘closed’. Default is ‘collinear’.

Returns:

norm – Dictionary containing normalization determinants and messages.

Return type:

float

afqmctools.wavefunction.common.check_slater_matrix_orthonormality(slater_matrix, nelec=None, matrix_type='collinear', verbose=True, tol=1e-10)#

Check orthonormality of a Slater matrix (n_orbitals, n_electrons).

Parameters:

  • slater_matrix (ndarray (n, m)) – Slater matrix with shape (n_orbitals, n_electrons).

  • nelec (int, optional) – Number of electrons in this spin block. If None, uses shape[1].

  • matrix_type (str, optional) – Type of matrix: ‘spin_block’ (default) or ‘full’. Only affects messaging.

  • verbose (bool, optional) – Print warnings if not orthonormal. Default: True.

  • tol (float, optional) – Tolerance for checking orthonormality. Default: 1.0e-10.

Returns:

  • norm (complex) – Determinant of the overlap matrix (product for all columns).

  • is_orthonormal (bool) – True if the overlap matrix is close to identity (within tolerance).

afqmctools.wavefunction.common.modified_gram_schmidt(mat, tol=1e-12)#

Orthonormalize the columns of mat using modified Gram-Schmidt.

Parameters:

  • mat (ndarray (n, m)) – Matrix whose columns will be orthonormalized in place order.

  • tol (float, optional) – Minimum norm allowed before considering vectors linearly dependent.

Returns:

Matrix with orthonormal columns spanning the same column space.

Return type:

ndarray

Raises:

ValueError – If a column is (near) linearly dependent on the previous ones.

afqmctools.wavefunction.common.write_nomsd(fh5, wfn, uhf, nelec, thresh=1e-08, init=None, orthonormalize=True)#

Write NOMSD to HDF.

Parameters:

  • fh5 (h5py group) – Wavefunction group to write to file.

  • wfn (np.ndarray) – NOMSD trial wavefunctions.

  • uhf (bool) – UHF style wavefunction.

  • nelec (tuple) – Number of alpha and beta electrons.

  • thresh (float) – Threshold for writing wavefunction elements.

  • init (tuple, optional) – Initial Slater determinants [alpha_block, beta_block]. Will be orthonormality-checked.

  • orthonormalize (bool, optional) – If True (default), orthonormalize Slater matrices if not properly normalized.

afqmctools.wavefunction.common.write_nomsd_ghf(fh5, wfn, nelec, thresh=1e-08, init=None, orthonormalize=True)#

Write ‘GHF’/’G. S. DET’ NOMSD to HDF.

Parameters:

  • fh5 (h5py group) – Wavefunction group to write to file.

  • wfn (np.ndarray) – NOMSD trial wavefunctions.

  • nelec (tuple) – Number of alpha and beta electrons.

  • thresh (float) – Threshold for writing wavefunction elements.

  • init (ndarray, optional) – Initial Slater determinant. Will be orthonormality-checked.

  • orthonormalize (bool, optional) – If True (default), orthonormalize Slater matrices if not properly normalized.

afqmctools.wavefunction.common.write_nomsd_single(fh5, psi, idet)#

Write single component of NOMSD to hdf.

Parameters:

  • fh5 (h5py group) – Wavefunction group to write to file.

  • psi (scipy.sparse.csr_array) – Sparse representation of trial wavefunction.

  • idet (int) – Determinant number.

afqmctools.wavefunction.common.write_phmsd(fh5, occa, occb, nelec, norb, init=None, orbmat=None, orthonormalize=True)#

Write PHMSD to HDF.

Parameters:

  • fh5 (h5py group) – Wavefunction group to write to file.

  • nelec (tuple) – Number of alpha and beta electrons.

  • init (tuple, optional) – Initial Slater determinant [alpha_block, beta_block]. Will be orthonormality-checked.

  • orbmat (tuple, optional) – Orbital transformation matrices.

  • orthonormalize (bool, optional) – If True (default), orthonormalize Slater matrices if not properly normalized.

afqmctools.wavefunction.common.write_wfn(filename, wfn, walker_type, nelec, norb, init=None, orbmat=None, verbose=False, orthonormalize=True)#

Write wavefunction to HDF5 file.

Parameters:

  • filename (str) – HDF5 file to write wavefunction to.

  • wfn (tuple) – Wavefunction description. Either a list containing an array of coefficients and occupation numbers (PHMSD) or a tuple containing an array of coefficients and an array of determinants (NOMSD).

  • walker_type (str) – Type of walker to write. Options are ‘closed’, ‘collinear’, ‘noncollinear’, ‘fullypolarized’.

  • nelec (tuple) – Number of alpha and beta electrons.

  • norb (int) – Number of orbitals.

  • init (tuple) – Initial Slater determinants for AFQMC.

  • orbmat (tuple) – Orbital matrices for PHMSD wavefunctions.

  • verbose (bool) – Print additional information.

  • orthonormalize (bool, optional) – If True (default), orthonormalize Slater matrices if not properly normalized.

Raises:

ValueError – If an unknown wavefunction type is passed.

Notes

The function supports two types of wavefunctions: PHMSD and NOMSD.

It writes the wavefunction data to the specified HDF5 file and handles different walker types, including corrections for user input.

For user-defined wavefunctions:

# PHMSD is a list of tuple of (ci, occa, occb). # NOMSD is a tuple of (list, np.ndarray).

afqmctools.wavefunction.converter module#

afqmctools.wavefunction.converter.convert_string(s)#
afqmctools.wavefunction.converter.orbs_from_dset(dset)#

Will read actually A^{H} but return A.

afqmctools.wavefunction.converter.read_dice_ascii_wavefunction(input_file, ndets, state)#

Reads SHCI wavefunction from the text-based output of Dice

Parameters:

  • input_file (str) – the name of a file containing Dice’s text-based output

  • ndets (int) – the number of Slater determinants to read

  • state (int) – the index of the state to read

Returns:

has length 5 and contains (wfn, nmo:int, nup:int, ndn:int, walker_type:int) where nmo is the number of orbitals, nup is the number of up electrons, ndn is the number of down electrons, and walker_type is an int encoding the type of walker (0 : CLOSED, 1: COLLINEAR, 2: NONCOLLINEAR 4: FULLYSPINPOLARIZED). wfn is a tuple containing: (coeffs:numpy.array, occa:numpy.array, occb:numpy.array) where ‘coeffs’ are the CI coefficients of the wavefunction, occa are the spin-up occupancies, and occb are the spin-down occupancies. All three arrays are the same length.

Return type:

tuple

Raises:

ValueError – If ndets is not specified

afqmctools.wavefunction.converter.read_dice_h5_wavefunction(input_file, ndets, state)#
afqmctools.wavefunction.converter.read_nomsd_hdf5(wgroup)#
afqmctools.wavefunction.converter.read_phmsd_hdf5(wgroup)#

Read particle-hole multi-Slater determinant wavefunction from HDF5

Parameters:

wgroup (h5py.Group) – the group containing wavefunction data

Returns:

  • wfn (tuple(coeffs:numpy.ndarray, occa:numpy.ndarray, occb:numpy.ndarray)) – where ‘coeffs’ are the CI coefficients of the wavefunction, occa are the spin-up occupancies, and occb are the spin-down occupancies.

  • psi0 (numpy.ndarray) – a numpy array containing the initial Slater determinant. The first na columns are spin-up orbitals, and the last nb columns are spin-down orbitals.

  • (na (int,nb:int)) – a tuple containing the number of up (na) and down (nb) electrons.

afqmctools.wavefunction.converter.read_wavefunction(filename)#
afqmctools.wavefunction.converter.read_with_check(f)#

afqmctools.wavefunction.free_electron module#

Free-Electron Trial Wavefunction builder

Author: Kyle Eskridge GitHub: bkesk

afqmctools.wavefunction.free_electron.free_electron(source, nelec, twist=None, spin_symm=None, use_dense=True, lattice=None, return_autohf=False, measure_spin=True, filling_strategy='aufbau', shell_tol=1e-06, measure_evar=True)#

Builds a free-electron trial wavefunction based on the ‘source’ lattice hamiltonian.

Parameters:

  • source (str | dict | Hamiltonian) – str - the name of an input file with lattice and hamiltonian blocks defined dict - a dict containing lattice and hamiltonian blocks

  • nelec (tuple(int,int)) – number of spin-up and spin-down electrons

  • twist (array-like, optional) – twist angle for the lattice (default: small irrational twist)

  • spin_symm (SpinSymm or str, optional) – spin symmetry to use

  • use_dense (bool) – whether to use dense matrix operations (default: True)

  • lattice (Lattice, optional) – pre-constructed lattice object

  • return_autohf (bool) – whether to return AutoHF results (default: False)

  • measure_spin (bool) – whether to measure spin in AutoHF (default: True)

  • filling_strategy (str) –

    strategy for filling orbitals within shells. Options:

    • ’aufbau’: fill shells from lowest to highest energy (default)

    • ’balanced’: for partially filled shells, select orbitals evenly

      to balance properties like momentum

    • ’hund’: apply Hund’s rule (maximize spin)

    • ’alternating’: fill from edges inward (0, -1, 1, -2, …)

      for momentum cancellation

  • shell_tol (float) – tolerance for grouping eigenvalues into shells (default: 1e-6) Orbitals with eigenvalues within this tolerance are considered to belong to the same shell.

  • measure_evar (bool) – whether to measure the variational energy with respect to the interacting Hamiltonian using AutoHF (default: True)

Returns:

  • wfn (list) – wavefunction as [coefficients, orbital_matrix]

  • spin_symm (SpinSymm) – spin symmetry of the wavefunction

  • results (dict (optional)) – AutoHF results if return_autohf=True

afqmctools.wavefunction.model module#

afqmctools.wavefunction.model.make_free_elec(hamiltonian_fname, nelec, spin_symm=None)#

Make a free-electron wavefunction with nelec = (Nup,Ndown) electrons based on the one-body Hamiltonian in hamiltonian_fame.

Parameters:

  • hamiltonian_fname (str) – Path to the Hamiltonian file.

  • nelec (tuple) – Number of electrons. (Nup,Ndown)

  • spin_symm (str | SpinSymm) – Spin symmetry of the wavefunction. If None, the spin symmetry is inferred from the Hamiltonian file.

Returns:

  • wfn (Wavefunction) – Free-electron wavefunction.

  • spin_symm (SpinSymm) – Spin symmetry of the wavefunction.

afqmctools.wavefunction.model.write_free_electron_wfn(hamiltonian_fname, nelec, output_fname=None, spin_symm=None)#

Write a free-electron wavefunction with nelec = (Nup,Ndown) electrons based on the one-body Hamiltonian in hamiltonian_fame. Optionally save the wavefunction to a different file (output_fname)

Parameters:

  • hamiltonian_fname (str) – Path to the Hamiltonian file.

  • nelec (tuple) – Number of electrons. (Nup,Ndown)

  • output_fname (str) – Path to the output wavefunction file.

  • spin_symm (str | SpinSymm) – Spin symmetry of the wavefunction. If None, the spin symmetry is inferred from the Hamiltonian file.

afqmctools.wavefunction.mol module#

afqmctools.wavefunction.mol.generate_wavefunction(scf_data, basis_scf_data=None, ortho_ao=False, cas=None, verbose=False)#
afqmctools.wavefunction.mol.write_cas_wfn(mol, cas_chkfile, outname='afqmc_wfn.h5', tol_trunc=0.0001, max_det=None)#

Write a CAS wavefunction to an HDF5 file.

Parameters:

  • mol (pyscf.gto.Mole) – Molecule object from PySCF.

  • cas_chkfile (str) – Path to the PySCF CAS checkpoint file.

  • outname (str) – Output HDF5 file name.

  • tol_trunc (float) – Truncation threshold for CI coefficients.

  • max_det (int) – Maximum number of determinants to keep. If None, all determinants within tol_trunc are kept.

afqmctools.wavefunction.mol.write_wfn_mol(scf_data, filename, basis_scf_data=None, wfn=None, init=None, verbose=False, ortho_ao=False, cas=None)#

Generate SAFIRE format trial wavefunction.

Parameters:

  • scf_data (dict) – Dictionary containing scf data extracted from pyscf checkpoint file.

  • filename (string) – HDF5 file path to store wavefunction to.

  • wfn (tuple) – User defined wavefunction. Not fully supported. Default None.

  • init (optional) – Initial wavefunction to use in AFQMC. Default is None.

  • basis_scf_data (dict, optional) – Dictionary containing scf data for the basis set in which to express the wavefunction. If None, the wavefunction will be expressed in the basis defined by scf_data.

  • verbose (bool, optional) – If True, print additional information. Default is False.

  • ortho_ao (bool, optional) – Work in Löwdin orthogonalized atomic orbitals instead of molecular orbitals. Make sure this is consistent with the Hamiltonian.

  • cas (tuple, optional) – If provided, indicates that the wavefunction is to be expressed in a CAS active space as (# active electrons, # active orbitals). Cannot be combined with ortho_ao.

Returns:

wfn – Wavefunction as numpy array. Format depends on wavefunction.

Return type:

np.ndarray

afqmctools.wavefunction.pbc module#

Write mean-field trial wavefunctions to file.

afqmctools.wavefunction.pbc.create_wavefunction(orbs, occs, nmo_pk, nelec, uhf, verbose)#
afqmctools.wavefunction.pbc.determine_occupancies(mo_occ, mo_energy, rhf, low=0.1, high=0.95, verbose=False, refdet=0, offset=0)#
afqmctools.wavefunction.pbc.generate_orbitals(fock, X, nmo_pk, rediag, ortho_ao, mo_energy, uhf, verbose=False)#
afqmctools.wavefunction.pbc.print_eigenvalues(ks, bands, eigs, uhf, srt, nelec, verbose)#
afqmctools.wavefunction.pbc.rediag_fock(fock, X)#

Rediagonalise Fock matrix.

Parameters:

  • fock (np.ndarray) – Fock matrix for given kpoint.

  • X (np.ndarray) – Transformation matrix.

Returns:

  • eigs (np.array) – MO eigenvalues.

  • eigv (np.ndarray) – Eigenvectors.

afqmctools.wavefunction.pbc.reoccupy(mo_occ, mo_energy, uhf, verbose, low=0.25, high=0.95, ndet_max=1)#
afqmctools.wavefunction.pbc.slater_gto2mo(phi, nelec=None, slater_type=None, transform_matrix=None, **kwargs)#

convert Slater determinant from gto basis to molecular orbital basis

Parameters:

  • (np.ndarray) (*optional* 'transform_mat') – in the underlying gto basis

  • 2) (*optional* nelec (iterable of length) – number of up(alpha) and down(beta) electrons expressed as ints. If provided, nelec is used to help distinguish between a Closed (i.e. RHF-like) determinant and a Noncollinear (i.e. GHF-like) determinant

  • ) (*optional* slater_type ( a _SlaterType instance or an int) – provided. If provided, this will override the automatic detection of the Slater determinant type

  • (np.ndarray)

  • **kwargs ((all optional) key-word arguments are ignored except for:) –

    • ‘orthAO’presence of keyword will force the use of an orthogonalized AO basis,

      as opposed to a molecule orbital basis.

    • ’basis’ (np.ndarray) : specifies an orbital basis to use - is ignored if orthAO is set (to anything!)

    • ’overlap’ (np.ndarray) : specifies the GTO-basis overlap matrix.

    • ’mol’ (pyscf.gto.Mole)a Mole object that describes the system (used to compute the overlap matrix

      if it was not provided)

afqmctools.wavefunction.pbc.write_wfn_pbc(scf_data, ortho_ao, filename, rediag=True, verbose=False, ndet_max=1, low=0.1, high=0.95)#

Generate trial wavefunction for PBC simulation.

Parameters:

  • scf_data (dict) – Dictionary containing scf data extracted from pyscf checkpoint file.

  • ortho_ao (bool) – Whether we are working in orthogonalised AO basis or not.

  • filename (string) – HDF5 file path to store wavefunction to.

  • rediag (bool) – Whether to rediagonalise Fock matrix to compute MO coeffs in orthogonalised AO basis. Default: True.

  • verbose (bool) – Print additional information. Default: False.

Returns:

wfn – Wavefunction as numpy array. Format depends on wavefunction.

Return type:

np.ndarray

afqmctools.wavefunction.pbc.write_wfn_pbc_old(scf_data, ortho_ao, filename, rediag=True, verbose=False, ndet_max=1, low=0.1, high=0.95)#

Generate trial wavefunction for PBC simulation.

Parameters:

  • scf_data (dict) – Dictionary containing scf data extracted from pyscf checkpoint file.

  • ortho_ao (bool) – Whether we are working in orthogonalised AO basis or not.

  • filename (string) – HDF5 file path to store wavefunction to.

  • rediag (bool) – Whether to rediagonalise Fock matrix to compute MO coeffs in orthogonalised AO basis. Default: True.

  • verbose (bool) – Print additional information. Default: False.

Returns:

wfn – Wavefunction as numpy array. Format depends on wavefunction.

Return type:

np.ndarray

Module contents#