ENH: Move large test models into examples

[timmens]

It would be nice to showcase our large test models also as examples. In particular the ISKHAKOV_ET_AL_2017 models and regimes.

For this we need to:

1. Decide which of these models we want to have as the example model(s)
   → This would also be a great time to define the derived models actually as a derivative of the base model (i.e., using the models and regimes replace method)
2. Ensure that we can import from the folder from within the tests

[hmgaudecker]

Thinking about it, I believe we'll actually want to have a separate repo pylcm-examples.

We could list it in [tool.pixi.feature.testing.dependencies] and import the models into the test suite. For any example that we import into the test suite, we will require a big red flag in the source code to not modify it / to always run the test suite.

The nice thing about that would be that each directory could be standalone and would look exactly like a project using LCM. The part making it a package could be pretty much ignored by people looking at it.

[timmens]

I like this, but I’d actually split the ideas here a bit:

• I’m fully on board with a separate pylcm-examples repo for the big models and replications like the Mahler & Yum (2024) model. This is could very well be structured just like real projects that use PyLCM. That’s also very similar to what PyTorch does with pytorch/examples.
• But I’d keep the test suite of pylcm completely self-contained and not import from pylcm-examples. This is also what all packages that I checked do (e.g., pytorch, tensorflow, etc.)

I’d avoid using pylcm-examples inside the tests:

• Any change in pylcm-examples can suddenly break pylcm’s tests, even without a change in pylcm itself. We now have to coordinate PRs across two repos and keep versions in sync.
• The “big red flag” can still be missed
• Most of the big example models cannot be run in the test suite anyways because they run too long or even require a GPU. Effectively, we would do this only for the Iskhakov et al. (2017) model.

I’d propose:

• Keep fast, canonical test models in pylcm itself, and base the core tests on those (this would include Iskhakov et al., 2017 but nothing bigger)
• In the main repo, we can still have a light examples/ folder for small, curated models without heavy pre-processing logic, which can be used in the documentation (once we have one)
• In pylcm-examples, we focus on replications of models like Mahler & Yum (2024) as standalone projects

[hmgaudecker]

I see the point, but still like the idea of having all models (also those where the primary purpose is educational / testing) in one place. The one concern is indeed your first point in the "why to avoid" bit:

Any change in pylcm-examples can suddenly break pylcm’s tests, even without a change in pylcm itself. We now have to coordinate PRs across two repos and keep versions in sync.

but I'd hope a fair share of that can be avoided by defining a pylcm development workspace, which would group both repos (Disclaimer: I have not worked with that pixi feature yet...). I am pretty sure we won't ever move to a developer base of the size of pytorch or the like, so we'll manage not to release versions of pylcm-examples that would break the tests.