Matey integration

[ScSteffen]

feat(examples): add initial MATEY harness integration

Summary

This PR adds an initial BaseSim integration for MATEY under examples/matey/, including a new MATEYHarness, example config files, and tests. It also wires the new harness into examples/utils.py so data.name = "matey" dispatches correctly. Root Python compatibility is widened from >=3.13 to >=3.12 to align with the integration environment.

Motivation & Context

Enable running MATEY workflows from within BaseSim as an example harness path.

Branch commits to main:

• e74b1ae MATEY runs now within base-SIM. Performance unclear. git submodule not set up
• 8379344 added matey toml config
• 620ed8d added pyproject

Approach

• Added examples/matey/model.py with:
  • MATEYHarness(BaseModelHarness) implementation.
  • Adapter dataclasses for MATEY input/target batch formats.
  • Loader/model adapters to bridge MATEY data/model interfaces to BaseSim expectations.
  • Guardrails for unsupported continual learning modes (jvp_reg, ewc_online, kfac_online not yet supported).
  • Validation and runtime import checks for local MATEY checkout and optional dependencies.
• Added examples/matey/matey.toml and examples/matey/Demo_SOLPS_vit.yaml for runnable example configuration.
• Added examples/matey/pyproject.toml (+ lockfile) to isolate MATEY-specific Python dependencies from BaseSim core.
• Updated examples/utils.py factory dispatch to instantiate MATEYHarness for data.name == "matey".
• Added unit tests in tests/test_matey_runsh_harness.py covering:
  • unsupported updater mode handling,
  • missing MATEY path handling,
  • mocked end-to-end stream/loss path,
  • examples factory dispatch.
• Updated root pyproject.toml/poetry.lock Python requirement to >=3.12,<3.15.

Screenshots / Logs (optional)

Executed locally:

poetry run pytest -q tests/test_matey_runsh_harness.py
# 4 passed, 2 warnings

poetry run ruff check examples/matey/model.py tests/test_matey_runsh_harness.py
# All checks passed

poetry run ruff format --check examples/matey/model.py tests/test_matey_runsh_harness.py
# 2 files already formatted

poetry run mypy examples/matey/model.py tests/test_matey_runsh_harness.py
# Fails (missing MATEY stubs/imports + typed override mismatches)

API / CLI Changes

• examples.matey.model.MATEYHarness (new)
• examples.matey.model.MateyInputBatch (new)
• examples.matey.model.MateyTargetBatch (new)
• examples.utils.get_example(...) now supports cfg.data.name == "matey"
• New example config: examples/matey/matey.toml
• New example dependency project: examples/matey/pyproject.toml
• Root runtime change: requires-python from >=3.13,<3.15 to >=3.12,<3.15

Breaking Changes

• None

Performance (optional)

• No reliable before/after performance numbers yet.

Security & Privacy

• No secrets committed
• Input validation added where needed ([data].path existence checks and dependency import validation)

Dependencies

• Added example-scoped dependency manifest at examples/matey/pyproject.toml:
  • einops, h5py, timm, torchinfo, zarr, ruamel.yaml==0.17.32, scipy, scikit-learn, torch_geometric, adios2
• Added examples/matey/poetry.lock
• Updated root dependency metadata/lock for Python 3.12 support (pyproject.toml, poetry.lock)

Testing Plan

• Unit tests
• Integration tests
• e2e / smoke test
• Manual steps:
  • poetry run pytest -q tests/test_matey_runsh_harness.py
  • poetry run ruff check examples/matey/model.py tests/test_matey_runsh_harness.py
  • poetry run ruff format --check examples/matey/model.py tests/test_matey_runsh_harness.py
  • poetry run mypy examples/matey/model.py tests/test_matey_runsh_harness.py (currently failing; see logs)

Documentation

• Docstrings updated
• User docs / README updated
• CHANGELOG entry

Checklist

• Code formatted (Ruff) → ruff format --check (targeted changed files)
• Lint passes (Ruff) → ruff check .
• Types pass (mypy/pyright) → mypy src
• Tests pass (pytest) → pytest -q (full suite not run)
• Backward compatibility considered
• Adequate comments for tricky parts
• CI green

Risk & Rollback Plan

Risk level: Medium.

Primary risks:

• Runtime dependency mismatch with local MATEY checkout/environment.
• Limited continual learning updater support in phase-1 harness.

Rollback:

• Revert this PR to remove MATEY integration points (examples/matey/*, examples/utils.py dispatch, and root Python requirement changes).

Notes for Reviewers

Please review in this order:

1. examples/matey/model.py (adapter/harness design and failure handling)
2. tests/test_matey_runsh_harness.py (coverage of expected behavior)
3. examples/matey/matey.toml and examples/matey/README.md (usability/documentation)

Known limitation: this is a phase-1 integration; advanced update modes are intentionally not enabled yet.