quchip.engine.problem

Package engine physics and solve inputs into frozen solve requests.

Responsibilities

  • Resolve the chip frame.

  • Flatten e_ops into solver-ready bands with decompose_eops().

  • Build an EngineResult for each variant and pack into a single SolveProblem, or merge homogeneous variants into a SolveBatch (N identical skeletons with per-element ScalarModulation signals).

Collapse operators enter the standard Lindblad master equation dρ/dt = −i[H, ρ] + Σₖ D[Lₖ]ρ. Rates are stored in 1/ns.

Functions

build_solve_batch_from_results(context, ...)

Package homogeneous EngineResult`s as one :class:`SolveBatch.

build_solve_problem(chip, drive_ops, tlist, *)

Resolve, assemble, and package a frozen SolveProblem.

prepare_solve_problem_context(chip, tlist, *)

Resolve the frame and retain authored observables and state specifications.

solve_problem_list(problems, backend, *[, ...])

Group problems by shared operator skeleton and dispatch as :class:`SolveBatch`es.

validate_drive_ops_window(drive_ops, tlist)

Validate every DriveOp in drive_ops against _validate_drive_op_window().

Classes

SolveProblemContext(chip, tlist, e_ops, ...)

Shared solve metadata reused across a homogeneous problem batch.
class quchip.engine.problem.SolveProblemContext(chip, tlist, e_ops, e_ops_meta, resolved_frame, approximation, _base_result, solver, options, default_initial_state)[source]

Bases: object

Shared solve metadata reused across a homogeneous problem batch.

Built once by prepare_solve_problem_context() so sweep points can skip redundant observable normalization.

Parameters:

  • chip (Chip)

  • tlist (Any)

  • e_ops (Any)

  • e_ops_meta (Any)

  • resolved_frame (Any)

  • approximation (Approximation)

  • _base_result (EngineResult | None)

  • solver (str | None)

  • options (dict[str, Any])

  • default_initial_state (Any)

chip: Chip
tlist: Any
e_ops: Any
e_ops_meta: Any
resolved_frame: Any
approximation: Approximation
solver: str | None
options: dict[str, Any]
default_initial_state: Any
classmethod from_problem(ref)[source]

Reconstruct a shared context from an existing SolveProblem.

Mirrors SolveBatch.element(): it lifts a single concrete problem back into the context shape so a homogeneous group of problems can be re-batched. The reference problem’s already-built initial_state becomes the default state specification, and options is defensively copied.

Parameters:

ref (SolveProblem)

Return type:

SolveProblemContext

quchip.engine.problem.validate_drive_ops_window(drive_ops, tlist)[source]

Validate every DriveOp in drive_ops against _validate_drive_op_window().

Parameters:
Return type:

None

quchip.engine.problem.prepare_solve_problem_context(chip, tlist, *, solver=None, options=None, e_ops=None, drive_ops=None, approximation=None)[source]

Resolve the frame and retain authored observables and state specifications.

Observables and states are materialized only after assembly resolves every local solver basis. The default ground state remains lazy, so callers that provide an explicit state do not pay for unused state construction.

tlist is validated by _validate_tlist(). When drive_ops is given, each entry’s pulse window is checked against tlist via validate_drive_ops_window(); omit it (the default) when the caller validates its own per-variant drive ops elsewhere (see build_batch()).

Parameters:
Return type:

SolveProblemContext

quchip.engine.problem.build_solve_batch_from_results(context, engine_results, *, initial_states=None)[source]

Package homogeneous EngineResult`s as one :class:`SolveBatch.

All results must share static_terms identity, the same number of dynamic terms, and matching operator payloads per slot (by identity or by canonical fingerprint — crosstalk rebuilds equal-by-value operators on every instantiation). initial_states=None fills every element with context.default_initial_state.

Parameters:
Return type:

SolveBatch

quchip.engine.problem.build_solve_problem(chip, drive_ops, tlist, *, solver=None, options=None, e_ops=None, initial_state=None, approximation=None)[source]

Resolve, assemble, and package a frozen SolveProblem.

Equivalent to prepare_solve_problem_context() followed by build_engine_result(). For many variants sharing one chip configuration, prefer that two-step form with build_solve_batch_from_results().

Parameters:
Return type:

SolveProblem

quchip.engine.problem.solve_problem_list(problems, backend, *, progress=True)[source]

Group problems by shared operator skeleton and dispatch as :class:`SolveBatch`es.

Problems that share an operator skeleton are merged into one batched solve. A backend may dispatch a large heterogeneous list independently; otherwise each structural group follows the normal batch path, with incompatible results falling back to per-problem backend.solve_problem calls.

Grouping uses two filters. The cheap identity-based prefilter here (_skeleton_prefilter_key()) buckets problems by id() of their shared operators/metadata so that obviously-incompatible problems are never compared by value. The canonical by-value compatibility check is intentionally a separate concern that lives inside build_solve_batch_from_results() (operator fingerprint): the prefilter is an identity prefilter, the fingerprint is the value check. Returns a SimulationBatchResult.

Parameters:
Return type:

Any