Quantum Many Body Model Class

High-level workflow class for building symmetry sectors, assembling Hamiltonians, diagonalizing/evolving them, and measuring observables.

class edlgt.models.quantum_model.QuantumModel(lvals, has_obc, ham_format='sparse', basis_projector=None)

Bases: object

High-level container orchestrating model building and measurements.

Initialize a lattice quantum model container.

Parameters:

• lvals (list) – Lattice dimensions.

• has_obc (list) – Boundary-condition flags per axis (True for open boundaries).

• ham_format (str, optional) – Preferred Hamiltonian representation (for example "sparse").

• basis_projector (numpy.ndarray, optional) – Optional site-local projector used to reduce the effective local Hilbert space uniformly on all sites.

default_params()

Initialize default keyword arguments and the Hamiltonian container.

Returns:

Updates self.def_params and (when possible) creates self.H.

Return type:

None

set_momentum_sector(k_unit_cell_size, k_vals, TC_symmetry=False)

Build and store a momentum-sector projector.

Parameters:

• k_unit_cell_size (list) – Translation unit-cell size used to define momentum sectors.

• k_vals (list) – Target momentum quantum numbers (one per lattice dimension).

• TC_symmetry (bool, optional) – Whether to include translation-charge symmetry reduction in the momentum basis construction.

Return type:

None

Raises:

ValueError – If symmetry-sector configurations are missing, OBC are present, or the momentum shape is inconsistent with the lattice dimension.

set_momentum_pair(k_left, k_right, k_unit_cell_size, TC_symmetry)

Build two momentum projectors for rectangular k_L-k_R blocks.

Parameters:

• k_left (list) – Left and right momentum quantum numbers.

• k_right (list) – Left and right momentum quantum numbers.

• k_unit_cell_size (list) – Translation unit-cell size.

• TC_symmetry (bool) – Whether to include translation-charge symmetry reduction.

Return type:

None

Notes

This prepares rectangular projections of the form P_kL^dagger O P_kR and stores them in self.momentum_basis in pair mode.

check_momentum_pair()

Validate orthonormality/orthogonality of the stored momentum pair basis.

Return type:

None

Raises:

ValueError – If either projector is not orthonormal or two distinct momentum sectors are not orthogonal.

project_operators(ops_dict, bg_sector_list=None)

Project local operators into the effective per-site basis.

Parameters:

• ops_dict (dict) – Dictionary of bare local operators.

• bg_sector_list (list, optional) – Optional per-site background-sector labels used to restrict the gauge-invariant basis on each site.

Returns:

Stores projected operators in self.ops and local dimensions in self.loc_dims.

Return type:

None

get_abelian_symmetry_sector(global_ops, global_sectors=None, global_sym_type='U', link_ops=None, link_sectors=None, nbody_ops=None, nbody_sectors=None, nbody_sites_list=None, nbody_sym_type=None)

Build symmetry-sector configurations from abelian constraints.

Parameters:

• global_ops (list or None) – Generators for global abelian symmetries.

• global_sectors (list or None, optional) – Target sectors for global symmetries.

• global_sym_type (str, optional) – Global symmetry type flag passed to symmetry-sector routines.

• link_ops (list or None) – Link-symmetry generators.

• link_sectors (list or None, optional) – Target sectors for link symmetries.

• nbody_ops (list or None) – Optional n-body symmetry generators.

• nbody_sectors (list or None, optional) – Target sectors for n-body symmetries.

• nbody_sites_list (object, optional) – Site patterns for n-body symmetries.

• nbody_sym_type (str or None, optional) – Symmetry type flag for n-body constraints.

Notes

The method supports pure global sectors, pure link sectors, mixed link-plus-nbody sectors, and pure n-body sectors.

Returns:

Stores the resulting sector configurations in self.sector_configs.

Return type:

None

diagonalize_Hamiltonian(n_eigs, ham_format=None, print_results=False, **kwargs)

Diagonalize the model Hamiltonian and cache energies/eigenstates.

Accepts the legacy format=... keyword for backward compatibility.

time_evolution_Hamiltonian(initial_state, time_line)

Evolve an initial state with the current Hamiltonian.

momentum_basis_projection(operator)

Project an operator into the currently stored momentum basis.

Parameters:

operator (str or numpy.ndarray or scipy.sparse.spmatrix) – Operator to project. If "H", projects self.H.Ham in place.

Returns:

Projected operator. Returns None when projecting "H" in place.

Return type:

scipy.sparse.csr_matrix or None

Raises:

ValueError – If no momentum basis has been set.

build_projector_from_sector_to_fullspace(indices)

Build a projector from a symmetry-reduced subsystem basis to the full basis.

Parameters:

indices (list) – Subsystem site indices.

Returns:

Column projector from the symmetry-sector subsystem basis to the full subsystem computational basis.

Return type:

scipy.sparse.csc_matrix

get_qmb_state_from_configs(configs)

Build an equal-weight state from explicit sector configurations.

Parameters:

configs (typing.Sequence or list) – Collection of basis configurations compatible with self.sector_configs.

Returns:

Normalized state vector in the symmetry-sector basis.

Return type:

numpy.ndarray

Raises:

• NotImplementedError – If a momentum sector is active.

• ValueError – If one configuration is not compatible with the current symmetry sector.

measure_fidelity(state, index, dynamics=False, print_value=False)

Compute fidelity with an eigenstate or a time-evolved state.

Parameters:

• state (numpy.ndarray) – Reference state vector.

• index (int) – Index of the comparison state.

• dynamics (bool, optional) – If True, compare against self.H.psi_time[index] instead of self.H.Npsi[index].

• print_value (bool, optional) – If True, log the fidelity value.

Returns:

Fidelity |<ref|state>|^2.

Return type:

float

compute_expH(beta)

Return exp(-beta H) as a sparse CSC matrix.

get_thermal_beta(state, threshold)

Estimate an effective thermal beta for a reference state.

canonical_avg(local_obs, beta)

Compute the canonical-ensemble average of a local observable.

Parameters:

• local_obs (str) – Observable key in self.ops.

• beta (float) – Inverse temperature.

Returns:

Canonical average per lattice site.

Return type:

float

microcanonical_avg(local_obs_list, state, special_norms=None, staggered_avgs=None)

Compute microcanonical averages for multiple local observables.

The energy shell is defined using the energy density of the reference state and its uncertainty:

• e_q = <H> / L

• delta_e = sqrt(<H^2> - <H>^2) / L

All eigenstates satisfying abs(e_i - e_q) < delta_e are included. For each observable in local_obs_list, the expectation value is measured on every state in the shell and then averaged.

Parameters:

• local_obs_list (list) – Keys of local observables. Each key must be present in self.ops.

• state (numpy.ndarray) – Reference state vector used to define the energy shell.

• special_norms (dict, optional) – Optional mapping from observable key to a custom normalization array.

• staggered_avgs (dict, optional) – Optional mapping from observable key to a staggered-averaging label or rule used by the local observable measurement.

Returns:

(psi_thermal, ME_avg) where psi_thermal is the normalized coherent superposition of shell eigenstates and ME_avg is a dictionary mapping observable names to microcanonical averages.

Return type:

tuple

diagonal_avg(local_obs_list, state, special_norms=None, staggered_avgs=None, tol_deg=1e-10)

Compute diagonal-ensemble averages for several local observables.

Parameters:

• local_obs_list (list) – Observable keys in self.ops.

• state (numpy.ndarray) – Reference state used to compute diagonal weights.

• special_norms (dict, optional) – Optional observable-specific normalization arrays.

• staggered_avgs (dict, optional) – Optional observable-specific staggered averaging labels.

• tol_deg (float, optional) – Tolerance used to group degenerate eigenvalues into blocks.

Returns:

Dictionary of diagonal-ensemble averages keyed as DE_<obs>.

Return type:

dict

get_observables(local_obs=[], twobody_obs=[], plaquette_obs=[], nbody_obs=[], nbody_dist=[], twobody_axes=None)

Instantiate observable objects and cache them in self.obs_list.

Parameters:

• local_obs (list, optional) – Names of local observables.

• twobody_obs (list, optional) – List of two-body operator-name pairs.

• plaquette_obs (list, optional) – List of plaquette operator-name lists.

• nbody_obs (list, optional) – List of n-body operator-name lists.

• nbody_dist (list, optional) – Relative distances for each n-body observable.

• twobody_axes (list, optional) – Axis labels for each two-body observable.

Return type:

None

measure_observables(index, dynamics=False)

Measure all observables stored in self.obs_list on one state.

Parameters:

• index (int) – Eigenstate or time-step index.

• dynamics (bool, optional) – If True, measure on self.H.psi_time[index].

Returns:

Results are stored in self.res.

Return type:

None

link_avg(obs_name)

Average a directional link observable over all valid lattice links.

Parameters:

obs_name (str) – Base observable name. Directional components are expected in self.res as f"{obs_name}_p<dir>".

Returns:

Average over all valid directed links.

Return type:

float

directed_link_shape(axis)

Return the positive-link array shape along one lattice axis.

directed_link_shapes()

Return positive-link array shapes in x, y, z order.

directed_link_observable(obs_name)

Return positive-link observable arrays for each lattice direction.

obs_name is the base name, for example "E", "E2", or "T2". The method reads measured dressed-site observables named f"{obs_name}_p<axis>" from self.res and returns a list [O_x, O_y, O_z] truncated only on open boundaries along the corresponding positive-link direction.

stag_avg(obs_name, staggered_avg=None)

Average a measured local observable on all, even, or odd sites.

Parameters:

• obs_name (str) – Observable key already stored in self.res as a site-resolved array.

• staggered_avg (str or None, optional) – None for the full average, or "even" / "odd" for a staggered sublattice average.

Returns:

Requested average value.

Return type:

float

Raises:

KeyError – If obs_name is not present in self.res.

configure_dtype_mode(dtype_mode='auto', auto_mode='complex')

Apply the global numeric dtype mode for Hamiltonian/operator assembly.

Parameters:

• dtype_mode (str or bool, optional) – Explicit mode ("real"/"complex" or bool) or "auto".

• auto_mode (str or bool, optional) – Fallback mode used when dtype_mode == "auto".

Returns:

Applied normalized mode ("real" or "complex").

Return type:

str