# Pyloric network simulator
The pyloric circuit model described by Prinz at al.[^model-def] continues to be studied today,
both as an instructive model of an interesting biological process[^prinz-research] and also as a case study of functional diversity in computational models.[^goncalves2022]
This repository is a reimplementation of the model in pure Python, using JAX to achieve comparable execution speeds as C/C++.
It is especially meant for users who want to modify the code themselves, or integrate as part of a Python stack.
## Other implementations:
- A variant of the [original C++](https://biology.emory.edu/research/Prinz/database-sensors/) implementation used in a later study.
- (As of July 2024 the link above seems dead, but this [ModelDB page](https://modeldb.science/144387) is still available.)
- 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.
- As an motivating example for the [Brian 2 simulator](https://doi.org/10.7554/eLife.47314).
- In a tutorial for the [xolotl simulator](https://xolotl.readthedocs.io/en/master/tutorials/first-network/).
## Overview
### Main features
- __Easy to install__
- From PyPI: `pip install pyloric-network-simulator "jax[cpu]"`
- As inlined source: Copy the handful of files under *pyloric_simulator* folder into your project.
- __Easy to use__
- Import as any Python package: `from pyloric_network_simulator import prinz2004`
- No need to learn about C linkers or HDF5 file formats.
- No dependency on a neuron simulator library
- This can be useful to use the model in conjunction with generic numerical toolboxes.
- However it also means we don’t benefit from the ecosystem of neuron simulators.
- _On-demand thermalization_
- The original implementation performs an initial sweep over 20 million parameter sets for individual neurons,
integrating each for a long period (~ 5 min simulated time) in order to find their realistic states.
This makes sense if we want to systematically test all of those models, but it takes a lot of time, uses a lot
of memory, and limits later simulations to those parameters for which we have thermalizations.
- The Brian and xolotl implementations are meant as illustrative examples, and to the best of my understanding
don’t perform any thermalization.
- Here models are thermalized on demand the first time a new parameter combination is used.
The result is then saved to an on-disk cache (managed with `shelve`).
This makes thermalizations completely transparent to the user (modulo a 5–10 min wait time) and ensures that
it is performed only on those models which we actually need. This is a much more efficient approach if
+ We will need to execute the model with a limited number of parameters (e.g. because the parameter ranges we
want to explore have already been identified).
+ We want to search the parameter space more efficiently, for example with a gradient-based parameter optimizer.
This can allow for much higher resolutions in parameter space, while still requiring much fewer model simulations
than a grid search.
- __Fast__
- Special care was taken to use vectorized operations wherever possible, and JAX’s JIT capability is used to compile
the model to C at runtime. This should provide speeds comparable with a plain C/C++ implementation.
Use of JAX also opens the possibility of using GPU acceleration for models with many neurons.
- __Fully documented__
- The original specification of the pyloric circuit model is spread across at least three resources[^model-def].
- Here all definitions are in one place, fully referenced and using consistent notation.
Since the documentation is inlined into the code, definitions appear right next to where they are actually used.
- __Easy to modify__
- 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:
Standard pyloric circuit with 4 populations
model = Prinz2004(pop_sizes = {"PD": 2, "AB": 1, "LP": 1, "PY": 5}, # Pop. sizes
gs = [ [ 0 , 0 , 3 , 0 ], # Syn. conductivities
[ 0 , 0 , 3 , 3 ],
[ 3 , 3 , 0 , 3 ],
[ 3 , 3 , 3 , 0 ] ],
g_ion = neuron_models.loc[["AB/PD 3", "AB/PD 3", "LP 1", "PY 5"]] # Neuron types
)
Reduced pyloric circuit with 2 populations
model = Prinz2004(pop_sizes = {"AB": 1, "LP": 1},
gs = [ [ 0 , 3 ],
[ 3 , 0 ] ],
g_ion = neuron_models.loc[["AB/PD 3", "LP 1"]]
)
- __Easy to understand__
- Python is easier to read than C++ and familiar to more users (especially to scientists).
- The code structure closely follows how the model is defined in the papers, making it easier to understand each component.
- The entire model fits in a single code file.
- The code file can be opened in a Jupyter Notebook,[^jupytext] providing structure and formatted documentation explaining each code section in detail.
 
### Limitation
The principal and very important disadvantage of this implementation is that currently it was only used for one example in one paper,
in contrast to the original C/C++ implementation which has received many years of focussed attention.
This implementation also has not been exhaustively tested for consistency with the original.
- Basic qualitative comparisons suggests that the single neuron conductance models closely reproduce the results reported by Prinz et al.
- Some differences in the simulated activity (with respect to the original implementation) do seem to occur when neuron models are combined into a circuit.
### Code structure
The 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.
The result is documentation and code which are located as near as possible.
This is especially useful for scientific programming, where the code itself may not be especially complicated, but may be the result of
complex arguments which need mathematics or figures to express intelligibly.
Literate code files like `prinz2004.py` are multi-purpose:
- Import them as normal Python modules.
- Run them as normal Python modules on the command line.
- When opened in Jupyter Notebook or VS Code, all markdown comments are rendered inline, placing math and figures right there alongside the code.
- Export to HTML book format (this is how we produce the documentation).
## Installation
### From the PyPI index
pip install pyloric-network-simulator "jax[cpu]"
### As inlined source
Since the entire project is just a few files, it is completely legitimate to just inline the entire thing into your project.
This 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.
This is the installation method I recommend, since it encourages you to take ownership of the code rather than trust it blindly.
It also ensures that the exact version you use is archived within your project.
1. Download the [most recent release](https://github.com/alcrene/pyloric-network-simulator/releases).
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.
2. Unpack into your project directory, so it looks something like
<my-project>
├─ ...
└─ pyloric_simulator
├─ config/
├─ prinz2004.py
├─ requirements.txt
└─ ...
or
<my-project>
├─ ...
└─ lib
└─ pyloric_simulator
├─ config/
├─ prinz2004.py
├─ requirements.txt
└─ ...
3. Install the requirements
pip install -r ./pyloric_simulator/requirements.txt
4. Add the contents of `requirements.txt` to your own dependencies.
To use the `prinz2004.py` module, just import it as you would any of your own modules.
### Developer alternative: as a separate editable package
If you want to develop the simulator, you may prefer to clone the repository and make it a dependency to your project.
1. Choose a location for the repo
cd ~/code
2. Clone the repo
git clone git@github.com:alcrene/pyloric-network-simulator.git
3. Install in [development mode](https://setuptools.pypa.io/en/latest/userguide/development_mode.html)
pip install -e ./pyloric-network-simulator
## Usage
If you installed as a package: `from pyloric_network_simulator import prinz2004`.
If you installed as inlined source: The exact import statement will depend on where you placed the unpacked files.
It may look like `from my_project.pyloric_network_simulator import prinz2004`.
See the [documentation](https://alcrene.github.io/pyloric-network-simulator/pyloric_simulator/prinz2004.html) for further instructions and examples.
## Building the documentation
Ensure the *.md* and *.py* files are synchronized
jupytext --sync pyloric_simulator/prinz2004.md
[Build](https://jupyterbook.org/en/stable/start/your-first-book.html) the documentation using
jb build .
[Push](https://jupyterbook.org/en/stable/publish/gh-pages.html#option-2-automatically-push-your-build-files-with-ghp-import) to GitHub Pages
ghp-import -n -p -f _build/html
[^model-def]:
• Prinz, A. A., Bucher, D. & 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)
• Prinz, A. A., Billimoria, C. P. & Marder, E. *Alternative to Hand-Tuning Conductance-Based Models: Construction and Analysis of Databases of Model Neurons.*
Journal of Neurophysiology 90, 3998–4015 (2003). [doi:10.1152/jn.00641.2003](https://doi.org/10.1152/jn.00641.2003)
• Marder, E. & Abbott, L. F. *Modeling small networks.* in Methods in neuronal modeling: from ions to networks (eds. Koch, C. & Segev, I.) (MIT Press, 1998).
[^prinz-research]: https://biology.emory.edu/research/Prinz/research.html
[^goncalves2022]: 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)
[^jupytext]: Presuming the [Jupytext](https://jupytext.readthedocs.io/) extension is installed.
Raw data
{
"_id": null,
"home_page": null,
"name": "pyloric-network-simulator",
"maintainer": "Alexandre Ren\u00e9",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "simulation, computational-neuroscience, jax, pyloric-network",
"author": "Alexandre Ren\u00e9",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/16/70/bc8a2cc8d9587bd7432085cc22c6c8cf0f0aa87216344002e4f66dbb7fe8/pyloric_network_simulator-0.1.1.tar.gz",
"platform": null,
"description": "# 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.[^goncalves2022]\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## 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\u2019t 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\u2019t 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 thermalizations completely transparent to the user (modulo a 5\u201310 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\u2019s 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  \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 <my-project>\n \u251c\u2500 ...\n \u2514\u2500 pyloric_simulator\n \u251c\u2500 config/\n \u251c\u2500 prinz2004.py\n \u251c\u2500 requirements.txt\n \u2514\u2500 ...\n\n or\n\n <my-project>\n \u251c\u2500 ...\n \u2514\u2500 lib\n \u2514\u2500 pyloric_simulator\n \u251c\u2500 config/\n \u251c\u2500 prinz2004.py\n \u251c\u2500 requirements.txt\n \u2514\u2500 ...\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 \u2022 Prinz, A. A., Bucher, D. & Marder, E. *Similar network activity from disparate circuit parameters.* Nature Neuroscience 7, 1345\u20131352 (2004). [doi:10.1038/nn1352](https://doi.org/10.1038/nn1352) \n \u2022 Prinz, A. A., Billimoria, C. P. & Marder, E. *Alternative to Hand-Tuning Conductance-Based Models: Construction and Analysis of Databases of Model Neurons.*\n Journal of Neurophysiology 90, 3998\u20134015 (2003). [doi:10.1152/jn.00641.2003](https://doi.org/10.1152/jn.00641.2003) \n \u2022 Marder, E. & Abbott, L. F. *Modeling small networks.* in Methods in neuronal modeling: from ions to networks (eds. Koch, C. & Segev, I.) (MIT Press, 1998).\n\n[^prinz-research]: https://biology.emory.edu/research/Prinz/research.html\n[^goncalves2022]: Gon\u00e7alves, 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",
"bugtrack_url": null,
"license": "MPL 2.0",
"summary": "Pure-Python, JAX-accelerate implementation of the pyloric circuit model described by Prinz et al (Nat. Neurosci., 2004)",
"version": "0.1.1",
"project_urls": {
"Source": "https://github.com/alcrene/pyloric-network-simulator"
},
"split_keywords": [
"simulation",
" computational-neuroscience",
" jax",
" pyloric-network"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "1665cadb78ea0dc268ae91fa5d925322dc9b88baa6385d9a2e85439caef90ffb",
"md5": "7bdbf7ff13bdd4acd2e9bc0755aa8f30",
"sha256": "81d965e824b61bfa4596fd7d5b174cba45e584f28a87ec42098f54c1ca8a76fd"
},
"downloads": -1,
"filename": "pyloric_network_simulator-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7bdbf7ff13bdd4acd2e9bc0755aa8f30",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 48081,
"upload_time": "2024-07-22T18:50:29",
"upload_time_iso_8601": "2024-07-22T18:50:29.658488Z",
"url": "https://files.pythonhosted.org/packages/16/65/cadb78ea0dc268ae91fa5d925322dc9b88baa6385d9a2e85439caef90ffb/pyloric_network_simulator-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "1670bc8a2cc8d9587bd7432085cc22c6c8cf0f0aa87216344002e4f66dbb7fe8",
"md5": "bca4a225bb181c9b98e1c97d30cba040",
"sha256": "d46e71ac356ae2d8962d1be8b9a33268887930b62aacc649c711c7c025b826e5"
},
"downloads": -1,
"filename": "pyloric_network_simulator-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "bca4a225bb181c9b98e1c97d30cba040",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 467555,
"upload_time": "2024-07-22T18:50:31",
"upload_time_iso_8601": "2024-07-22T18:50:31.064115Z",
"url": "https://files.pythonhosted.org/packages/16/70/bc8a2cc8d9587bd7432085cc22c6c8cf0f0aa87216344002e4f66dbb7fe8/pyloric_network_simulator-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-22 18:50:31",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "alcrene",
"github_project": "pyloric-network-simulator",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "numpy",
"specs": []
},
{
"name": "scipy",
"specs": []
},
{
"name": "jax",
"specs": []
},
{
"name": "flufl.lock",
"specs": []
},
{
"name": "scitying",
"specs": []
},
{
"name": "pandas",
"specs": []
},
{
"name": "holoviews",
"specs": []
},
{
"name": "addict",
"specs": []
}
],
"lcname": "pyloric-network-simulator"
}
JSON
