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]).

This axis as plain data, which solve_over takes in its place.

json.dumps writes it, and an archive's axis.json is this. It holds a carry key only where the axis carries something.

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 nothing is carried between them.

This axis as plain data, which solve_over takes in its place.

json.dumps writes it, and an archive's axis.json is this. It holds a carry key only where the axis carries something.

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.

The rows and bounds that make the last solve infeasible, by declaration and coordinate.

The verb for this model has no solution and I do not know why. It asks the solver that ran the last solve for an IIS (irreducible infeasible subsystem). The search runs only on this call, since it can cost more than the solve, and under the solve's solver_options, so a solver's IIS settings and time limit go there. Read a member row's terms with row.

Every sink finds one for a linear model. For a discrete model, every sink leaves out the integrality that makes the rows and bounds conflict, and highs can find none where integrality causes the conflict.

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; diagnostics counts the solves that loaded it again.

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. Carried only where the solve was asked for it with outputs={'activity'}.

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.

The basis status of each row of constraint name where the solve ended — (dims…, value), dual's shape and order.

In variable_basis's words, with the right-hand side as the row's bound: a binding <= row is at_upper, a binding >= row at_lower, a binding == row fixed, and a row that is not binding basic. Carried only where the solve was asked for it with outputs={'basis'}, and only an LP that ended on a basis has one.

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.

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:.

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.

Reduced costs of variable name — (dims…, value), primal's shape and order.

Each is the rate at which the optimal objective rises as the variable's binding bound rises, in the sign convention of dual for every sense and sink: of x >= l, the rate in d of x >= l + d. A variable strictly between its bounds has zero.

It is computed from the duals as the objective's gradient less each row's gradient times that row's dual, so it exists wherever dual does and nowhere else. Carried only where the solve was asked for it with outputs={'reduced_cost'}.

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, and spec.yaml the spec it answered. Beside them are primal/<name>.parquet per variable, dual/<name>.parquet per constraint where the duals are defined, expression/<name>.parquet per named expression this data can evaluate, and <output>/<name>.parquet for each Output the solve was asked for, such as activity/ per constraint. 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 and the spec alone. The same model and data write the same bytes.

format.json stamps the layout, the specsolve that wrote it and the outputs the answer carries: {"layout": 4, "specsolve": "…", "outputs": ["activity"]}. 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.

How far constraint name is from binding at the solution — (dims…, value), dual's shape and order.

Non-negative wherever the row holds, whichever side a term is written on: rhs - lhs for <=, lhs - rhs for >=, and -|rhs - lhs| for ==, which holds only at zero. A binding row reads zero, and a violated one, such as at an incumbent within the solver's tolerance, reads below zero by how much. Computed from activity, so readable wherever it is, and carried only where the solve was asked for it with outputs={'slack'}.

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, expression, or the reader of an Output the solve was asked for. Needs pandas, which specsolve does not install; the xarray bridges need xarray too.

The basis status of each column of variable name where the solve ended — (dims…, value), primal's shape and order.

value is one of basic, at_lower, at_upper, fixed (nonbasic at bounds that are equal) and superbasic (nonbasic between its bounds), in that order as an Enum, the same words for every sink. Carried only where the solve was asked for it with outputs={'basis'}, and only an LP that ended on a basis has one.

One constraint's left-hand side at every slice's solution.

primal's shape and arguments, and carried only where the sweep was asked for it with outputs={'activity'}. In the answer of an EachWindow sweep each coordinate carries the window that owns it.

One constraint's basis status where every slice's solve ended.

primal's shape and arguments, and Result.constraint_basis's words. Carried only where the sweep was asked for it with outputs={'basis'}. A slice that ended on no basis contributes none.

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.

One variable's reduced costs at every slice's solution.

primal's shape and arguments, and Result.reduced_cost's sign. Carried only where the sweep was asked for it with outputs={'reduced_cost'}. A slice whose model had an integer variable contributes none, as it contributes no duals.

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

<kind>/<name>/<position>.parquet for every primal, dual, expression and output it carries, 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, evaluate or an output, 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 constraint's distance to binding at every slice's solution.

primal's shape and arguments, and Result.slack's sign. Carried only where the sweep was asked for it with outputs={'slack'}.

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.

One variable's basis status where every slice's solve ended.

primal's shape and arguments, and Result.variable_basis's words. Carried only where the sweep was asked for it with outputs={'basis'}. A slice that ended on no basis contributes none.

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.