neuroseq 0.30.0__tar.gz

neuroseq-0.30.0/.gitignore

@@ -0,0 +1,149 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+/artifacts/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+*.prof
+latest.prof
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv*
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# Generated documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# OS specifics
+*.DS_Store
+
+# ide
+.vscode
+.idea
+
+# AI tool internal files
+.claude/
+.codex
+uv.lock
+uv.lock
+uv.lock
+
+# Stray pytest --basetemp directories
+.pytest-*/

neuroseq-0.30.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 Andrey Formozov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

neuroseq-0.30.0/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.5
+Name: neuroseq
+Version: 0.30.0
+Summary: Qt-based desktop GUI application for computational neuroscience, combining Brian2 spiking neural network simulation with interactive stimulus design, multi-source experimental data import, and hardware export for holographic stimulation (HOLO4D .seq files).
+Project-URL: Homepage, https://neuroseq.github.io/
+Project-URL: Documentation, https://neuroseq.github.io/
+Project-URL: Source, https://github.com/neuroseq/neuroseq
+Project-URL: Issues, https://github.com/neuroseq/neuroseq/issues
+Author: Andrey Formozov
+License-Expression: MIT
+License-File: LICENSE
+Keywords: brian2,calcium imaging,gui,holographic stimulation,neuroscience,optogenetics,spiking neural networks
+Classifier: Environment :: X11 Applications :: Qt
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.12
+Requires-Dist: brian2
+Requires-Dist: cellpose[gui]
+Requires-Dist: click
+Requires-Dist: fastplotlib
+Requires-Dist: h5py
+Requires-Dist: igor2
+Requires-Dist: matplotlib
+Requires-Dist: numpy
+Requires-Dist: nvidia-ml-py
+Requires-Dist: pillow
+Requires-Dist: platformdirs
+Requires-Dist: psutil
+Requires-Dist: pyparsing!=3.2.4
+Requires-Dist: pyqt6
+Requires-Dist: pyqt6-qt6!=6.11.1
+Requires-Dist: pyqtgraph!=0.14.0
+Requires-Dist: qtawesome
+Requires-Dist: qtpy
+Requires-Dist: scipy
+Requires-Dist: suite2p>=1.0
+Requires-Dist: tifffile
+Requires-Dist: torch
+Requires-Dist: torchvision
+Provides-Extra: chat
+Requires-Dist: anthropic>=0.40; extra == 'chat'
+Requires-Dist: httpx>=0.27; extra == 'chat'
+Requires-Dist: keyring>=24; extra == 'chat'
+Requires-Dist: openai>=1.40; extra == 'chat'
+Description-Content-Type: text/markdown
+
+# NeuroSeq - Neuronal Sequencer
+
+[![CI](https://github.com/neuroseq/neuroseq/actions/workflows/ci.yml/badge.svg)](https://github.com/neuroseq/neuroseq/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/neuroseq)](https://pypi.org/project/neuroseq/)
+[![Docs](https://img.shields.io/badge/docs-neuroseq.github.io-blue)](https://neuroseq.github.io/)
+
+NeuroSeq is a Qt-based desktop GUI application for computational neuroscience. It combines Brian2 spiking neural network simulation with interactive stimulus design, multi-source experimental data import, and hardware export for holographic stimulation (HOLO4D `.seq` files).
+
+![screenshot](https://raw.githubusercontent.com/neuroseq/neuroseq/main/docs/images/screenshot.png)
+
+## Installation
+
+NeuroSeq requires Python 3.12 or newer. Install the latest release from
+[PyPI](https://pypi.org/project/neuroseq/), ideally into a virtual environment
+or Conda environment:
+
+```bash
+pip install neuroseq
+```
+
+Then launch the GUI with:
+
+```bash
+neuroseq
+```
+
+To upgrade to a newer release, run `pip install --upgrade neuroseq`.
+
+See the [installation guide](https://neuroseq.github.io/getting_started/installation/)
+for details, including GPU setup and Cython on Windows, and the
+[developer installation guide](https://neuroseq.github.io/developer/developer_installation/)
+to work on NeuroSeq from a repository checkout with uv or Conda.
+
+## Documentation
+
+Documentation for the project is available [online](https://neuroseq.github.io/).
+See the [documentation guide](https://neuroseq.github.io/developer/documentation/) to build or preview it locally.
+
+## Contributing and providing feed-back
+
+The NeuroSeq is an open-source project. Everyone can suggest and implement improvements as well as improve overall reliability and stability of its operation.
+
+To report a bug or suggest a new feature functionality please open a new issue. To implement a new feature, please fork the repository, modify the code accordingly and open a discussion with core developers via submitting a pull request.
+
+## License
+
+NeuroSeq is released under the [MIT License](https://github.com/neuroseq/neuroseq/blob/main/LICENSE). Copyright © 2024-2026 Andrey Formozov.
+See [AUTHORS.md](https://github.com/neuroseq/neuroseq/blob/main/AUTHORS.md) for the list of contributors.

neuroseq-0.30.0/README.md

@@ -0,0 +1,48 @@
+# NeuroSeq - Neuronal Sequencer
+
+[![CI](https://github.com/neuroseq/neuroseq/actions/workflows/ci.yml/badge.svg)](https://github.com/neuroseq/neuroseq/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/neuroseq)](https://pypi.org/project/neuroseq/)
+[![Docs](https://img.shields.io/badge/docs-neuroseq.github.io-blue)](https://neuroseq.github.io/)
+
+NeuroSeq is a Qt-based desktop GUI application for computational neuroscience. It combines Brian2 spiking neural network simulation with interactive stimulus design, multi-source experimental data import, and hardware export for holographic stimulation (HOLO4D `.seq` files).
+
+![screenshot](https://raw.githubusercontent.com/neuroseq/neuroseq/main/docs/images/screenshot.png)
+
+## Installation
+
+NeuroSeq requires Python 3.12 or newer. Install the latest release from
+[PyPI](https://pypi.org/project/neuroseq/), ideally into a virtual environment
+or Conda environment:
+
+```bash
+pip install neuroseq
+```
+
+Then launch the GUI with:
+
+```bash
+neuroseq
+```
+
+To upgrade to a newer release, run `pip install --upgrade neuroseq`.
+
+See the [installation guide](https://neuroseq.github.io/getting_started/installation/)
+for details, including GPU setup and Cython on Windows, and the
+[developer installation guide](https://neuroseq.github.io/developer/developer_installation/)
+to work on NeuroSeq from a repository checkout with uv or Conda.
+
+## Documentation
+
+Documentation for the project is available [online](https://neuroseq.github.io/).
+See the [documentation guide](https://neuroseq.github.io/developer/documentation/) to build or preview it locally.
+
+## Contributing and providing feed-back
+
+The NeuroSeq is an open-source project. Everyone can suggest and implement improvements as well as improve overall reliability and stability of its operation.
+
+To report a bug or suggest a new feature functionality please open a new issue. To implement a new feature, please fork the repository, modify the code accordingly and open a discussion with core developers via submitting a pull request.
+
+## License
+
+NeuroSeq is released under the [MIT License](https://github.com/neuroseq/neuroseq/blob/main/LICENSE). Copyright © 2024-2026 Andrey Formozov.
+See [AUTHORS.md](https://github.com/neuroseq/neuroseq/blob/main/AUTHORS.md) for the list of contributors.

neuroseq-0.30.0/docs/common_issues.md

@@ -0,0 +1,49 @@
+## Issues during installation
+
+### Long paths in windows
+
+During installation on windows one can encounter the following error:
+
+```
+ERROR: Could not install packages due to an OSError: [Errno 2] No such file or directory: 'C:\\Users\\af24\\AppData\\Local\\Temp\\pip-install-i3syxwx0\\imgui-bundle_3462a851e1e44f9caa7b8510206f002e\\external\\hello_imgui\\hello_imgui\\hello_imgui_cmake\\android\\apkCMake\\templates\\sdl\\gradle_template\\app\\src\\main\\java\\org\\libsdl\\app\\HIDDeviceBLESteamController.java'
+HINT: This error might have occurred since this system does not have Windows Long Path support enabled. You can find information on how to enable this at https://pip.pypa.io/warnings/enable-long-paths
+```
+
+The issues can be fixed by entering Registry Editor and modifying _LongPathsEnabled_ variable under _HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem_ from "0" to "1".
+
+Refer to [this webpage](https://learn.microsoft.com/en-us/windows/win32/fileio/maximum-file-path-limitation?tabs=registry#enable-long-paths-in-windows-10-version-1607-and-later) on the instructions to fix it.
+
+## Imaging / segmentation
+
+### Cellpose "use GPU" is greyed out (segmentation is very slow)
+
+Cellpose (and Suite2p) only offer GPU acceleration when **PyTorch** exposes a
+GPU backend — **CUDA** (NVIDIA) or **MPS** (Apple Silicon). A **CPU-only**
+PyTorch build disables the "use GPU" checkbox. This is common on **Windows**,
+where PyPI's default `torch` wheel is CPU-only.
+
+Check the installed build (in the NeuroSeq environment):
+
+```bash
+python -c "import torch; print(torch.__version__, torch.cuda.is_available())"
+```
+
+`…+cpu` / `False` means CPU-only. If the machine has an NVIDIA (or
+Apple-Silicon) GPU, install a GPU build and relaunch:
+
+```bash
+uv pip install --torch-backend=auto torch
+```
+
+Not using `uv` (e.g. NeuroSeq is installed into a conda environment)? Install
+directly with pip instead:
+
+```bash
+pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu128
+```
+
+If the machine has **only Intel integrated graphics**, Cellpose cannot use it
+(CUDA/MPS only) — run segmentation on a GPU machine and import its `_seg.npy`
+instead. See
+[Importing imaging data → GPU acceleration](user_guide/importing_imaging_data.md#gpu-acceleration-cellpose-suite2p)
+for details.

neuroseq-0.30.0/docs/developer/analysis_plugins.md

@@ -0,0 +1,43 @@
+# Analysis Plugins (Developer)
+
+This page describes how the custom analysis plugin system works internally and how to implement new analysis plugins.
+
+## Architecture Overview
+
+Plugin support is split across three core modules:
+
+- `src/neuroseq/analysis_plugins.py`
+  - Discovers plugin modules from `src/neuroseq/resources/analysis_plugins`
+    and from the per-user folder returned by `user_plugins_directory()`
+    (user plugins never shadow built-in filenames or `PLUGIN_ID`s)
+  - Loads each plugin file dynamically
+  - Builds `AnalysisPlugin` objects (`id`, `label`, `icon`, `render`)
+- `src/neuroseq/visualization/timeseries_widget.py`
+  - Rebuilds right-click analysis menu on demand
+  - Adds built-in analysis actions and plugin actions
+  - Emits `custom_analysis_requested` with either a built-in `CustomAnalysisType` or an `AnalysisPlugin`
+- `src/neuroseq/visualization/custom_analysis_widget.py`
+  - Executes built-in analysis logic
+  - Executes plugin `render` callback for plugin analyses
+  - Catches plugin exceptions, logs the plugin id, and shows a failure message in the plot
+
+## Plugin Discovery
+
+A plugin is a Python file in: `src/neuroseq/resources/analysis_plugins`. It must have `*.py` extention (files starting with `_` will be ignored) and define callable `render_analysis`. Each pluging has ID, NAME and ICON. The default value for ID and NAME is a filename without extention but user can also define them as `PLUGIN_ID`, `PLUGIN_NAME`, and `PLUGIN_ICON` (e.g. `mdi6.puzzle`). `PLUGIN_ID` should be stable over time. Use a machine-oriented id (for example, `mean_activity`) and keep display text in `PLUGIN_NAME`. At the present momement dropdown menu does not distinguish the type of the data that is being analysed and shows all improrted plugins regardless of datatype.
+
+See [`src/neuroseq/resources/analysis_plugins/mean_activity.py`](https://github.com/neuroseq/neuroseq/blob/main/src/neuroseq/resources/analysis_plugins/mean_activity.py) for a working example plugin.
+
+## Advanced Interactive Example
+
+The ELiSe plugins are thin wrappers; their supporting code is a regular
+package, `src/neuroseq/elise_support/`: `replay_metrics.py` provides replay
+metrics and CSV export, `workflows.py` connects project data to the analysis
+windows, and `protocol_dialog.py` provides protocol settings. Keep core code
+out of the plugin folder: it is scanned and executed on every right-click
+menu and is excluded from coverage.
+
+For an advanced plugin example with UI controls, see [`src/neuroseq/resources/analysis_plugins/advanced_mean_activity.py`](https://github.com/neuroseq/neuroseq/blob/main/src/neuroseq/resources/analysis_plugins/advanced_mean_activity.py).
+
+This plugin extends the basic mean-activity analysis by adding an interactive control bar in the same analysis window.
+
+important: for the analysis widgets opened in the same window as it is the case for "show custom analysis" pad it is important to prevent duplicating of controls when the same plugin is run repeatedly in one open analysis widget.

neuroseq-0.30.0/docs/developer/contributing.md

@@ -0,0 +1,41 @@
+# Contributing
+
+The NeuroSeq is an open-source project. Everyone can suggest and implement improvements as well as improve overall reliability and stability of its operation.
+
+## Development pipeline
+
+1. Fork and clone repository.
+2. Create a feature branch.
+3. [Install](developer_installation.md) in editable mode.
+4. Modify the code.
+5. Test new functionality.
+6. Run [pytests](testing.md) before opening a pull request.
+
+## Project workspaces
+
+`gui.py` contains the application shell. Each tab embeds a separate
+`ProjectWorkspace` from `project_workspace.py`, which owns its project's widgets,
+controllers, console namespace, undo history, input designers, detached windows,
+and background jobs. The workspace uses a child `QMainWindow` to lay out its own
+menus and toolbars. `Gui.active_workspace` is the explicit access point for the
+current tab; `Gui.project` and forwarded attribute reads remain available for
+integrations.
+
+Switching tabs changes the visible workspace without calling `update_project()`
+or copying widget state into `Project`. Playback pauses when leaving a tab;
+background jobs continue and deliver their results to their owning workspace.
+`update_project()` refreshes data within a workspace, for example after imports
+or model edits. GUI state remains in memory and is not serialized to `.nseq`.
+
+Settings and physical connections are application resources. `workspace_devices.py`
+shares the ScanImage connection and SysCon2 transport. Each SysCon2 panel receives
+a session that routes command replies to the requesting workspace; connection
+status is shared. Only the active workspace receives live ScanImage frames.
+Acquisition results are matched by run ID to the workspace that requested them.
+Closing a tab stops its jobs and releases its resources without disconnecting
+other tabs. Application shutdown checks unsaved projects individually and stops
+all workspaces before shutting down the shared connections.
+
+Run `uv run pytest tests/test_project_workspaces.py` for tab isolation, background
+result routing, device sessions, and workspace lifecycle tests. Existing widget
+and workflow tests exercise `ProjectWorkspace` directly.

neuroseq-0.30.0/docs/developer/custom_simulators.md

@@ -0,0 +1,156 @@
+# Integration of Custom Simulators
+
+This page describes the current structure used for NeuroSeq external simulators and how to implement a new backend.
+
+## Overview
+
+NeuroSeq has built-in Brian2 simulator but also supports arbitraty simulation backends. These backends are loaded through `Project.load_external_simulator()` and are expected to produce an `Experiment` object from stimulus arrays.
+
+There are now two layers:
+
+1. A shared base class in [src/neuroseq/example_models/NN.py](https://github.com/neuroseq/neuroseq/blob/main/src/neuroseq/example_models/NN.py).
+2. A backend implementation class such as [src/neuroseq/example_models/elise.py](https://github.com/neuroseq/neuroseq/blob/main/src/neuroseq/example_models/elise.py).
+
+The base class is intentionally lightweight. It does not use `abc`; instead, subclass methods are expected to override the base methods and the defaults raise `NotImplementedError`.
+
+## Structure of the Base NN Class
+
+The shared `NN` class in [src/neuroseq/example_models/NN.py](https://github.com/neuroseq/neuroseq/blob/main/src/neuroseq/example_models/NN.py) provides common state and parameter handling.
+
+It currently contains:
+
+1. `__init__(default_params_schema)`
+   Stores a deep copy of the editable parameter schema, initializes flat parameter values from the schema defaults, and initializes cumulative simulated time.
+2. `simulated_time_seconds`
+   Property exposing the amount of simulated time already accumulated by the backend instance.
+3. `default_params_schema()`
+   Returns a deep copy of the editable parameter schema for use in the GUI.
+4. `flat_default_params()`
+   Returns a flat `{name: default_value}` mapping derived from the schema.
+5. `update_params(params)`
+   Merges user-provided parameter overrides onto defaults and resets backend state if anything changed.
+6. `_flat_defaults()`
+   Internal helper that flattens the schema into default values.
+7. `reset()`
+   Subclass hook that must clear backend-specific runtime state.
+8. `simulate(stims_dict, simulation_time, params=None)`
+   Subclass hook that must run one simulation chunk and return an `Experiment`.
+
+The important design point is that the base class owns parameter bookkeeping and cumulative time, while the subclass owns backend-specific runtime objects.
+
+## Structure of a Backend Implementation
+
+An implementation module should define a backend class derived from `NN`. The ELISE backend in [src/neuroseq/example_models/elise.py](https://github.com/neuroseq/neuroseq/blob/main/src/neuroseq/example_models/elise.py) is the current reference implementation.
+
+The backend class should typically provide:
+
+1. `__init__()`
+   Calls `super().__init__(DEFAULT_PARAMS)` and initializes backend-specific runtime fields such as cached networks, signatures, RNG state, or imported backend types.
+2. `reset()`
+   Clears runtime state that should be rebuilt when parameters change.
+3. Backend-specific initialization helpers
+   For example, ELISE uses `_import_elise_types()` and `_initialize_network(num_vis)`.
+4. `simulate(...)`
+   Validates inputs, applies parameter updates, initializes or reuses the backend state, advances the simulation, and returns an `Experiment` containing the generated data.
+
+For stateful backends, `simulate(...)` should preserve runtime state between calls so repeated runs can continue from the previous state instead of starting over.
+
+## Module-Level Entry Points
+
+For integration with the current project and GUI code, the module should expose these entry points:
+
+1. `simulate(stims_dict, simulation_time, params=None)`
+   Compatibility wrapper used by the existing call sites.
+2. `get_simulator()`
+   Returns the singleton backend instance.
+3. `NN`
+   Constructor used by `Project.load_external_simulator()` when a module exposes a class-based backend entry point.
+4. A singleton instance such as `_SIMULATOR = Elise()`.
+
+This keeps the current GUI and project logic simple while still allowing a class-based implementation internally.
+
+When restoring an archive, `Project` calls the backend instance's optional
+`migrate_project(project)` method after loading the simulator and project data.
+Backends can use this hook to upgrade their own legacy stimulus formats. The
+ELISE implementation keeps these conversions, its example project factory
+(`create_project()`), and teaching-pattern helpers in
+`src/neuroseq/example_models/elise.py`. The example menu registers a small
+wrapper in `example_projects/networks/elise_project.py` that delegates to this factory.
+
+Example project factories live in `src/neuroseq/example_projects/`, with one
+project per file under `neurons/` or `networks/`. The package's `__init__.py`
+exports the factories and imports them in their existing menu order.
+`_registry.py` provides the `register_example_project` decorator. New examples
+should define a decorated factory in the appropriate folder, import it in
+the package entry point, and add it to `__all__` so it is exported and appears
+in the example-project menu.
+
+## Expected Data Flow
+
+The external simulator call path is:
+
+1. The GUI collects stimulus arrays into `stims_dict`.
+2. `Project.load_external_simulator()` loads either:
+   a. a built-in NeuroSeq simulator module such as `neuroseq:elise`, or
+   b. a Python file containing a `simulate(...)` entry point.
+3. The backend `simulate(...)` method returns an `Experiment`.
+4. The GUI offers the returned experiment for import or append into the project.
+
+## Minimal Template
+
+```python
+from collections.abc import Mapping
+
+from neuroseq.data import Experiment
+from neuroseq.example_models.NN import ParamValue
+from neuroseq.example_models.NN import NN
+
+DEFAULT_PARAMS = {
+    "example_param": {
+        "value": 1.0,
+        "default": 1.0,
+        "type": "float",
+        "group": "General",
+        "description": "Example parameter.",
+    }
+}
+
+
+class MyBackend(NN):
+    def __init__(self) -> None:
+        super().__init__(DEFAULT_PARAMS)
+        self._runtime = None
+
+    def reset(self) -> None:
+        self._runtime = None
+        self._simulated_time_s = 0.0
+
+    def simulate(
+        self,
+        stims_dict: dict,
+        simulation_time: float,
+        params: Mapping[str, ParamValue] | None = None,
+    ) -> Experiment:
+        self.update_params(params)
+        # build or reuse runtime state
+        # run the backend
+        # return Experiment(...)
+        raise NotImplementedError
+
+
+def simulate(stims_dict, simulation_time, params=None):
+    return _SIMULATOR.simulate(stims_dict, simulation_time, params=params)
+
+
+def get_simulator() -> MyBackend:
+    return _SIMULATOR
+
+
+_SIMULATOR = MyBackend()
+```
+
+## Notes
+
+1. The GUI parameter editor consumes the schema stored in `project.external_simulate_params`, so schema keys and value types should remain simple.
+2. The `Experiment` returned by the backend should be self-contained for the run chunk that was just simulated.
+3. If the backend is stateful, use `self._simulated_time_s` to align repeated runs with previously simulated time.