Skip to content

Commit

Permalink
Doc upgrades (#2229)
Browse files Browse the repository at this point in the history 
- Polish & modernise two cells + gap junction example.
- Investigate problems with mathjax
- Update spike data format docs.
- Switches theme to FURO, which is better maintained and document (like
... at all)
- with the new theme, we gain dark mode, yet we need to fix our graphics
to make it a really nice experience.

Fixes #2227 
Fixes #2228

---------

Co-authored-by: Simon Frasch <[email protected]>
  • Loading branch information
@thorstenhater @AdhocMan
thorstenhater and AdhocMan authored Dec 22, 2023
1 parent 5a965a3 commit d4579b1
Show file tree
Hide file tree
Showing 33 changed files with 1,467 additions and 6,569 deletions.
91 changes: 53 additions & 38 deletions doc/concepts/domdec-diag-1.html
View file
Original file line number Diff line number Diff line change
@@ -1,63 +1,70 @@
<div class="diag-cont">
<div class="diag-cont" style="color: #202020; max-width: 100%; margin-left: 0%;">
<div id="recipe_src">Recipe
<div>Cell descriptions
<div>gid 1
<div>type <code>lif_cell_0</code>
<div>...</div>
</div>
<div>
gid 1</br>
type <code>lif_cell</code></br>
description</br>
...
</div>
<div>...</div>
<div> gid 37
<div>type <code>cable_cell_A</code>
<div>Morphology</div>
<div>Decor
<div>Mechanisms</div>
<div>Connection sites</div>
</div>
<div>Label dictionary</div>
</div>
<div>
gid 37</br>
type <code>cable_cell</code></br>
description
<ul>
<li>Morphology</li>
<li>Ion channels</li>
<li>Connection sites</li>
<li>Labels</li>
</ul>
</div>
</div>
<div>Cell kinds
<div>gid 1
<div>type <code>arbor.lif_cell</code>
</div>
</div>
<div>gid 1 <code>lif_cell</code></div>
<div>...</div>
<div>gid 37
<div>type <code>arbor.cable_cell</code></div>
</div>
</div>
<div>...
<div>gid 37 <code>cable_cell</code></div>
</div>
<div>...</div>
</div>
<div class="diag-col">

<div class="diag-col" style="width: auto;">
<div class="diag-right">
Simulator: requests cell description of <code>gid=37</code>
Simulator: kind of <code>gid=1</code>?
</div>
<div class="diag-left">
Recipe: <code>type=cable_cell_A</code>.
Recipe: <code>lif_cell</code>.
</div>
<div class="diag-right2">
...
</div>
<div class="diag-right">
Simulator: requests cell kind of <code>gid=37</code>
Simulator: kind of <code>gid=37</code>?
</div>
<div class="diag-left">
Recipe: <code>kind=arbor.cable_cell</code>.
</div>
<div class="diag-right">
Simulator: look up cell group implementation for kind <code>arbor.cable_cell</code>.
Recipe: <code>cable_cell</code>.
</div>
<div class="diag-right2">
Domain decomposition: <code>cable_cell_group_gpu</code>
Group implementations for <code>lif_cell</code>, <code>cable_cell</code></br>
Domain decomposition: <code>group-0</code>, <code>group-1</code>
</div>

<div class="diag-right">
Simulator: <code>cable_cell_group_gpu</code> construct <code>cable_cell_A</code> object.
Simulator requests cell description of <code>gid=37</code>
</div>
<div class="diag-right3">
<code>cable_cell_group_gpu</code>: Construction complete.
<div class="diag-left">
Recipe: <code>morphology, ...</code>.
</div>
<div class="diag-right2">
Simulator:</br>
<code>group-0</code> make <code>cable_cell</code></br>
<code>group-1</code> make <code>lif_cell</code>
</div>
<div class="diag-right">
Simulator: <code>cable_cell_group_gpu</code> simulate for <code>t .. t + dt</code>
Simulator:</br>
<code>group-0</code> simulate for <code>dt</code>
</br>
<code>group-1</code> simulate for <code>dt</code>
</div>
</div>
<div>Simulation
Expand All @@ -72,8 +79,16 @@
</div>
<div id="domdec_src">Domain decomposition
<div>
cable_cell_group_gpu
<div>1 GPU</div>
<code>group-0</code></br>
kind: <code>cable</code></br>
hardware: 1 GPU</br>
gids: <code>37, ...</code>
</div>
<div>
<code>group-1</code></br>
kind: <code>lif</code></br>
hardware: 12 threads</br>
gids: <code>1, ...</code>
</div>
<div>
...
Expand Down
4 changes: 2 additions & 2 deletions doc/concepts/hardware.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,15 +19,15 @@ first, it might be instructive to see how recipes are used by Arbor:
An *allocation* enumerates the computational resources to be used for a
simulation, typically a subset of the resources available on a physical hardware
node. It also contains flags to enable thread and process `affinity
<https://en.wikipedia.org/wiki/Processor_affinity>`. When asked to set affinity,
<https://en.wikipedia.org/wiki/Processor_affinity>`_. When asked to set affinity,
Arbor will try to maximize the use of the available resources, i.e. it will
spread out processes and threads such that each gets a maximal share of compute
units and cache. Existing affinity settings will honoured, so setting it for
processes while an external mechanism (e.g. SLURM or OpenMPI) does the same is
ill advised. Threads can not be managed externally, thus requesting thread
binding is generally safe and may yield significant performance improvements for
CPU-only simulations and/or the model build phase. Affinity requires `hwloc
<https://www.open-mpi.org/projects/hwloc/>` to be found during build time.
<https://www.open-mpi.org/projects/hwloc/>`_ to be found during build time.

New users can find using contexts a little verbose. The design is very
deliberate, to allow fine-grained control over which computational resources an
Expand Down
72 changes: 40 additions & 32 deletions doc/concepts/index-diag-1.html
View file
Original file line number Diff line number Diff line change
@@ -1,36 +1,44 @@
<div class="diag-spacer"></div>
<div class="diag-spacer"></div>
<div class="diag-cont">
<div id="recipe_src">Recipe
<div id="recipe_dsc" class="diag-note">describe the neuroscience</div>
<div>Cells
</div>
<div>Network
</div>
<div>In- & outputs
</div>
<div>...
</div>
<div>
<div class="diag-inner">
<strong style="color: SlateGray;">
Simulation
</strong>
</div>
<div id="sim_src">Simulation
<div id="sim_dsc" class="diag-note">describe the execution</div>
<div id="recipe_dst">Recipe</div>
<div class="diag-spacer"></div>
<div id="conc_src">Context
<div id="conc_dsc" class="diag-note">describe hardware</div>
</div>
<div class="diag-spacer"></div>
<div id="domdec_src">Domain decomposition
<div id="domdec_dsc" class="diag-note">describe how to use hardware</div>
</div>
<div class="diag-note">
<strong>
Recipe
</strong>
</br>
Describe the science
</div>
<div id="conc_dsc" class="diag-note">
<strong>
Context
</strong>
</br>
Determine the Hardware
</div>
</div>
<div class="diag-caption">An overview of Arbor. The two columns reflect a division that is core to Arbor: the neuroscience is described entirely separate from the execution of the simulation. The Recipe ties the neuroscience together: the user can provide any number of cells, each with a particular type, morphology and set of mechanisms; a network configuration; and in- & outputs like event generators and probes. This description, the recipe, is self-contained and can be executed by any configuration of execution. Execution is determined by the available hardware and instructions for how certain parts of a recipe (e.g. cell groups) are executed on that hardware.</div>

<connection width="1" from="#recipe_src" to="#recipe_dst" fromX="1" fromY="0" toX="0" toY="0" onlyVisible></connection>
<connection width="1" from="#recipe_src" to="#recipe_dst" fromX="1" fromY="1" toX="0" toY="1" onlyVisible></connection>

<connection from="#recipe_src" to="#recipe_dsc" color="rgb(221, 191, 146)" fromX="0.1" fromY="0" toX="0" tail onlyVisible></connection>
<connection from="#sim_src" to="#sim_dsc" color="rgb(221, 191, 146)" fromX="0.1" fromY="0" toX="0" tail onlyVisible></connection>
<connection from="#conc_src" to="#conc_dsc" color="rgb(221, 191, 146)" fromX="0.1" fromY="0" toX="0" tail onlyVisible></connection>
<connection from="#domdec_src" to="#domdec_dsc" color="rgb(221, 191, 146)" fromX="0.1" fromY="0" toX="0" tail onlyVisible></connection>
<div class="diag-note">
<strong>
Domain decomposition
</strong></br>
Map recipe to hardware
</div>
</div>
</div>
<div class="diag-caption">
An overview of Arbor at the highest level. The layout reflects a division
that is core to Arbor: the science is described entirely separate from the
execution of the simulation.
</br>
The Recipe describes the network by declaring its constituent cells and
their connections in addition to the stimuli and data extraction.
</br>
Execution is determined by mapping out the available hardware in a context
as processes (via MPI) plus the threads and GPUs associated with each process.
</br>
Finally, a domain decomposition maps the network onto said resources taking into
account the capabilities of each cell type.
</div>
42 changes: 42 additions & 0 deletions doc/concepts/index-diag-2.html
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
<div class="diag-cont">
<div>
<div class="diag-inner">
<strong style="color: SlateGray;">
Recipe
</strong>
</div>
<div class="diag-note">
<strong>
Size
</strong>
</br>
The number of cells regardless of type.
</div>
<div class="diag-note">
<strong>
Cells
</strong>
</br>
A cell description.
</div>
<div id="conc_dsc" class="diag-note">
<strong>
Network
</strong>
</br>
List of incoming connections.
</div>
<div class="diag-note">
<strong>
In- and Outputs
</strong></br>
List of stimuli and probes.
</div>
</div>
</div>
<div class="diag-caption">
The recipe is the core abstraction to building networks. It declares a number
of cells present in the network and will then be interrogated for each about
its properties. By asking the recipe about each cell in isolation, Arbor can
build the network in parallel while keeping memory consumption low.
</div>
45 changes: 26 additions & 19 deletions doc/concepts/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,10 +12,10 @@ with sensible defaults.
:file: index-diag-1.html

To learn how to use Arbor, it is helpful to understand some of its concepts.
Arbor's design aims to enable scalability through abstraction.
To achieve this, Arbor makes a distinction between the **description** of a model, and the
**execution** of a model:
a *recipe* describes a model, and a *simulation* is an executable instantiation of a model.
Arbor's design aims to enable scalability through abstraction. To achieve this,
Arbor makes a distinction between the **description** of a model, and the
**execution** of a model: a *recipe* describes a model, and a *simulation* is an
executable instantiation of a model.

To be able to simulate a model, three basic steps need to be considered:

Expand All @@ -27,20 +27,27 @@ The Python front-end further abstracts away some of these steps for single cell
describe the cell and simulation; and the details of the recipe and computational resources construction are
handled under the hood. Generally speaking though, these 3 steps are the building blocks of an Arbor application.

:ref:`Recipes <modelrecipe>` represent a set of neuron constructions and connections with :ref:`mechanisms <mechanisms>` specifying
ion channel and synapse dynamics in a cell-oriented manner. This has the advantage that cell data can be initiated
in parallel.

A cell represents the smallest unit of computation and forms the smallest unit of work distributed across processes.
Arbor has built-in support for different :ref:`cell types <modelcells>`, which can be extended by adding new cell
types to the C++ cell group interface.

:ref:`modelsimulation` manage the instantiation of the model and the scheduling of spike exchange as well as the
integration for each cell group. A cell group represents a collection of cells of the same type computed together
on the GPU or CPU. The partitioning into cell groups is provided by :ref:`modeldomdec` which describes the distribution
of the model over the locally available computational resources.

In order to visualize the result of detected spikes a spike recorder can be used, and to analyse Arbor's performance a
meter manager is available.
.. raw:: html
:file: index-diag-2.html

:ref:`Recipes <modelrecipe>` represent a set of neuron constructions and
connections with :ref:`mechanisms <mechanisms>` specifying ion channel and
synapse dynamics in a cell-oriented manner. This has the advantage that cell
data can be initiated in parallel.

A cell represents the smallest unit of computation and forms the smallest unit
of work distributed across processes. Arbor has built-in support for different
:ref:`cell types <modelcells>`, which can be extended by adding new cell types
to the C++ cell group interface.

:ref:`modelsimulation` manage the instantiation of the model and the scheduling
of spike exchange as well as the integration for each cell group. A cell group
represents a collection of cells of the same type computed together on the GPU
or CPU. The partitioning into cell groups is provided by :ref:`modeldomdec`
which describes the distribution of the model over the locally available
computational resources.

In order to visualize the result of detected spikes a spike recorder can be
used, and to analyse Arbor's performance a meter manager is available.

:ref:`probesample` shows how to extract data from simulations.
2 changes: 1 addition & 1 deletion doc/concepts/recipe-diag-1.html
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
<div class="diag-cont">
<div class="diag-cont" style="color: #202020;">
<div id="recipe_src">Recipe
<div>
<input id="collapsible1" type="checkbox" checked><label for="collapsible1">Cell descriptions</label>
Expand Down
9 changes: 5 additions & 4 deletions doc/conf.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,12 +24,10 @@ def setup(app):
"sphinx.ext.autodoc",
"sphinx.ext.todo",
"sphinx.ext.mathjax",
"divio_docs_theme",
]
source_suffix = ".rst"
master_doc = "index"

html_logo = "images/arbor-lines-proto-colour.svg"
html_favicon = "images/arbor-lines-proto-colour-notext.svg"

intersphinx_mapping = {
Expand All @@ -41,8 +39,11 @@ def setup(app):
author = "ETHZ & FZJ"
todo_include_todos = True

html_theme = "divio_docs_theme"
html_theme_options = {}
html_theme = "furo"
html_theme_options = {
"dark_logo": "arbor-lines-proto-colour-dark.svg",
"light_logo": "arbor-lines-proto-colour.svg",
}

# This style makes the source code pop out a bit more
# from the background text, without being overpowering.
Expand Down
2 changes: 1 addition & 1 deletion doc/dev/cell_groups.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ Cell groups are created by domain decomposition methods on consideration of soft
be in the same group) constraints.

Cable Cell group ``cable_cell_group``
----------------------------------
-------------------------------------

Cable cell groups have backing store in ``shared_state`` (given the
introduction, we now understand that the ``shared`` stands for 'shared' between
Expand Down
11 changes: 7 additions & 4 deletions doc/ecosystem/index-sims.html
View file
Original file line number Diff line number Diff line change
@@ -1,12 +1,14 @@
<div class="diag-cont">
<div id="nm">Neural Mass Models
<div id="nm" style="color: #202020;">Neural Mass Models
<div>The Virtual Brain</div>
</div>
<div id="pn">Point Neurons
<div id="pn" style="color: #202020;">
Point Neurons
<div>NEST</div>
<div>BRIAN</div>
</div>
<div id="dt">Detailed Neurons
<div id="dt" style="color: #202020;">
Detailed Neurons
<div>Arbor</div>
<div>(Core)NEURON, NeuroGPU</div>
<div>GENESIS</div>
Expand All @@ -15,7 +17,8 @@
<div>jNML</div>
<div>EDEN</div>
</div>
<div id="md">Molecular Dynamics
<div id="md" style="color: #202020;">
Molecular Dynamics
<div>ALMOST</div>
<div>NAMD</div>
</div>
Expand Down
Loading

0 comments on commit d4579b1

Please sign in to comment.