Python API¶

The (key, sources) list this axis would run — what axis= takes hand-built.

For building one slice alone: sps.build(spec, axis.slices(sources)[3][1]).

The (key, sources) list this axis would run — what axis= takes hand-built.

For building one window alone: sps.build(spec, axis.slices(sources)[37][1]). The pairs carry no ownership: solved as a list, the slices need key_name=, the answer is keyed by slice rather than stitched, and a carry cannot collapse a dimension.

Refuse the built model where sink cannot take it; no solve, no file.

::

sps.build('dispatch.yaml', sources).check('highs')

The answer is read off the built model, not the file: a square the data prices at zero, an integer variable with no built column or a set with no members asks for nothing. solve and write refuse exactly what this refuses, with the same message.

Release the built model, and any solver still holding it.

What this build and its solves did that the answer does not show.

Answerable after close, and after a build that raised. A raise leaves the sizes at zero, since they are taken once a model is whole, and everything measured before it stands.

One built constraint row at one coordinate — its terms, sense and right-hand side.

The verb for this row is wrong and I do not know why. It reads the built model and needs no solve: a term whose variable was absent is missing, and a row a where masked out is not there at all. A column has no reader: a variable's bounds are in the spec, and its coefficients are this read transposed.

Hand the built model to a solver and solve it.

A solver that can stay loaded is kept between calls, so an updated model pushes only its numbers. How much this solve kept is its kept.

Put new numbers on the same model, in place.

::

model.update({'cap_hat': capacity}).solve()

model.update(x) answers what build(spec, sources | x) answers, whatever changed. Data that moves a mask renumbers labels, so the model is rebuilt and solved cold rather than pushed onto a loaded solver; loads says which ran.

Results taken before the update keep reading their own frames, and keep their build's label frames alive until dropped or until close is called. A sweep, a rolling horizon or a myopic pathway is solve_over, which runs this loop.

Stream the built model to path, in the format its suffix names.

The left-hand side of constraint name at the solution — (dims…, value), dual's shape and order.

The solver's own number, not a recomputation, and readable whenever there is a solution, a mixed-integer one included.

Release this result's frames, and its hold on the build's label frames, early. Optional.

Frames already read stay valid. The model and the solver are the Model's to close.

Shadow prices of constraint name — (dims…, value), primal's shape and order.

Each is the rate at which the optimal objective rises as the row's right side rises: of lhs <= rhs, the rate in d of lhs <= rhs + d. That is mathspec's dual(c) for every comparator, sense and sink, so which side a term is written on decides the sign.

Duals exist only where a solver ran here, not for a model written to a file and solved elsewhere. Reduced costs and slacks are not read.

Constraint name's share of the certificate that this model has no solution — (dims…, value).

The only reader that answers on an infeasible solve, where primal, dual and activity all raise. Weight every row by its value here and add them, and the combined row demands more than the columns can deliver inside their bounds: the proof that nothing satisfies all of them at once, and what a Benders feasibility cut is built from.

dual's shape and order, and the row's own sign on every sink. Where every column is held only by a lower bound of zero, the proof is Σ weight * right-hand side > 0.

highs always produces a certificate; gurobi needs {'InfUnbdInfo': 1} and xpress needs {'presolve': 0} in solver_options, set before the solve. A ray is live only: save writes none, and no sweep spills one.

The value of expression at this solution — (dims…, value), primal's shape and order.

expression is what one expressions: entry takes: a name the file declares, an expression string, or the mapping carrying cases: with dims: and otherwise:. The value is aggregated to the expression's own dims, in declaration order.

Anything but a declared name lowers the spec as written, which costs what check costs. save writes, and a sweep spills, only the expressions declared under expressions:.

Which model this answered — the document and the data it was attached to.

spec_digest names the document alone, so two scenarios of one spec share that and differ here. Computed on the first ask and kept.

The tidy solution of variable name — (dims…, value).

Rows come back in label order, row-major over the variable's coordinate product, so two reads and two runs agree.

Every kind this solve answered with, one file per name, into directory.

record.parquet holds the Record, with a null rather than nan objective where none was reached. Beside it are primal/<name>.parquet per variable, dual/<name>.parquet per constraint where the duals are defined, activity/<name>.parquet per constraint, and expression/<name>.parquet per named expression this data can evaluate. reasons.parquet holds (kind, name, reason) for whatever is deliberately left out — one row per failed expression, one with an empty name for the duals — and is absent when nothing is. A solve that left no values writes the record alone. The same model and data write the same bytes.

format.json stamps the layout and the specsolve that wrote it: {"layout": 3, "specsolve": "…"}. Every reader refuses another layout with a LayoutError that says to solve the model again and save it.

Whatever a previous save left in directory is removed first; files outside the layout are left alone.

One name's values as a labelled xarray.DataArray, to_pandas's arguments.

Dense over the name's dims: a masked coordinate comes back NaN.

The named values of one kind as one xarray.Dataset; every name of that kind where none is given.

Each arrives dense over its own dims, all at once — on a large model name the few you need.

One name's values as a tidy pandas.DataFrame.

name is read through the reader kind names: primal, dual or expression. Needs pandas, which specsolve does not install; the xarray bridges need xarray too.

One constraint's shadow prices.

primal's shape and arguments. A slice whose model had an integer variable contributes no duals. In the answer of an EachWindow sweep each coordinate carries the price of the window that owns it, never a blend of several.

The value of expression at every slice's solution, as an answer.

evaluate over the sweep, with primal's shape. A declared name is read from what the sweep holds, live or off disk. Anything else is valued at each slice's own solution with no re-solve, which needs the spec, sources and axis the sweep load_archive hands back carries; a Sweep a live solve returned retains no model. An expression over a parameter the sweep carried is refused, that value being a previous slice's answer rather than stored data.

In an EachWindow sweep's answer each coordinate carries the value of the window that owns it, so a sum does not double-count the lookahead.

One variable's answer.

A slice that reached no solution contributes no rows, so this can be shorter than the sweep; record is one row per slice always.

Everything the sweep holds, per slice, in the layout spill_to= writes.

<kind>/<name>/<position>.parquet for every primal, dual and expression, the slice key a column of each, with record/, metrics/ and the manifest beside them. scan reads it, and the call that made this sweep, pointed at it with spill_to=, reads it back without solving a slice. A sweep whose every slice terminated without values writes each slice's record and no frames.

One name's answer as a polars.LazyFrame: primal, dual or evaluate, not collected.

On a sweep whose frames lie on disk — solved with spill_to=, or read by scan_sweep or scan_archive — nothing is read until the frame is collected, so a filter or a select runs before the bytes move.

One name's answer as a xarray.DataArray; to_pandas's arguments.

An EachWindow sweep's answer is indexed by the dimension it sliced. Any other sweep adds the slice key as a dimension named by the axis, (scenario, …), and a read per window adds <dim>_start; there a slice that reached no solution comes back NaN, as a masked coordinate does from Result.

The named answers of one kind as one xarray.Dataset; all of that kind by default.

One name's answer as a tidy pandas.DataFrame; scan's arguments.

The name is resolved before pandas is imported, so a sweep that never held name says so on any install.

The sizes, counters and clocks as one value — the row archive= records beside the answer.

Metrics says what each field means. A phase this build never entered reads zero, and specsolve_run is null.

The row a solve that terminated this way writes; each argument fills the column of its name.

status is derived from termination_condition, objective is kept only where has_primal says there are values, and provenance fills its own fields' columns.

This row less earlier's counts and clocks: the share of the solves between the two.