quchip.engine.truncation

Captured physical cutoff checks, sampled without storing state histories.

Functions

boundary_rows(check, xp)	Rows defining a captured cutoff projector in the local solver basis.
boundary_sampling_frequency(plan)	Fastest nonzero frame band in local cutoff reconstruction, in GHz.
boundary_traces(plan, values, times, backend)	Reconstruct boundary populations in the physical frame, independent of readout LO.
capture_truncation(chip, engine_result)	Capture boundary selections and bases, with no work that grows with the space.
check_truncation(result, *[, threshold])	Report the maximum sampled boundary population of each device in a solved result.
compile_truncation(plan, backend)	Lower captured cutoff projectors through the ordinary frame-band machinery.
evaluate_boundaries(result)	Use sampled traces or derive them from a kept full history without a rerun.
excitation_rows(plan)	Compact rows of the retained totals that a generator change can move above the cutoff.
with_truncation(problem)	Return a request collecting physical cutoff populations without saving states.

Classes

BoundaryCheck(label, boundary, basis[, energy])
TruncationPlan(checks, unavailable, dims, ...)

class quchip.engine.truncation.BoundaryCheck(label: str, boundary: quchip.devices.spaces.TruncationBoundary, basis: Any, energy: bool = False)

Bases: object

label: str

boundary: TruncationBoundary

basis: Any

energy: bool = False

class quchip.engine.truncation.TruncationPlan(checks: tuple[quchip.engine.truncation.BoundaryCheck, ...], unavailable: tuple[str, ...], dims: tuple[int, ...], labels: tuple[str, ...], frame_frequencies: dict[str, Any], operators: tuple[Any, ...] = (), metadata: tuple[quchip.engine.observables.BandMeta, ...] = (), sampled: bool = False, space: Any = None, excitation: tuple[int, tuple[int, ...]] | None = None)

Bases: object

checks: tuple[BoundaryCheck, ...]

unavailable: tuple[str, ...]

dims: tuple[int, ...]

labels: tuple[str, ...]

frame_frequencies: dict[str, Any]

operators: tuple[Any, ...] = ()

metadata: tuple[BandMeta, ...] = ()

sampled: bool = False

space: Any = None

excitation: tuple[int, tuple[int, ...]] | None = None

quchip.engine.truncation.capture_truncation(chip, engine_result)

Capture boundary selections and bases, with no work that grows with the space.

quchip.engine.truncation.excitation_rows(plan)

Compact rows of the retained totals that a generator change can move above the cutoff.

quchip.engine.truncation.boundary_rows(check, xp)

Rows defining a captured cutoff projector in the local solver basis.

quchip.engine.truncation.boundary_sampling_frequency(plan)

Fastest nonzero frame band in local cutoff reconstruction, in GHz.

quchip.engine.truncation.compile_truncation(plan, backend)

Lower captured cutoff projectors through the ordinary frame-band machinery.

quchip.engine.truncation.with_truncation(problem)

Return a request collecting physical cutoff populations without saving states.

Parameters:

problem (SolveProblem or SolveBatch) – Captured request or parameter batch. Its existing time grid is kept. Samples can miss excursions between save times and do not prove convergence.

Returns:

Request with additional diagnostic observables. No solve occurs.

Return type:

SolveProblem or SolveBatch

quchip.engine.truncation.boundary_traces(plan, values, times, backend)

Reconstruct boundary populations in the physical frame, independent of readout LO.

The traces follow plan.checks. An excitation cutoff with known boundary sectors adds their population as the last trace.

quchip.engine.truncation.evaluate_boundaries(result)

Use sampled traces or derive them from a kept full history without a rerun.

quchip.engine.truncation.check_truncation(result, *, threshold=0.001)

Report the maximum sampled boundary population of each device in a solved result.

Each device model declares the levels at its cutoff, and a basis with fewer retained than native levels adds its highest retained energy level. The check reads these populations from the saved states, or from the samples that with_truncation() adds to a request, and warns for each value above threshold. This warning heuristic can miss excursions between samples, and it is not an error bound. To confirm convergence, increase the applicable cutoff and compare observables. Native arrays stay differentiable. Warning thresholds are evaluated only for concrete results.

Under an ExcitationCutoff, the report also holds the policy as a key. Its value is the maximum population in the retained sectors that a Hamiltonian term, drive, or jump can move above the cutoff. To check convergence, compare observables at a larger max_total.

Parameters:

• result (SimulationResult, TrajectoryResult, or PartitionedSimulationResult) – Time-domain result built by quchip. It needs saved states (states="all" or states="final") or the samples of a request prepared with with_truncation(). A final state alone covers only the final time. A trajectory result needs each run’s states or samples.

• threshold (float, default=1e-3) – Maximum accepted boundary population.

Returns:

For a SimulationResult, the maximum population at each device label, and at the ExcitationCutoff policy if one applies. For a TrajectoryResult, runs holds the report of each run, deterministic the report of each no-click run, and maximum the largest value of each key over both. For a PartitionedSimulationResult, the reports of the components merge into one per-device report.

Return type:

dict

Raises:

• TypeError – If result is not one of these result types.

• RuntimeError – If the result holds neither saved states nor diagnostic samples.

• ValueError – If threshold is negative or not finite.