Use cases¶

A use case selects models, conventions and steps from the libraries and wires them into a graph.

usecases ¶

Use cases: model graphs assembled from the model and transformation libraries.

A use case selects models from qsimod.models at given conventions, relates them by transformations from qsimod.transformations, wires them into a ModelGraph, and names their parameter namespaces.

schwinger: the case study, a lattice Schwinger model carried to an analogue and a digital simulator model.
heisenberg: a Heisenberg magnet on a two-component lattice.
ising: an Ising chain on the hardware model of the case study.

Each module defines ParameterNames, build_graph and NAMESPACES; only the symbols of the first module are re-exported from this package.

base ¶

The model graph object every use case returns.

UseCaseGraph `dataclass` ¶

The model graph of a use case together with the pipelines through it.

Attributes:

Name	Type	Description
`source`	`str`	the artifact from which every pipeline of the use case starts; a class attribute.
`graph`	`ModelGraph`	the model graph.

targets ¶

targets() -> tuple[str, ...]

Every terminal artifact reachable from the source.

levels ¶

levels() -> dict[str, AbstractionLevel]

The abstraction level of every artifact, by name.

schwinger ¶

The case study of the article: the lattice Schwinger model, assembled from the libraries.

The graph runs from lattice_qed (H_sys) through quantum_link_staggered (H_IR1) to the branch point quantum_link_homogeneous (H_IR2). The analogue branch continues through effective_bosonic (H_IR3) to the Bose-Hubbard chain bose_hubbard (H_sim); the digital branch through qubit_register (H_IR4) to the Trotter product formula trotter (U_approx). A second digital branch leaves quantum_link_staggered directly, via qubit_register_staggered to trotter_staggered. The guide page of the documentation gives the Hamiltonians, the transformations and the conventions.

ParameterNames ¶

The fully qualified parameter names of this use case.

SchwingerGraph `dataclass` ¶

Bases: UseCaseGraph

The model graph of the use case, together with the pipelines through it.

Attributes:

Name	Type	Description
`matter_sites`	`int`	the chain length `N`.
`analogue`	`Pipeline`	the pipeline to `bose_hubbard` through `effective_bosonic`.
`digital`	`Pipeline`	the pipeline to `trotter` through `quantum_link_homogeneous` and `qubit_register`.
`alternative_digital`	`Pipeline`	the pipeline to `trotter_staggered` that leaves `quantum_link_staggered` directly.

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.

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.

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.

matter_occupation_observable ¶

matter_occupation_observable(
    matter_sites: int,
) -> OperatorSum

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

theory ¶

theory(matter_sites: int) -> HamiltonianModel

lattice_qed: the Kogut-Susskind lattice Schwinger model, H_sys.

staggered_quantum_link ¶

staggered_quantum_link(
    matter_sites: int,
) -> HamiltonianModel

quantum_link_staggered: the spin-1/2 quantum-link model, staggered, H_IR1.

homogeneous_quantum_link ¶

homogeneous_quantum_link(
    matter_sites: int,
) -> HamiltonianModel

quantum_link_homogeneous: the quantum-link model after particle-hole, H_IR2.

The model carries the constant -m * floor(N/2) the mass staggering left behind and is the branch point of the case study.

effective_bosonic ¶

effective_bosonic(matter_sites: int) -> HamiltonianModel

effective_bosonic: the effective bosonic pair-coupling model, H_IR3.

The model is the one realised by the superlattice.

superlattice ¶

superlattice(
    matter_sites: int,
    admissible_set: AdmissibleSet | None = None,
) -> HamiltonianModel

bose_hubbard: the tilted, staggered Bose-Hubbard chain, the analogue H_sim.

qubit_register ¶

qubit_register(matter_sites: int) -> HamiltonianModel

qubit_register: the 3-local Pauli Hamiltonian on the qubit register, H_IR4.

qubit_register_from_staggered ¶

qubit_register_from_staggered(
    matter_sites: int,
) -> HamiltonianModel

qubit_register_staggered: the qubit register reached from the staggered form.

The branch point is quantum_link_staggered instead of quantum_link_homogeneous.

truncation ¶

truncation() -> QuantumLinkTruncation

The quantum-link truncation, lattice_qed -> quantum_link_staggered.

particle_hole ¶

particle_hole() -> ParticleHoleTransformation

The particle-hole transformation, quantum_link_staggered -> quantum_link_homogeneous.

encoding ¶

encoding() -> HardcoreBosonEncoding

The boson encoding, quantum_link_homogeneous -> effective_bosonic.

perturbation ¶

perturbation(
    admissible_set: AdmissibleSet | None = None,
) -> SecondOrderPerturbationTheory

Second-order degenerate perturbation theory, effective_bosonic -> bose_hubbard.

The relation is solved for the knob settings Theta_sim = {J, U, delta, Delta}.

to_qubits ¶

to_qubits() -> JordanWignerToQubits

The Jordan-Wigner transformation, quantum_link_homogeneous -> qubit_register.

to_qubits_from_staggered ¶

to_qubits_from_staggered() -> JordanWignerToQubits

The Jordan-Wigner transformation from the staggered quantum-link model.

The transformation is the edge quantum_link_staggered -> qubit_register_staggered.

trotterisation ¶

trotterisation(
    *,
    time: float = 1.0,
    steps: int = 1,
    order: int = 2,
    from_staggered: bool = False,
) -> SuzukiTrotter

The Trotterisation, qubit_register -> trotter.

Parameters:

Name	Type	Description	Default
`time`	`float`	the simulated time `t`.	`1.0`
`steps`	`int`	the step count `n`.	`1`
`order`	`int`	the order of the product formula.	`2`
`from_staggered`	`bool`	whether the transformation of the second digital branch, `qubit_register_staggered -> trotter_staggered`, is built instead.	`False`

Returns:

Type	Description
`SuzukiTrotter`	The transformation.

validity ¶

validity(**thresholds: float) -> Conjunction

The validity conditions of the perturbative step, over the namespaces of this use case.

coupling_map ¶

coupling_map() -> Scalar

The coupling of the perturbative step in the forward direction of the derivation.

The expression is stated over the hardware namespace of this use case.

mass_map ¶

mass_map() -> Scalar

The mass of the perturbative step in the forward direction of the derivation.

The expression is stated over the hardware namespace of this use case.

device_limits ¶

device_limits(
    *,
    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 the superlattice hardware, over the namespace of this use case.

The keywords are those of bose_hubbard_admissible_set.

build_graph ¶

build_graph(
    matter_sites: int,
    *,
    admissible_set: AdmissibleSet | None = None,
    time: float = 1.0,
    steps: int = 1,
    order: int = 2,
) -> SchwingerGraph

Assemble the model graph of the use case at a given chain length.

Parameters:

Name	Type	Description	Default
`matter_sites`	`int`	the chain length `N`.	required
`admissible_set`	`AdmissibleSet \| None`	the admissible knob set of the superlattice hardware; defaults to `bose_hubbard_admissible_set` on the namespace of this use case.	`None`
`time`	`float`	the simulated time with which the Trotterisation transformations are configured.	`1.0`
`steps`	`int`	the step count with which they are configured.	`1`
`order`	`int`	the order of the product formula.	`2`

Returns:

Type	Description
`SchwingerGraph`	The model graph and the three pipelines through it.

analogue_pipeline ¶

analogue_pipeline(
    matter_sites: int = 3,
    admissible_set: AdmissibleSet | None = None,
) -> Pipeline

The analogue pipeline alone.

digital_pipeline ¶

digital_pipeline(
    matter_sites: int = 4,
    *,
    time: float = 2.0,
    steps: int = 16,
    order: int = 2,
) -> Pipeline

The digital pipeline alone, at the given resource settings.

heisenberg ¶

The anisotropic Heisenberg magnet, assembled from the model and transformation libraries.

The graph runs from xxz_magnet to the branch point xxz_chain, whose two branches are the exact Jordan-Wigner image fermion_chain and the second-order superexchange onto the two-component Bose-Hubbard chain two_component_bose_hubbard, after Jepsen et al. (2020). The longitudinal field the superexchange also produces is returned by field_map and is not part of the magnet. The guide page of the documentation gives the Hamiltonians and the conventions.

ParameterNames ¶

The fully qualified parameter names of this use case.

HeisenbergGraph `dataclass` ¶

Bases: UseCaseGraph

The model graph of the use case, together with the pipelines through it.

Attributes:

Name	Type	Description
`sites`	`int`	the chain length `N`.
`device`	`Pipeline`	the pipeline to `two_component_bose_hubbard`.
`fermions`	`Pipeline`	the pipeline to `fermion_chain`.

coordination_numbers ¶

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

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

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.

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.

magnet ¶

magnet(sites: int) -> HamiltonianModel

xxz_magnet: the XXZ magnet stated by its anisotropy.

spin_chain ¶

spin_chain(sites: int) -> HamiltonianModel

xxz_chain: the same chain, stated by two coupling energies.

fermion_chain ¶

fermion_chain(sites: int) -> HamiltonianModel

fermion_chain: the Jordan-Wigner image, spinless fermions with a neighbour V.

lattice ¶

lattice(
    sites: int, admissible_set: AdmissibleSet | None = None
) -> HamiltonianModel

two_component_bose_hubbard: the two-component Bose-Hubbard chain, the hardware model.

anisotropy ¶

anisotropy() -> AnisotropyResolution

The anisotropy resolution, xxz_magnet -> xxz_chain.

jordan_wigner ¶

jordan_wigner() -> JordanWignerToFermions

The Jordan-Wigner transformation to fermions, xxz_chain -> fermion_chain.

superexchange ¶

superexchange(
    admissible_set: AdmissibleSet | None = None,
) -> SuperexchangeReduction

Second-order superexchange solved for the knobs, to two_component_bose_hubbard.

validity ¶

validity(**thresholds: float) -> Conjunction

The validity conditions of the superexchange step, over the namespaces of this use case.

transverse_map ¶

transverse_map() -> Scalar

The coupling Jxy in the forward direction of the derivation.

The expression is stated over the hardware namespace of this use case.

longitudinal_map ¶

longitudinal_map() -> Scalar

The coupling Jz in the forward direction of the derivation.

The expression is stated over the hardware namespace of this use case.

field_map ¶

field_map() -> Scalar

The strength of the longitudinal field that the superexchange step also produces.

The field is not part of the target model; see superexchange_field.

device_limits ¶

device_limits(
    *,
    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 the lattice, over the namespace of this use case.

The keywords are those of two_component_admissible_set.

device_start ¶

device_start(
    anisotropy: float = 0.0,
    *,
    hopping: float = START_HOPPING,
    interaction: float = START_INTERACTION,
) -> dict[str, float]

A deterministic starting point for the knob solve, on the intended side of the pole.

The admissible interval of U_dd straddles the pole U_dd = 0, and an anisotropy below -1 is reachable only with a repulsive U_dd; the starting point selects the branch.

Parameters:

Name	Type	Description	Default
`anisotropy`	`float`	the requested anisotropy.	`0.0`
`hopping`	`float`	the starting tunnelling.	`START_HOPPING`
`interaction`	`float`	the starting magnitude of all three interaction channels.	`START_INTERACTION`

Returns:

Type	Description
`dict[str, float]`	A starting value per hardware knob.

build_graph ¶

build_graph(
    sites: int,
    *,
    admissible_set: AdmissibleSet | None = None,
) -> HeisenbergGraph

Assemble the model graph of the use case at a given chain length.

Parameters:

Name	Type	Description	Default
`sites`	`int`	the chain length `N`.	required
`admissible_set`	`AdmissibleSet \| None`	the admissible knob set of the lattice; defaults to `two_component_admissible_set` on the namespace of this use case.	`None`

Returns:

Type	Description
`HeisenbergGraph`	The model graph and the two pipelines through it.

device_pipeline ¶

device_pipeline(
    sites: int = 3,
    admissible_set: AdmissibleSet | None = None,
) -> Pipeline

The pipeline to the hardware model alone.

fermion_pipeline ¶

fermion_pipeline(sites: int = 6) -> Pipeline

The analytic pipeline alone.

ising ¶

The antiferromagnetic Ising chain, on the hardware model of the case study.

The graph runs from ising_magnet through ising_chain to bose_hubbard, the artifact of schwinger, by the resonant dipole reduction of Simon et al. (2011); shared_graph holds both theories in one model graph. A dipole resides on a bond, so a register of 2N-1 sites carries 2N-2 spins. The end-spin field omitted by the target Hamiltonian is returned by boundary_field. The guide page of the documentation gives the Hamiltonians and the conventions.

ParameterNames ¶

The fully qualified parameter names; the hardware half is that of bose_hubbard.

IsingGraph `dataclass` ¶

Bases: UseCaseGraph

The model graph of the use case, together with the pipeline through it.

Attributes:

Name	Type	Description
`matter_sites`	`int`	the chain length `N` of the hardware model; the magnet has `2N-2` spins.
`device`	`Pipeline`	the pipeline to the shared `bose_hubbard`.

spins `property` ¶

spins: int

The chain length of the magnet.

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.

spins_for ¶

spins_for(matter_sites: int) -> int

The number of Ising spins on a register of 2N-1 sites: 2N-2, one per bond.

magnet ¶

magnet(matter_sites: int) -> HamiltonianModel

ising_magnet: the Ising chain stated by its two dimensionless fields.

ising_chain ¶

ising_chain(matter_sites: int) -> HamiltonianModel

ising_chain: the same chain, stated by three energies.

lattice ¶

lattice(
    matter_sites: int,
    admissible_set: AdmissibleSet | None = None,
) -> HamiltonianModel

bose_hubbard: the tilted Bose-Hubbard chain, the analogue simulator of the case study.

fields ¶

fields() -> FieldResolution

The field resolution, ising_magnet -> ising_chain.

dipoles ¶

dipoles(
    admissible_set: AdmissibleSet | None = None,
) -> DipoleReduction

The resonant dipole reduction solved for the knobs, ising_chain -> bose_hubbard.

validity ¶

validity(**thresholds: float) -> Conjunction

The validity conditions of the dipole reduction, over the namespaces of this use case.

coupling_map ¶

coupling_map() -> Scalar

The coupling Jz in the forward direction of the derivation.

The expression is stated over the namespace of the shared hardware model.

transverse_map ¶

transverse_map() -> Scalar

The transverse field Gamma in the forward direction of the derivation.

The expression is stated over the namespace of the shared hardware model.

longitudinal_map ¶

longitudinal_map() -> Scalar

The longitudinal field B in the forward direction of the derivation.

The expression is stated over the namespaces of this use case.

detuning_map ¶

detuning_map() -> Scalar

The detuning Delta - U from the dipole resonance.

boundary_field ¶

boundary_field() -> Scalar

The end-spin field Jz / 2 that the dipole reduction also produces.

The field is not part of the target model; see dipole_boundary_field.

device_limits ¶

device_limits(
    *,
    tunnelling_max: float = DEFAULT_TUNNELLING_MAX,
    interaction_range: tuple[
        float, float
    ] = DEFAULT_INTERACTION_RANGE,
    superlattice_max: float = DEFAULT_SUPERLATTICE_MAX,
    tilt_max: float = DEFAULT_RESONANT_TILT_MAX,
) -> AdmissibleSet

The admissible knob set of the lattice, of which that of the case study is a sub-region.

The set is built from schwinger.device_limits with the constraints at the level of the derivation removed by apparatus_only, and with the upper limit of the tilt raised above that of the interaction. The validity conditions of the superlattice transformation of the case study still declare Delta << delta and Delta << U.

Returns:

Type	Description
`AdmissibleSet`	The admissible set.

device_start ¶

device_start(coupling: float) -> dict[str, float]

A deterministic starting point for the dipole solve, in the resonant corner.

Parameters:

Name	Type	Description	Default
`coupling`	`float`	the requested Ising coupling `Jz`, which is the interaction and, near the multicritical point, the tilt as well.	required

Returns:

Type	Description
`dict[str, float]`	A starting value per hardware knob.

build_graph ¶

build_graph(
    matter_sites: int,
    *,
    admissible_set: AdmissibleSet | None = None,
) -> IsingGraph

Assemble the model graph of the use case at a given chain length of the hardware model.

Parameters:

Name	Type	Description	Default
`matter_sites`	`int`	the chain length `N` of the hardware model; the magnet is built at `2N-2` spins.	required
`admissible_set`	`AdmissibleSet \| None`	the admissible knob set of the hardware; defaults to `device_limits`.	`None`

Returns:

Type	Description
`IsingGraph`	The model graph and the pipeline through it.

shared_graph ¶

shared_graph(
    matter_sites: int,
    *,
    admissible_set: AdmissibleSet | None = None,
) -> ModelGraph

One model graph carrying both theories, which meet at the artifact bose_hubbard.

Both requests are posed against the admissible set of the lattice from device_limits.

Parameters:

Name	Type	Description	Default
`matter_sites`	`int`	the chain length `N` of the hardware model.	required
`admissible_set`	`AdmissibleSet \| None`	the admissible knob set of the hardware, shared by both theories.	`None`

Returns:

Type	Description
`ModelGraph`	The combined model graph.

device_pipeline ¶

device_pipeline(
    matter_sites: int = 3,
    admissible_set: AdmissibleSet | None = None,
) -> Pipeline

The Ising pipeline alone.

Use cases¶

usecases ¶

base ¶

UseCaseGraph dataclass ¶

targets ¶

levels ¶

schwinger ¶

ParameterNames ¶

SchwingerGraph dataclass ¶

canonical_state_configuration ¶

gauge_violation_observable ¶

local_occupation_subspace ¶

matter_occupation_observable ¶

theory ¶

staggered_quantum_link ¶

homogeneous_quantum_link ¶

effective_bosonic ¶

superlattice ¶

qubit_register ¶

qubit_register_from_staggered ¶

truncation ¶

particle_hole ¶

encoding ¶

perturbation ¶

to_qubits ¶

to_qubits_from_staggered ¶

trotterisation ¶

validity ¶

coupling_map ¶

mass_map ¶

device_limits ¶

build_graph ¶

analogue_pipeline ¶

digital_pipeline ¶

heisenberg ¶

ParameterNames ¶

HeisenbergGraph dataclass ¶

coordination_numbers ¶

magnetisation_observable ¶

mott_manifold_operators ¶

weighted_magnetisation_term ¶

magnet ¶

spin_chain ¶

fermion_chain ¶

lattice ¶

anisotropy ¶

jordan_wigner ¶

superexchange ¶

validity ¶

transverse_map ¶

longitudinal_map ¶

field_map ¶

device_limits ¶

device_start ¶

build_graph ¶

device_pipeline ¶

fermion_pipeline ¶

ising ¶

ParameterNames ¶

IsingGraph dataclass ¶

spins property ¶

end_magnetisation_term ¶

spins_for ¶

magnet ¶

ising_chain ¶

lattice ¶

fields ¶

dipoles ¶

validity ¶

coupling_map ¶

transverse_map ¶

longitudinal_map ¶

detuning_map ¶

boundary_field ¶

device_limits ¶

device_start ¶

build_graph ¶

shared_graph ¶

device_pipeline ¶

UseCaseGraph `dataclass` ¶

SchwingerGraph `dataclass` ¶

HeisenbergGraph `dataclass` ¶

IsingGraph `dataclass` ¶

spins `property` ¶