[PatrickHenkel1]

Release review of refactoring_v1.0.0 before the merge into main and the tag v1.0.0. Architecture, pipeline, models, examples, tests and documentation were checked against each other. The smaller errors are fixed here; larger points are listed at the end as proposals.

Fixed errors

• The embargo deleted test and validation rows. When a training block was shorter than gap_steps, apply_embargo purged rows of the neighbouring test or validation block (gap 2: [2,2,2,0,2,2,2] → [2,2,-1,-1,-1,2,2]). This happens with small data sets, where min_blocks shortens the blocks. Now only rows of the block at the boundary are purged.
• physXAI.set_seed had no effect on the models. All keras models had random_seed=42 as default and set it again in prepare(). Now random_seed=None resolves to the global seed, otherwise a new seed is drawn and stored in the config (like random_state of the preprocessing). The same holds for px.RBF(random_state=...) and for the k-means of RBFModel/LinANNModel. Before, the k-means of these two models ignored the seed that repeat_training sets. online_pipeline now seeds as well.
• Unknown model arguments were silently ignored (SingleStepModel/MultiStepModel.__init__(**kwargs): pass). They now raise a TypeError. from_config drops the meta keys of saved configs in one place. This also showed a test error: test_comparison.py trained the default network because of hidden_layer_size=[4].
• Several outputs with keras single step networks. The single output neuron was broadcast against k target columns, so the network learned their mean and the metrics only showed output 0. These networks now require one output; LinearRegressionModel and RNNs keep supporting several.
• shift is now 0 or 1 (decision in the review). With shift > 1, the horizon metrics, the recursive training and the RNN trajectories were wrong.
  • shift=1 (default): states and outputs over the interval [t, t+1), as AgentLib-MPC uses them.
  • shift=0: algebraic outputs of point-sampled data. A leakage guard rejects the output feature as input, also as Change(X) and inside columns expressions. shift=0 allows no Change output, no eval_horizon, no recursive training and no multi step data, and it cannot be exported to AgentLib-MPC.
  • TrainingData stores the shift.
• LinANNModel evaluated its linear regression into td, including a recursive rollout. It is now only fitted.
• RBF construction without normalization called .numpy() on a NumPy array.

Additions

• check_agentlib_compatibility warns about inputs that the preprocessing computes (columns, Change(X), transform), because the MPC has to provide them as variables.
• Saved configs record environment (versions of Python, NumPy, pandas, scikit-learn, Keras, TensorFlow and CasADi). All from_config methods ignore the key, and AgentLib-MPC reads only known keys.
• Example 04, part D: px.Pretrained (the model of part B as a frozen block) plus a px.Polynomial correction scaled by a px.Param that starts at 0.

Tests (+40)

• Config round trip through model_from_config for all 9 model classes, with the meta keys of saved files.
• Unknown arguments.
• Seeds: the global seed is used, an explicit seed wins, and training with the same seed gives bitwise identical weights.
• Multi-output networks are rejected.
• Monotonicity of CMNNModel and px.MonotoneMLP: gradient signs at points up to 2× outside the range of the training data. Before, monotonicity was not tested anywhere.
• Save/load with a prediction comparison for CMNN, RBF and LinANN.
• Embargo edge cases: short blocks, VAL/TEST boundaries, the edges of the data.
• shift validation and the leakage guard, plus a shift=0 fit.
• TrainingData.save/load including labels, valid, datetime, loss columns and derived columns.

Documentation

Docs and API were compared identifier by identifier. Corrected:

• CHANGELOG: wrong example names, the path of model_report, and contradictions between Changed and Removed (recursive_feature_elimination_pipeline, save_result, ModularModel).
• Guides:
  • The PCNN snippet had no td and no time_index_col.
  • The px.MonotoneMLP signature was wrong: its second positional argument is name.
  • Which blocks normalize their inputs.
  • The shift and loss_columns options, and the default of the embargo.
  • TrainingDataMultiStep has no save.
  • Feature selection keeps the recursive feature only with criterion='horizon'.
  • The output folder of the comparison CLI.
  • AgentLib rules: derived inputs, PCNN, branch 143.
  • Reproducibility.
  • Snippets made self-contained.
• README:
  • python -m venv physXAI collided with git clone.
  • The CMNN description was wrong.
  • PCNN was missing, and the project structure is updated.
• Docstrings: module and class docstrings of the keras models and configs (autodoc_inherit_docstrings = False), and 'class_name' → '__class_name__'.

Verification (Windows, Python 3.12)

• PHYSXAI_REQUIRE_AGENTLIB=1 pytest tests: 199 passed, 1 skipped (test_agentlib_rnn: the installed AgentLib-MPC
  (main) has no RNN support; the saved step model is unchanged by this PR).
• constraints.txt resolves on Windows and Linux (pip install --dry-run, Python 3.12).
• python tests/smoke_examples.py: all 13 examples OK (74 s). Example 04 also ran with full epochs. RMSE of T after 12 h: A 0.353 K, B 0.080 K, D 0.110 K.
• ruff check physXAI tests examples and sphinx-apidoc + sphinx-build -W: no findings.

Notes for the merge

• v1/shape-constraints (Constrained regression as ModularANN(solver='qp') with certified shape constraints #83) changes modular_ann.py. This PR touches the same file: the random_seed default, a docstring, and from_config, which moves to AbstractModel. Merging refactoring_v1.0.0 into Constrained regression as ModularANN(solver='qp') with certified shape constraints #83 will give a small conflict there. Resolution: drop ModularANN.from_config.
• Merge of refactoring_v1.0.0 into main after physXAI 0.3.0: Python 3.11 - 3.13, dependency versions fixing the security advisories #86 (security pins on main): requirements.txt gives a modify/delete conflict, resolve by deleting it (1.0 has constraints.txt); in the dependency list of pyproject.toml take the 1.0 version.
• pyproject.toml: Constrained regression as ModularANN(solver='qp') with certified shape constraints #83 adds scipy>=1.11 to the dependencies, this PR adds upper bounds to the same list. Resolution: keep the bounds and add "scipy>=1.11,<2".
• Behaviour change: without set_seed, models no longer use 42 but draw a new seed (stored in the config).

Implemented from the review proposals

1. Dependency bounds: keras>=3.15.0 (older versions are vulnerable when loading models, GitHub advisories; the pins of constraints.txt are all patched). Upper bounds on the next major versions (keras<4, tensorflow<3, numpy<3, pandas<4, plotly<8, ...). The CasADi converter of AgentLib-MPC recognises layers by their names and attributes, so a Keras major release could silently break the export. constraints.txt pins all 47 runtime dependencies to the tested versions (pip install . -c constraints.txt). The new job tested-versions in windows.yml installs them and runs the tests on Linux and Windows.

2. GPU: physXAI itself is device-agnostic, but tensorflow from PyPI has no CUDA, and native Windows has no GPU support since TF 2.11. New extra physXAI[gpu] (tensorflow[and-cuda], Linux/WSL2) and a GPU section in Getting started. set_seed(seed, deterministic=True) enables tf.config.experimental.enable_op_determinism() for exactly reproducible runs on a GPU.

3. RNN/PCNN export: the CHANGELOG and the release checklist state it as a known limitation (needs AgentLib-MPC branch 143-feature-multistep-model-support). check_agentlib_compatibility warns when the installed AgentLib-MPC cannot load recurrent models.

4. Required contract tests: with PHYSXAI_REQUIRE_AGENTLIB=1 (set in windows.yml), a missing AgentLib-MPC or plugin fails the contract tests instead of skipping them. Only the RNN tests may still skip, until AgentLib-MPC releases RNN support. The model saved with physXAI 0.x is now versioned as a test fixture (tests/contract/data/legacy_model_0x.keras), so test_legacy_model_still_loads runs everywhere. ci.yml (shared template) does not set the variable; the Windows job covers it.

5. Python 3.11–3.13: constraints.txt pins numpy 2.4.6 and scipy 1.17.1 for Python 3.11, because numpy 2.5 and scipy 1.18 require Python 3.12. Resolution was checked with uv for 3.11, 3.12 and 3.13 on Windows and Linux. tested-versions runs on 3.11 and 3.13. Python 3.14 needs TensorFlow 2.22, which is only a release candidate so far (noted in Getting started).

Still open, fine for 1.0: evaluation as a separate strategy class instead of late imports in SingleStepModel/MultiStepModel.

Notes on #83 (shape constraints)

The findings (undeclared scipy, certificate exact without a check of the corners) are fixed on #83 (verified in dc5b36b).

🤖 Generated with Claude Code

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota. Try requesting a review at a lower effort level.

An organization owner can choose the repository organization as the billing source for reviews requested by members with a paid Copilot license. Learn about Copilot code review billing.