This is the development version of the OSS-DBS rewrite. Use with caution and please wait for the first official release before deploying it. Bug reports are highly welcome, though!
OSS-DBS is tested with Python 3.10, 3.11, 3.12, and 3.13.
Windows users: Please install NEURON separately before installing OSS-DBS. The instructions can be found here.
All other users can run
pip install ossdbs
We recommend uv for development. It is a fast,
drop-in replacement for pip/virtualenv that manages the virtual environment
and Python interpreter for you and uses the checked-in uv.lock for fully
reproducible installs. See the installation instructions.
Clone OSS-DBS into a local directory, cd into it, and create the environment
with the exact locked dependencies:
uv sync
uv sync creates a .venv/ and installs OSS-DBS in editable mode. Select
optional dependency groups with --extra:
uv sync --extra test # to run the test suite
uv sync --extra dev # to develop OSS-DBS
uv sync --extra doc # to locally build the docs
uv sync --extra all # everything of the above
Run commands inside the environment with uv run, e.g. uv run pytest or
uv run ossdbs input.json (no manual activation needed).
Prefer plain pip? Click to expand.
Everything above also works with pip. Clone OSS-DBS, cd into the directory
and run one of:
pip install -e . # base install
pip install -e ".[test]" # to run the test suite
pip install -e ".[dev]" # to develop OSS-DBS
pip install -e ".[doc]" # to locally build the docs
pip install -e ".[all]" # everything of the above
Note that pip resolves dependencies fresh and does not use uv.lock.
To run OSS-DBS, cd into the input_files directory, insert your parameters in the input.json
and start the simulation with
ossdbs input.json
Also check out the examples directory and the documentation.
The code development follows different coding styles that are checked
by git pre-commit hooks.
After uv sync --extra dev (or pip install -e ".[dev]"), activate the hooks
with uv run pre-commit install (or pre-commit install).
OSS-DBS has two types of tests:
Unit Tests (tests/): Fast, isolated tests that run on every push/PR.
pytest # Run all unit tests
pytest --cov # With coverageSimulation Tests (input_test_cases/): Full simulation tests that validate the complete pipeline. These run only on pull requests to avoid slowing down regular development.
pytest input_test_cases/test_simulations.py -m simulation # All simulation tests
pytest input_test_cases/test_simulations.py -m "simulation and not slow" # Fast onlySee input_test_cases/README.md for detailed documentation on the simulation test suite, including how to add new tests.
tests/- Unit tests (run on every commit)input_test_cases/- Simulation tests (run on PR only)input_files/- Reference input filesexamples/- Example code for users (may be resource-intensive)
build_merged.py freezes OSS-DBS and all of its dependencies into a
self-contained bundle with PyInstaller, so that
end users do not need a Python toolchain. On Windows this is also how NEURON is
shipped: install and compile NEURON into the build environment first, then
freeze it into the bundle so users get PAM support without installing NEURON
themselves.
PyInstaller freezes whatever is present in the current environment, so
provision that environment reproducibly with uv and the checked-in
uv.lock before building:
uv sync --locked --group bundle # locked deps + PyInstaller, from uv.lock
# (Windows only) install + compile NEURON into .venv here, see
# docs/windows_neuron_setup.md
uv run python build_merged.pyPyInstaller lives in the bundle dependency group,
so it is pinned in uv.lock and installed from there rather than pulled from an
external pip.
The bundle is written to dist/ossdbs_bundle/. Because the environment comes
from uv.lock, the frozen dependency set is identical across rebuilds; run
uv lock (and commit the result) whenever you intentionally update a
dependency.