drto 0.0.0__tar.gz

drto-0.0.0/.githooks/README.md

@@ -0,0 +1,25 @@
+# Git hooks
+
+Tracked hooks for this repo. They are **not active until you opt in**:
+`core.hooksPath` is local git config and does not travel with a clone.
+
+Enable once per clone:
+
+```sh
+git config core.hooksPath .githooks
+```
+
+## `pre-commit`
+
+Runs `black --check src/ tests/`, the same gate CI enforces, and rejects the
+commit if any file is not black-clean. This keeps formatting drift from
+reaching CI.
+
+Fix a rejection with:
+
+```sh
+make fmt
+git add -u
+```
+
+Bypass for a single commit with `git commit --no-verify` (discouraged).

drto-0.0.0/.githooks/pre-commit

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+# Reject commits that are not black-clean, mirroring CI's `black --check`
+# gate so formatting drift never reaches CI. Enable with:
+#
+#     git config core.hooksPath .githooks
+#
+# Bypass for a single commit with `git commit --no-verify` (discouraged).
+set -euo pipefail
+
+if ! command -v black >/dev/null 2>&1; then
+    echo "pre-commit: black not found on PATH; skipping format check" >&2
+    exit 0
+fi
+
+if ! black --check src/ tests/; then
+    echo >&2
+    echo "pre-commit: black check failed; run 'make fmt', re-stage, and commit again." >&2
+    exit 1
+fi

drto-0.0.0/.github/workflows/ci.yml

@@ -0,0 +1,56 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      # Pinned so CI formatting matches what the code was formatted with.
+      - run: python -m pip install black==24.8.0
+      - run: black --check --diff src/ tests/
+      - uses: crate-ci/typos@v1.48.0
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: python -m pip install -e ".[dev]"
+      - run: python -m pytest -q --cov=drto --cov-report=term-missing
+
+  import-base:
+    # The package must import with only its base (non-dev) dependencies.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - run: python -m pip install -e .
+      - run: python -c "import drto; print('drto', drto.__version__)"
+
+  min-deps:
+    # Exercise the declared floor: oldest supported Python and minimum Pyomo.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.10"
+      - run: python -m pip install -e ".[dev]"
+      - run: python -m pip install "pyomo==6.8.1"
+      - run: python -m pytest -q

drto-0.0.0/.github/workflows/publish.yml

@@ -0,0 +1,50 @@
+name: publish
+
+# Publishes to PyPI on a version tag (e.g. `git tag v0.1.0 && git push --tags`).
+# Uses PyPI Trusted Publishing (OIDC) -- no API token needed, but the project
+# must be configured for trusted publishing on PyPI first (one-time setup).
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write  # required for trusted publishing
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - name: Build sdist and wheel
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  # Cut a GitHub Release for the same tag, with notes lifted from the matching
+  # CHANGELOG section, so the repo's Releases page tracks the PyPI versions.
+  github-release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write  # required to create the release
+    steps:
+      - uses: actions/checkout@v7
+      - name: Extract release notes from CHANGELOG
+        run: |
+          version="${GITHUB_REF_NAME#v}"
+          awk -v ver="$version" 'BEGIN{s="## [" ver "]"} index($0,s)==1{f=1;next} f && index($0,"## [")==1{exit} f{print}' CHANGELOG.md | grep -vE '^\[[^]]+\]: ' | sed '/./,$!d' > release_notes.md
+          if [ ! -s release_notes.md ]; then
+            echo "${GITHUB_REF_NAME}. See CHANGELOG.md for details." > release_notes.md
+          fi
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh release create "$GITHUB_REF_NAME" \
+            --title "$GITHUB_REF_NAME" \
+            --notes-file release_notes.md \
+            --verify-tag

drto-0.0.0/.gitignore

@@ -0,0 +1,29 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Coverage
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+
+# Environments
+.venv/
+venv/
+env/
+
+# Notebooks
+.ipynb_checkpoints/
+
+# Editors / OS
+.vscode/
+.idea/
+.DS_Store

drto-0.0.0/AGENTS.md

@@ -0,0 +1,81 @@
+# Agent guide for drto
+
+drto is a Python package: receding-horizon NMPC and moving horizon estimation
+for `pyomo.dae` models. This file is the entry point for coding agents. Read
+it before working in this repo.
+
+## Status: design phase
+
+There is no implementation yet. The design is settled and recorded:
+
+- **DESIGN.md** is the authoritative design record: the six-mode framework,
+  the declaration surface, and every locked decision.
+- **README.md** is the user-facing overview of the same.
+
+Treat both as the source of truth. Before touching anything on the
+declaration or API surface, read DESIGN.md. A decision logged there as
+`USER DECISION <date>` is authoritative: do not silently reverse or
+reinterpret it. If new work seems to require changing one, surface it and
+ask, do not just diverge.
+
+## Repo conventions
+
+Canonical commands (they mirror CI, so local green means CI green; do not
+hand-roll black or pytest flags):
+
+- `make dev` -- editable install with dev extras.
+- `make lint` -- `black --check` plus `typos`.
+- `make test` -- `pytest` with coverage.
+- `make check-imports` -- import drto with only base deps.
+
+If `make` is not on PATH (a bare Windows shell), the targets are thin
+wrappers: run `black --check --diff src/ tests/`, `typos`, and
+`python -m pytest` directly. `make help` (or reading the Makefile) lists the
+exact command behind each target.
+
+This is a single pure-Python package that matches its siblings pyomo-cvp and
+pyomo-cp. When adding a file, copy the shape of the nearest sibling rather
+than inventing a new one.
+
+- **License:** BSD-3-Clause. Every source file carries the two-line header
+  `# Copyright (c) 2026 Devin Griffith` /
+  `# SPDX-License-Identifier: BSD-3-Clause`.
+- **Layout:** hatchling build, `src/drto/` package.
+- **Formatting:** Black, line length 88, skip-string-normalization,
+  skip-magic-trailing-comma (Pyomo's own settings). Spell-check with `typos`.
+- **Versioning:** Keep a Changelog plus SemVer in `CHANGELOG.md`.
+- **Optional dependencies** go through
+  `pyomo.common.dependencies.attempt_import` so the package imports cleanly
+  when a backend (the pounce solver, pyomo-cvp) is absent. Prefer explicit
+  declaration over introspection throughout.
+- **Do not defer tech debt:** fix deprecated deps, outdated action versions,
+  and floating refs in the same pass you notice them.
+
+## Definition of done
+
+A user-facing change is not done until code plus a pinning `pytest`, a bullet
+under `## [Unreleased]` in `CHANGELOG.md`, and the relevant
+README/docstring/notebook update all land in the same change. See
+CONTRIBUTING.md.
+
+## House style
+
+No em dashes anywhere: code, comments, docs, commit messages, changelog.
+Short plain sentences. Comments state present-tense constraints and
+rationale, not development history. Design history lives in `dev-notes/` and
+`DESIGN.md`, not in code comments.
+
+## Intended module map (aspirational, grows from DESIGN.md)
+
+Not built yet; recorded so the first code lands in the right shape:
+
+- The declaration surface (`declare_state`, `declare_control`, the cost and
+  boundary declarations, the estimation declarations) is the public API.
+- One receding-horizon loop underlies the six modes (steady-state / dynamic
+  by simulation / optimization / estimation); the ideal / real-time /
+  advanced-step execution variants are variants of dynamic optimization, not
+  separate modes.
+- The sensitivity fast update rides on pyomo-pounce; control parameterization
+  on pyomo-cvp. Both are dependencies, not vendored.
+
+Grow this into a "how to drive drto" table once there is a runnable loop.

drto-0.0.0/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/), and the project adheres to
+[Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.0.0] - 2026-07-14
+
+### Added
+
+- Repository scaffolding and the PyPI name reservation. Design phase: the
+  declaration framework and the six modes are recorded in DESIGN.md and the
+  README. No functionality yet.
+
+[Unreleased]: https://github.com/devin-griff/drto/compare/v0.0.0...HEAD
+[0.0.0]: https://github.com/devin-griff/drto/releases/tag/v0.0.0

drto-0.0.0/CITATION.cff

@@ -0,0 +1,22 @@
+cff-version: 1.2.0
+message: "If you use drto in academic work, please cite it as below."
+title: "DRTO: A Unified Framework for Dynamic Real-Time Optimization"
+abstract: >
+  DRTO is a framework that provides steady-state and dynamic estimation, 
+  simulation, and optimization from a core Pyomo model, as well as the
+  moving-horizon machinery for implementations of dynamic real-time optimization.
+type: software
+license: BSD-3-Clause
+repository-code: "https://github.com/devin-griff/drto"
+url: "https://github.com/devin-griff/drto"
+authors:
+  - family-names: Griffith
+    given-names: Devin
+keywords:
+  - nmpc
+  - moving horizon estimation
+  - pyomo
+  - dynamic optimization
+  - receding horizon
+# TODO: add ORCID, the Zenodo DOI, and date-released once the first tagged
+# release is archived.

drto-0.0.0/CLAUDE.md

@@ -0,0 +1,3 @@
+# drto
+
+Agent instructions for this repo live in [AGENTS.md](AGENTS.md). Read them there.

drto-0.0.0/CONTRIBUTING.md

@@ -0,0 +1,40 @@
+# Contributing to drto
+
+This file is about getting a change *merge-ready*. The agent-facing
+conventions and the repo map live in [AGENTS.md](AGENTS.md).
+
+## Enable the git hooks (one-time)
+
+```sh
+git config core.hooksPath .githooks
+```
+
+The `pre-commit` hook runs `black --check`, mirroring CI so formatting drift
+never reaches `main`.
+
+## Definition of done for a user-facing change
+
+A change that adds or changes user-visible behavior is not done until **all
+three** of these land in the same PR:
+
+1. **Code + test.** The behavior, with a `pytest` that pins it.
+2. **CHANGELOG entry.** A bullet under the `## [Unreleased]` section of
+   `CHANGELOG.md`, in the user's terms. At release time the section is renamed
+   to the version and dated.
+3. **Docs.** The relevant README, docstring, or example-notebook update, so
+   the feature is documented where a user looks.
+
+## Run the CI guards locally before pushing
+
+These mirror the CI jobs; run them for fast feedback:
+
+```sh
+make lint    # black --check + typos
+make test    # pytest with coverage
+```
+
+## House style
+
+No em dashes anywhere: code, comments, docs, commits, changelog. Short plain
+sentences. Comments state present-tense rationale, not history; design history
+lives in `dev-notes/` and `DESIGN.md`.

drto-0.0.0/DESIGN.md

@@ -0,0 +1,251 @@
+## What it is
+
+DRTO is a framework that provides steady-state and dynamic estimation, 
+simulation, and optimization from a core Pyomo model, as well as the 
+moving-horizon machinery for implementations of dynamic real-time optimization.
+The intent is to apply to a broad range of model and problem types, with functionality 
+being built incrementally. 
+
+## The mode framework (six modes)
+
+drto is one framework over one declared model, run in any of six modes:
+the 2x3 grid of {steady-state, dynamic} by {simulation, optimization,
+estimation}. The mode fixes what is free and what the objective is; the
+model and (mostly) the declarations are shared.
+
+|  | Simulation | Optimization | Estimation |
+| --- | --- | --- | --- |
+| Steady-state | solve f(z,u)=0 for z at fixed u | economic RTO: optimize phi(z_ss, u_ss) | data reconciliation: fit z to steady data |
+| Dynamic | integrate the ODE forward (IVP) | NMPC / D-RTO over the horizon | moving horizon estimation (MHE) |
+
+- Columns are what the mode does with the degrees of freedom. Simulation
+  frees nothing and solves the square model. Optimization frees the
+  controls and adds a cost. Estimation frees the states (and parameters)
+  and fits them to measurements.
+- Rows are the time treatment. Steady-state collapses the model to one
+  point with every dz/dt = 0. Dynamic keeps the horizon and the
+  discretized dynamics.
+- The optimization and estimation columns are duals: one frees inputs to
+  minimize a cost, the other frees states to fit data. MHE is the dual of
+  NMPC, and steady-state reconciliation the dual of RTO. This is why one
+  declaration surface can cover both halves; the seams are the initial
+  anchor (a hard condition for control, a soft arrival cost for
+  estimation) and the measurement.
+
+## Steady-state reduction (setpoint consistency and economic RTO)
+
+A first-class feature: drto reduces the dynamic model to its
+steady-state problem, the same equations with every dz/dt = 0 at a
+single time point, solving f(z,u)=0 and g(z,u)=0 for an equilibrium
+(z_ss, u_ss). Two uses:
+
+1. **Setpoint consistency.** The tracking target is DERIVED from the
+   model, not hand-specified, so the state target and the control
+   target are a true fixed point of the dynamics by construction.
+   Motivating case (2026-07-13): a hand-typed Hicks CSTR tracking pair
+   (xss, uss) that was not an exact equilibrium: the control that
+   actually holds xss was v1 = 0.578, not the declared 0.583. The
+   controller could not zero both the state-tracking and the
+   control-tracking terms at once, so the controls never settled: they
+   drifted ~5e-4 at the tail hunting a compromise, at any horizon
+   (with a model-consistent uss the tail spread dropped ~100x to
+   4e-6). A model-derived setpoint removes the whole failure mode.
+
+2. **Economic RTO.** The same reduced problem plus an economic
+   objective phi(z_ss, u_ss) over the steady-state variables, subject
+   to constraints: the RTO layer that computes the economically-
+   optimal operating point, which the NMPC then tracks (or uses as an
+   economic-NMPC terminal reference). This is what makes the D-RTO
+   name literal: steady-state RTO is the dz/dt -> 0 limit of the
+   dynamic problem, so the dynamic controller and its setpoint
+   optimizer are one package.
+
+## Dependency stack
+
+- pyomo + pyomo.dae for modeling and discretization.
+- pyomo-cvp for piecewise-constant control parameterization
+  (`declare_profile`); the controls' declaration already lives there.
+  pyomo-cvp STAYS a standalone package (independently useful for
+  offline dynamic optimization, and a Pyomo upstream candidate); drto
+  depends on it and re-exports the declarations so users get one
+  import surface. Revisit only if the warm shift needs to reach inside
+  cvp's substitution machinery.
+- pyomo-pounce (pounce >= 0.8.0) for the in-process solve session,
+  sensitivity gradients, and the `estimate()` fast update (merged as
+  jkitchin/pounce#199). The estimation-side machinery (covariance with
+  hessian="lagrangian"|"gauss-newton" and active-bound projection)
+  merged as #203 on 2026-07-12; it ships in the release after 0.8.0.
+- pounce coupling is a hard dependency for v1: simpler and honest about
+  what works today. A sensitivity-backend interface (with k_aug as a
+  legacy alternative) was considered and deferred.
+
+## Declarations
+
+Explicit declarations throughout, matching the pyomo-cvp / pyomo-pounce
+family. USER DECISION: no DerivativeVar introspection for states. The
+divergence cases that killed auto-detection: quadrature/cost
+accumulators carry DerivativeVars but are not plant states; spatial
+derivatives are not temporal states; quasi-steady treatments; discrete
+time or hand-discretized models have states but no DerivativeVars; and
+no structure implies the measured vs unmeasured distinction MHE will
+need.
+
+Each declaration tags a Pyomo component the user already wrote, a Var, a
+Constraint, or a Param (USER DECISION 2026-07-14): the point is to bolt
+onto an existing pyomo.dae model, not to introduce a new modeling
+framework. State and control tag Vars; the cost and boundary declarations
+tag Constraints; the measurement and steady-state targets tag Params. The
+control-scope declaration surface (the estimation-side surface follows
+below):
+
+- `declare_state(m.z1, m.z2, ...)`: tags the differential-state Vars. Varargs,
+  indexed-container-aware (one call declares all members). drto then picks
+  up each state's dynamics automatically from its DerivativeVar (USER
+  DECISION 2026-07-14, good-enough starting point; no `declare_dynamics`).
+  This is NOT the rejected state auto-detection: the state role is still
+  declared, and the DerivativeVar only locates the ODE of an
+  already-declared state.
+- `declare_control(m.u, ..., wrt=m.t, profile=...)`: tags the
+  manipulated-input Vars, the free decision variables. The `profile` flag folds in the
+  control's parameterization: `declare_control` calls pyomo-cvp's
+  `declare_profile` automatically (USER DECISION 2026-07-14). One call
+  declares the control and its parameterization; cvp stays the dependency
+  that implements the parameterization underneath.
+- `declare_tracking_stage_cost(m.tracking_stage_con)`: tags the equality
+  Constraint defining the setpoint-tracking running cost (the
+  ||z - z_ss|| + ||u - u_ss|| regulation penalty). LHS a lone scalar Var;
+  drto adds it to the objective it assembles. The tracking targets are the
+  declared steady-state Params (`declare_steady_state` /
+  `declare_steady_state_control` below), populated by the steady-state/RTO
+  solve. The RHS is however the user expressed the accumulated cost (a
+  finite-element sum, a pyomo.dae Integral, an accumulator's terminal
+  value): drto does not care as long as it resolves to the LHS scalar.
+- `declare_economic_stage_cost(m.economic_stage_con)`: tags the equality
+  Constraint defining the economic running cost phi(z, u). Same LHS-scalar
+  convention. This is the same economic objective the steady-state RTO
+  mode optimizes at its single point, so one declaration serves economic
+  NMPC and RTO both (economic NMPC itself is post-v1; RTO uses it in v1).
+  USER DECISION 2026-07-14: split the running cost into tracking and
+  economic terms so a mode selects which is live.
+- `declare_tracking_terminal_cost(m.tracking_terminal_con)`: tags the
+  equality Constraint defining the terminal (Mayer) tracking cost
+  V_f(z(tN)), the terminal regulation penalty. Same LHS-scalar convention;
+  drto adds the terminal-cost Var to the objective. Dropped in
+  steady-state (see the objective note below). Renamed from
+  `declare_terminal_cost` for clarity against the economic term (USER
+  DECISION 2026-07-14).
+- `declare_initial_condition(m.init_con)`: tags the equality Constraint
+  anchoring the initial state, LHS the anchored state at t0. If the RHS is
+  a mutable Param, that Param is the feedback-injection point drto updates
+  each step, so this convention doubles as the state-feedback hook (z_hat)
+  for the online loop. Named "condition" deliberately: it pins the state
+  (an equality), a different job from a boundary set. This is the exact
+  seam where MHE will diverge, since its initial anchor is the soft
+  arrival cost, not a hard equality, so a soft mode or a separate
+  `declare_arrival_cost` is the estimation follow-on, not this.
+- `declare_terminal_constraint(m.terminal_con)`: tags the Constraint
+  (equality or inequality) defining the terminal set/region z(tN) in X_f.
+  Requirement (USER DECISION 2026-07-14): every Var it references is a
+  declared state at tN, the final time; a control at tN is excluded, the
+  standard OCP convention (X_f lives in state space). No LHS convention,
+  which is what separates it from a path constraint (present at every t).
+  "Constraint" not "condition" because it restricts to a set rather than
+  pinning a value.
+- `declare_steady_state(m.z_ss, ...)`: tags the Params holding the
+  steady-state state target z_ss. The tracking costs drive toward these
+  (z - z_ss); the steady-state/RTO mode populates them from its solve (or
+  they are set directly, since they are Params), so the target is
+  model-derived rather than hand-typed (the Hicks CSTR lesson above).
+- `declare_steady_state_control(m.u_ss, ...)`: tags the Params holding the
+  steady-state control target u_ss, driven toward the same way (u - u_ss)
+  and populated the same way (USER DECISION 2026-07-14).
+
+Convention on the declared constraints (verified
+against Pyomo 6.10):
+
+- The cost and initial-condition constraints must be equalities; an
+  inequality is rejected with a clear error (a cost term or anchor written
+  as an inequality is a user mistake).
+- Their LHS is the appropriate scalar, read as `con.expr.args[0]`. Pyomo
+  canonicalizes the constraint body to `LHS - RHS` (lower=upper=0), but
+  `con.expr` preserves the as-written relational expression, so the LHS is
+  a stable read and a misplaced scalar (a non-Var LHS) is detectable and
+  rejected. For a cost the scalar is the cost-term Var drto puts in the
+  objective; for the initial condition it is the anchored state at t0.
+
+The objective is drto's, not the user's: it assembles `min` over the
+declared cost-term Vars that are live in the current mode. Modes add or
+drop terms by including or excluding a cost's (Var, defining constraint)
+pair; in steady-state the reduced model never instantiates the terminal
+cost, so that term is simply absent, nothing to zero-weight. This is the
+practical payoff of representing each cost as a Var defined by a
+constraint rather than a bare expression: the pair is one handle drto can
+find and drop.
+
+Naming: fully-written-out, not abbreviated
+(`declare_terminal_cost` not `declare_term_cost`,
+`declare_initial_condition` not `declare_init_con`). These are setup-time
+calls, never hot-path, so brevity buys nothing; `con` is ambiguous
+between condition and constraint, the exact distinction that matters; the
+full forms are the OCP literature's own vocabulary, so a reader who knows
+the theory maps straight on; and spelling them out forces the precise
+concept (condition vs constraint vs set) rather than hiding behind an
+abbreviation.
+
+Not declared, by design:
+
+- Path constraints: the states' upper and lower bounds, i.e. the Var
+  bounds, which drto reads off the model. Not
+  a separate declaration.
+
+Moving-horizon data hooks now have homes: the state anchor z_hat is the
+mutable Param on the RHS of the initial-condition constraint; the tracking
+setpoint is the declared steady-state Params z_ss/u_ss; the measurements
+are the mutable Param stream in `declare_measurement` below. Each is
+updated each step. Dynamics source is decided too: picked up from each
+state's DerivativeVar, above.
+
+Shared conventions:
+
+- Each declaration has an explicit call-time form as well (the
+  declared/explicit duality established in pyomo-cvp and pyomo-pounce).
+- Family conventions locked in pounce#203: varargs on every declaration,
+  keyword options (e.g. `group=`) apply to every component in the call.
+
+Estimation-side surface (surface designed now,
+built with the MHE follow-on). MHE is the dual of the control problem, so
+the same conventions hold (each tags a Var or a Constraint; cost
+constraints are equalities with the scalar on the LHS; drto assembles the
+estimation objective from the live cost-term Vars):
+
+- `declare_estimated_parameter(m.theta, ...)`: tags the Vars for unknown
+  model parameters to estimate, constant over the window. Shared with the
+  steady-state data-reconciliation mode.
+- `declare_disturbance(m.w, ...)`: tags the process-noise Vars w in
+  dz/dt = f + w, the free variables the estimator adjusts to reconcile the
+  model with the data, penalized by their inverse covariance in the
+  estimation stage cost. It is noise, not a manipulated input: unrelated to
+  `declare_control`, with no profile parameterization (USER DECISION
+  2026-07-14).
+- `declare_measurement(m.y_meas, ...)`: tags the measurement Param(s), the
+  measured values y_meas that appear in the estimation cost residuals
+  (||y_meas - h(z)||). Like the z_hat feedback hook, it is a mutable Param
+  drto refreshes each step, here the incoming measurements over the window.
+  Nothing else to tag: h(z) is written inline in the cost, so there is no
+  output Var or defining constraint (USER DECISION 2026-07-14).
+- `declare_estimation_stage_cost(m.est_stage_con)`: tags the equality
+  Constraint for the running estimation cost over the window, the
+  measurement residual ||y_meas - h(z)|| plus the process-noise penalty
+  ||w||, weighted by inverse covariances. LHS-scalar convention.
+- `declare_estimation_terminal_cost(m.est_terminal_con)`: tags the equality
+  Constraint for the current-time (window-present) term, the current-state
+  measurement residual ||y_meas(tN) - h(z(tN))|| with no process noise
+  (nothing leads out of the last point), which is why it is a distinct
+  terminal term rather than part of the stage sum. This IS a standard MHE
+  term (USER correction 2026-07-14).
+- `declare_arrival_cost(m.arrival_con)`: tags the equality Constraint for
+  the soft prior on the window's initial state, ||z(t0) - z_prior||
+  weighted by the arrival-cost inverse covariance. The dual of the
+  control-side initial condition, but SOFT (a cost, not a hard equality).
+  Its weight is the piece the covariance propagation updates each step
+  (Gauss-Newton, the pounce#203 machinery in Follow-on).

drto-0.0.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Devin Griffith
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

drto-0.0.0/Makefile

@@ -0,0 +1,41 @@
+# drto -- Makefile wrapper around the Python toolchain.
+# Each target mirrors one CI job, so local green means CI green.
+#
+#   make help          # list targets
+#   make dev           # editable install with dev extras
+#   make fmt           # format with black
+#   make fmt-check     # check formatting (CI gate)
+#   make typos         # spell-check with typos
+#   make lint          # fmt-check + typos
+#   make test          # run pytest with coverage
+#   make check-imports # import drto with only base deps present
+#   make min-deps      # install the pyomo floor, then test
+
+.PHONY: help dev fmt fmt-check typos lint test check-imports min-deps
+
+help:
+	@sed -n 's/^#   //p' Makefile
+
+dev:
+	python -m pip install -e ".[dev]"
+
+fmt:
+	black src/ tests/
+
+fmt-check:
+	black --check --diff src/ tests/
+
+typos:
+	typos
+
+lint: fmt-check typos
+
+test:
+	python -m pytest -q --cov=drto --cov-report=term-missing
+
+check-imports:
+	python -c "import drto; print('drto', drto.__version__)"
+
+min-deps:
+	python -m pip install "pyomo==6.8.1"
+	python -m pytest -q

drto-0.0.0/PKG-INFO

@@ -0,0 +1,122 @@
+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.

drto-0.0.0/README.md

@@ -0,0 +1,95 @@
+# 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.

drto-0.0.0/_typos.toml

@@ -0,0 +1,10 @@
+# Configuration for the `typos` spell-checker (crate-ci/typos), matching the
+# Pyomo contribution guide's spell-check step.
+[files]
+# Executed-notebook outputs carry base64 blobs and verbatim solver log text;
+# the notebook prose is reviewed by eye instead.
+extend-exclude = ["*.ipynb"]
+
+[default.extend-words]
+# Domain terms, not misspellings.
+RTO = "RTO"  # real-time optimization

drto-0.0.0/dev-notes/README.md

@@ -0,0 +1,27 @@
+# dev-notes
+
+drto's durable engineering memory: design records, code-review logs, progress
+trackers, and forward-looking research. This is the one place development
+history is allowed to accrete, which keeps code comments clean (they state
+present-tense rationale only).
+
+`DESIGN.md` at the repo root stays the top-level design record. These notes
+are the working layer beneath it.
+
+## Naming so notes are findable
+
+Use these patterns so an agent can Glob for a genre:
+
+- `code-review-YYYY-MM.md` -- a dated, severity-ranked review, read-only once
+  written; follow-ups go in `code-review-YYYY-MM-followups.md`.
+- `issue-NNN-<slug>.md` -- work notes for a specific issue.
+- `<feature>-progress.md` -- live state for a multi-session or loop task, with
+  `[ ]` / `[x]` checkboxes.
+- `release.md` -- the release runbook, once there is one.
+- `research/` -- forward-looking work not tied to a single change.
+
+## House style for a note
+
+Open with a one-line **Status**. When a note's framing is overtaken by later
+findings, append a "Progress / current state" section that corrects the
+original rather than editing it away, so the correction stays visible.

drto-0.0.0/dev-notes/research/roadmap.md

@@ -0,0 +1,25 @@
+# Roadmap
+
+Status: design complete, no code. Seeded from DESIGN.md (Delivery plan and
+Follow-on). DESIGN.md stays authoritative for decisions; this note tracks
+sequence.
+
+## Near term
+
+1. Quad-tank spike: the ideal-NMPC mode end-to-end on the quad tank (build on
+   the Quad_tank_cvp model), then flip on the advanced-step mode with the
+   existing pounce `estimate()`. The three-variant comparison plot falls out.
+2. v1 package: the loop, the three execution variants, the control-side
+   declarations, tests, docs, executed notebooks.
+
+## Follow-on
+
+- Moving horizon estimation (the estimation half): the six estimation
+  declarations, the soft arrival cost, and covariance propagation for the
+  arrival-cost weight (pounce covariance machinery).
+- Steady-state reduction wiring (setpoint consistency and economic RTO) via
+  the reusable-object mechanism.
+
+## Stretch
+
+- One large-scale dynamic flowsheet as a credibility example.

drto-0.0.0/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "drto"
+version = "0.0.0"
+description = "Dynamic real-time optimization: receding-horizon NMPC and moving horizon estimation for Pyomo models."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "BSD-3-Clause"
+license-files = ["LICENSE"]
+authors = [{ name = "Devin Griffith", email = "dwg176@gmail.com" }]
+keywords = [
+  "nmpc",
+  "mhe",
+  "moving-horizon-estimation",
+  "pyomo",
+  "dynamic-optimization",
+  "receding-horizon",
+  "dae",
+]
+classifiers = [
+  "Development Status :: 1 - Planning",
+  "Intended Audience :: Science/Research",
+  "License :: OSI Approved :: BSD License",
+  "Programming Language :: Python :: 3",
+  "Topic :: Scientific/Engineering :: Mathematics",
+]
+dependencies = ["pyomo>=6.8.1"]
+
+[project.optional-dependencies]
+dev = ["pytest", "pytest-cov"]
+examples = ["numpy", "matplotlib", "jupyter"]
+
+[project.urls]
+Homepage = "https://github.com/devin-griff/drto"
+Repository = "https://github.com/devin-griff/drto"
+Issues = "https://github.com/devin-griff/drto/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/drto"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+# Mirrors Pyomo's own Black settings so formatting matches upstream exactly.
+[tool.black]
+line-length = 88
+skip-string-normalization = true
+skip-magic-trailing-comma = true

drto-0.0.0/src/drto/__init__.py

@@ -0,0 +1,16 @@
+# Copyright (c) 2026 Devin Griffith
+# SPDX-License-Identifier: BSD-3-Clause
+"""drto: dynamic real-time optimization for Pyomo models.
+
+Receding-horizon NMPC and moving horizon estimation for ``pyomo.dae`` models.
+Design phase: the framework is recorded in DESIGN.md and AGENTS.md. No
+functionality yet.
+"""
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("drto")
+except PackageNotFoundError:  # not installed (e.g. running from a source tree)
+    __version__ = "0.0.0"
+
+__all__ = ["__version__"]

drto-0.0.0/tests/test_import.py

@@ -0,0 +1,8 @@
+# Copyright (c) 2026 Devin Griffith
+# SPDX-License-Identifier: BSD-3-Clause
+"""Phase 0 smoke test: the package imports and exposes a version string."""
+import drto
+
+
+def test_version_is_string():
+    assert isinstance(drto.__version__, str)