drto

DRTO is a unified framework for dynamic real-time optimization built on Pyomo.

Status

Alpha. The registry (drto.info), the declaration surface, objective assembly, the control-profile application, and the infinite-horizon terminal segment (features 001-004 and 017) are implemented and tested; the mode transforms, initializers, and closed-loop frameworks follow. The feature statuses live in features/README.md, and DESIGN.md remains the design record.

Install

pip install drto

The pounce solver and pyomo-pounce are needed for full functionality (sensitivity updates, the advanced-step frameworks); any NLP solver runs the open-loop modes.

Spec-driven development

drto is built spec-first: every feature is specified under features/ before it is implemented, as a short doc with a status, a user-story description, a benefit hypothesis, and acceptance criteria that drive the tests. See features/README.md. A feature request may be made by opening a pull request that adds a feature file under features/ in the template format.

Modes

drto runs one declared model in any of six modes, the 2x3 grid of {steady-state, dynamic} by {simulation, optimization, estimation}. You write the model once; the mode fixes what is free and what the objective is.

Down the columns: simulation frees nothing and solves the model as given; optimization frees the controls and adds a cost; estimation frees the states and fits them to measurements. Across the rows: the steady-state modes solve at a single equilibrium point, the dynamic modes keep the time horizon. A dynamic model is collapsed to that equilibrium, and a model authored directly as steady-state, with no time or dynamics, runs in the steady-state modes as it stands, so a user can define the model either way and still use it across the modes. The optimization and estimation columns are duals (NMPC with MHE, RTO with reconciliation), so one declaration surface serves both.

The near-term focus is the optimization column: dynamic NMPC/D-RTO, whose ideal, nonideal, and advanced-step execution variants are the headline, plus steady-state RTO. Estimation is the planned follow-on.

Transformations

The six modes above are each a single solve exposed as a Pyomo transformation under the drto. namespace, alongside the lower-level transformations they compose. You build one declared model and apply the transformation you want, the same way you apply any Pyomo transformation.

Closed-loop frameworks

Separately from the modes come the closed-loop frameworks: the dynamic optimization loop in ideal, nonideal, and advanced-step forms (drafted as features 014-016), and the estimation loops, specced later.

The advanced-step column, asnmpc and asMHE, is built on drto.advanced_step_controller: it solves the horizon at a predicted state and then corrects to the actual state with a fast pounce sensitivity update rather than a re-solve.

Initialization routines

A good initial guess is often the difference between an IPOPT solve that converges and one that stalls, so drto provides named initializers rather than leaving each user to hand-roll one. These are plain functions, not transformations: they leave the model structure alone and only populate the variable values (the initial guess), so there is no apply_to or create_using form.

warm_start_dynamic is really a loop operation that belongs with the closed-loop frameworks, listed here alongside its siblings for completeness.

Declaring an optimization or simulation problem

drto is declaration-first, and each declaration tags a Pyomo component you already wrote: a Variable, a Constraint, a Parameter, or a Set. You build your dynamic model as an ordinary Pyomo model, then point the declarations at its pieces; drto assembles the horizon problem and runs the loop. It bolts onto an existing model rather than replacing how you build one. The same functions also wrap construction (m.z = state(pyo.Var(m.t)) registers at attachment), and the constraint-role declarations double as decorators (@drto.dynamics(m, m.t)); the styles mix freely per component (feature 002 shows both in full). The pieces are the object types of a dynamic optimization or simulation problem:

Conventions drto enforces on those constraints: the cost and initial-condition constraints are equalities with the scalar the declaration is about (the cost term, or the anchored state) on one side, either orientation; a stage cost applies at every sample point except the final one, where only the terminal cost applies; a terminal constraint may reference only states at the final time, which is what separates it from a path constraint. The objective is drto's own: it sums the declared cost terms that are live in the current mode, so a mode drops a term just by leaving out its constraint.

One modeling practice worth following: leave cost variables unbounded. The defining equality already fixes each cost value (a sum of squares is nonnegative without being told), and a NonNegativeReals bound puts the optimum exactly on the bound wherever the cost vanishes, at settled samples on long horizons or through an infinite-horizon tail at equilibrium, which drags interior-point solvers (measured on the Hicks example at N = 50: 43 ipopt iterations bounded, 6 unbounded, identical solutions).

One thing you never declare, because it already lives in the model: the path constraints are the state variables' own upper and lower bounds.

The vocabulary is the optimal-control literature's own (stage cost, terminal cost, terminal constraint), so a model reads the way the theory does. The other modes reuse the same model: simulation drops the cost, and estimation swaps the initial condition for a soft arrival cost and adds the estimation pieces below.

Declaring an estimation problem

Estimation is the dual half (moving horizon estimation, the planned follow-on), and it declares its own pieces the same way. MHE fits the model to a moving window of measurements, so the free variables and the objective terms differ, but the conventions carry over: each declaration tags a Var, a Constraint, or a Param, and drto assembles the estimation objective from the live cost terms.

The arrival cost is the soft dual of the control side's initial condition, and the estimation stage and terminal costs are the measurement-fitting counterparts of the tracking costs.