Model Zoo: structure and support model for contributed models

[rtimms]

Summary

We want a clear, lightweight home for community- and partner-contributed models (the 3D pouch submodel PR being the immediate example) without those models holding up core PyBaMM releases or being silently broken by upstream changes. This issue is to agree the short-term structure and capture the longer-term options.

Background

At the recent developer meeting we agreed that a dedicated model_zoo/ (or similarly named) folder inside the PyBaMM repository is the right short-term home for contributed models. The motivation:

• Lowers the barrier to contributing — no separate repo, packaging, or release coordination required.
• Models discoverable next to the core code that they extend.
• Lets us evolve the support model in-place before committing to a heavier solution (separate PyPI package, registry, etc.).

Proposed short-term structure

• A top-level model_zoo/ folder, with one subfolder per contributed model.
• Each model folder contains the model code, a short README, and a tests/ subfolder.
• Each model is assigned a support tier at merge time:
  • Tier 1 — must pass tests on every PR; treated like core code.
  • Tier 2+ — tests run but failures are allowed/skipped; flagged on the model's page rather than blocking PRs.
• PRs gate on model zoo tests for the tier the changed model belongs to (or above).
• We auto-track which PyBaMM versions a model passes against and surface that history (e.g. a generated compatibility table per model).
• Failure to pass tests in the model zoo does not block a core PyBaMM release.

Open questions / longer-term options (not deciding now)

• Discoverability — do we adopt a pytest-plugin-style convention so external packages can register themselves as model zoo entries?
• Should the model zoo eventually move to a separate PyPI package?
• A registry text file (repo URLs of external models) vs. all-in-tree.
• Per-model Zenodo DOIs for citability when models live in their own repos.
• Ownership/maintainership — how do we surface a contact and avoid orphaned models?
• Relationship to the planned Imperial / MSM extension model repo — we should make sure these don't diverge.

Suggested next steps

1. Agree the folder layout and tier system in this issue.
2. Land an initial model_zoo/ skeleton with one example model and the CI wiring.
3. Migrate the 3D pouch submodel PR as the first real entry.
4. Spin out a separate issue for the longer-term discoverability/ownership question once we have a few models in-tree.

cc: @BradyPlanden @agriyakhetarpal @aabills @brosaplanella @martinjrobins (please add anyone I've missed)

[martinjrobins]

To reduce effort on maintainers I would suggest:

1. The PR author is responsible for writing a set of tests for their model
2. Rather than the two tiers, we could just have a badge in the readme for that model indicating if those tests pass or fail

So as part of CI we run the tests but we do not require them to pass.

If someone wants to use one of the models in the zoo, they are responsible for looking at the quality of tests and and the pass/fail status and making their own judgement on if to use that model or not