PlaquetteTerm Class

Plaquette Hamiltonian contribution and plaquette-observable measurements on lattice models.

class edlgt.modeling.plaquette_term.PlaquetteTerm(axes, op_list, op_names_list, print_plaq=True, **kwargs)

Bases: QMBTerm

Four-body plaquette term on a lattice.

The class supports both:

• direct sparse-matrix construction (no symmetry-sector reduction), and

• symmetry-sector workflows where Hamiltonian contributions are returned as (rows, cols, vals) triplets.

Initialize a plaquette term definition.

Parameters:

• axes (list) – Two lattice axes defining the plaquette plane (for example ["x", "y"]).

• op_list (list) – Operators used to build the plaquette term.

• op_names_list (list) – Human-readable names corresponding to op_list.

• print_plaq (bool, optional) – If True, print plaquette values when calling get_expval().

• **kwargs – Additional keyword arguments forwarded to QMBTerm.

Return type:

None

get_hamiltonian(strength, add_dagger=False, mask=None)

Build the plaquette Hamiltonian contribution.

The plaquette term is summed over all lattice sites where a plaquette is defined (and where mask allows it), then multiplied by strength.

Parameters:

• strength (scalar) – Coupling constant multiplying the plaquette term.

• add_dagger (bool, optional) – If True, add the Hermitian conjugate of the constructed term.

• mask (numpy.ndarray, optional) – Boolean mask controlling where the local term is applied.

Returns:

Return type depends on the current workflow:

• if self.sector_configs is None: sparse matrix Hamiltonian term;

• otherwise: (row_list, col_list, val_list) as three NumPy arrays in the symmetry-reduced basis.

Return type:

scipy.sparse.csr_matrix or tuple

Raises:

TypeError – If strength is not scalar or add_dagger is invalid.

get_Hamiltonian(strength, add_dagger=False, mask=None)

Build the plaquette Hamiltonian contribution.

The plaquette term is summed over all lattice sites where a plaquette is defined (and where mask allows it), then multiplied by strength.

Parameters:

• strength (scalar) – Coupling constant multiplying the plaquette term.

• add_dagger (bool, optional) – If True, add the Hermitian conjugate of the constructed term.

• mask (numpy.ndarray, optional) – Boolean mask controlling where the local term is applied.

Returns:

Return type depends on the current workflow:

• if self.sector_configs is None: sparse matrix Hamiltonian term;

• otherwise: (row_list, col_list, val_list) as three NumPy arrays in the symmetry-reduced basis.

Return type:

scipy.sparse.csr_matrix or tuple

Raises:

TypeError – If strength is not scalar or add_dagger is invalid.

get_expval(psi, component='real', stag_label=None)

Compute plaquette expectation values site by site and aggregate statistics.

Parameters:

• psi (QMB_state) – Quantum many-body state on which the expectation values are evaluated.

• component (str, optional) – Component of the plaquette operator to measure. Allowed values are "real" (Hermitian part) and "imag" (anti-Hermitian part).

• stag_label (str, optional) – Optional staggered-site selector passed through the common validation logic. Allowed values are "even" and "odd". If None, all plaquettes are considered.

Returns:

Results are stored on the instance attributes obs, var, avg, and std.

Return type:

None

Raises:

• TypeError – If psi is not a QMB_state instance.

• ValueError – If component is not "real" or "imag".

Notes

In symmetry-sector mode, variances are currently not computed.

print_plaquette(sites_list, value)

Log a formatted ASCII representation of a plaquette value.

Parameters:

• sites_list (list) – List of four coordinate labels describing the plaquette corners.

• value (float) – Plaquette value to print.

Return type:

None

Raises:

• TypeError – If sites_list is not a list or value is not a float.

• ValueError – If sites_list does not contain exactly four entries.

print_Plaquette(sites_list, value)

Log a formatted ASCII representation of a plaquette value.

Parameters:

• sites_list (list) – List of four coordinate labels describing the plaquette corners.

• value (float) – Plaquette value to print.

Return type:

None

Raises:

• TypeError – If sites_list is not a list or value is not a float.

• ValueError – If sites_list does not contain exactly four entries.

get_plaquette_shape()

Return the resolved plaquette-array shape for this term.

Plane axes have one fewer plaquette origin under open boundary conditions and one origin per lattice site under periodic boundary conditions. Spectator axes keep the full lattice extent.

iter_plaquettes()

Enumerate valid plaquette origins, corner coordinates, and sites.

get_empty_obs_array(fill_value=0.0)

Return a plaquette-resolved observable array with the proper shape.