{"id":22322659,"url":"https://github.com/alcrene/pyloric-network-simulator","last_synced_at":"2026-01-05T10:40:30.298Z","repository":{"id":165578442,"uuid":"640947117","full_name":"alcrene/pyloric-network-simulator","owner":"alcrene","description":"Pure-Python, JAX-accelerate implementation of the pyloric circuit model described by Prinz et al (Nat. Neurosci., 2004)","archived":false,"fork":false,"pushed_at":"2024-07-23T21:41:25.000Z","size":9928,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-05T16:51:32.962Z","etag":null,"topics":["computational-neuroscience","jax","pyloric-network","simulation"],"latest_commit_sha":null,"homepage":"https://alcrene.github.io/pyloric-network-simulator/pyloric_simulator/prinz2004.html","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alcrene.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-05-15T13:07:04.000Z","updated_at":"2024-07-23T21:41:29.000Z","dependencies_parsed_at":null,"dependency_job_id":"45a8db88-38e3-452f-9cd6-4d41a6ab2501","html_url":"https://github.com/alcrene/pyloric-network-simulator","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alcrene%2Fpyloric-network-simulator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alcrene%2Fpyloric-network-simulator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alcrene%2Fpyloric-network-simulator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alcrene%2Fpyloric-network-simulator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alcrene","download_url":"https://codeload.github.com/alcrene/pyloric-network-simulator/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245284707,"owners_count":20590307,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["computational-neuroscience","jax","pyloric-network","simulation"],"created_at":"2024-12-04T01:08:11.967Z","updated_at":"2026-01-05T10:40:30.287Z","avatar_url":"https://github.com/alcrene.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Pyloric network simulator\n\nThe pyloric circuit model described by Prinz at al.[^model-def] continues to be studied today,\nboth as an instructive model of an interesting biological process[^prinz-research] and also as a case study of functional diversity in computational models.[^goncalves2020]\n\nThis repository is a reimplementation of the model in pure Python, using JAX to achieve comparable execution speeds as C/C++.\n\nIt is especially meant for users who want to modify the code themselves, or integrate as part of a Python stack.\n\n[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.12797199.svg)](https://doi.org/10.5281/zenodo.12797199)\n\n## Other implementations:\n\n- A variant of the [original C++](https://biology.emory.edu/research/Prinz/database-sensors/) implementation used in a later study.\n  - (As of July 2024 the link above seems dead, but this [ModelDB page](https://modeldb.science/144387) is still available.)\n- In [Open source brain](https://v1.opensourcebrain.org/projects/pyloricnetwork). This implementation is designed for interoperability between different neuron simulation solutions, such as NeuroML and NEURON.\n- As an motivating example for the [Brian 2 simulator](https://doi.org/10.7554/eLife.47314).\n- In a tutorial for the [xolotl simulator](https://xolotl.readthedocs.io/en/master/tutorials/first-network/).\n\n## Overview\n\n### Main features\n\n- __Easy to install__\n  - From PyPI: `pip install pyloric-network-simulator \"jax[cpu]\"`\n  - As inlined source: Copy the handful of files under *pyloric_simulator* folder into your project.\n- __Easy to use__\n  - Import as any Python package: `from pyloric_network_simulator import prinz2004`\n  - No need to learn about C linkers or HDF5 file formats.\n  - No dependency on a neuron simulator library\n      - This can be useful to use the model in conjunction with generic numerical toolboxes.\n      - However it also means we don’t benefit from the ecosystem of neuron simulators.\n  - _On-demand thermalization_\n    - The original implementation performs an initial sweep over 20 million parameter sets for individual neurons,\n      integrating each for a long period (~ 5 min simulated time) in order to find their realistic states.\n      This makes sense if we want to systematically test all of those models, but it takes a lot of time, uses a lot\n      of memory, and limits later simulations to those parameters for which we have thermalizations.\n    - The Brian and xolotl implementations are meant as illustrative examples, and to the best of my understanding\n      don’t perform any thermalization.\n    - Here models are thermalized on demand the first time a new parameter combination is used.\n      The result is then saved to an on-disk cache (managed with `shelve`).\n      This makes thermalization completely transparent to the user (modulo a 5–10 min wait time) and ensures that\n      it is performed only on those models which we actually need. This is a much more efficient approach if\n      + We will need to execute the model with a limited number of parameters (e.g. because the parameter ranges we\n        want to explore have already been identified).\n      + We want to search the parameter space more efficiently, for example with a gradient-based parameter optimizer.\n        This can allow for much higher resolutions in parameter space, while still requiring much fewer model simulations\n        than a grid search.\n- __Fast__\n  - Special care was taken to use vectorized operations wherever possible, and JAX’s JIT capability is used to compile\n    the model to C at runtime. This should provide speeds comparable with a plain C/C++ implementation.\n    Use of JAX also opens the possibility of using GPU acceleration for models with many neurons.\n- __Fully documented__\n  - The original specification of the pyloric circuit model is spread across at least three resources[^model-def].\n  - Here all definitions are in one place, fully referenced and using consistent notation.\n    Since the documentation is inlined into the code, definitions appear right next to where they are actually used.\n- __Easy to modify__\n  - Users have full control over the circuit topology: number, size and type of populations, as well as the synaptic conductivities, are all specified when creating the model:\n\n    Standard pyloric circuit with 4 populations\n    \n        model = Prinz2004(pop_sizes = {\"PD\": 2, \"AB\": 1, \"LP\": 1, \"PY\": 5},      # Pop. sizes\n                          gs      = [ [    0  ,     0  ,     3  ,     0 ],       # Syn. conductivities\n                                      [    0  ,     0  ,     3  ,     3 ],\n                                      [    3  ,     3  ,     0  ,     3 ],\n                                      [    3  ,     3  ,     3  ,     0 ] ],\n                          g_ion = neuron_models.loc[[\"AB/PD 3\", \"AB/PD 3\", \"LP 1\", \"PY 5\"]]   # Neuron types\n                          )\n\n     Reduced pyloric circuit with 2 populations\n    \n        model = Prinz2004(pop_sizes = {\"AB\": 1, \"LP\": 1},\n                          gs      = [ [    0  ,     3 ],\n                                      [    3  ,     0 ] ],\n                          g_ion = neuron_models.loc[[\"AB/PD 3\", \"LP 1\"]]\n                          )\n- __Easy to understand__\n  - Python is easier to read than C++ and familiar to more users (especially to scientists).\n  - The code structure closely follows how the model is defined in the papers, making it easier to understand each component.\n  - The entire model fits in a single code file.\n  - The code file can be opened in a Jupyter Notebook,[^jupytext] providing structure and formatted documentation explaining each code section in detail.  \n    ![Screenshot: Conductance model](docs/inlined-docs-1.png)  ![Screenshot: Constants](docs/inlined-docs-2.png)\n\n### Limitation\n\nThe principal and very important disadvantage of this implementation is that currently it was only used for one example in one paper,\nin contrast to the original C/C++ implementation which has received many years of focussed attention.\nThis implementation also has not been exhaustively tested for consistency with the original.\n\n- Basic qualitative comparisons suggests that the single neuron conductance models closely reproduce the results reported by Prinz et al.\n- Some differences in the simulated activity (with respect to the original implementation) do seem to occur when neuron models are combined into a circuit.\n\n### Code structure\n\nThe code uses [MyST Markdown](https://mystmd.org/) and [Jupytext](https://jupytext.readthedocs.io/), which enables a [literate programming](https://texfaq.org/FAQ-lit) style by embedding rich Markdown comments in Python comments.\nThe result is documentation and code which are located as near as possible.\nThis is especially useful for scientific programming, where the code itself may not be especially complicated, but may be the result of\ncomplex arguments which need mathematics or figures to express intelligibly.\n\nLiterate code files like `prinz2004.py` are multi-purpose:\n- Import them as normal Python modules.\n- Run them as normal Python modules on the command line.\n- When opened in Jupyter Notebook or VS Code, all markdown comments are rendered inline, placing math and figures right there alongside the code.\n- Export to HTML book format (this is how we produce the documentation).\n\n## Installation\n\n### From the PyPI index\n\n    pip install pyloric-network-simulator \"jax[cpu]\"\n\n### As inlined source\n\nSince the entire project is just a few files, it is completely legitimate to just inline the entire thing into your project.\nThis has the advantage that it makes it easy for you to peruse the code and inlined documentation, and to make changes to suit your needs.\n\nThis is the installation method I recommend, since it encourages you to take ownership of the code rather than trust it blindly.\nIt also ensures that the exact version you use is archived within your project.\n\n1. Download the [most recent release](https://github.com/alcrene/pyloric-network-simulator/releases).  \n   Alternatively, you can use [`git-subrepo`](https://github.com/ingydotnet/git-subrepo) to clone this repository into a subdirectory of your project. This has the advantage of later allowing you to pull updates.\n\n2. Unpack into your project directory, so it looks something like\n\n       \u003cmy-project\u003e\n       ├─ ...\n       └─ pyloric_simulator\n          ├─ config/\n          ├─ prinz2004.py\n          ├─ requirements.txt\n          └─ ...\n\n   or\n\n       \u003cmy-project\u003e\n       ├─ ...\n       └─ lib\n          └─ pyloric_simulator\n             ├─ config/\n             ├─ prinz2004.py\n             ├─ requirements.txt\n             └─ ...\n\n3. Install the requirements\n\n       pip install -r ./pyloric_simulator/requirements.txt\n\n4. Add the contents of `requirements.txt` to your own dependencies.\n\nTo use the `prinz2004.py` module, just import it as you would any of your own modules.\n\n### Developer alternative: as a separate editable package\n\nIf you want to develop the simulator, you may prefer to clone the repository and make it a dependency to your project.\n\n1. Choose a location for the repo\n\n       cd ~/code\n   \n2. Clone the repo\n\n       git clone git@github.com:alcrene/pyloric-network-simulator.git\n\n3. Install in [development mode](https://setuptools.pypa.io/en/latest/userguide/development_mode.html)\n\n       pip install -e ./pyloric-network-simulator\n\n## Usage\n\nIf you installed as a package: `from pyloric_network_simulator import prinz2004`.\n\nIf you installed as inlined source: The exact import statement will depend on where you placed the unpacked files.\nIt may look like `from my_project.pyloric_network_simulator import prinz2004`.\n\nSee the [documentation](https://alcrene.github.io/pyloric-network-simulator/pyloric_simulator/prinz2004.html) for further instructions and examples.\n\n## Building the documentation\n\nEnsure the *.md* and *.py* files are synchronized\n\n    jupytext --sync pyloric_simulator/prinz2004.md\n\n[Build](https://jupyterbook.org/en/stable/start/your-first-book.html) the documentation using\n\n    jb build .\n\n[Push](https://jupyterbook.org/en/stable/publish/gh-pages.html#option-2-automatically-push-your-build-files-with-ghp-import) to GitHub Pages\n\n    ghp-import -n -p -f _build/html\n\n\n[^model-def]:\n    • Prinz, A. A., Bucher, D. \u0026 Marder, E. *Similar network activity from disparate circuit parameters.* Nature Neuroscience 7, 1345–1352 (2004). [doi:10.1038/nn1352](https://doi.org/10.1038/nn1352)  \n    • Prinz, A. A., Billimoria, C. P. \u0026 Marder, E. *Alternative to Hand-Tuning Conductance-Based Models: Construction and Analysis of Databases of Model Neurons.*\n      Journal of Neurophysiology 90, 3998–4015 (2003). [doi:10.1152/jn.00641.2003](https://doi.org/10.1152/jn.00641.2003)  \n    • Marder, E. \u0026 Abbott, L. F. *Modeling small networks.* in Methods in neuronal modeling: from ions to networks (eds. Koch, C. \u0026 Segev, I.) (MIT Press, 1998).\n\n[^prinz-research]: https://biology.emory.edu/research/Prinz/research.html\n[^goncalves2020]: Gonçalves, P. J. et al. *Training deep neural density estimators to identify mechanistic models of neural dynamics.* eLife 9, e56261 (2020). [doi:10.7554/eLife.56261](https://doi.org/10.7554/eLife.56261)\n[^jupytext]: Presuming the [Jupytext](https://jupytext.readthedocs.io/) extension is installed.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falcrene%2Fpyloric-network-simulator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falcrene%2Fpyloric-network-simulator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falcrene%2Fpyloric-network-simulator/lists"}