diff --git a/doc/contrib/coding-style.rst b/doc/contrib/code.rst similarity index 96% rename from doc/contrib/coding-style.rst rename to doc/contrib/code.rst index e740ced0b3..0bced16c24 100644 --- a/doc/contrib/coding-style.rst +++ b/doc/contrib/code.rst @@ -1,7 +1,18 @@ -.. _contribcodingstyle: +.. _contribcode: -Coding Guidelines -================= +Code +==== + +Some general tips to keep in mind: + +- If you add functionality, please update the documentation + accordingly. +- If you add functionality, add tests if applicable. This helps make + sure Arbor is stable and functionality does what it's supposed to + do. +- If you work on the public C++ API, provide Python wrappings. +- Make sure Arbor compiles and has no new warnings. +- Consider the coding guidelines below. Python ------ diff --git a/doc/contrib/doc.rst b/doc/contrib/doc.rst index a567ba450b..666ec081ec 100644 --- a/doc/contrib/doc.rst +++ b/doc/contrib/doc.rst @@ -3,9 +3,9 @@ Documentation ============= -The source for `the documentation `__ is -found in the ``/doc`` subdirectory. You can add your contribution to the documentation -in the same way you would contribute code, please see the :ref:`contribpr` section. +The source for `the documentation `__ is found in the ``/doc`` subdirectory. +We use `Sphinx `_ to build our docs. +You can add your contribution to the documentation in the same way you would contribute code, please see the :ref:`contribpr` section. .. _contribdoc-tut: diff --git a/doc/contrib/index.rst b/doc/contrib/index.rst index fc995c347a..a35faf9825 100644 --- a/doc/contrib/index.rst +++ b/doc/contrib/index.rst @@ -1,127 +1,48 @@ .. _contribindex: -Contributing to Arbor -===================== +Contributing +============ -First off, thank you for considering contributing to Arbor! It’s people +First off, thank you for considering contributing to Arbor! It's people like you that make Arbor such a great tool. Feel welcome and read the following sections in order to know how to ask questions and how to work on something. -.. _contribindex-types: - -Types of contributions ----------------------- - There are many ways to contribute: sharing models, writing tutorials or blog posts, improving the documentation, helping other users, submitting bug reports and feature requests or writing code which can be incorporated into Arbor itself. -Use the `Arbor Discussions `__ -page for support questions. - -.. _contribindex-github: - -Github ------- - -Arbor uses Git for version control and Github to host its code -repository and nearly all of its infrastructure. - -- If you’re not familiar with Git or Github, please have at look at - `this introduction `__. -- Make sure you have a `GitHub - account `__. - -.. _contribindex-model: - -Model -~~~~~ - -Sharing research and findings that used Arbor is the best contribution you can make to the project. - -- We encourage the use of our Github Discussions board for public discussions on modelling: `Github Discussions `_. - -- Users can share their models by adding them to the model collection on GitHub at `arbor-contrib `_. - -.. _contribindex-discuss: - -Start a discussion -~~~~~~~~~~~~~~~~~~ - -You can use the `Arbor -Discussions `__ to help -other users of Arbor, or get help with you own simulations. Also, we’re -eager to discover what you’re using Arbor for, so don’t hesitate to -share your Arbor simulations or publications! - -.. _contribindex-fileissue: - -Filing an issue -~~~~~~~~~~~~~~~ - -If you have found a bug or problem in Arbor, or want to request a feature, you -can use our `issue tracker `__. If -you issue is not yet filed in the issue tracker, please do so and describe the -problem, bug or feature as best you can. You can add supporting data, code or -documents to help make your point. For bugs in particular, stacktraces (either -from inside a debugger or by enabling ``ARB_BACKTRACE``) are extremely useful. - -.. _contribindex-solveissue: - -Help solving an Issue -~~~~~~~~~~~~~~~~~~~~~ - -If you want to help solve an issue, that’s great! Issue labels can help -you find an something that fits your expertise or interest, and if -you’re just getting started, you can look for the “`good 1st -issue `__” -label. Don’t hesitate to post a comment to the Issue if you want to ask -clarifying questions. If you have implemented a fix, you can make a pull -request. - -Write code -~~~~~~~~~~ +Arbor uses Git for version control and GitHub to host its code repository and nearly +all of its infrastructure. If you're not familiar with Git or GitHub, please have at look at +`this introduction `_. +Make sure you have a `GitHub account `_. -Some tips when contributing code: +You can reach out in the following ways for support or sharing of your work, questions: -- Consider the :ref:`contribcodingstyle`. -- If you add functionality, please update the documentation - accordingly. -- If you add functionality, add tests if applicable. This helps make - sure Arbor is stable and functionality does what it’s supposed to - do. -- If you work on the public C++ API, provide Python wrappings. -- Make sure Arbor compiles and has no new warnings. - -Add examples or unit tests -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -See :ref:`contribexample` and :ref:`contribtest`. - -Modify documentation -~~~~~~~~~~~~~~~~~~~~ - -See :ref:`contribdoc`. - -Making a pull request -~~~~~~~~~~~~~~~~~~~~~ - -See :ref:`contribpr`. - -.. _contribindex-other: +- `Discussions `__. Any + questions or remarks regarding using Arbor for your research are + welcome. +- `Gitter `__. If you're interested in + developing Arbor itself, get in touch on Gitter. +- `Email `__. -Other contributions -------------------- +Howtos +------ -We try to collect models scientists have built in our `contributor space `_. -In addition to the tutorials, browsing these models should give you a good idea of what's possible with Arbor -and find get in contact with other Arbor users. +.. toctree:: + :titlesonly: + :maxdepth: 1 -We're always happy to hear about Arbor being used! Have you used Arbor to create a model? -Have you used Arbor in a publication? Do you have a workflow or tool that involves Arbor? -Get in touch and we'd be very happy to showcase your work through our channels. + File an Issue + Make a Pull Request + Share a model + Write code + Modify documentation + Add examples + Add test + Make a release + dependency-management .. _contribindex-coc: @@ -132,7 +53,7 @@ We have a brief code of conduct which we ask you to respect: * We are committed to providing a friendly, safe and welcoming environment for all, regardless of level of experience, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, ethnicity, age, religion, nationality, or any other characteristic. * Please avoid using overtly provoking aliases or nicknames that might detract from a friendly, safe and welcoming environment for all. -* Please be kind and courteous. There’s no need to be mean or rude. +* Please be kind and courteous. There's no need to be mean or rude. * Respect that people have differences of opinion and that every design or implementation choice carries a trade-off and numerous costs. * Please keep unstructured critique to a minimum. If you have solid ideas you want to experiment with, make a fork and see how it works. @@ -156,17 +77,3 @@ Arbor is an Ebrains/HBP project. Its policies and recourse options in case of co * `ALLEA Code of Conduct `_ * `Ebrains Point of registration for ethical concerns `_ * `Ebrains Ombudsperson `_ - -.. _contribindex-contact: - -Get in touch ------------- - -You can reach out in the following ways: - -- `Discussions `__. Any - questions or remarks regarding using Arbor for your research are - welcome. -- `Gitter `__. If you’re interested in - developing Arbor itself, get in touch on Gitter. -- `Email `__. diff --git a/doc/contrib/issue.rst b/doc/contrib/issue.rst new file mode 100644 index 0000000000..4e06238aa3 --- /dev/null +++ b/doc/contrib/issue.rst @@ -0,0 +1,11 @@ +.. _contribissue: + +File an Issue +============= + +If you have found a bug or problem in Arbor, or want to request a feature, you +can use our `issue tracker `__. If +you issue is not yet filed in the issue tracker, please do so and describe the +problem, bug or feature as best you can. You can add supporting data, code or +documents to help make your point. For bugs in particular, stacktraces (either +from inside a debugger or by enabling ``ARB_BACKTRACE``) are extremely useful. diff --git a/doc/contrib/model.rst b/doc/contrib/model.rst new file mode 100644 index 0000000000..e467bba042 --- /dev/null +++ b/doc/contrib/model.rst @@ -0,0 +1,15 @@ +.. _contribmodel: + +Modelling +========= + +Sharing research and findings that used Arbor is the best contribution you can make to the project. +We encourage the use of our Github Discussions board and Gitter for public discussions on modelling. + +We try to collect models scientists have built in our `contributor space `_. +In addition to the tutorials, browsing these models should give you a good idea of what's possible with Arbor +and find get in contact with other Arbor users. + +We're always happy to hear about Arbor being used! Have you used Arbor to create a model? +Have you used Arbor in a publication? Do you have a workflow or tool that involves Arbor? +Get in touch and we'd be very happy to showcase your work through our channels. \ No newline at end of file diff --git a/doc/index.rst b/doc/index.rst index f375b97a28..f058be2745 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -125,6 +125,7 @@ A full list of our software attributions can be found `here `_. +- To download and install Arbor on your system, enter ``pip install arbor`` in a terminal. +- Download a `pre-built Arbor GUI `_. + +More and more advanced installation instructions (such as building Arbor with GPU or MPI support) +can be found below: .. toctree:: :maxdepth: 1 diff --git a/doc/tutorial/gui/cell-3d.png b/doc/tutorial/gui/cell-3d.png new file mode 100644 index 0000000000..b7efd06667 Binary files /dev/null and b/doc/tutorial/gui/cell-3d.png differ diff --git a/doc/tutorial/gui/gui-startup.png b/doc/tutorial/gui/gui-startup.png new file mode 100644 index 0000000000..58611dbb7f Binary files /dev/null and b/doc/tutorial/gui/gui-startup.png differ diff --git a/doc/tutorial/gui/load-morph.png b/doc/tutorial/gui/load-morph.png new file mode 100644 index 0000000000..8a19d7226a Binary files /dev/null and b/doc/tutorial/gui/load-morph.png differ diff --git a/doc/tutorial/gui/load-swc.png b/doc/tutorial/gui/load-swc.png new file mode 100644 index 0000000000..80286f618a Binary files /dev/null and b/doc/tutorial/gui/load-swc.png differ diff --git a/doc/tutorial/gui/locset-error.png b/doc/tutorial/gui/locset-error.png new file mode 100644 index 0000000000..cf7764ffab Binary files /dev/null and b/doc/tutorial/gui/locset-error.png differ diff --git a/doc/tutorial/gui/locset-ok.png b/doc/tutorial/gui/locset-ok.png new file mode 100644 index 0000000000..4d3094ff18 Binary files /dev/null and b/doc/tutorial/gui/locset-ok.png differ diff --git a/doc/tutorial/gui/param-set-Vm.png b/doc/tutorial/gui/param-set-Vm.png new file mode 100644 index 0000000000..acaec348db Binary files /dev/null and b/doc/tutorial/gui/param-set-Vm.png differ diff --git a/doc/tutorial/gui/param-set-hh.png b/doc/tutorial/gui/param-set-hh.png new file mode 100644 index 0000000000..f9ff32b976 Binary files /dev/null and b/doc/tutorial/gui/param-set-hh.png differ diff --git a/doc/tutorial/gui/sim-iclamp.png b/doc/tutorial/gui/sim-iclamp.png new file mode 100644 index 0000000000..f852fda8ef Binary files /dev/null and b/doc/tutorial/gui/sim-iclamp.png differ diff --git a/doc/tutorial/gui/sim-probe.png b/doc/tutorial/gui/sim-probe.png new file mode 100644 index 0000000000..f111ac3705 Binary files /dev/null and b/doc/tutorial/gui/sim-probe.png differ diff --git a/doc/tutorial/gui/trace.png b/doc/tutorial/gui/trace.png new file mode 100644 index 0000000000..4965ec4bdc Binary files /dev/null and b/doc/tutorial/gui/trace.png differ diff --git a/doc/tutorial/gui/viewport-options.png b/doc/tutorial/gui/viewport-options.png new file mode 100644 index 0000000000..ea989a99c7 Binary files /dev/null and b/doc/tutorial/gui/viewport-options.png differ diff --git a/doc/tutorial/index.rst b/doc/tutorial/index.rst index 9bbcaeac5b..2a3073668d 100644 --- a/doc/tutorial/index.rst +++ b/doc/tutorial/index.rst @@ -21,6 +21,7 @@ Cells :maxdepth: 1 single_cell_model + single_cell_gui single_cell_detailed single_cell_cable single_cell_allen diff --git a/doc/tutorial/single_cell_gui.rst b/doc/tutorial/single_cell_gui.rst new file mode 100644 index 0000000000..1afa856332 --- /dev/null +++ b/doc/tutorial/single_cell_gui.rst @@ -0,0 +1,155 @@ +.. _tutorialgui: + +Single Cell in GUI +================== + +Here we will show you how to re-create the :ref:`single segment cell example ` +in the GUI. + +Get the GUI +----------- + +Download a pre-built binary from the `GUI releases +page `__. + +Start the GUI and you should see a window like this: |image0| + +Define a Morphology +------------------- + +As we need a morphology that can be loaded from disk for use in the GUI, +we will make a very simple SWC file: + +:: + + 1 1 -3.0 0.0 0.0 3 -1 + 2 1 3.0 0.0 0.0 3 1 + +This sets up a cell consisting of a soma with radius ``3 μm``, extending +``6 μm`` along the x-axis. If you are unfamiliar with SWC, do not worry, +this is all we need to do with it. Store this data as eg ``soma.swc``. + +Now we need to load this file. In the GUI: + +1. Click on 'File' in the top left: |image1| +2. Choose 'Morphology > Load' +3. Navigate to your file using the dialogue: |image2| +4. Pick your file and click 'Load' + +- If your file is among many others, you can filter for the ``.swc`` + extension only by choosing that suffix in 'Filter' +- SWC data has multiple interpretations; here we use the 'Neuron' + flavor + +5. Go to the cell tab and take a look at your cell in 3D + +- Mouse wheel and +/- zoom the view +- Pressing Shift brings up a rotation handle +- Pressing Ctrl brings up a translation handle +- Right click the cell tab to + + - Reset the camera + - Manipulate the axes cross + - Save a screenshot + - Tweak the model rendering resolution, might help performance in + complex views + - Hover segments to learn some details about the geometry + +E.g.: |image3| |image4| + +Defining Locations +------------------ + +Now we are ready to continue work on the tutorial by setting up regions +and locsets. On the left pane switch to the 'Locations' and expand the +'Regions' and 'Locset' All regions we need are defined, as we just have +made a simple soma-only cell. + +To attach stimuli and probes we will need a location set, or 'locset'. +Click on the '+' right of 'Locsets' to add one. + +Type in the following definition in the text box + +:: + + (location 0 0.5) + +Keep track of the status icon changing state from ❔ (empty) over ⚠️ +(invalid) to ✔️ (ok) as you type. You can hover your mouse over it to +learn more. |image5| + +The locset we just defined designates the center (0.5) of segment 0. +Segment 0 happens to be the soma. We can assign names to locsets to +remember their use or definition. So, change the name from 'Locset 0' to +'midpoint'. When done zoom in on the cell to see a marker at the locset +point(s). |image6| + +Note: If you have defined overlapping regions and locsets you can drag +the definitions to reorder them. That will change rendering order +accordingly and allow you to see hidden parts. + +Assigning Bio-physical Properties +--------------------------------- + +We are now done with 'Locations'. Switch to the 'Parameters' tab and +assign ``-40 mV`` under 'Cable Cell Properties' > 'Default' > 'Membrane +Potential'. This set the initial value of the cell's membrane potential. +|image7| + +Next, expand the 'Mechanisms' > 'soma' tree and add a mechanism by +clicking the '+' icon on the right and choosing 'hh' under the 'default' +section from the combo box. You can expand this item further to take a +look at the 'hh' mechanism's properties. |image8| With that, the soma +will exhibit Hodgekin-Huxley model behaviour and we are almost ready to +run the model. + +Setting up the Simulation +------------------------- + +Switch to the 'Simulation' tab. Under 'End time', enter ``20 ms``. Then +expand 'Stimuli' and current clamp to the 'midpoint' locset by clicking +'+' on the right. + +Note: if 'midpoint' described more than one point, multiple current +source would be applied. In this case we only have one. + +Expand the 'I Clamp 0' item and look for the 'Envelope' section. There, +add a point at 10ms with 0.8nA and another at 12ms going back to 0nA. +The result should look like this: + +|image9| + +The last step: click on 'Probes' and add a 'Voltage' probe to 'midpoint' +This will allow us to record the membrane potential at the soma's +center. + +|image10| + +Running Simulations and Getting Outputs +--------------------------------------- + +Now click 'Run' at the top of the tab. Next switch from 'Cell' to +'Traces' on the right pane. Expand 'midpoint' on the right and select +'0: Voltage'. You should now see this |image11| + +Congratulations! This a complete simulation of a simple cell. + +Where to go from here +--------------------- + +You can play with the simulation you just made, but beforehand it might +help to save the current state (except probes). To do that choose 'File' > +'Cable' > 'Save'. + +.. |image0| image:: gui/gui-startup.png +.. |image1| image:: gui/load-morph.png +.. |image2| image:: gui/load-swc.png +.. |image3| image:: gui/cell-3d.png +.. |image4| image:: gui/viewport-options.png +.. |image5| image:: gui/locset-error.png +.. |image6| image:: gui/locset-ok.png +.. |image7| image:: gui/param-set-Vm.png +.. |image8| image:: gui/param-set-hh.png +.. |image9| image:: gui/sim-iclamp.png +.. |image10| image:: gui/sim-probe.png +.. |image11| image:: gui/trace.png