Expose MicroSimulationInterface as public abstract base class for user subclassing #65

[AdityaGupta716]

Closes #65

Exposes MicroSimulationInterface as a public abstract base class that users can inherit from when writing their micro simulations. This ensures users stick to the required API and get clear errors if they miss a method.

Changes:

• Added full docstrings with examples to all abstract methods in MicroSimulationInterface
• Exported MicroSimulationInterface from init.py so users can do from micro_manager import MicroSimulationInterface
• Updated load_backend_class() to warn users with a DeprecationWarning if their class does not inherit from MicroSimulationInterface (will become a hard error in a future version)
• Updated examples/python-dummy/micro_dummy.py to demonstrate the new inheritance pattern

[AdityaGupta716]

Hey @MakisH @IshaanDesai, plz review! Let me know if the deprecation warning approach works for you or if you'd prefer a hard error right away.

[precice-bot]

This pull request has been mentioned on preCICE Forum on Discourse. There might be relevant details there:

https://precice.discourse.group/t/gsoc-2026-aditya-gupta/2773/1

[Snapex2409]

Overall great idea and would be nice to have. Some minor changes requested, and please check regarding C++ bindings. Thank You.

[Snapex2409]

PS: run pre-commit run -a -v for example to get rid of the formatting issue in the CI.

[AdityaGupta716]

@Snapex2409 hi , addressed all the review comments, Removed @AbstractMethod from initialize and output and made them optional with default pass implementations, added requires_initialize() and requires_output() for class-level override detection, and updated check_initialize() and check_output() to use these instead of hasattr. Also wrapped the issubclass check in a try/except for pybind11 compatibility,, added type hints throughout, and ran black to fix the pre-commit failure.
Couldn't test the C++ dummy directly since it needs pybind11 compiled locally, but the logic should handle it fine since non-inheriting classes fall back to the existing hasattr path.

[Snapex2409]

Overall thank you for your efforts. Nicely done. Please consider what I wrote in the comments. Let me know if I should clarify further.

[AdityaGupta716]

@Snapex2409 hi done with the changes , Wrapped non-conforming classes in a dynamic adapter in load_backend_class so it always returns a proper MicroSimulationInterface subclass. The adapter delegates everything via getattr and only adds initialize/output overrides if the original class actually has them — so requires_initialize()/requires_output() work correctly for all cases including pybind11. check_initialize and check_output are now clean with no guards.
Also caught a bug while implementing — the wrapper chain (MicroSimulationWrapper, MicroSimulationLocal, MicroSimulationRemote) was unconditionally overriding initialize and output, which made requires_initialize()/requires_output() always return True. Fixed that too.
Still can't test the C++ dummy locally, but the logic should handle it correctly since the TypeError from issubclass triggers the wrap path and that test fail seems unrelated

[Snapex2409]

Looks very good. Thank you 👍

Could you determine why the test fails?

The suggested changes are just to have the same docstring style as in other files.

[AdityaGupta716]

@Snapex2409 Hi , applied all the docstring suggestions
Looked into the CI failure too — reproduced it on upstream/develop directly with no changes from this PR, so it's pre-existing. The root cause is in test_set_state itself: it calls del sim mid-test which triggers cleanup on the MicroSimulationRemote object, then immediately tries to reuse the same worker connection to send a GetStateTask. The workers have already lost state at that point, so recv() hits an EOFError. It's a resource management issue in the test unrelated to our changes.
Happy to fix it in this PR if that works for you

[Snapex2409]

@AdityaGupta716 I think you did not check out develop while testing, but that's ok. Issue is resolved now.
Thank you for your help.

Apart from that: As you already mentioned, that is not clean resource management. But I am already addressing that in another PR. So, no need to deal with that here.

[AdityaGupta716]

@Snapex2409 i Ran test_set_state on upstream/develop locally it gets stuck in setUp at spawn_local_workers, hanging on server.accept() waiting for a worker to connect. prterun can't find the python executable so the worker never spawns and the socket just hangs. Had to kill it manually

[Snapex2409]

@AdityaGupta716 Looks like your mpi is not able to find to find python. What python environment are you using venv, conda or other? Is it perhaps not in PATH?

[AdityaGupta716]

@Snapex2409 ahh got it my bad was using venv and the path is python3 not python , got it