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]). Pairs, so a window's ownership is not in them: solved as a list the slices key by key_name=, original_index is refused and a carry cannot collapse a dimension.

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: every field is a count, a clock or a small frame the engine keeps, not a read of the model it releases. A raise leaves the sizes at zero — they are taken once a model is whole — and everything measured before it stands.

An ad-hoc expression reader over a saved solution, put back against this build.

What an archive and a sweep hand evaluate for a quantity the file never named: the saved frames are laid back in this build's label order, and the reader is the one a live solve gives. A build, never a solve.

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. to_latex and its siblings render the spec as math before any data, and dual gives a row's number without its terms; this gives the row the build actually produced, at the coordinate you name.

Reads the built model and needs no solve, so it answers on a model that never reached a solver — and it is the built row, so a term whose variable was absent is missing from it and a row a where masked out is not there at all. It shows what the model says rather than what the file appears to say. 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 skips the hand-off and only its numbers are pushed. Whether the work that solver did is kept too is keep, off by default. How much this solve actually kept is its kept.

Put new numbers on the same model, in place.

::

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

Any new data is accepted: 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 instead of pushed onto a loaded solver, and loads says which ran.

Results taken before the update keep reading: each owns the frames it reads, and an update builds new ones rather than touching those. A retained result keeps its build's label frames alive until it is dropped or close is called.

A loop whose next numbers depend on the last answer is this; a sweep, a rolling horizon or a myopic pathway is solve_over, which runs the 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, and the other half of a row's story: how far each row's Σ aᵢxᵢ sits from its bound. The solver's own number, not a recomputation. Readable whenever there is a solution — unlike dual it is well-defined on a mixed-integer model. On an == row it equals the right-hand side up to solver tolerance by construction.

Release what this result holds early. Optional.

Its frames, which carry both its own values and its hold on the label frames of the build it answered. Frames already read stay valid. Never the model or the solver, which are the Model's to close.

Shadow prices of constraint name — (dims…, value).

primal's shape and order, over constraint rows. Duals exist only where a solver ran here: a model written to a file and solved elsewhere never passes back through this package. Reduced costs and slacks are not read.

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

The one thing an infeasible solve has to say, and the only reader that answers on one: primal, dual and activity all raise there, because there is no solution behind them. Weight every row by its value here and add them together, and the combined row demands more than the columns can deliver inside their bounds — which is the proof that nothing satisfies all of them at once. That is what a Benders feasibility cut is built from, and it is why a driver no longer needs a second model to ask how far from feasible a subproblem was.

dual's shape and order. The sign is the row's own, one convention across every sink, so a driver never asks who solved — a sink whose solver signs the other way negates what it reads. Where every column is held only by a lower bound of zero, as a dispatch variable is, the bounds deliver nothing and the proof is the simpler Σ weight * right-hand side > 0.

A certificate is computed only where it was asked for. highs always produces one; 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).

expression is what one expressions: entry takes: a name the file declares, an expression string, or the mapping carrying cases: with dims: and otherwise:. It may use every name the model declares and only those. The value is aggregated to the expression's own dims, in declaration order, rows in label order over them — primal's shape and order.

A declared name is served by its own reader, compiled on this call and never lowered again, so a spec whose expressions go unread compiles none of them. Anything else lowers the spec as written, which costs what check costs. An undeclared expression names nothing, so it is not a kind: save does not write it and a sweep does not spill it. To keep a quantity, declare it 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, which is what keeps a solve that never asks free of it.

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 — how the solve terminated and what it reached, in the columns a sweep keys and folds. A solve that reached no objective writes null there rather than nan, so a directory per case is a table an aggregate reads. Then primal/<name>.parquet for every variable, dual/<name>.parquet for every constraint where the duals are defined, and expression/<name>.parquet for every named expression this data can evaluate — an integer variable leaves the duals out, and an expression that fails on this data is left out, evaluate still saying why. The primals are streamed to disk in primal's order, so the same model and data write the same bytes.

activity/<name>.parquet goes beside them for every constraint, which no kind= names — a sweep folds three kinds and never holds these, so a saved result carries them under a name of their own.

reasons.parquet holds (kind, name, reason) for whatever is deliberately not here, and is absent when everything is: one row per expression that failed, and one with an empty name for the duals, whose absence is never per-constraint. Written because a directory that simply lacks a file cannot tell "there is none, and here is why" from "no such name", which is the one thing dual and evaluate do say.

format.json stamps the directory with the layout it is written in and the specsolve that wrote it: {"layout": 1, "specsolve": "…"}. A release that changes what a result, a sweep or an archive writes raises the layout, and its notes say so. Nothing reads another layout back, and an answer 0.1.0 or earlier wrote carries none, so every reader refuses it with a LayoutError that says to solve the model again and save it.

A solve that left no values writes the record and nothing else. A run that came back infeasible is an answer a set of saved cases needs on disk, rather than a directory that does not exist.

The directory holds this answer and no other. Whatever a previous save left there is removed first, so a re-run cannot leave one model's frames beside another's record. Files that are not part of 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; all of that kind by default.

One kind per call: a dual and a variable of the same name would collide, and mean something else per row. 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.

Needs pandas, which specsolve does not install; the xarray bridges need xarray too.

One constraint's shadow prices across every slice, the key prepended.

primal's shape and arguments. A slice whose model had an integer variable contributes no duals; over the original index 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, the slice key prepended.

evaluate one dimension wider, and primal's shape and arguments. expression is what one expressions: entry takes: a name the file declares, an expression string, or the mapping carrying cases: with dims: and otherwise:.

A declared name was valued at each slice's solution when the fold read it, so it is stitched from what the sweep holds, live or off disk, and never lowered again. Anything else is valued at each slice's own solution with no re-solve: the slice's model is rebuilt from the archive's spec and that slice's cut of the sources, and its saved primal put back against it — so it is available on the sweep load_archive hands back, which carries the spec, sources and axis, and a Sweep a live solve returned says it retains no model. It reads only what an archive can put back: an expression over a parameter the sweep carried is refused, that value being a previous slice's answer rather than stored data.

Over the original index each coordinate carries the value of the window that owns it — the recomputed lookahead rows are dropped, which is what makes summing the stitched frame safe where summing per-window values double-counts.

One variable's values across every slice, the slice key prepended.

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, written as spill_to= would have written it.

The same layout: <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. So the directory is a spilled sweep: 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, as one such solve does, rather than refusing.

One name's values across every slice as a polars.LazyFrame, the slice key prepended.

The reader for a sweep solved with spill_to=, whose frames are on disk; on one held in memory it is primal, dual or evaluate made lazy, so the same line reads either.

One name's values as a xarray.DataArray, the slice key a dimension; to_pandas's arguments.

The extra dimension is named by the axis — a scenario sweep gives (scenario, …) and a window (<dim>_start, …). A slice that reached no solution has no rows and comes back NaN, the same answer a masked coordinate gets from Result. original_index=True gives the array over the dimension the axis sliced instead, so a rolling horizon's dispatch, or its price, comes back indexed by time.

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

One kind per call: a dual and a variable of the same name would collide, and mean something else per row. Name the few you need, or use save, which writes every kind.

No original_index: this and save export what the sweep holds, lookahead rows included.

One name's values across every slice as a tidy pandas.DataFrame.

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 an archive records.

What archive= records beside the answer, and what a caller feeding its own store reads off a model it solved. Which fields reach it and what it means cumulatively are Metrics's to say; a phase this build never entered reads zero there. run is null: the name is the publisher's, and nothing has published this yet.

The row a solve that terminated this way writes.

status is derived here rather than passed, and an objective is dropped to null here rather than at each writer.