Realisation layer¶

Numerical realisation of symbolic models as dense complex128 operators in JAX.

The package provides operator construction, basis ordering, subspace and sector projectors, exact diagonalisation and time evolution by eigendecomposition. It supports the numerical validation of the static declarations made along a pipeline by a classical simulation of the same model at small chain length. Importing the package enables the 64-bit mode of JAX via qsimod.jax_setup.

Hilbert spaces, basis ordering and single-site operator matrices.

The following conventions are fixed in this module:

• Basis ordering. The local basis index is the occupation number on every algebra; a boson with cutoff n_max has n_max + 1 levels.
• Tensor-factor order. Register site 0 is the leftmost, most significant factor, index = sum_j config[j] * prod_{k>j} dim[k].
• Pauli matrices. Z = 2n - 1 = diag(-1, +1), X = [[0,1],[1,0]], Y = [[0,i],[-i,0]]; hence n = (Z+1)/2, sigma^+ = |1><0| = (X+iY)/2 and XY = iZ. qsimod.pauli uses the same conventions.
• Spin-1/2. S^z = Z/2; S^+- coincide with sigma^+-.
• Bosons. The occupation cutoff is set by a RealisationRequest, with default n_max = 2.

Every operator is realised as a dense array.

sites: tuple[int, ...]

dimensions: tuple[int, ...]

dimension: int

strides: tuple[int, ...]

fermionic_sites: tuple[int, ...]

of(
    structure: StructureType,
    request: RealisationRequest | None = None,
) -> HilbertSpace

space_at(site: int) -> LocalSpace

position_of(site: int) -> int

configuration(index: int) -> tuple[int, ...]

index_of(configuration: Sequence[int]) -> int

basis_state(configuration: Sequence[int]) -> Array

configurations() -> tuple[tuple[int, ...], ...]

label(index: int) -> str

identity() -> Array

embed(site: int, matrix: Array) -> Array

kron_of(factors: Mapping[int, Array]) -> Array

jordan_wigner_string(site: int) -> tuple[int, ...]

local_matrix(
    symbol: OpSymbol, algebra: Algebra, dimension: int
) -> Array

Construction of dense JAX operators from symbolic models and Pauli sums.

Jordan-Wigner convention: a fermionic ladder operator at Jordan-Wigner position p is realised as

psi_l = (-1)**p * (prod_{q < p} P_q) * sigma^-_l, P = diag(+1, -1) = 1 - 2n,

that is, the Jordan-Wigner transformation with alternating signs, under which psi_l psi_{l+1} -> + sigma^-_{2l} sigma^-_{2l+2}. The parity string runs over the fermionic sites with a strictly smaller Jordan-Wigner position. The anticommutation relations are carried entirely by the explicit parity strings, and each term is assembled as a single tensor product.

build_operator(
    hamiltonian: OperatorSum,
    space: HilbertSpace,
    environment: Mapping[str, float],
) -> Array

build_pauli_string(
    string: PauliString, qubits: int
) -> Array

build_pauli_sum(pauli: PauliSum, qubits: int) -> Array

local_subspace_projector(
    subspace: LocalSubspace, space: HilbertSpace
) -> Array

sector_projector(
    constraints: Sequence[ConstraintOperator],
    space: HilbertSpace,
    environment: Mapping[str, float],
    tolerance: float = 1e-10,
) -> Array

sandwich(operator: Array, projector: Array) -> Array

subspace_indices(
    projector: Array, tolerance: float = 0.5
) -> Array

restrict(operator: Array, indices: Array) -> Array

Numerical realisation inside a declared sector, without constructing the full space.

SectorBasis enumerates the configurations admitted by a LocalSubspace and a family of diagonal ConstraintOperators by a pruned depth-first search, and build_operator_in assembles P H P in that basis by lookup. Terms that leave the sector are dropped. The realisation is therefore exact for a model that is confined to the sector and lossy for a model whose leakage out of the sector is the observable; the latter is realised densely. Fermionic degrees of freedom are rejected: a Jordan-Wigner string is a property of the ordering and not a per-configuration amplitude.

dimension: int

of(
    structure: StructureType,
    subspace: LocalSubspace | None = None,
    constraints: Sequence[ConstraintOperator] = (),
    request: RealisationRequest | None = None,
    environment: Mapping[str, float] | None = None,
) -> SectorBasis

state(configuration: Sequence[int]) -> Array

build_operator_in(
    hamiltonian: OperatorSum,
    basis: SectorBasis,
    environment: Mapping[str, float],
) -> Array

Exact diagonalisation, time evolution and error measures.

Time evolution is computed exactly: the propagator U(t) = V diag(exp(-i E t)) V^dagger is obtained from one Hermitian eigendecomposition and carries no time-discretisation error. Two error measures are provided: spectral_norm, the operator 2-norm in which the Trotter error bounds are stated, and max_abs_deviation, the largest absolute entry, which is not a submultiplicative norm.

hermiticity_defect(operator: Array) -> float

eigensystem(operator: Array) -> tuple[Array, Array]

low_lying_spectrum(
    operator: Array, count: int = 8
) -> Array

manifold_levels(
    operator: Array, manifold: Sequence[int]
) -> tuple[Array, float]

spacing_deviation(
    left: ArrayLike, right: ArrayLike, scale: float = 1.0
) -> float

propagator(operator: Array, time: float) -> Array

evolve_state(
    operator: Array,
    state: Array,
    times: Sequence[float] | ArrayLike,
) -> Array

expectation(operator: Array, states: Array) -> Array

gauss_violation(
    constraint_operators: Sequence[Array], states: Array
) -> Array

spectral_norm(operator: Array) -> float

max_abs_deviation(left: Array, right: Array) -> float

commutator_spectral_norm(
    left: Array, right: Array
) -> float

Process-global JAX configuration.

Importing this module enables the 64-bit mode of JAX. The setting is process-global and also affects the JAX code of the importing program. Every operator is built in complex128; real spectra, times and observables use float64.

enable_x64() -> None

x64_enabled() -> bool

require_x64() -> None