models

Model constructors define the physical problem without building many-body operators or running solvers. They return eight values: seven inputs describing the Hamiltonians, Fock bases, and transition operators, plus a scalar shift equal to the filled core’s shell-level energy.

Pass the first seven outputs to get_ops. For dense, SciPy, or PETSc diagonalization, optionally pass shift to ed to reduce numerical errors. The returned eigenvalues retain their original energy reference, so the shift does not change the physics. Fortran ED ignores a nonzero shift with a warning.

Backend-independent physical model construction for EDRIXS.

The model functions in this module describe orbital-space Hamiltonians, interactions, Fock-basis specifications, and photon-transition matrices without constructing backend-owned many-body operators.

edrixs.models.model_1v1c(shell_name, *, shell_level=None, v_soc=None, c_soc=0, v_noccu=1, slater=None, ext_B=None, on_which='spin', v_cfmat=None, v_othermat=None, loc_axis=None, verbose=False, sparse_U=False)

Set up orbital-space data and Fock-basis metadata for a 1v1c problem.

This routine defines the physical one-valence-shell/one-core-shell problem independently of the numerical backend. It constructs the one-body orbital matrices, Coulomb tensors, Fock-basis specifications, and orbital-space transition matrices, but it does not build many-body Hamiltonians and does not diagonalize anything.

Parameters:

shell_nametuple of str

Names of the valence and core shells.

shell_level, v_soc, c_soc, v_noccu, slater, ext_B, on_which,

v_cfmat, v_othermat, loc_axis

Same physical model parameters as ed_1v1c_py.

verbosebool, optional

If True, print a setup summary (Slater integrals and Hilbert-space dimensions). Default False.

sparse_Ubool, optional

If False, return dense rank-4 Coulomb tensors. If True, return each Coulomb tensor as a sparse matrix with shape (ntot*ntot, ntot*ntot), using the flattened convention row = lorb * ntot + korb and col = jorb * ntot + iorb.

Returns:

emat_i, umat_i, basis_i, emat_n, umat_n, basis_n, trans_mat, shift

Backend-independent problem definition. basis_i and basis_n are compact Fock-basis specifications with a filled initial core and one intermediate core hole. Occupancy arguments count valence electrons only. Both one-body matrices have shape (ntot, ntot), both dense Coulomb tensors have shape (ntot,) * 4, and trans_mat has shape (npol, ntot, ntot). Initial core interactions are included. shift is the filled core shell-level energy, c_norb * shell_level[1] (zero if unspecified), excluding Coulomb contributions. Pass the first seven outputs to get_ops() and shift to dense, SciPy, or PETSc ed(). The returned integrals retain the full, unshifted energies.

edrixs.models.model_2v1c(shell_name, *, shell_level=None, v1_soc=None, v2_soc=None, c_soc=0, v_tot_noccu=1, slater=None, v1_ext_B=None, v2_ext_B=None, v1_on_which='spin', v2_on_which='spin', v1_cfmat=None, v2_cfmat=None, v1_othermat=None, v2_othermat=None, hopping_v1v2=None, trans_to_which=1, loc_axis=None, verbose=False, sparse_U=False)

Set up orbital-space data and Fock-basis metadata for a 2v1c problem.

This is the backend-neutral setup analogue of the 2-valence-shell, 1-core-shell Fortran ED/RIXS input construction. It does not build many-body Hamiltonians and does not diagonalize anything. If sparse_U=True, the returned Coulomb tensors are sparse flattened matrices rather than dense rank-4 arrays.

Parameters:

shell_nametuple of str

Names of the first valence shell, second valence shell, and core shell, in that order. Each valence shell must be one of 's', 'p', 't2g', 'd', or 'f'. The core shell may additionally be a spin-orbit-split shell such as 'p12', 'p32', 'd32', 'd52', 'f52', or 'f72'.

shell_levelsequence of three float or None, optional

One-body energy levels of the first valence, second valence, and core shells. All levels default to zero.

v1_soc, v2_socsequence of two float or None, optional

Spin-orbit coupling strengths for the corresponding valence shell in the initial and intermediate Hamiltonians, respectively. Spin-orbit coupling is omitted when the value is None.

c_socfloat, optional

Core-shell spin-orbit coupling strength. This is applied to unsplit 'p', 'd', and 'f' core shells. Default is zero.

v_tot_noccuint, optional

Total number of electrons occupying the two valence shells in the initial state. Default is one.

slatertuple of two sequences of float or None, optional

Slater integrals for the initial and intermediate Hamiltonians. Each sequence follows the order returned by slater_integrals_name(shell_name, ('v1', 'v2', 'c1')). Missing trailing values and all values when slater is None are treated as zero.

v1_ext_B, v2_ext_Barray-like of float, shape (3,), or None, optional

Zeeman/exchange-field coefficients in the global Cartesian frame for the corresponding valence shell. No field is applied when the value is None.

v1_on_which, v2_on_which{‘spin’, ‘orbital’, ‘both’}, optional

Sector on which the corresponding external field acts. Default is 'spin'.

v1_cfmat, v2_cfmatarray-like of complex or None, optional

Crystal-field matrix for the corresponding valence shell. Its shape must match that shell’s number of spin-orbitals. Defaults to zero.

v1_othermat, v2_othermatarray-like of complex or None, optional

Additional one-body matrix for the corresponding valence shell. Its shape must match that shell’s number of spin-orbitals. Defaults to zero.

hopping_v1v2array-like of complex or None, optional

Hopping matrix from the second valence shell to the first, with shape (v1_norb, v2_norb). Its Hermitian conjugate is inserted automatically. Defaults to zero.

trans_to_which{1, 2}, optional

Valence shell reached by the core-to-valence transition. Default is the first valence shell.

loc_axisarray-like of float, shape (3, 3), or None, optional

Rotation from local crystal-field coordinates to the global frame for the transition operators. The identity rotation is used by default.

verbosebool, optional

If True, print a setup summary (Slater integrals and Hilbert-space dimensions). Default is False.

sparse_Ubool, optional

If False, return dense rank-4 Coulomb tensors. If True, return CSR matrices using the flattened convention row = lorb * norb + korb and col = jorb * norb + iorb. Default is False.

Returns:

emat_inumpy.ndarray

Initial-state one-body matrix over both valence shells and the core, with shape (ntot, ntot).

umat_inumpy.ndarray or scipy.sparse.csr_matrix

Initial-state Coulomb interaction including core interactions. The dense representation has shape (ntot,) * 4; the sparse representation has shape (ntot**2, ntot**2).

basis_iFockBasisSpec

Initial-state Fock-basis specification with v_tot_noccu valence electrons and a fully occupied core shell.

emat_nnumpy.ndarray

Intermediate-state one-body matrix over both valence shells and the core shell, with shape (ntot, ntot).

umat_nnumpy.ndarray or scipy.sparse.csr_matrix

Intermediate-state Coulomb interaction. The dense representation has shape (ntot,) * 4; the sparse representation has shape (ntot**2, ntot**2).

basis_nFockBasisSpec

Intermediate-state Fock-basis specification with one additional valence electron and one core hole.

trans_matnumpy.ndarray

Core-to-valence transition matrices in the global frame, with shape (npol, ntot, ntot).

shiftfloat

Filled core shell-level energy, c_norb * shell_level[2] (zero if unspecified), excluding Coulomb contributions. Pass the first seven outputs to get_ops() and shift to dense, SciPy, or PETSc ed(). Integrals remain unshifted.

See also

edrixs.models.model_1v1c

Construct a model with one valence shell and one core shell.

edrixs.models.model_siam

Construct a single-impurity Anderson model.

edrixs.solvers.get_ops

Convert a model definition into backend-owned many-body operators.

Examples

Construct a model for two valence shells and build its SciPy operators:

>>> import edrixs
>>> *problem, shift = edrixs.model_2v1c(
...     ('d', 'p', 's'), v_tot_noccu=2, trans_to_which=2
... )
>>> hmat_i, hmat_n, trans_ops = edrixs.get_ops(
...     *problem, backend='scipy'
... )

edrixs.models.model_siam(shell_name, nbath, *, siam_type=0, v_noccu=1, static_core_pot=0, c_level=0, c_soc=0, trans_c2n=None, imp_mat=None, imp_mat_n=None, bath_level=None, bath_level_n=None, hyb=None, hyb_n=None, hopping=None, hopping_n=None, slater=None, ext_B=None, on_which='spin', loc_axis=None, verbose=False, sparse_U=False)

Set up a single-impurity Anderson model (SIAM) for ED, XAS, and RIXS.

Construct backend-independent one-body matrices, Coulomb interactions, Fock-basis specifications, and core-to-impurity transition matrices. This is the setup analogue of ed_siam_fort() at fixed v_noccu; it does not search over occupancies, build many-body Hamiltonians, or diagonalize them. Pass the returned tuple to get_ops() to construct the many-body operators with the SciPy, dense, or PETSc backend.

All energies, Slater integrals, hybridizations, spin-orbit coupling constants, and magnetic-field components are in eV. Let v_norb and c_norb be the numbers of impurity and core spin-orbitals, respectively, ntot_v = (nbath + 1) * v_norb, and ntot = ntot_v + c_norb. Orbitals are ordered as impurity, successive bath sites, then core. Each bath site has v_norb spin-orbitals and no Coulomb interaction.

Parameters:

shell_nametuple of two str

Impurity valence and core shell names, in that order. The valence shell can be ‘s’, ‘p’, ‘t2g’, ‘d’, or ‘f’. The core shell can be ‘s’, ‘p’, ‘p12’, ‘p32’, ‘t2g’, ‘d’, ‘d32’, ‘d52’, ‘f’, ‘f52’, or ‘f72’. For example, ('d', 'p32') describes an L3-edge transition from a p3/2 core shell to a d impurity.

nbathint

Number of bath sites.

siam_type{0, 1}, optional

Parameterization of the impurity and bath one-body terms. For 0 (default), use imp_mat, bath_level, and hyb to describe diagonal hybridization. For 1, use the full hopping matrix, allowing off-diagonal hybridization. The corresponding *_n parameters specify intermediate-state terms. Parameters belonging to the other parameterization are ignored.

v_noccuint, optional

Total number of electrons in the impurity and bath orbitals in the initial state, excluding the filled core. Default is 1. Must satisfy 0 <= v_noccu < ntot_v so that the intermediate state can accommodate one additional electron.

static_core_potfloat, optional

Static core-hole potential, subtracted from every impurity diagonal element in the intermediate state. Positive values are attractive. This is added independently of the core-valence Slater interactions. Default is 0.

c_levelfloat, optional

Core-shell energy level, added to each core diagonal element in both states. Default is 0.

c_socfloat, optional

Core spin-orbit coupling strength, applied for unsplit ‘p’, ‘d’, and ‘f’ core shells only. For split shells such as ‘p32’, the shell choice already selects the total-angular-momentum subspace. Default is 0.

trans_c2narray_like of complex, shape (v_norb, v_norb), optional

Unitary transformation from complex spherical harmonics to the basis used for the impurity and bath one-body input parameters. Its columns are the input basis vectors expressed in spherical harmonics. The same transformation is used on the impurity and every bath site to convert the one-body matrices back to spherical harmonics. Default is the identity.

imp_matarray_like of complex, shape (v_norb, v_norb), optional

Initial-state impurity one-body matrix for siam_type=0, including the impurity energy level, crystal field, and valence spin-orbit coupling as needed. Default is zero.

imp_mat_narray_like of complex, shape (v_norb, v_norb), optional

Intermediate-state impurity matrix for siam_type=0. If None, use imp_mat.

bath_levelnumpy.ndarray, shape (nbath, v_norb), optional

Initial-state bath energy levels for siam_type=0. The first index selects the bath site and the second its spin-orbital. Default is zero.

bath_level_nnumpy.ndarray, shape (nbath, v_norb), optional

Intermediate-state bath levels for siam_type=0. If None, use bath_level.

hybnumpy.ndarray, shape (nbath, v_norb), optional

Initial-state hybridization amplitudes for siam_type=0. hyb[i, j] is the matrix element from spin-orbital j of bath site i to impurity spin-orbital j; its complex conjugate is inserted for the reverse hopping. Default is zero.

hyb_nnumpy.ndarray, shape (nbath, v_norb), optional

Intermediate-state hybridization amplitudes for siam_type=0. If None, use hyb.

hoppingarray_like of complex, shape (ntot_v, ntot_v), optional

Full initial-state one-body matrix for siam_type=1, including impurity terms, bath levels, and hybridization. Supply a Hermitian matrix in impurity-then-bath order. Default is zero.

hopping_narray_like of complex, shape (ntot_v, ntot_v), optional

Full intermediate-state impurity and bath matrix for siam_type=1. If None, use hopping.

slatertuple of two lists, optional

Slater integrals for the initial and intermediate states, respectively. Each list is ordered as [FX_vv, FX_vc, GX_vc, FX_cc], with ranks X in ascending order within each group; v denotes the impurity and c the core. Use slater_integrals_name(shell_name, ('v', 'c')) to obtain the names in the required order. Trailing zeros may be omitted; entries beyond the required number are ignored. For example, d-impurity/p-core integrals begin with [F0_dd, F2_dd, F4_dd, F0_dp, F2_dp, G1_dp, G3_dp]. Initial-state core-valence and core-core terms act on the explicit filled core. Default is all zeros.

ext_Barray_like of float, shape (3,), optional

External Zeeman/exchange field components along the global x, y, and z axes, applied only to the impurity in both states. Components are energy coefficients, not magnetic fields in tesla. Default is zero.

on_which{‘spin’, ‘orbital’, ‘both’}, optional

Couple ext_B to 2S, L, or L + 2S, respectively, with a positive sign in the Hamiltonian. Default is ‘spin’.

loc_axisarray_like of float, shape (3, 3), optional

Rotation from local crystal-field coordinates to the global frame for the transition operators. Columns are the local axes expressed in global coordinates. Default is the identity rotation.

verbosebool, optional

If True, print Slater integrals and Hilbert-space dimensions. Default is False.

sparse_Ubool, optional

If False (default), return dense rank-4 Coulomb tensors. If True, embed the impurity/core interactions directly as CSR matrices, avoiding dense rank-4 tensors over the full impurity and bath space. The flattened convention is row = lorb * norb + korb and col = jorb * norb + iorb, where norb is ntot_v for the initial state and ntot for the intermediate state.

Returns:

emat_inumpy.ndarray, shape (ntot, ntot)

Initial-state one-body matrix over impurity, bath, and core orbitals.

umat_inumpy.ndarray or scipy.sparse.csr_matrix

Initial-state Coulomb interaction on impurity and core orbitals. Dense shape is (ntot,) * 4; sparse shape is (ntot**2, ntot**2).

basis_iFockBasisSpec

Initial-state basis specification with v_noccu electrons in the impurity and bath orbitals and c_norb core electrons.

emat_nnumpy.ndarray, shape (ntot, ntot)

Intermediate-state one-body matrix over impurity, bath, and core.

umat_nnumpy.ndarray or scipy.sparse.csr_matrix

Intermediate-state Coulomb interaction on impurity and core orbitals. Dense shape is (ntot,) * 4; sparse shape is (ntot**2, ntot**2).

basis_nFockBasisSpec

Intermediate-state basis specification with v_noccu + 1 impurity and bath electrons and c_norb - 1 core electrons.

trans_matnumpy.ndarray, shape (npol, ntot, ntot)

Core-to-impurity absorption matrices, with nonzero entries only in the impurity-row/core-column block. npol is 3 for dipole and 5 for quadrupole transitions; components are in the global frame.

shiftfloat

Filled core shell-level energy, c_norb * c_level, excluding Coulomb contributions. Pass the first seven outputs to get_ops() and shift to dense, SciPy, or PETSc ed(). Integrals remain unshifted.

edrixs.models.model_siam_2d1p(*, slater, impurity_levels, bath_levels, hyb, Delta, nd, v_soc=None, c_soc=0, om_shift=0, ext_B=None, on_which='spin', loc_axis=None, verbose=False, sparse_U=False)

Set up the commonly used d-impurity, one-bath, p-core charge-transfer model. This is a convenience wrapper around model_siam(). All energies, Slater integrals, hoppings, SOC constants, and magnetic-field components are in eV. The bath has ten spin-orbitals and no Coulomb interaction.

Parameters:

slatertuple of array_like

Initial [F0_dd, F2_dd, F4_dd] and intermediate [F0_dd, F2_dd, F4_dd, F0_dp, F2_dp, G1_dp, G3_dp]. Each state’s average Coulomb interactions are recovered by subtracting the corresponding get_F0 contribution from its F0 integrals.

impurity_levels, bath_levelsarray_like, shape (5,)

Real orbital offsets in the order (dz2, dzx, dzy, dx2-y2, dxy). The mean of each five-orbital array is subtracted before adding the charge-transfer-derived shell center. Each level applies to both spins; the input arrays are not modified.

hybarray_like, shape (5,)

Orbital-diagonal impurity-to-bath hoppings in the same order. Complex values are allowed. Both spins and both states use the same hoppings.

Deltafloat

Charge-transfer energy. This is defined in the atomic limit (without crystal field, hybridization, or multipolar Coulomb interactions) as the energy cost of transferring one electron from the bath to the impurity. Used for both states in CT_imp_bath() and CT_imp_bath_core_hole().

ndint

Nominal impurity occupancy, from 0 through 9. The nominal bath is full; the initial total valence occupancy is nd + 10.

v_socpair of float, optional

Initial and intermediate impurity SOC constants. None means zero.

c_socfloat, optional

Core SOC constant. Default zero.

om_shiftfloat, optional

Overall XAS energy alignment. The core energy passed to model_siam is -om_shift - 5*E_p, where E_p comes from the core-hole CT helper. Increasing om_shift raises transition energies by the same amount. Default zero; the filled-core reference convention is preserved.

ext_B, on_which, loc_axis, verbose, sparse_U

Passed through to model_siam() with the same meaning and defaults. The magnetic field acts on the impurity only.

Returns:

emat_i, umat_i, basis_i, emat_n, umat_n, basis_n, trans_mat, shift

The eight model_siam outputs. Pass the first seven to get_ops() and the final shift to dense, SciPy, or PETSc ed(). Here shift = 6 * (-om_shift - 5*E_p); it excludes Coulomb contributions and does not alter the integrals. One-body matrices both have shape (26, 26) and use complex spherical harmonics. Basis metadata fixes initial valence occupancy to nd+10, intermediate valence occupancy to nd+11, and core occupancies to six and five, respectively. Coulomb tensors are dense unless sparse_U=True. No diagonalization or spectrum calculation is performed.