Metadata-Version: 2.4
Name: drto
Version: 0.0.0
Summary: Dynamic real-time optimization: receding-horizon NMPC and moving horizon estimation for Pyomo models.
Project-URL: Homepage, https://github.com/devin-griff/drto
Project-URL: Repository, https://github.com/devin-griff/drto
Project-URL: Issues, https://github.com/devin-griff/drto/issues
Author-email: Devin Griffith <dwg176@gmail.com>
License-Expression: BSD-3-Clause
License-File: LICENSE
Keywords: dae,dynamic-optimization,mhe,moving-horizon-estimation,nmpc,pyomo,receding-horizon
Classifier: Development Status :: 1 - Planning
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.10
Requires-Dist: pyomo>=6.8.1
Provides-Extra: dev
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Provides-Extra: examples
Requires-Dist: jupyter; extra == 'examples'
Requires-Dist: matplotlib; extra == 'examples'
Requires-Dist: numpy; extra == 'examples'
Description-Content-Type: text/markdown

# drto

Dynamic real-time optimization: receding-horizon optimization and
estimation for Pyomo models, with advanced-step NMPC as the headline
capability and moving horizon estimation as the planned follow-on.

## The six 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.

|  | Simulation | Optimization | Estimation |
| --- | --- | --- | --- |
| **Steady-state** | solve the model at equilibrium | economic RTO | data reconciliation |
| **Dynamic** | integrate the model forward | NMPC / D-RTO | moving horizon estimation |

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: steady-state
collapses the model to a single equilibrium point, dynamic keeps the time
horizon. 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, real-time, and advanced-step execution variants are the headline,
plus steady-state RTO. Estimation is the planned follow-on.

## Declaring a control problem

drto is declaration-first, and each declaration tags a Pyomo component you
already wrote: a Variable, a Constraint, or a Parameter. You build your dynamic model as
an ordinary `pyomo.dae` 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 pieces are the
object types of an optimal control problem (the dynamic-optimization
mode):

| DRTO object type | Pyomo object type | Declaration | What it is |
| --- | --- | --- | --- |
| State | Variable | `declare_state(m.z, ...)` | A differential state. drto reads its dynamics from the state's `DerivativeVar`. |
| Control | Variable | `declare_control(m.u, ..., wrt=m.t, profile=...)` | A manipulated input, the decision variable. The `profile` flag sets its parameterization (piecewise-constant, ...) via pyomo-cvp. |
| Tracking stage cost | Constraint | `declare_tracking_stage_cost(m.tracking_stage_con)` | Equality defining the setpoint-tracking running cost; its left-hand-side scalar goes in the objective. The setpoint it references is the declared steady-state Param (below). |
| Economic stage cost | Constraint | `declare_economic_stage_cost(m.economic_stage_con)` | Equality defining the economic running cost; the same objective the steady-state RTO mode uses. |
| Tracking terminal cost | Constraint | `declare_tracking_terminal_cost(m.tracking_terminal_con)` | Equality defining the terminal tracking cost; its left-hand-side scalar goes in the objective. |
| Initial condition | Constraint | `declare_initial_condition(m.init_con)` | Equality anchoring the initial state; left-hand side is the state at t0, right-hand side the feedback. |
| Terminal constraint | Constraint | `declare_terminal_constraint(m.terminal_con)` | Constraint on the states at the final time; the terminal set the final state must lie in. |
| Steady-state target | Parameter | `declare_steady_state(m.z_ss)` | The state setpoint the tracking costs drive toward; populated by the steady-state/RTO solve. |
| Steady-state control target | Parameter | `declare_steady_state_control(m.u_ss)` | The control setpoint the tracking costs drive toward. |

Conventions drto enforces on those constraints: the cost and
initial-condition constraints are equalities whose left-hand side is the
scalar the declaration is about (the cost term, or the anchored state); 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.

Two things you never declare, because they already live in the model: the
**dynamics** are read from the `pyomo.dae` `DerivativeVar`s of the
declared states, and 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.

| DRTO object type | Pyomo object type | Declaration | What it is |
| --- | --- | --- | --- |
| Estimated parameter | Variable | `declare_estimated_parameter(m.theta, ...)` | Unknown model parameters to estimate, constant over the window. Shared with steady-state data reconciliation. |
| Disturbance | Variable | `declare_disturbance(m.w, ...)` | Process-noise variables (`dz/dt = f + w`) the estimator adjusts to fit the data, penalized by their covariance. |
| Measurement | Parameter | `declare_measurement(m.y_meas, ...)` | The measured values in the estimation cost residuals; a mutable Param drto refreshes each step. |
| Estimation stage cost | Constraint | `declare_estimation_stage_cost(m.est_stage_con)` | Equality defining the running estimation cost: measurement residual plus process-noise penalty over the window. |
| Estimation terminal cost | Constraint | `declare_estimation_terminal_cost(m.est_terminal_con)` | Equality for the current-time measurement residual (no process noise leads out of the last point). |
| Arrival cost | Constraint | `declare_arrival_cost(m.arrival_con)` | Equality for the soft prior on the window's initial state; its weight is updated by covariance propagation. |

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.

## Status

Design phase: see [DESIGN.md](DESIGN.md). No code yet.
