Solving layer¶

The solve for the knob settings: parameter realisation as a constrained solve.

The parameter relation of a pipeline is inverted in a single constrained solve for the knob settings of the hardware model. qsimod.solving.problem collects the equations, admissible sets and validity conditions of a relation into a constraint system; qsimod.solving.backends contains the only modules that import an optimiser; qsimod.solving.dispatch selects a backend after an attempt to prove infeasibility with qsimod.solving.reachability; and qsimod.solving.feasible evaluates the same declarations point-wise and region-wise. qsimod.solving.stepcount poses the step count of a product formula as an integer solve against the a-priori error bound.

The declarative statement of a parameter-realisation problem.

RealisationProblem collects the equations, admissible sets and validity conditions of a parameter relation into a ConstraintSystem; the backend that solves it is selected in qsimod.solving.dispatch, and this module imports no solver. Unknown records whether an unknown ranges over the reals or the integers, and a backend declares the problem shapes it handles through supports.

interval: Interval

unknown_names: tuple[str, ...]

has_integral_unknown: bool

unknown(name: str) -> Unknown

bounds() -> tuple[Bound, ...]

admissible_set(description: str = '') -> AdmissibleSet

interval_environment() -> dict[str, Interval]

residuals(
    assignment: Mapping[str, float],
) -> dict[str, float]

definitions() -> tuple[Definition, ...]

hard_constraints() -> tuple[tuple[str, Scalar], ...]

enforced_conditions() -> tuple[ValidityCondition, ...]

rejections(point: Mapping[str, float]) -> tuple[str, ...]

parameters() -> frozenset[str]

build_system(
    relation: ParameterRelation,
    targets: Mapping[str, float],
    unknowns: Sequence[str],
    admissible_set: AdmissibleSet,
    *,
    initial: Mapping[str, float] | None = None,
    integral: Sequence[str] = (),
) -> ConstraintSystem

Objectives for an under-determined solve.

An under-determined system of parameter relations admits multiple knob settings that realise the same request; an objective selects among them. The default, MaximiseWeakestMargin, places the operating point as deep inside the declared regime as the constraints allow. It is posed by epigraph transformation: an auxiliary variable s (SLACK_VARIABLE) is introduced, the margin of every regime condition is constrained to be at least s, and s is maximised; Objective.slack_variable declares the auxiliary variable to a backend. MinimiseExpression and MaximiseExpression accept any scalar expression.

slack_variable: str | None

cost_expression() -> Scalar | None

value(assignment: Mapping[str, float]) -> float

cost(assignment: Mapping[str, float]) -> float

parameters() -> frozenset[str]

epigraph_constraints() -> tuple[tuple[str, Scalar], ...]

cost_expression() -> None

value(assignment: Mapping[str, float]) -> float

parameters() -> frozenset[str]

cost_expression() -> Scalar

value(assignment: Mapping[str, float]) -> float

parameters() -> frozenset[str]

cost_expression() -> Scalar

value(assignment: Mapping[str, float]) -> float

cost(assignment: Mapping[str, float]) -> float

parameters() -> frozenset[str]

regime_conditions: tuple[ValidityCondition, ...]

slack_variable: str

cost_expression() -> Scalar

value(assignment: Mapping[str, float]) -> float

cost(assignment: Mapping[str, float]) -> float

parameters() -> frozenset[str]

epigraph_constraints() -> tuple[tuple[str, Scalar], ...]

default_objective(
    conditions: Sequence[ValidityCondition],
) -> Objective

minimise(
    expression: ScalarLike,
    name: str = "",
    description: str = "",
) -> MinimiseExpression

maximise(
    expression: ScalarLike,
    name: str = "",
    description: str = "",
) -> MaximiseExpression

The result of a parameter-realisation solve: a status and a point.

SolveStatus distinguishes an exact solution, a best fit with a residual per equation, a proved infeasibility that names the binding constraint, and an unconverged search (UNSOLVED), which is not an infeasibility. The backend, its termination message, its iteration count and any random seed are recorded; every backend of the package is deterministic, and the seed is therefore None.

EXACT_SOLUTION = 'EXACT_SOLUTION'

APPROXIMATE_SOLUTION = 'APPROXIMATE_SOLUTION'

INFEASIBLE = 'INFEASIBLE'

UNSOLVED = 'UNSOLVED'

is_success: bool

max_residual: float

value(parameter: str) -> float

subset(parameters: Sequence[str]) -> dict[str, float]

Proving a request unreachable for a hardware model by interval arithmetic.

The proof involves no numerical solve. The procedure is as follows: (1) every solved form whose inputs are fixed values or bounded knobs is substituted, repeatedly, until no further parameter can be eliminated; (2) for each remaining equation with one side thereby constant, the other side is bounded over the admissible box by the intersection of the interval-arithmetic bound and the qsimod.affine bound; (3) if the constant lies outside the bound, the request is proved unreachable; (4) the binding constraints are named by relaxing the knob boxes one at a time. A bound that contains the request establishes only that infeasibility is not proved, not that the request is reachable: check_reachability then returns None and the caller proceeds to a backend.

achievable_range(
    expression: Scalar,
    system: ConstraintSystem,
    substitutions: Mapping[str, Scalar] | None = None,
) -> Interval

bound_over(
    expression: Scalar, env: Mapping[str, Interval]
) -> Interval

check_reachability(
    system: ConstraintSystem, admissible_set: AdmissibleSet
) -> ReachabilityVerdict | None

reachability_report(
    system: ConstraintSystem,
) -> ReachabilityReport

The feasible set of a realisation problem, evaluated point-wise or region-wise.

FeasibleSet.check decides one assignment against the admissible box, the coupled constraints, the equation residuals and the validity conditions. FeasibleSet.grid evaluates the feasible set on a Cartesian grid, FeasibleSet.sample on a seeded uniform sample of the box (default seed DEFAULT_SAMPLE_SEED), and FeasibleSet.constraint_system returns the constraint system unevaluated.

max_residual: float

weakest_margin: float

as_row() -> dict[str, float | bool | str]

check(assignment: Mapping[str, float]) -> FeasiblePoint

grid(
    axes: Mapping[str, Sequence[float]],
    complete: Callable[
        [Mapping[str, float]], Mapping[str, float]
    ]
    | None = None,
) -> tuple[FeasiblePoint, ...]

sample(
    count: int,
    complete: Callable[
        [Mapping[str, float]], Mapping[str, float]
    ]
    | None = None,
    seed: int = DEFAULT_SAMPLE_SEED,
) -> tuple[FeasiblePoint, ...]

constraint_system() -> ConstraintSystem

feasible_fraction(points: Sequence[FeasiblePoint]) -> float

best(
    points: Sequence[FeasiblePoint],
) -> FeasiblePoint | None

Selection and execution of a solver backend.

solve first attempts to prove infeasibility by interval arithmetic (qsimod.solving.reachability); if nothing is proved, it runs the first backend whose supports accepts the problem. The default order is ClosedFormBackend, MonotoneBisectionBackend, ScipyNlpBackend.

default_backends() -> tuple[SolverBackend, ...]

solve(
    problem: RealisationProblem,
    backends: Sequence[SolverBackend] | None = None,
) -> SolveResult

classify_request(
    relation: ParameterRelation,
    targets: Mapping[str, float],
) -> RelationClassification

realise_parameters(
    pipeline: Pipeline,
    targets: Mapping[str, float],
    unknowns: Sequence[str],
    admissible_set: AdmissibleSet,
    *,
    objective: Objective | None = None,
    validity: Conjunction | None = None,
    initial: Mapping[str, float] | None = None,
    integral: Sequence[str] = (),
    enforce_regime_conditions: bool = True,
    tolerance: float = 1e-10,
    max_iterations: int = 400,
    backends: Sequence[SolverBackend] | None = None,
    name: str = "",
) -> SolveResult

problem_for(
    relation: ParameterRelation,
    targets: Mapping[str, float],
    unknowns: Sequence[str],
    admissible_set: AdmissibleSet,
    *,
    objective: Objective | None = None,
    validity: Conjunction | None = None,
    initial: Mapping[str, float] | None = None,
    integral: Sequence[str] = (),
    tolerance: float = 1e-10,
    max_iterations: int = 400,
    name: str = "realisation",
) -> RealisationProblem

The Trotter step count as an instance of the general solve.

The Trotterisation is an approximate transformation whose error is controlled by a resource parameter, the step count n of the product formula. Given a simulated time t, an order p and a target error epsilon, the solve determines the smallest integer n with error_bound(t, n, p) <= epsilon. Every bound in qsimod.trotter.bounds has the form A / n**p at fixed t and order; A is recovered by evaluating the bound at n = 1, and the constraint becomes the scalar expression epsilon - A * n**(-p) >= 0 over the integral unknown STEPS_SYMBOL. The joint choice of (n, order) is one bisection per order, ranked by the total count of k-local unitaries.

bound_coefficient(
    decomposition: LayerDecomposition,
    order: int,
    time: float,
    estimator: NormEstimator | None = None,
) -> float

step_count_problem(
    decomposition: LayerDecomposition,
    order: int,
    time: float,
    target_error: float,
    *,
    estimator: NormEstimator | None = None,
    max_steps: int = DEFAULT_MAX_STEPS,
    name: str = "",
) -> RealisationProblem

minimal_steps(
    decomposition: LayerDecomposition,
    order: int,
    time: float,
    target_error: float,
    *,
    estimator: NormEstimator | None = None,
    max_steps: int = DEFAULT_MAX_STEPS,
    backends: Sequence[SolverBackend] | None = None,
) -> SolveResult

resource_candidates(
    decomposition: LayerDecomposition,
    time: float,
    target_error: float,
    orders: Sequence[int] = (1, 2, 4),
    *,
    estimator: NormEstimator | None = None,
    max_steps: int = DEFAULT_MAX_STEPS,
) -> tuple[ResourceChoice, ...]

Solver backends: the only modules of the package that import an optimiser.

The physics modules declare equations, admissible sets and validity conditions in qsimod.relations, qsimod.parameters and qsimod.validity; none of these imports a backend.

The interface of a solver backend.

A backend accepts a RealisationProblem and returns a SolveResult; SolverBackend.supports declares the problem shapes a backend handles, by which the dispatcher selects one.

solve(problem: RealisationProblem) -> SolveResult

supports(problem: RealisationProblem) -> bool

A backend that evaluates a closed-form elimination chain.

When the static classification identifies the relation as a closed form in the requested direction, the elimination chain is evaluated in order, without iteration, tolerance, starting point or optimiser. The backend imports nothing beyond the expression evaluator of the package.

supports(problem: RealisationProblem) -> bool

solve(problem: RealisationProblem) -> SolveResult

The constrained non-linear-programming backend on scipy.optimize.

The default method is SLSQP (sequential least-squares programming) from SciPy. The box bounds are passed to the solver directly. The parameter relations enter as equality constraints; the hard inequalities, that is the coupled admissibility constraints and the domain and regime conditions, and the epigraph objective enter as inequality constraints. Each constraint is a NonlinearConstraint object with an analytic Jacobian obtained by JAX automatic differentiation of the expression layer. An OVER_DETERMINED problem is solved as a least-squares fit of the residuals. The method is local and never returns INFEASIBLE: a failed search is reported as UNSOLVED, and infeasibility is proved separately by qsimod.solving.reachability.

solve(problem: RealisationProblem) -> SolveResult

A discrete backend: monotone bisection over one integral unknown.

The hard constraints are assumed monotone in the unknown; the a-priori error bounds of the product formulas are proportional to n**-p. The feasible set is therefore an up-set, and the least feasible integer is found by doubling to bracket it and bisecting within the bracket, in O(log n) evaluations. Minimality is witnessed by the bisection: the result records that n - 1 violates the constraints and n satisfies them. minimal_resource_setting selects the (order, steps) candidate of least cost.

supports(problem: RealisationProblem) -> bool

solve(problem: RealisationProblem) -> SolveResult

minimal_feasible_integer(
    predicate: Callable[[int], bool],
    *,
    lower: int = 1,
    maximum: int = 1 << 30,
) -> DiscreteSolution | None

minimal_resource_setting(
    candidates: Sequence[ResourceChoice],
) -> ResourceChoice