Add experimental LyoPRONTO policy OCP adapter

[bernalde]

Summary

• Add an experimental lyopronto.pyomo_models.policy_ocp adapter that reuses the existing quasi-steady Pyomo optimizer model in LyoPRONTO units.
• Add optional Policy 3 path caps for sublimation flux (kg/hr/m^2) and interface velocity (cm/hr), plus paper-style rich result extraction and active policy classification.
• Export the experimental API and document how it differs from the paper-reference OCP while keeping web/high-level integration out of scope.

Tests run

• python -m ruff check lyopronto/pyomo_models/policy_ocp.py lyopronto/pyomo_models/__init__.py tests/test_pyomo_models/test_policy_ocp.py tests/test_pyomo_models/test_init.py -> passed
• python -m ruff format --check lyopronto/pyomo_models/policy_ocp.py lyopronto/pyomo_models/__init__.py tests/test_pyomo_models/test_policy_ocp.py tests/test_pyomo_models/test_init.py -> passed
• pytest tests/test_pyomo_models/test_policy_ocp.py tests/test_pyomo_models/test_init.py -n 0 -> 8 passed
• python -m pytest tests/test_benchmarks.py tests/test_opt_Tsh.py::TestOptTsh::test_optimizer_example_script_runs -n 0 -> 19 passed
• python -m pytest tests/ -m "not notebook and not pyomo" --ignore=tests/test_pyomo_models -n auto -> 262 passed

Notes

• A direct local console-script run of pytest tests/ -m "not notebook and not pyomo" --ignore=tests/test_pyomo_models -n auto reached 243 passes but failed on local import-path errors for benchmarks and examples; the focused rerun and full broader rerun both passed through python -m pytest.
• Full IPOPT-backed Pyomo solve coverage was not run locally beyond the targeted Pyomo construction/export/classification tests.

Closes #31

[bernalde]

Blocking issues: active flux/velocity caps can fail through the default SciPy staged warmstart path before the optimized control is released. I attempted to submit this as REQUEST_CHANGES, but GitHub rejects change requests from the PR author's own account. Nonblocking issues: none. Questions: none. Tests run: python -m ruff check lyopronto/pyomo_models/policy_ocp.py lyopronto/pyomo_models/__init__.py tests/test_pyomo_models/test_policy_ocp.py tests/test_pyomo_models/test_init.py passed; python -m ruff format --check lyopronto/pyomo_models/policy_ocp.py lyopronto/pyomo_models/__init__.py tests/test_pyomo_models/test_policy_ocp.py tests/test_pyomo_models/test_init.py passed; python -m pytest tests/test_pyomo_models/test_policy_ocp.py tests/test_pyomo_models/test_init.py -n 0 passed with 8 tests; no-cap smoke solve with solve_lyopronto_policy_ocp(..., n_elements=4, warmstart_scipy=True) reached optimal termination; active flux-cap smoke solve with default warmstart failed in Stage 1 as described inline; the same active cap with warmstart_scipy=False solved and classified Policy 3; python -m pytest tests/ -m "not notebook and not pyomo" --ignore=tests/test_pyomo_models -n auto passed with 262 tests. I would not merge this until the blocking issue is addressed.

[bernalde]

Blocking: With the default warmstart_scipy=True, an active flux or interface-velocity cap can make the staged solve fail before the optimized shelf control is ever released. Stage 1 fixes Tsh and t_final to the uncapped SciPy warmstart while the new cap constraints are already active, so a valid capped OCP becomes infeasible if the warmstart trajectory violates the cap. I reproduced this with the standard fixture inputs, n_elements=4, and a flux cap set below the uncapped max flux: the default path failed in Stage 1, while the same capped problem solved with warmstart_scipy=False and classified Policy 3. Since this new public solve API defaults to the failing path, please make capped solves use a cap-aware initialization/staged sequence, skip the fixed-control staged solve when caps are present, or temporarily relax/deactivate cap constraints until controls are released. Add a regression smoke test that solves an active cap case through the default API.

[bernalde]

Addressed in 6690b29. Capped solves now skip the fixed-control staged solve while preserving SciPy initialization, and tests/test_pyomo_models/test_policy_ocp.py::test_policy_ocp_default_warmstart_solves_active_flux_cap covers the default active flux-cap path.

[bernalde]

Pushed commit 6690b29b01bbe3920a3f84fa760e43f644d71959 (Fix capped policy OCP warmstarts (#31)).

Main changes:

• Capped policy OCP solves now skip the fixed-control staged solve when a flux or interface-velocity cap is active, while still using the SciPy trajectory as an initial point.
• Policy OCP result metadata now records whether the staged solve was used and why it was skipped.
• Added a regression smoke test for the default API with an active flux cap.
• Documented the capped warm-start behavior in the Pyomo model README and paper-validation notes.

Tests run:

• python -m ruff check lyopronto/pyomo_models/policy_ocp.py lyopronto/pyomo_models/__init__.py tests/test_pyomo_models/test_policy_ocp.py tests/test_pyomo_models/test_init.py: passed.
• python -m ruff format --check lyopronto/pyomo_models/policy_ocp.py lyopronto/pyomo_models/__init__.py tests/test_pyomo_models/test_policy_ocp.py tests/test_pyomo_models/test_init.py: passed.
• python -m pytest tests/test_pyomo_models/test_policy_ocp.py tests/test_pyomo_models/test_init.py -n 0: 9 passed in 17.30s.
• python -m pytest tests/ -m "not notebook and not pyomo" --ignore=tests/test_pyomo_models -n auto: 262 passed in 473.14s.

Comments intentionally not addressed:

• None.

Remaining risks or follow-up:

• Notebook tests and the full Pyomo test directory were not run locally. The targeted Pyomo regression covers the reviewed failure, and the broader non-notebook/non-Pyomo CI-equivalent passed.