Skip to content

Model library

Indexed by abstraction level. Every builder takes a chain length and a parameter Namespace.

models

The model library of the framework, indexed by abstraction level.

Module Level Contents
application 1 the application layer: physical system models
intermediate 2 the intermediate representations
hardware 3 the hardware layer: simulator models with knob sets

Every builder takes the chain length and a Namespace for its parameters. gauge and magnetism hold the ingredients shared within each family of models; names fixes the local parameter names.

levels

Abstraction levels: the axis along which the model library is indexed.

Four levels are ordered by value: the application layer (1), the intermediate representations (2), the hardware layer (3) and the executable layer (4). The executable layer is named but out of scope. A level is not a type; structural typing is defined in qsimod.structure.

AbstractionLevel

Bases: Enum

The layer of the model graph at which an artifact is located.

The values are the level numbers, so that levels are ordered.

APPLICATION class-attribute instance-attribute
APPLICATION = 1

The application layer: a physical theory stated in its own terms, independent of any hardware model.

INTERMEDIATE class-attribute instance-attribute
INTERMEDIATE = 2

An intermediate representation, shaped by the theory and by the hardware, usually still a Hamiltonian.

HARDWARE class-attribute instance-attribute
HARDWARE = 3

The hardware layer: the model a simulator realises natively, either an analogue Hamiltonian over the hardware knobs or a digital ordered product of k-local unitaries on a qubit register.

EXECUTABLE class-attribute instance-attribute
EXECUTABLE = 4

The executable layer: a routed and scheduled gate set, or a pulse schedule. This layer is out of scope.

in_scope property
in_scope: bool

Whether the package models the level.

label property
label: str

A short lower-case name for reports and table columns.

names

Canonical local parameter names of the model library.

A builder names its parameters inside a Namespace; the fully qualified name is <namespace>.<local>, and the local halves are fixed in this module.

MASS module-attribute

MASS = 'm'

The fermion rest mass m.

COUPLING module-attribute

COUPLING = 'kappa'

The gauge-invariant matter-gauge coupling kappa, written t~ by Yang et al. (2020).

LATTICE_SPACING module-attribute

LATTICE_SPACING = 'a'

The lattice spacing a; dimensionless, since a -> 1 below the quantum-link truncation.

GAUGE_COUPLING module-attribute

GAUGE_COUPLING = 'e'

The gauge coupling e; dimensionless, since e -> 1 below the quantum-link truncation.

ELECTRIC_GAP module-attribute

ELECTRIC_GAP = 'electric_gap'

The energy cost of one additional unit of electric flux on a link, a e**2 / 2.

TUNNELLING module-attribute

TUNNELLING = 'J'

The nearest-neighbour tunnelling amplitude J.

INTERACTION module-attribute

INTERACTION = 'U'

The on-site interaction U.

SUPERLATTICE module-attribute

SUPERLATTICE = 'delta'

The staggered superlattice depth delta.

TILT module-attribute

TILT = 'Delta'

The linear potential tilt Delta.

HOPPING module-attribute

HOPPING = 't'

The nearest-neighbour tunnelling t of a model whose spin couplings are written J.

INTERACTION_UP module-attribute

INTERACTION_UP = 'U_uu'

The on-site interaction between two atoms of the first (spin-up) component.

INTERACTION_DOWN module-attribute

INTERACTION_DOWN = 'U_dd'

The on-site interaction between two atoms of the second (spin-down) component.

INTERACTION_MIXED module-attribute

INTERACTION_MIXED = 'U_ud'

The on-site interaction between one atom of each component.

TRANSVERSE_COUPLING module-attribute

TRANSVERSE_COUPLING = 'Jxy'

The nearest-neighbour XX + YY (spin-exchange) coupling Jxy.

LONGITUDINAL_COUPLING module-attribute

LONGITUDINAL_COUPLING = 'Jz'

The nearest-neighbour ZZ coupling Jz.

ANISOTROPY module-attribute

ANISOTROPY = 'Delta'

The XXZ anisotropy Delta = Jz / Jxy, dimensionless.

The glyph coincides with that of TILT; the two names never share a namespace.

FIELD module-attribute

FIELD = 'h'

The transverse or longitudinal field strength h.

TRANSVERSE_FIELD module-attribute

TRANSVERSE_FIELD = 'hx'

The transverse field hx of an Ising chain in units of its coupling; dimensionless.

LONGITUDINAL_FIELD module-attribute

LONGITUDINAL_FIELD = 'hz'

The longitudinal field hz of an Ising chain in units of its coupling; dimensionless.

TRANSVERSE_AMPLITUDE module-attribute

TRANSVERSE_AMPLITUDE = 'Gamma'

The transverse field of an Ising chain as an energy, Gamma = Jz * hx.

LONGITUDINAL_BIAS module-attribute

LONGITUDINAL_BIAS = 'B'

The longitudinal field of an Ising chain as an energy, B = Jz * hz.

gauge

Shared ingredients of the lattice-gauge models: generators, sectors, subspaces, observables.

Every function assumes the interleaved layout of qsimod.structure: the matter site l occupies register index 2l and the gauge link (l, l+1) occupies register index 2l + 1.

Conventions: the link operator U ~ S^+ raises the electric field, which fixes the relative sign of the two E in the Gauss generator G_l; the charge enters G_l with the coefficient e, and the factor one half belongs to the constant alone; on an open chain the boundary generators omit one link, take values in {-1/2, +1/2, +3/2}, and the declared background is +1/2, the sector of the canonical state |1 0 1 0 1 ...>.

ElectricField

Bases: Enum

The operator by which an abstraction level writes the electric field on a link.

OPERATOR class-attribute instance-attribute
OPERATOR = 'E'

The untruncated compact U(1) field operator E, with unbounded spectrum.

SPIN class-attribute instance-attribute
SPIN = 'S^z'

The operator S^z on a spin-1/2 link, with eigenvalues +-1/2.

QUBIT class-attribute instance-attribute
QUBIT = 'sigma^z / 2'

The operator sigma^z / 2 on a qubit, with eigenvalues +-1/2.

BOSON class-attribute instance-attribute
BOSON = '(n - 1)/2'

The operator (n - 1)/2 on a bosonic link whose occupations are {0, 2}.

GaussForm

Bases: Enum

The generator form taken by the Gauss operators of an abstraction level.

STAGGERED class-attribute instance-attribute
STAGGERED = 'staggered'

The form G_l = E_{l,l+1} - E_{l-1,l} - e [ n_l - (1 - (-1)**l)/2 ] before a particle-hole transformation. The target eigenvalue is zero in the bulk and (-1)**(l+1) times the background at the ends, which is the image of the homogeneous sector under the particle-hole map V G_l^st V^dag = (-1)**(l+1) G_l.

HOMOGENEOUS class-attribute instance-attribute
HOMOGENEOUS = 'homogeneous'

The form G_l = S^z_{l-1,l} + S^z_{l,l+1} + n_l after a particle-hole transformation. The target eigenvalue is zero in the bulk and the background at the ends.

matter_gauge_structure

matter_gauge_structure(
    matter_sites: int,
    matter_algebra: Algebra,
    gauge_algebra: Algebra,
    *,
    name: str,
    gauge_symmetry: bool = True,
) -> StructureType

The interleaved matter-gauge structural type of an open chain.

Parameters:

Name Type Description Default
matter_sites int

the chain length N; the register has 2N - 1 positions.

required
matter_algebra Algebra

the algebra on the even positions.

required
gauge_algebra Algebra

the algebra on the odd positions.

required
name str

the name of the structural type, used in reports.

required
gauge_symmetry bool

whether the local U(1) symmetry is declared.

True

Returns:

Type Description
StructureType

The structural type.

matter_gauge_pattern

matter_gauge_pattern(
    description: str,
    *,
    matter_algebras: Iterable[Algebra],
    gauge_algebras: Iterable[Algebra],
    require_gauge_symmetry: bool = True,
    minimum_sites: int = 2,
) -> StructurePattern

A structural pattern over the interleaved matter-gauge chain.

Parameters:

Name Type Description Default
description str

the summary used in diagnostics.

required
matter_algebras Iterable[Algebra]

the algebras accepted on the matter positions.

required
gauge_algebras Iterable[Algebra]

the algebras accepted on the gauge positions.

required
require_gauge_symmetry bool

whether the local U(1) symmetry must be declared.

True
minimum_sites int

the least number of matter sites accepted.

2

Returns:

Type Description
StructurePattern

The pattern.

link_triples(
    matter_sites: int,
) -> Iterator[tuple[int, int, int, int]]

Each link of an open chain as the indices (link, left matter, link, right matter).

gauss_operators

gauss_operators(
    matter_sites: int,
    *,
    field: ElectricField,
    form: GaussForm = GaussForm.HOMOGENEOUS,
    boundary_value: float = BOUNDARY_GAUSS_VALUE,
    charge: ScalarLike = 1,
) -> tuple[ConstraintOperator, ...]

The Gauss operators of an abstraction level, with their declared target eigenvalues.

On an open chain the two boundary generators omit one link and take half-integer values; their targets are the background boundary_value in the homogeneous form and its particle-hole image (-1)**(l+1) * boundary_value in the staggered form.

Parameters:

Name Type Description Default
matter_sites int

the chain length N.

required
field ElectricField

the operator by which the level writes the electric field.

required
form GaussForm

the generator form taken by the Gauss operators of the level.

HOMOGENEOUS
boundary_value float

the background eigenvalue at the chain ends, in the homogeneous form.

BOUNDARY_GAUSS_VALUE
charge ScalarLike

the coefficient of the charge term in the staggered form: the gauge coupling e in the application layer, 1 below the quantum-link truncation.

1

Returns:

Type Description
tuple[ConstraintOperator, ...]

One ConstraintOperator per matter site.

gauss_sector

gauss_sector(
    operators: Sequence[ConstraintOperator],
) -> Sector

The superselection sector declared by the target values of a Gauss family.

Raises:

Type Description
ValueError

if the sequence of operators is empty.

local_occupation_subspace

local_occupation_subspace(
    matter_sites: int,
    *,
    matter_occupations: tuple[int, ...] = (0, 1),
    gauge_occupations: tuple[int, ...] = (0, 2),
    name: str = "local occupation subspace P",
) -> LocalSubspace

A declared per-site occupation subspace on the interleaved chain.

The default is the doublon encoding, {0, 1} on matter positions and {0, 2} on gauge positions, for which a numerical realisation requires an occupation cutoff of at least two.

Parameters:

Name Type Description Default
matter_sites int

the chain length N.

required
matter_occupations tuple[int, ...]

the occupations allowed on matter positions.

(0, 1)
gauge_occupations tuple[int, ...]

the occupations allowed on gauge positions.

(0, 2)
name str

the name of the subspace, used in reports.

'local occupation subspace P'

Returns:

Type Description
LocalSubspace

The subspace.

canonical_state_configuration

canonical_state_configuration(
    matter_sites: int,
) -> tuple[int, ...]

The occupation pattern |1 0 1 0 1 ...>: matter sites occupied, gauge links empty.

matter_occupation_observable

matter_occupation_observable(
    matter_sites: int,
) -> OperatorSum

The mean matter occupation <n_matter> = (1/N) sum_l n_{2l}.

occupation_projector

occupation_projector(
    site: int,
    occupations: Iterable[int],
    cutoff: int,
    coefficient: float = 1.0,
) -> OperatorSum

The projector onto a set of occupations at one site, as a polynomial in n.

The polynomial P_k = prod_{j != k} (n - j) / (k - j) interpolates over the ladder {0, ..., cutoff}, and P_A = sum_{k in A} P_k. For A = {1} at cutoff = 2 the projector is 2n - n**2, the parity n mod 2.

Parameters:

Name Type Description Default
site int

the register position.

required
occupations Iterable[int]

the occupations projected onto.

required
cutoff int

the largest occupation carried by the ladder, n_max.

required
coefficient float

an overall prefactor.

1.0

Returns:

Type Description
OperatorSum

The projector, as a sum of powers of n at the site.

Raises:

Type Description
ValueError

if an occupation lies outside the ladder.

gauge_violation_observable

gauge_violation_observable(
    matter_sites: int,
    subspace: LocalSubspace | None = None,
    name: str = "<eta>",
) -> OperatorSum

The mean weight on forbidden gauge-link occupations, (1/L_g) sum_{j in g} (1 - P_j).

This observable is the gauge violation eta of the article. Under the doublon encoding a forbidden link occupation is an odd one, so the observable is the mean link parity n mod 2.

Parameters:

Name Type Description Default
matter_sites int

the chain length N.

required
subspace LocalSubspace | None

the declared subspace; defaults to local_occupation_subspace.

None
name str

the display name of the observable.

'<eta>'

Returns:

Type Description
OperatorSum

The observable.

magnetism

Shared ingredients of the quantum-magnetism models: layouts, patterns, terms, observables.

Two plain-chain layouts occur: a spin chain of N sites at register positions 0 .. N-1, a Lattice with link_count=0, and a two-component chain of N sites with two bosonic modes each, at positions 2j and 2j+1. Both carry the global U(1) symmetry of the total magnetisation sum_j S^z_j.

SPIN_ROLE module-attribute

SPIN_ROLE = 'spins'

The role of the single degree-of-freedom family of a plain chain.

UP_ROLE module-attribute

UP_ROLE = 'up'

The role of the first component of a two-component chain.

DOWN_ROLE module-attribute

DOWN_ROLE = 'down'

The role of the second component of a two-component chain.

MOTT_FAMILY module-attribute

MOTT_FAMILY = 'M'

The family name of the per-site occupation operators of a two-component chain.

PARTICLE_FAMILY module-attribute

PARTICLE_FAMILY = 'N'

The family name of the total particle-number operator of a two-component chain.

MAGNETISATION_SYMMETRY module-attribute

MAGNETISATION_SYMMETRY = SymmetryDeclaration(
    name="magnetisation", group="U(1)", local=False
)

The conservation of the total magnetisation sum_j S^z_j, which reads (N_up - N_down) / 2 on a two-component chain.

spin_chain_structure

spin_chain_structure(
    sites: int,
    algebra: Algebra,
    *,
    name: str,
    role: str = SPIN_ROLE,
    symmetries: Iterable[SymmetryDeclaration] = (
        MAGNETISATION_SYMMETRY,
    ),
) -> StructureType

A plain open chain of sites degrees of freedom of a single algebra.

Parameters:

Name Type Description Default
sites int

the chain length N; the register positions are 0 .. N-1.

required
algebra Algebra

the algebra at every position.

required
name str

the name of the structural type, used in reports.

required
role str

the role name of the family.

SPIN_ROLE
symmetries Iterable[SymmetryDeclaration]

the symmetries declared; defaults to the magnetisation symmetry. An Ising chain in a transverse field passes an empty tuple.

(MAGNETISATION_SYMMETRY,)

Returns:

Type Description
StructureType

The structural type.

spin_chain_pattern

spin_chain_pattern(
    description: str,
    algebras: Iterable[Algebra],
    *,
    role: str = SPIN_ROLE,
    require_magnetisation: bool = True,
    forbid_magnetisation: bool = False,
) -> StructurePattern

The structural type a transformation requires of a plain chain of a single algebra.

Parameters:

Name Type Description Default
description str

the summary used in diagnostics.

required
algebras Iterable[Algebra]

the algebras accepted at the positions of the chain.

required
role str

the role that must be present.

SPIN_ROLE
require_magnetisation bool

whether the magnetisation symmetry must be declared.

True
forbid_magnetisation bool

whether the magnetisation symmetry must be absent. If both are false, either is accepted.

False

Returns:

Type Description
StructurePattern

The pattern.

Raises:

Type Description
ValueError

if the symmetry is both required and forbidden.

up_index

up_index(site: int) -> int

The register index of the first component at chain site j, 2*j.

down_index

down_index(site: int) -> int

The register index of the second component at chain site j, 2*j + 1.

two_component_site_count

two_component_site_count(sites: int) -> int

The register size of a two-component chain of N sites, 2N.

two_component_structure

two_component_structure(
    sites: int, *, name: str
) -> StructureType

A chain of sites positions, each carrying two bosonic modes.

The first component occupies position 2j and the second position 2j+1; the positions of the second component are declared through the link_count of the lattice.

Parameters:

Name Type Description Default
sites int

the chain length N.

required
name str

the name of the structural type, used in reports.

required

Returns:

Type Description
StructureType

The structural type, carrying

StructureType

two_component_pattern

two_component_pattern(description: str) -> StructurePattern

The structural type a transformation into a two-component bosonic chain requires.

coordination_numbers

coordination_numbers(sites: int) -> tuple[int, ...]

The nearest-neighbour bond count of each site of an open chain, (1, 2, ..., 2, 1).

xxz_chain_terms

xxz_chain_terms(
    sites: int, transverse: Scalar, longitudinal: Scalar
) -> OperatorSum

The nearest-neighbour XXZ terms of an open spin-1/2 chain.

sum_{j=0}^{N-2} [ (Jxy/2)( S^+_j S^-_{j+1} + h.c. ) + Jz S^z_j S^z_{j+1} ]

Parameters:

Name Type Description Default
sites int

the chain length N.

required
transverse Scalar

the spin-exchange coupling Jxy.

required
longitudinal Scalar

the ZZ coupling Jz.

required

Returns:

Type Description
OperatorSum

The symbolic operator sum.

weighted_magnetisation_term

weighted_magnetisation_term(
    sites: int, strength: ScalarLike
) -> OperatorSum

The term strength * sum_j z_j S^z_j, with z_j the coordination number of site j.

Since sum_j z_j S^z_j = 2 sum_j S^z_j - S^z_0 - S^z_{N-1}, the term is a constant within a magnetisation sector plus a field on the two end spins.

Parameters:

Name Type Description Default
sites int

the chain length N.

required
strength ScalarLike

the field strength per unit coordination.

required

Returns:

Type Description
OperatorSum

The symbolic operator sum.

ising_chain_terms

ising_chain_terms(
    sites: int,
    coupling: Scalar,
    transverse: Scalar,
    longitudinal: Scalar,
) -> OperatorSum

The nearest-neighbour Ising terms of an open spin-1/2 chain.

Jz sum_{j=0}^{N-2} S^z_j S^z_{j+1}  -  Gamma sum_j S^x_j  -  B sum_j S^z_j

with S^x = (S^+ + S^-)/2; the chain is antiferromagnetic for Jz > 0.

Parameters:

Name Type Description Default
sites int

the chain length N.

required
coupling Scalar

the ZZ coupling Jz.

required
transverse Scalar

the transverse field as an energy, Gamma.

required
longitudinal Scalar

the longitudinal field as an energy, B.

required

Returns:

Type Description
OperatorSum

The symbolic operator sum.

end_magnetisation_term

end_magnetisation_term(
    sites: int, strength: ScalarLike
) -> OperatorSum

The term strength * (S^z_0 + S^z_{N-1}), a field on the two end spins only.

Parameters:

Name Type Description Default
sites int

the chain length N.

required
strength ScalarLike

the field on each end spin.

required

Returns:

Type Description
OperatorSum

The symbolic operator sum.

magnetisation_observable

magnetisation_observable(sites: int) -> OperatorSum

The total magnetisation sum_j S^z_j of a spin chain.

mott_manifold_operators

mott_manifold_operators(
    sites: int,
) -> tuple[ConstraintOperator, ...]

The per-site occupation operators M_j = n_{j,up} + n_{j,down}, targeted at one.

The operators select the one-atom-per-site manifold in which the superexchange derivation expands. The Hamiltonian does not commute with them, since a tunnelling event changes two of them at once, so they do not define a superselection sector; sector_projector nevertheless projects onto the manifold.

Parameters:

Name Type Description Default
sites int

the chain length N.

required

Returns:

Type Description
tuple[ConstraintOperator, ...]

One operator per chain site, each with target eigenvalue one.

unit_filling_operators

unit_filling_operators(
    sites: int,
) -> tuple[ConstraintOperator, ...]

The total particle number N = sum_j (n_{j,up} + n_{j,down}), targeted at sites.

The total particle number is a conserved quantity, so the hardware Hamiltonian is built exactly inside this sector with SectorBasis.

Parameters:

Name Type Description Default
sites int

the chain length N, which equals the target particle number at unit filling.

required

Returns:

Type Description
tuple[ConstraintOperator, ...]

A family with a single member.

unit_filling_sector

unit_filling_sector(sites: int) -> Sector

The superselection sector of unit filling, N_total = N.

application

Models of the application layer: physical system models, stated in their own terms.

Level 1 of AbstractionLevel. A physical system model may have no finite-dimensional representation; for instance, a compact U(1) link carries an unbounded electric field. Its structural type declares this property, and a numerical realisation is refused until a truncation has been applied.

kogut_susskind_gauge_theory

kogut_susskind_gauge_theory(
    matter_sites: int,
    namespace: Namespace,
    *,
    name: str = "H_QED",
    hamiltonian_name: str = "H_QED",
) -> HamiltonianModel

The Kogut-Susskind lattice Schwinger model with staggered fermions in 1+1 dimensions.

One-dimensional lattice QED, the application model H_sys of the case study:

H = (a/2) sum_l E^2_{l,l+1}
  + m sum_l (-1)**l psi^dag_l psi_l
  - (i/2a) sum_l ( psi^dag_l U_{l,l+1} psi_{l+1} - h.c. )

The parameters are the mass m, the lattice spacing a and the gauge coupling e, plus electric_gap = a e**2 / 2, the energy of one unit of electric flux, which enters no term and is read by the validity condition of the quantum-link truncation.

Parameters:

Name Type Description Default
matter_sites int

the chain length N; the register has 2N - 1 positions.

required
namespace Namespace

the parameter namespace owned by this model.

required
name str

the name of the model, used as the name of its artifact in a model graph.

'H_QED'
hamiltonian_name str

the name under which the Hamiltonian prints.

'H_QED'

Returns:

Type Description
HamiltonianModel

The model, in the application layer.

heisenberg_magnet

heisenberg_magnet(
    sites: int,
    namespace: Namespace,
    *,
    name: str = "H_XXZ",
    hamiltonian_name: str = "",
) -> HamiltonianModel

The anisotropic Heisenberg (XXZ) chain, stated by an energy and a dimensionless anisotropy.

H = sum_j [ Jxy ( S^x_j S^x_{j+1} + S^y_j S^y_{j+1} ) + Delta Jxy S^z_j S^z_{j+1} ]

The anisotropy Delta = Jz / Jxy is dimensionless: 0 is the XX point, 1 the isotropic magnet.

Parameters:

Name Type Description Default
sites int

the chain length N; the register has N positions.

required
namespace Namespace

the parameter namespace owned by this model; it names Jxy and Delta.

required
name str

the name of the model, used as the name of its artifact in a model graph.

'H_XXZ'
hamiltonian_name str

the name under which the Hamiltonian prints; defaults to name.

''

Returns:

Type Description
HamiltonianModel

The model, in the application layer.

ising_magnet

ising_magnet(
    sites: int,
    namespace: Namespace,
    *,
    name: str = "H_Ising",
    hamiltonian_name: str = "",
) -> HamiltonianModel

The antiferromagnetic Ising chain in longitudinal and transverse fields.

H = Jz sum_j ( S^z_j S^z_{j+1} - hz S^z_j - hx S^x_j )

One energy Jz and two dimensionless fields (hz, hx), as in Simon et al. (2011). The transverse field breaks the magnetisation symmetry, so the structural type declares none.

Parameters:

Name Type Description Default
sites int

the chain length N.

required
namespace Namespace

the parameter namespace owned by this model; it names Jz, hz and hx.

required
name str

the name of the model, used as the name of its artifact in a model graph.

'H_Ising'
hamiltonian_name str

the name under which the Hamiltonian prints; defaults to name.

''

Returns:

Type Description
HamiltonianModel

The model, in the application layer.

intermediate

Models of the intermediate representations: theory- and hardware-influenced Hamiltonians.

Level 2 of AbstractionLevel. A quantum-link model (QLM) exists in four self-consistent conventions, given by the coupling form, the mass pattern and the link operator; quantum_link_model takes the convention as an argument, and QuantumLinkConvention rejects a mixed convention, whose Hamiltonian would not commute with its own Gauss operators.

STAGGERED_CONVENTION module-attribute

STAGGERED_CONVENTION = QuantumLinkConvention(
    CouplingForm.HOPPING, MassPattern.STAGGERED
)

The convention before a particle-hole transformation: hopping coupling and staggered mass.

This is the convention of the quantum-link model H_IR1 of the article, the artifact quantum_link_staggered of the case study.

HOMOGENEOUS_CONVENTION module-attribute

HOMOGENEOUS_CONVENTION = QuantumLinkConvention(
    CouplingForm.PAIR, MassPattern.UNIFORM
)

The convention after a particle-hole transformation: pair coupling and uniform mass.

This is the convention of the quantum-link model H_IR2 of the article, the artifact quantum_link_homogeneous of the case study and its branch point.

CouplingForm

Bases: Enum

The matter-gauge coupling carried by a quantum-link model.

PAIR class-attribute instance-attribute
PAIR = 'pair'

The pair coupling psi_l S^+ psi_{l+1} of two annihilation operators; the total matter charge is not conserved.

HOPPING class-attribute instance-attribute
HOPPING = 'hopping'

The hopping coupling psi^dag_l S^+ psi_{l+1} of one creation and one annihilation operator; the charge is conserved.

MassPattern

Bases: Enum

Whether the mass term alternates in sign along the chain.

LinkPattern

Bases: Enum

Whether the link operator alternates along the chain.

UNIFORM class-attribute instance-attribute
UNIFORM = 'uniform'

The operator S^+ on every link.

ALTERNATING class-attribute instance-attribute
ALTERNATING = 'alternating'

The operators S^+ and S^- on alternate links. The pattern is spectrally invisible; it changes which G_l is conserved.

QuantumLinkConvention dataclass

One of the four self-consistent quantum-link conventions.

The mass pattern is determined by the coupling form: a pair coupling is combined with a uniform mass and a hopping coupling with a staggered mass, since the particle-hole transformation changes both at once. The link pattern is unconstrained.

Attributes:

Name Type Description
coupling CouplingForm

the coupling form.

mass MassPattern

the mass pattern.

link LinkPattern

the link operator pattern.

gauss_form property
gauss_form: GaussForm

The generator form conserved by this convention.

quantum_link_model(
    matter_sites: int,
    namespace: Namespace,
    convention: QuantumLinkConvention = HOMOGENEOUS_CONVENTION,
    *,
    name: str = "H_QLM",
    hamiltonian_name: str = "",
    additive_constant: Scalar | float | None = None,
) -> HamiltonianModel

A spin-1/2 U(1) quantum-link model, in any of the four conventions.

H = sum_l [ (kappa/2)( <coupling> + h.c. ) + m <mass sign>_l psi^dag_l psi_l ] + constant

The staggered convention is H_IR1 of the case study and the homogeneous convention H_IR2, its branch point.

Parameters:

Name Type Description Default
matter_sites int

the chain length N.

required
namespace Namespace

the parameter namespace owned by this model; it names m and kappa.

required
convention QuantumLinkConvention

the convention of the model; defaults to the homogeneous one.

HOMOGENEOUS_CONVENTION
name str

the name of the model.

'H_QLM'
hamiltonian_name str

the name under which the Hamiltonian prints; defaults to name.

''
additive_constant Scalar | float | None

a constant retained as an explicit identity term, for instance the -m * floor(N/2) left behind by a particle-hole transformation.

None

Returns:

Type Description
HamiltonianModel

The model, as an intermediate representation.

bosonic_pair_coupling_model

bosonic_pair_coupling_model(
    matter_sites: int,
    namespace: Namespace,
    *,
    name: str = "H_eff",
    hamiltonian_name: str = "",
    additive_constant: Scalar | float | None = None,
) -> HamiltonianModel

The boson encoding of a pair-coupling quantum-link model.

H = sum_{j even, 0 <= j <= 2N-4} [ (kappa / 2 sqrt(2)) b_j b_{j+2} (b^dag_{j+1})^2 + h.c. ]
  + sum_{j even, 0 <= j <= 2N-2}   m n_j
  + constant

H_IR3 of the case study. The encoding is exact on the declared occupation subspace, {0, 1} on matter positions and {0, 2} on links, as the projected operator P H P (sandwich).

Parameters:

Name Type Description Default
matter_sites int

the chain length N.

required
namespace Namespace

the parameter namespace; it names m and kappa.

required
name str

the name of the model.

'H_eff'
hamiltonian_name str

the name under which the Hamiltonian prints; defaults to name.

''
additive_constant Scalar | float | None

a constant retained as an explicit identity term.

None

Returns:

Type Description
HamiltonianModel

The model, as an intermediate representation.

k_local_qubit_model

k_local_qubit_model(
    matter_sites: int,
    namespace: Namespace,
    convention: QuantumLinkConvention = HOMOGENEOUS_CONVENTION,
    *,
    name: str = "H_qubit",
    hamiltonian_name: str = "",
    additive_constant: Scalar | float | None = None,
) -> HamiltonianModel

The qubit-register form of a quantum-link model, a 3-local Pauli Hamiltonian.

H = sum_l (kappa/2) ( sigma^-_{2l} sigma^+_{2l+1} sigma^-_{2l+2} + h.c. )
  + sum_l m n_{2l} + constant                          (pair convention)

H_IR4 of the case study, the Jordan-Wigner image of H_IR2. Each coupling term expands into four mutually commuting Pauli strings; in the hopping convention the Jordan-Wigner string contributes a factor -1 to the coupling.

Parameters:

Name Type Description Default
matter_sites int

the chain length N.

required
namespace Namespace

the parameter namespace; it names m and kappa.

required
convention QuantumLinkConvention

the convention of which this model is the image.

HOMOGENEOUS_CONVENTION
name str

the name of the model.

'H_qubit'
hamiltonian_name str

the name under which the Hamiltonian prints; defaults to name.

''
additive_constant Scalar | float | None

a constant retained as an explicit identity term.

None

Returns:

Type Description
HamiltonianModel

The model, as an intermediate representation.

xxz_spin_chain

xxz_spin_chain(
    sites: int,
    namespace: Namespace,
    *,
    name: str = "H_XXZ",
    hamiltonian_name: str = "",
) -> HamiltonianModel

The XXZ chain, stated by two coupling energies.

H = sum_{j=0}^{N-2} [ (Jxy/2)( S^+_j S^-_{j+1} + h.c. ) + Jz S^z_j S^z_{j+1} ]

Parameters:

Name Type Description Default
sites int

the chain length N.

required
namespace Namespace

the parameter namespace owned by this model; it names Jxy and Jz.

required
name str

the name of the model.

'H_XXZ'
hamiltonian_name str

the name under which the Hamiltonian prints; defaults to name.

''

Returns:

Type Description
HamiltonianModel

The model, as an intermediate representation.

interacting_fermion_chain

interacting_fermion_chain(
    sites: int,
    namespace: Namespace,
    *,
    name: str = "H_tV",
    hamiltonian_name: str = "",
) -> HamiltonianModel

The Jordan-Wigner image of an XXZ chain: spinless fermions with a nearest-neighbour V.

H = - (Jxy/2) sum_j ( c^dag_j c_{j+1} + h.c. )
  + Jz sum_j n_j n_{j+1}
  - (Jz/2) sum_j z_j n_j
  + (N-1) Jz/4

z_j is the coordination number of site j; the last two terms expand Jz sum_j (n_j - 1/2)(n_{j+1} - 1/2). The hopping sign is the alternating-sign Jordan-Wigner gauge of qsimod.realise.build, under which this model and the spin chain realise to the same matrix.

Parameters:

Name Type Description Default
sites int

the chain length N.

required
namespace Namespace

the parameter namespace; it names Jxy and Jz.

required
name str

the name of the model.

'H_tV'
hamiltonian_name str

the name under which the Hamiltonian prints; defaults to name.

''

Returns:

Type Description
HamiltonianModel

The model, as an intermediate representation.

ising_spin_chain

ising_spin_chain(
    sites: int,
    namespace: Namespace,
    *,
    name: str = "H_Ising",
    hamiltonian_name: str = "",
) -> HamiltonianModel

The Ising chain, stated by three energies.

H = Jz sum_{j=0}^{N-2} S^z_j S^z_{j+1} - Gamma sum_j S^x_j - B sum_j S^z_j

Parameters:

Name Type Description Default
sites int

the chain length N.

required
namespace Namespace

the parameter namespace; it names Jz, Gamma and B.

required
name str

the name of the model.

'H_Ising'
hamiltonian_name str

the name under which the Hamiltonian prints; defaults to name.

''

Returns:

Type Description
HamiltonianModel

The model, as an intermediate representation.

hardware

Models of the hardware layer: what a simulator natively realises, with its admissible knob set.

Level 3 of AbstractionLevel. The parameters are the hardware knobs set in the experiment, and each model declares an AdmissibleSet of box bounds and coupled constraints. The models of this module are analogue simulator models; the digital simulator model is ProductFormulaModel.

on_site_interaction

on_site_interaction(
    position: int, strength: Scalar
) -> OperatorSum

The on-site interaction (U/2) n (n - 1) at one register position, as two terms.

bose_hubbard_admissible_set

bose_hubbard_admissible_set(
    namespace: Namespace,
    *,
    tunnelling_max: float = DEFAULT_TUNNELLING_MAX,
    interaction_range: tuple[
        float, float
    ] = DEFAULT_INTERACTION_RANGE,
    superlattice_max: float = DEFAULT_SUPERLATTICE_MAX,
    tilt_max: float = DEFAULT_TILT_MAX,
    tilt_fraction: float = 0.5,
) -> AdmissibleSet

The admissible knob set of an optical-superlattice simulator.

J = 0 and Delta = 0 are excluded strictly. Two coupled constraints of origin DERIVATION bound the tilt by tilt_fraction of the superlattice depth and of the resonance gap U - delta; a second theory on the same lattice drops them with apparatus_only.

Parameters:

Name Type Description Default
namespace Namespace

the namespace whose knobs are constrained.

required
tunnelling_max float

the largest reachable J.

DEFAULT_TUNNELLING_MAX
interaction_range tuple[float, float]

the reachable range of U.

DEFAULT_INTERACTION_RANGE
superlattice_max float

the largest reachable delta.

DEFAULT_SUPERLATTICE_MAX
tilt_max float

the largest reachable Delta.

DEFAULT_TILT_MAX
tilt_fraction float

the largest fraction of delta and of U - delta the tilt may take.

0.5

Returns:

Type Description
AdmissibleSet

The admissible set.

tilted_bose_hubbard_chain

tilted_bose_hubbard_chain(
    matter_sites: int,
    namespace: Namespace,
    *,
    admissible_set: AdmissibleSet | None = None,
    name: str = "H_BHM",
    hamiltonian_name: str = "",
    tunnelling_sign: int = -1,
    staggered: bool = True,
    tilted: bool = True,
) -> HamiltonianModel

A tilted, staggered Bose-Hubbard chain on an optical superlattice.

The analogue simulator model H_sim of the case study:

H = sign * J sum_{j=0}^{2N-3} ( b^dag_j b_{j+1} + h.c. )
  + sum_{j=0}^{2N-2} [ (U/2) n_j (n_j - 1) + eps_j n_j ],
eps_j = (-1)**j delta/2 + j Delta

Parameters:

Name Type Description Default
matter_sites int

the chain length N; the lattice has 2N - 1 sites.

required
namespace Namespace

the namespace of the knobs J, U, delta and Delta.

required
admissible_set AdmissibleSet | None

the knob limits of the simulator; defaults to bose_hubbard_admissible_set.

None
name str

the name of the model.

'H_BHM'
hamiltonian_name str

the name under which the Hamiltonian prints; defaults to name.

''
tunnelling_sign int

-1 for the tunnelling term -J(...) of Yang et al. (2020), +1 for +J(...) of Zhou et al. (2022); the sign is a gauge choice on the b operators.

-1
staggered bool

whether the superlattice term is present.

True
tilted bool

whether the linear tilt is present.

True

Returns:

Type Description
HamiltonianModel

The model, in the hardware layer.

ising_admissible_set

ising_admissible_set(
    namespace: Namespace,
    *,
    coupling_max: float = 5.0,
    field_max: float = 2.0,
) -> AdmissibleSet

The admissible knob set of a transverse-field Ising simulator.

transverse_field_ising_chain

transverse_field_ising_chain(
    sites: int,
    namespace: Namespace,
    *,
    admissible_set: AdmissibleSet | None = None,
    name: str = "H_TFIM",
    hamiltonian_name: str = "",
) -> HamiltonianModel

A transverse-field Ising chain of qubits, Jz sum ZZ + h sum X.

Parameters:

Name Type Description Default
sites int

the number of qubits of the chain.

required
namespace Namespace

the namespace of the knobs Jz and h.

required
admissible_set AdmissibleSet | None

the knob limits of the simulator; defaults to ising_admissible_set.

None
name str

the name of the model.

'H_TFIM'
hamiltonian_name str

the name under which the Hamiltonian prints; defaults to name.

''

Returns:

Type Description
HamiltonianModel

The model, in the hardware layer.

two_component_admissible_set

two_component_admissible_set(
    namespace: Namespace,
    *,
    hopping_max: float = DEFAULT_HOPPING_MAX,
    interaction_magnitude_range: tuple[
        float, float
    ] = DEFAULT_INTERACTION_MAGNITUDE_RANGE,
    mott_ratio: float = DEFAULT_MOTT_RATIO,
) -> AdmissibleSet

The admissible knob set of a two-component optical-lattice simulator.

t = 0 is excluded strictly. U_uu and U_ud are attractive, so that Jxy > 0; U_dd may take either sign, so its box contains the pole U_dd = 0 and a solve needs an initial point on the intended side. Three coupled constraints U**2 >= (mott_ratio * t)**2 keep the Mott gap of every channel above the tunnelling.

Parameters:

Name Type Description Default
namespace Namespace

the namespace whose knobs are constrained.

required
hopping_max float

the largest reachable t.

DEFAULT_HOPPING_MAX
interaction_magnitude_range tuple[float, float]

the reachable range of |U|.

DEFAULT_INTERACTION_MAGNITUDE_RANGE
mott_ratio float

the ratio |U| / t at which the unit-filling Mott lobe closes.

DEFAULT_MOTT_RATIO

Returns:

Type Description
AdmissibleSet

The admissible set.

two_component_bose_hubbard_chain

two_component_bose_hubbard_chain(
    sites: int,
    namespace: Namespace,
    *,
    admissible_set: AdmissibleSet | None = None,
    name: str = "H_2BHM",
    hamiltonian_name: str = "",
) -> HamiltonianModel

A two-component Bose-Hubbard chain: two hyperfine states in one optical lattice.

H = -t sum_{sigma} sum_{j=0}^{N-2} ( b^dag_{j,sigma} b_{j+1,sigma} + h.c. )
  + (U_uu/2) sum_j n_{j,up} (n_{j,up} - 1)
  + (U_dd/2) sum_j n_{j,down} (n_{j,down} - 1)
  + U_ud     sum_j n_{j,up} n_{j,down}

Component up sits at register position 2j and down at 2j+1 (two_component_structure). The model declares the conserved total particle number, N at unit filling.

Parameters:

Name Type Description Default
sites int

the chain length N; the register has 2N positions.

required
namespace Namespace

the namespace of the knobs t, U_uu, U_ud and U_dd.

required
admissible_set AdmissibleSet | None

the knob limits of the simulator; defaults to two_component_admissible_set.

None
name str

the name of the model.

'H_2BHM'
hamiltonian_name str

the name under which the Hamiltonian prints; defaults to name.

''

Returns:

Type Description
HamiltonianModel

The model, in the hardware layer.