Python API

The top-level continuo package exposes a small, focused API: a parser, a model object that wraps the parsed file with its solvers, and a solution object that wraps the solved path. The remaining modules (parser, IR, codegen, solve) are public to the extent that their exceptions are catchable by the user, but their internals are implementation details.

Entry points

continuo.parse(path)

Load a .mod file (macro expansion, parsing, IR) into a Model.

Parameters:

path (str | Path)

Return type:

Model

continuo.parse_string(source, *, base_dir=None)

Load model source given as a string into a Model.

Parameters:

• source (str)

• base_dir (str | Path | None)

Return type:

Model

The Model object

class continuo.api.Model(model)

Bases: object

A loaded model: its symbol table and the solver entry points.

Parameters:

model (ir.Model)

steady_state(*, exogenous=None, solver=None, options=None, nodomain=None)

Compute the steady state at the given exogenous configuration.

solver selects the nonlinear algorithm for the numerical path: a preset name ("newton", "hybr", "kinsol", "homotopy", …), a SteadySolver instance, or None — which falls back to the model’s steady(solver=…) directive, then to "auto". options configures a named preset (e.g. {"strategy": "picard"} for kinsol); when both are omitted, the directive’s solver and options are used. nodomain disables the domain change of variable (solve in raw x despite declared constraints); None defers to the model’s steady(nodomain) directive, an explicit bool overrides it.

Parameters:

• exogenous (dict[str, float] | None)

• solver (str | SteadySolver | None)

• options (dict[str, object] | None)

• nodomain (bool | None)

Return type:

dict[str, float]

simul(*, horizon=None, intervals=None, scheme=None, order=None, adapt=None, monitor=None, solver=None, steady_solver=None, steady_solver_options=None)

Run the perfect-foresight simulation, returning a Solution.

horizon / intervals / scheme / order override the model’s simulate command; order selects the collocation order of a multi-stage scheme (the family default when None). adapt turns on adaptive mesh refinement to the given error tolerance, driven by monitor ("residual" by default, or "richardson"); both override the directive. solver selects the linear backend: a preset name ("superlu", "auto"), a LinearSolver instance, or None (the "auto" default). steady_solver selects the nonlinear algorithm for the internal steady-state solves, overriding the steady(solver=…) directive, and steady_solver_options configures it.

Parameters:

• horizon (float | None)

• intervals (int | None)

• scheme (str | None)

• order (int | None)

• adapt (float | None)

• monitor (str | None)

• solver (str | LinearSolver | None)

• steady_solver (str | SteadySolver | None)

• steady_solver_options (dict[str, object] | None)

Return type:

Solution

The Solution object

class continuo.io.solution.Solution(segments, names, diagnostics=<factory>, converged=True)

Bases: object

A solved path over [0, T], glued from one or more segments.

Parameters:

• segments (tuple[Segment, ...])

• names (tuple[str, ...])

• diagnostics (dict)

• converged (bool)

to_dataframe()

Return the path as a time-indexed pandas.DataFrame.

to_xarray()

Return the path as an xarray.Dataset over the time coordinate.

A Solution aggregates one or more Segment records (one per active belief — see The shocks block):

class continuo.io.solution.Segment(start_time, times, path, names, info_set, terminal_ss, iterations)

Bases: object

One realised segment of the path and the regime it was solved under.

Parameters:

• start_time (float)

• times (ndarray)

• path (ndarray)

• names (tuple[str, ...])

• info_set (dict[str, float])

• terminal_ss (dict[str, float])

• iterations (int)

Diagnostics

Solution.diagnostics is a free-form dict populated by the solver with run-level summary information. The keys currently set are:

scheme (str)

The discretisation scheme that was used (e.g. "crank_nicolson"). Matches the scheme argument of the simulate command.

segments (int)

Number of perfect-foresight segments the orchestrator solved. Equals 1 when no surprise revelations split the horizon, and 1 + k when k surprise reveal times fall inside [0, T].

newton_iterations (int)

Total Newton iterations summed across all segments. A sudden jump from one run to the next — same model, similar parameters — usually means the new instance is closer to a singularity or the initial guess is poorer; inspect the per-segment counts via [seg.iterations for seg in sol.segments].

equidistribution_ratio (float)

A cheap grid-adequacy hint: the max / mean of the per-interval curvature over the solved path. Near 1 the grid is well balanced; >> 1 flags resolution misallocated relative to where the solution bends, i.e. a candidate for adaptive refinement. See Time grids and adaptive refinement.

solver (str)

The linear backend that was used (e.g. "klu", "superlu"). See Linear solvers.

factorizations / refactorizations (int)

How many full factorisations versus cheap refactorisations the backend performed over the run. With the cross-segment warm-start, later segments refactor from the first segment’s factorisation rather than re-analysing, so refactorisations dominate.

refactor_fallbacks (int)

How many times a reused factorisation failed (a stale-pivot re-pivot) and was redone from scratch. Normally 0.

min_rcond (float or None)

The worst reciprocal-condition estimate seen over the run, or None when the backend exposes none (SuperLU, PARDISO).

fill (int or None)

The factorisation fill nnz(L) + nnz(U), where the backend exposes it (SuperLU, UMFPACK); None otherwise.

The same summary is also emitted at logging.INFO level on the continuo.solve.orchestrator logger, so a caller that configures logging.basicConfig(level=logging.INFO) will see one line per run without having to read the dict.

The set of keys may grow in future releases; treat unknown keys as informational and the documented ones as the stable contract.

Exceptions

Each pipeline stage raises a dedicated exception so user code can distinguish where a problem originated. All four inherit from Exception (not from one another); a CLI-style “any pipeline error” catch is except (MacroError, LarkError, IRError, CodegenError, SolveError).

exception continuo.macro.MacroError(message, *, file=None, line=None)

Bases: Exception

A macro-layer error, optionally carrying a source position.

The expression layer raises these without a position; the expansion driver attaches file/line as it unwinds.

Parameters:

• message (str)

• file (str | None)

• line (int | None)

exception continuo.ir.IRError(message, pos=None)

Bases: Exception

A semantic error, optionally carrying a source position.

pos refers to the post-macroexpansion source; callers holding the macro line map format it back to the user’s original file.

Parameters:

• message (str)

• pos (SourcePos | None)

exception continuo.codegen.CodegenError(message, pos=None)

Bases: Exception

A lowering error, optionally carrying a source position.

Parameters:

• message (str)

• pos (SourcePos | None)

exception continuo.solve.SolveError

Bases: Exception

A numerical solve failure.