feat: accept model instance + docs + readme pypi install

Author: maedoc

README.md

@@ -20,6 +20,16 @@ Interactive phase plane widget for neural mass models, usable in Jupyter noteboo
 
 ## Installation
 
+```bash
+pip install tvb-phaseplane
+```
+
+For development with Jupyter:
+```bash
+pip install tvb-phaseplane[dev]
+```
+
+Or install from source:
 ```bash
 # Using uv
 uv venv
@@ -29,11 +39,6 @@ uv pip install -e .
 pip install -e .
 ```
 
-For development with Jupyter:
-```bash
-uv pip install -e ".[dev]"
-```
-
 ## Quick Start
 
 ### Jupyter / VS Code — Built-in Models

docs/deployment.md

@@ -36,6 +36,42 @@ pp
 
 The SymPy expressions are transpiled to JavaScript via an inlined Nerdamer CAS (~100 KB) that compiles and runs entirely in the browser.
 
+### Passing a Model Instance {#model-instance}
+
+You can also instantiate a model class first, configure its defaults, and then pass it to the widget. This is useful when you want to programatically set initial parameter values or read back tuned values after the user interacts with the sliders.
+
+```python
+from tvb_phaseplane import PhasePlaneWidget, MPRModel
+
+# 1. Create a model instance
+model = MPRModel()
+
+# 2. Optionally override default parameter values
+model.default_params.update({"J": 15.0, "eta_bar": -5.0})
+
+# 3. Pass the instance to the widget
+widget = PhasePlaneWidget(model=model)
+widget
+```
+
+After the user adjusts sliders in the widget, read back the tuned parameter values:
+
+```python
+print("Current parameter values:")
+for name, value in widget.params.items():
+    print(f"  {name:12s} = {value:.4f}")
+```
+
+You can also read back computed data:
+
+```python
+print(f"Fixed points: {len(widget.fixed_points)}")
+for fp in widget.fixed_points:
+    print(f"  x={fp[0]:.4f}, y={fp[1]:.4f}, type={fp[2]}")
+```
+
+The ``model=`` argument accepts any ``BaseModel`` subclass whose ``name`` is registered in ``MODEL_REGISTRY`` (so the JavaScript front-end knows how to evaluate it). For arbitrary ODE systems that are *not* built in, use :func:`phase_plane` instead.
+
 ### Exporting Notebooks
 
 Use [jupytext](https://jupytext.readthedocs.io/) to keep notebooks in plain `.py` percent-format:

examples/model_instance_demo.py

@@ -0,0 +1,67 @@
+"""Demo: pass a Python model instance to the widget and read back tuned parameters.
+
+This demonstrates the ``model=`` argument to ``PhasePlaneWidget``,
+which accepts any ``BaseModel`` subclass instance.  After the user
+interacts with the widget (dragging sliders, clicking the phase plane),
+the current parameter values can be read back from the ``.params``
+traitlet.
+
+If the model name is registered in ``MODEL_REGISTRY`` the JavaScript
+front-end will recognise it and carry out all computation client-side.
+For arbitrary custom models that are *not* in the built-in registry use
+:func:`phase_plane` instead (see ``custom_model_demo.py``).
+"""
+
+from tvb_phaseplane import PhasePlaneWidget, MPRModel
+
+# ------------------------------------------------------------------
+# 1. Instantiate a model class and optionally override defaults
+# ------------------------------------------------------------------
+model = MPRModel()
+
+# You can pre-configure parameters before creating the widget
+# (the widget will pick these up as its initial slider positions)
+initial_params = {
+    "delta": 1.0,
+    "eta_bar": -5.0,
+    "J": 15.0,
+    "I": 0.0,
+}
+
+# Override the model's default parameter values with your own
+for k, v in initial_params.items():
+    model.default_params[k] = v
+
+# ------------------------------------------------------------------
+# 2. Pass the instance to PhasePlaneWidget
+# ------------------------------------------------------------------
+widget = PhasePlaneWidget(model=model)
+
+# The widget is now live — display it in Jupyter / VS Code
+widget
+
+# ------------------------------------------------------------------
+# 3. After user interaction, read back tuned parameters
+# ------------------------------------------------------------------
+# Run this cell *after* adjusting sliders in the widget:
+print("Current parameter values after tuning:")
+for name, value in widget.params.items():
+    print(f"  {name:12s} = {value:.4f}")
+
+# You can also programmatically set parameters and trigger updates:
+# widget.params["J"] = 20.0
+
+# ------------------------------------------------------------------
+# 4. Read back computed data (nullclines, fixed points, trajectory)
+# ------------------------------------------------------------------
+print(f"\nFixed points detected: {len(widget.fixed_points)}")
+for fp in widget.fixed_points[:5]:
+    print(f"  x={fp[0]:.4f}, y={fp[1]:.4f}, type={fp[2]}")
+
+print(f"\nTrajectory points: {len(widget.trajectory)}")
+
+# ------------------------------------------------------------------
+# 5. Export the tuned configuration to standalone HTML
+# ------------------------------------------------------------------
+widget.to_standalone_html("mpr_tuned.html", title="MPR Model – Tuned Parameters")
+print("\nExported to 'mpr_tuned.html' with current parameter values.")

src/tvb_phaseplane/widget.py

@@ -90,13 +90,20 @@ def _validate_display_mode(self, proposal):
             )
         return v
 
-    def __init__(self, **kwargs):
+    _model_instance = None
+
+    def __init__(self, model=None, **kwargs):
+        if model is not None:
+            self._model_instance = model
+            kwargs.setdefault("model_name", model.name)
         super().__init__(**kwargs)
         self._update_model()
 
     def _get_model(self):
         from .models import MODEL_REGISTRY
 
+        if self._model_instance is not None:
+            return self._model_instance
         cls = MODEL_REGISTRY.get(self.model_name, MODEL_REGISTRY["wilson_cowan"])
         return cls()