From bb17276e60f15927ce5af48ee4ce2c77eb828fd2 Mon Sep 17 00:00:00 2001 From: Michael Deistler Date: Tue, 7 Nov 2023 18:08:58 +0100 Subject: [PATCH] update docs --- .gitignore | 5 ++ docs/docs/index.md | 61 ++++++++++++++++++++++- docs/docs/reference.md | 110 +++++++++++++++++++++++++++++++++++++++++ docs/mkdocs.yml | 24 ++++++++- setup.py | 4 +- 5 files changed, 201 insertions(+), 3 deletions(-) diff --git a/.gitignore b/.gitignore index b6e47617..6ee73943 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,8 @@ +# Project specific +/docs/docs/tutorial/* +/docs/docs/examples/* +/docs/site/* + # Byte-compiled / optimized / DLL files __pycache__/ *.py[cod] diff --git a/docs/docs/index.md b/docs/docs/index.md index a1c7c5af..3996eda6 100644 --- a/docs/docs/index.md +++ b/docs/docs/index.md @@ -1,2 +1,61 @@ -# `neurax`: differentiable networks of multicompartment neurons +

+neurax +

+ +`neurax` is a differentiable simulator for networks of multicompartment neurons in [JAX](https://github.com/google/jax). Its key features are: + +- automatic differentiation, allowing gradient-based optimization of thousands of parameters +- support for CPU and GPU without any changes to the code +- `jit`-compilation, making it as fast as other packages while being fully written in python +- backward-Euler solver for stable numerical solution of multicompartment neurons +- elegant mechanisms for parameter sharing + + +### Tutorial + +Tutorial notebooks with some explanation are in [`tutorials`](https://github.com/mackelab/neurax/tree/main/tutorials). We currently have tutorials on how to: + +- [run a simple network simulation](https://github.com/mackelab/neurax/blob/main/tutorials/01_small_network.ipynb) +- [set parameters](https://github.com/mackelab/neurax/blob/main/tutorials/02_setting_parameters.ipynb) +- [obtain a gradient and train](https://github.com/mackelab/neurax/blob/main/tutorials/03_gradient.ipynb) +- [define groups (aka sectionlists)](https://github.com/mackelab/neurax/blob/main/tutorials/04_groups.ipynb) +- [define your own channels and synapses](https://github.com/mackelab/neurax/blob/main/tutorials/05_new_mechanisms.ipynb) +- [use diverse channels](https://github.com/mackelab/neurax/blob/main/tutorials/06_diverse_channels.ipynb) + + +### Units + +`neurax` uses the same [units as `NEURON`](https://www.neuron.yale.edu/neuron/static/docs/units/unitchart.html). + + +### Installation +`neurax` requires that you first download and install [tridiax](https://github.com/mackelab/tridiax). Then, install `neurax` via: +```sh +git clone https://github.com/mackelab/neurax.git +cd neurax +pip install -e . +``` + + +### Feedback and Contributions + +We welcome any feedback on how neurax is working for your neuron models and are happy to receive bug reports, pull requests and other feedback (see [contribute](https://github.com/mackelab/neurax/blob/main/CONTRIBUTING.md)). We wish to maintain a positive community, please read our [Code of Conduct](https://github.com/mackelab/neurax/blob/main/CODE_OF_CONDUCT.md). + + +### Acknowledgements + +We greatly benefited from previous toolboxes for simulating multicompartment neurons, in particular [NEURON](https://github.com/neuronsimulator/nrn). + + +### License + +[MIT License](https://github.com/mackelab/neurax/blob/main/LICENSE) + + +### Citation + +If you use `neurax`, consider citing the corresponding paper: +``` +@article{} +``` \ No newline at end of file diff --git a/docs/docs/reference.md b/docs/docs/reference.md index e69de29b..d65fa97a 100644 --- a/docs/docs/reference.md +++ b/docs/docs/reference.md @@ -0,0 +1,110 @@ +# API Reference + +## Modules + +::: neurax.modules.compartment.Compartment + rendering: + show_root_heading: true + selection: + filters: [ "!^_", "^__", "!^__class__" ] + inherited_members: true + +::: neurax.modules.branch.Branch + rendering: + show_root_heading: true + selection: + filters: [ "!^_", "^__", "!^__class__" ] + inherited_members: true + +::: neurax.modules.cell.Cell + rendering: + show_root_heading: true + selection: + filters: [ "!^_", "^__", "!^__class__" ] + inherited_members: true + +::: neurax.modules.network.Network + rendering: + show_root_heading: true + selection: + filters: [ "!^_", "^__", "!^__class__" ] + inherited_members: true + + +## Channels + +::: neurax.channels.hh.HHChannel + rendering: + show_root_heading: true + selection: + filters: [ "!^_", "^__", "!^__class__" ] + inherited_members: true + +::: neurax.channels.pospischil.CaLChannelPospi + rendering: + show_root_heading: true + selection: + filters: [ "!^_", "^__", "!^__class__" ] + inherited_members: true + +::: neurax.channels.pospischil.CaTChannelPospi + rendering: + show_root_heading: true + selection: + filters: [ "!^_", "^__", "!^__class__" ] + inherited_members: true + +::: neurax.channels.pospischil.KChannelPospi + rendering: + show_root_heading: true + selection: + filters: [ "!^_", "^__", "!^__class__" ] + inherited_members: true + +::: neurax.channels.pospischil.KmChannelPospi + rendering: + show_root_heading: true + selection: + filters: [ "!^_", "^__", "!^__class__" ] + inherited_members: true + +::: neurax.channels.pospischil.Leak + rendering: + show_root_heading: true + selection: + filters: [ "!^_", "^__", "!^__class__" ] + inherited_members: true + +::: neurax.channels.pospischil.NaChannelPospi + rendering: + show_root_heading: true + selection: + filters: [ "!^_", "^__", "!^__class__" ] + inherited_members: true + + +## Synapses + +::: neurax.synapses.glutamate.GlutamateSynapse + rendering: + show_root_heading: true + selection: + filters: [ "!^_", "^__", "!^__class__" ] + inherited_members: true + + +## Optimization + +::: neurax.optimize.transforms.ParamTransform + rendering: + show_root_heading: true + selection: + filters: [ "!^_", "^__", "!^__class__" ] + inherited_members: true + + +## Utils + +::: neurax.read_swc + rendering: + show_root_heading: true diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 3ee67f4d..fbe9bb97 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -3,6 +3,14 @@ site_url: "https://mackelab.org/neurax/" nav: - Home: index.md + - Tutorials: + - Getting started: tutorial/01_small_network.md + - Run a network simulation: tutorial/01_small_network.md + - Set parameters: tutorial/02_setting_parameters.md + - Obtain gradient and train: tutorial/03_gradient.md + - Define groups: tutorial/04_groups.md + - Define your own channels: tutorial/05_new_mechanisms.md + - Use diverse channels: tutorial/06_diverse_channels.md - Installation: install.md - Contributing: - Guide: contribute.md @@ -48,4 +56,18 @@ markdown_extensions: - pymdownx.superfences - pymdownx.tasklist: custom_checkbox: true - - pymdownx.tilde \ No newline at end of file + - pymdownx.tilde + + +plugins: + - search + - mkdocstrings: + default_handler: python + handlers: + python: + rendering: + show_source: true + heading_level: 3 + +watch: + - ../neurax \ No newline at end of file diff --git a/setup.py b/setup.py index a9acd35c..9c2335e3 100644 --- a/setup.py +++ b/setup.py @@ -13,9 +13,11 @@ "black", "isort", "jupyter", - "markdown-include", "mkdocs", "mkdocs-material", + "markdown-include", + "mkdocs-redirects", + "mkdocstrings[python]>=0.18", "neuron", "pytest", "pyright",