models

Model constructors return eight values: seven orbital-space problem inputs and a scalar shift equal to the filled core’s shell-level energy. Coulomb contributions are excluded from this shift, and the integrals remain unshifted. Use it explicitly for dense or SciPy diagonalization:

*problem, shift = edrixs.model_1v1c(('p', 's'), shell_level=(0, -100))
hmat_i, hmat_n, trans_ops = edrixs.get_ops(*problem, backend='scipy')
eval_i, evec_i = edrixs.ed(hmat_i, shift=shift)

The returned eigenvalues retain their absolute energy reference. Fortran callers pass only problem to get_ops and omit shift from ed.

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)[source]

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 or SciPy 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)[source]

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 or SciPy 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)[source]

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.

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 or SciPy 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)[source]

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 or SciPy 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.