Skip to content

About

C++20 library and experiments for theta-method-consistent discrete optimality systems, state reconstruction, and qualification

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

ThetaOptimality

A small C++20 library for building and testing a numerically consistent discrete optimality system for time-dependent inverse problems.

The project develops one coupled discrete construction: a theta-method state trajectory, a matching theta-quadrature objective, its tangent linear model, the exact discrete adjoint, reduced gradients, and incremental-adjoint Hessian-vector products. It also includes state-estimation and engineering qualification experiments that compare discrete results with analytical solutions, bounded observation sets, and numerical error estimates.

The purpose is educational and methodological: make the pieces inspectable on small problems, test their derivatives and convergence, and expose cases where good numerical optimization does not imply that the physical state is identifiable or sufficiently known. This is a research and teaching codebase, not a general-purpose sparse PDE or production estimation package.

Why this project

For a time-discrete model, the objective and its derivatives should belong to the same discrete problem as the forward state. Differentiating a different continuous or discretized problem can produce gradients that do not match the numerical objective actually optimized. ThetaOptimality makes that connection explicit and tests it with directional finite differences, tangent-adjoint pairings, Hessian checks, analytical references, and mesh refinement.

The examples also separate three questions that are easy to conflate:

  1. Did the numerical optimization converge?
  2. Do the observations determine the state or parameters?
  3. Does the available information establish the requested engineering tolerance, including measurement and numerical uncertainty?

An unqualified result means the stated assumptions and error budgets do not establish the tolerance. It does not prove that the actual state error exceeds it. Local information diagnostics are not global uniqueness certificates.

The discrete workflow

For a model (\dot{x}=f(t,x,\xi)) with unknown finite-dimensional vector (\xi), the library supplies these parts of one discrete optimality system:

Component Role in the experiment
Theta-method forward solve Defines the numerical trajectory used in the inverse problem.
Matching theta-quadrature objective Evaluates running and terminal costs on that trajectory.
Tangent linear model Propagates perturbations in initial conditions or model controls.
Discrete adjoint Computes objective sensitivities through the discrete equations.
Reduced gradient and Hessian-vector products Drive optimization and test second-order derivatives.
State qualification Compares whole-interval state uncertainty and numerical error with engineering tolerances.

The complete equations and conventions are in docs/formulation.md; callback contracts and usage are in docs/api.md. The library is header-only in include/theta_opt/.

Experiments and documentation

Each experiment has a standalone write-up describing its model, assumptions, numerical formulation, checks, findings, and limitations. The table links to every experiment document so readers can go directly from the overview to the derivation.

Experiment What it tests Documentation
Nonlinear decay and accumulated exposure Full forward, cost, tangent, adjoint, gradient, Hessian, and analytical convergence workflow. Decay example · State qualification
Electrical state from resistor temperature Nonlinear observation ambiguity, local curvature, and disconnected feasible state sets. Electrothermal experiment
Persistent unobservable thermal mode Difference observations identify a decaying mode but not the common temperature offset. Insulated thermal experiment
Poorly timed oscillator samples Half-period sampling loses the initial-velocity direction; moving sample times restores it. Oscillator experiment · Weak-information sweep
Nonuniform oscillator mesh Tests the full discrete system and convergence on nested, nonuniform time grids. Nonuniform-mesh experiment
Goal-dependent qualification Shows why different physical goals can qualify at different times and one can block a joint decision. Goal-dependence experiment
Transient amplification in two tanks A stable coupled system can temporarily amplify concentration error and delay qualification. Two-tank experiment
Hidden-state oscillator Reconstructs an unmeasured initial velocity from displacement observations. Oscillator experiment
Static Peng–Robinson composition Estimates gas-mixture fractions from thermodynamic density observations and compares identifiability. Peng–Robinson experiment
Two-temperature state finding Infers two coupled temperatures from one thermometer and tests engineering qualification. Two-temperature experiment
Time-varying heater schedule Estimates a finite-dimensional control schedule from thermal observations. Thermal schedule experiment · Control and path-constraint theory
Weakly coupled winding and housing Tests separated thermal time scales, hidden modes, and goal-specific qualification. Weak-coupling experiment
Stiff sequential reaction Uses a closed-form chemical system to examine stiffness, positivity, sampling, and convergence. Stiff-reaction experiment
State constraints and boundary optima Checks active bounds, KKT multipliers, stationarity, and qualification at constrained optima. Bounded washout experiment
Nonlinear logistic growth Estimates an initial state for nonlinear dynamics and checks discrete derivative convergence. Logistic-growth experiment
Joint predator–prey recovery Separately estimates initial conditions, model parameters, and both together. Predator–prey experiment
Measurement versus numerical accuracy Separates sensor-error and discretization contributions in a drug-washout model. Drug-washout experiment
Correlated observation errors Tests the effect of correlated assay errors on fit, information, and qualification. Correlated-washout experiment
Unit and scaling invariance Checks that changing concentration and time units transforms derivatives and decisions consistently. Unit-scaling experiment
Time-varying gas composition Reconstructs a changing feed composition and vessel state from Peng–Robinson density observations. Dynamic gas experiment
Roadmap and cross-cutting tests Tracks the theory features tested across multiple examples and future cases. Feature-test roadmap
Transient state and parameter analysis Discrete state maps, finite-horizon amplification, observation sensitivities, Fisher information, covariance, and correlation. Transient analysis
Matrix-based regularization Correlated priors, weak-sensitivity subspaces, spatial H1/H2 penalties, and weak-constraint trajectory penalties. Regularizers

These cases deliberately include both qualified and NOT QUALIFIED results. An unqualified result means that the stated data and error assumptions do not establish the requested tolerance; it does not prove that the actual state error exceeds that tolerance. Local information or a small optimization gradient is not, by itself, evidence of global uniqueness or engineering sufficiency.

Start here

The nonlinear decay example is the smallest complete optimality-system verification. Its continuous solution, objective, tangent, adjoint, gradient, and Hessian have analytical references. Numerical optimization still uses the library's discrete forward solve and objective; analytical formulas are used as independent comparisons, not as substitutes for the numerical calculation.

make example       # Run the basic decay optimality-system example
make validation    # Check library identities and derivatives
make test          # Build and run the C++ validation and experiment suite

To run the full set of examples and regenerate their figures:

make qualification-plots

Requirements: a C++20 compiler, GNU Make, and the C++ standard library. Python 3 with Matplotlib is only needed to render figures; simulations, fits, derivatives, convergence estimates, and qualification decisions are computed in C++20. The optional Peng–Robinson examples use the pinned scalar CPU ThermoGPU source included in third_party/ThermoGPU; they do not require CUDA. See its PROVENANCE.md for provenance and licensing details.

Install the plotting dependency, if needed, with:

python3 -m pip install matplotlib

The Peng–Robinson examples use the pinned scalar CPU ThermoGPU implementation in third_party/ThermoGPU/. No CUDA is required. Its provenance and separate licensing are documented in third_party/ThermoGPU/PROVENANCE.md.

CMake is also supported:

cmake -S . -B build-cmake -DCMAKE_BUILD_TYPE=Release
cmake --build build-cmake --parallel
ctest --test-dir build-cmake --output-on-failure

Example gallery

Each example documents its model, assumptions, theory exercised, checks, and limitations in a standalone page under docs/. Figures below are committed outputs from the corresponding C++ experiment; their Python scripts only render the saved results.

Case What it tests Experiment notes and representative figure
Nonlinear decay and exposure Complete forward, quadrature, tangent, adjoint, gradient, Hessian, and second-order midpoint convergence workflow. State qualification · qualification figure
Hidden-state oscillator Recover an unmeasured initial velocity; compare analytical and discrete fits, derivatives, and convergence. Oscillator · reconstruction
Poor versus proper sampling Show exact rank loss at half-period sample times and recovery when the same number of samples are placed informatively. Sampling experiment · comparison
State qualification Retain bounded data-consistent uncertainty and include a numerical-model allowance in whole-interval decisions. Qualification theory · decision plot
Time-varying thermal control Estimate a finite-dimensional heater schedule using a discrete optimality system. Thermal schedule · reconstruction
Dynamic gas composition Infer initial vessel composition and a changing feed from Peng–Robinson density observations. Gas schedule · reconstruction
Stiff reaction kinetics Test a closed-form sequential reaction, stiff time scales, positivity, observation timing, and qualification. Stiff reaction · reconstruction
Nonlinear population dynamics Estimate initial state, model parameters, and both jointly for Lotka–Volterra dynamics. Predator–prey · phase portrait
Ambiguity and missing modes Preserve multiple feasible branches or persistent unobservable directions rather than reporting a unique-looking fit. Electrothermal · Insulated thermal
Cross-cutting cases Nonuniform meshes, transient amplification, correlated observations, units/scaling, path constraints, and goal-dependent qualification. Feature roadmap

The complete set of derivations and experiments is indexed in docs/. To regenerate figures after running the relevant C++ cases, use make qualification-plots (requires Matplotlib).

Library use

For a model with (N) states and (P) unknown controls, define a Problem<N,P> and a time Grid:

#include <theta_opt/theta_opt.hpp>
#include "decay_model.hpp"

using namespace theta_opt;

System<2, 1> system(decay::problem(),
    Grid::uniform(decay::t0, decay::tf, 160, 0.5));
Vec<1> xi{2.4};

auto trajectory = system.forward(xi);
auto tangent = system.tangent(xi, trajectory, Vec<1>{1.0});
auto adjoint = system.adjoint(xi, trajectory);
auto gradient = adjoint.gradient;
auto hessian_vector = system.hessian_vector(xi, Vec<1>{1.0});
auto evaluation = system.evaluate(xi); // forward + cost + adjoint + gradient

Second-order callbacks are explicit. A Hessian request without the required directional derivatives throws; there is no silent finite-difference Hessian. See docs/api.md for the callback contract and docs/formulation.md for the full discrete equations.

Scope and interpretation

  • The core uses dense, compile-time-sized vectors and matrices for small ODE systems; it is not a sparse PDE or large-scale optimization library.
  • Time-varying controls are finite-dimensional schedules or bases, not unrestricted functions of time.
  • Qualification conclusions depend on the stated model, prior, observation assumptions, tolerances, and numerical-error estimates. They are not formal directed-rounding certificates or safety certifications.
  • The examples are synthetic or idealized method demonstrations, not validated clinical, industrial, or safety-critical tools.
  • See the feature-test roadmap for current coverage, limitations, and proposed cases.

License

ThetaOptimality project code is licensed under AGPL-3.0-only. ThermoGPU source and the connected composition examples carry their separately identified GPL-3.0-or-later terms; see third_party/ThermoGPU/PROVENANCE.md. The AGPL version is available under the terms of LICENSE. Separate commercial licensing, if offered by the rights holders, requires a separate written agreement. See COPYRIGHT for the licensing notice.

About

C++20 library and experiments for theta-method-consistent discrete optimality systems, state reconstruction, and qualification

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages