qarp.operators.models

Model Hamiltonian builders.

Two return types, split by physics — check before encoding:

  • fermi_hubbard → FermionOperator (map it with a Mapping before use on qubits);

  • lipkin, transverse_field_ising, xy_model → QubitOperator, native to the qubit basis — no fermion-to-qubit mapping is involved or needed.

Fermionic models are built from numpy tensors via qarp.operators.fermion_operator_from_tensor().

Lattice models share one geometry: sites of an n-dimensional box dims are indexed with the first dimension fastest (site = x + dims[0]·y + dims[0]·dims[1]·z + ...), and nearest-neighbour bonds optionally wrap around dimensions of size > 2 (a wrap on a smaller dimension would double an existing bond).

qarp.operators.models.fermi_hubbard(dims: Sequence[int], t: float, U: float, V: float = 0.0, periodic: bool = False) → FermionOperator[source]

(Extended) Fermi-Hubbard Hamiltonian on a hypercubic lattice.

\[H = -t \sum_{\langle i,j \rangle, \sigma} (a^\dagger_{i\sigma} a_{j\sigma} + \text{h.c.}) + U \sum_i n_{i\uparrow} n_{i\downarrow} + V \sum_{\langle i,j \rangle} n_i n_j\]

Site s owns the abab spin-orbital pair (2s, 2s + 1); for a 2D lattice the conventions coincide with openfermion’s fermi_hubbard (the test oracle). A chain is dims=(n,), a 3D box (n_x, n_y, n_z).

Parameters:

  • dims – Lattice extents, e.g. (4,), (3, 2), (2, 2, 2).

  • t – The kinetic (hopping) energy.

  • U – The on-site repulsion.

  • V – Nearest-neighbour density-density coupling (extended Hubbard).

  • periodic – If true, wrap neighbours around each dimension of size > 2.

Returns:

The Hamiltonian as a FermionOperator.

qarp.operators.models.lipkin(n: int, t: float, V: float) → QubitOperator[source]

Lipkin-model Hamiltonian, natively in the qubit basis (no mapping required).

\[H = \frac{t}{2} \sum_p Z_p - \frac{V}{2} \sum_{p < q} (X_p X_q - Y_p Y_q)\]
Parameters:

  • n – The number of sites in the chain.

  • t – The kinetic energy.

  • V – The two-site coupling constant.

Returns:

The Hamiltonian as a QubitOperator.

qarp.operators.models.transverse_field_ising(dims: Sequence[int], j: float, h_x: float | Sequence[float], h_z: float | Sequence[float] = 0.0, periodic: bool = False) → QubitOperator[source]

Transverse-field Ising Hamiltonian on a hypercubic lattice (one qubit per site).

\[H = -j \sum_{\langle a,b \rangle} Z_a Z_b - \sum_s h^x_s X_s - \sum_s h^z_s Z_s\]

h_x and h_z accept a scalar or a per-site sequence — per-site fields give the random-field Ising model, with the caller owning the randomness (pass a seeded draw).

Parameters:

  • dims – Lattice extents, e.g. (6,) or (3, 3).

  • j – The ZZ coupling.

  • h_x – Transverse field, scalar or one value per site.

  • h_z – Longitudinal field, scalar or one value per site.

  • periodic – If true, wrap neighbours around each dimension of size > 2.

Returns:

The Hamiltonian as a QubitOperator.

qarp.operators.models.xy_model(dims: Sequence[int], j: float, periodic: bool = False) → QubitOperator[source]

Isotropic XY Hamiltonian on a hypercubic lattice (one qubit per site).

\[H = -\frac{j}{2} \sum_{\langle a,b \rangle} (X_a X_b + Y_a Y_b)\]

On a chain this is exactly the Jordan-Wigner image of free-fermion hopping (the test oracle), and it is the hardcore Bose-Hubbard model.

Parameters:

  • dims – Lattice extents, e.g. (6,) or (3, 3).

  • j – The XY coupling.

  • periodic – If true, wrap neighbours around each dimension of size > 2.

Returns:

The Hamiltonian as a QubitOperator.