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=, 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. The solver's own number, not a recomputation. Readable whenever there is a solution, a mixed-integer one included. On an == row it equals the right-hand side up to solver tolerance.

Release what this result holds early. Optional.

Its frames and its hold on the label frames of the build it answered. Frames already read stay valid. The model and the solver are the Model's to close.

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

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 definition of dual(c), and it holds for every comparator, under either sense and on every sink, so which side a term is written on decides the sign.

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 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 together, 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. The sign is the row's own, the same on every sink. Where every column is held only by a lower bound of zero, the proof is Σ 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.

Anything but a declared name lowers the spec as written, which costs what check costs. An undeclared expression is not written by save or spilled by a sweep; 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.

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; a solve that reached no objective writes null there rather than nan. Then primal/<name>.parquet for every variable, dual/<name>.parquet for every constraint where the duals are defined, activity/<name>.parquet for every constraint, and expression/<name>.parquet for every named expression this data can evaluate. The same model and data write the same bytes.

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.

format.json stamps the directory with the layout it is written in and the specsolve that wrote it: {"layout": 1, "specsolve": "…"}. Every reader refuses another layout 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.

The directory holds this answer and no other: whatever a previous save left there is removed first. 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.

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 is stitched from what the sweep holds, live or off disk. Anything else is valued at each slice's own solution with no re-solve, so it is available on the sweep load_archive hands back, which carries the spec, sources and axis; a Sweep a live solve returned says it 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.

Over the original index each coordinate carries the value of the window that owns it — the recomputed lookahead rows are dropped, so summing the stitched frame does not double-count.

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: (scenario, …) or (<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 indexes the array by the dimension the axis sliced instead, so a rolling horizon's dispatch 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, since a dual and a variable may share a name; save 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. Metrics says what each field means. A phase this build never entered reads zero, and run is null.

The row a solve that terminated this way writes.

status is derived from termination_condition.