From 49884318bd17f32e33738fdc50433ecba640fa94 Mon Sep 17 00:00:00 2001
From: boeschf <48126478+boeschf@users.noreply.github.com>
Date: Tue, 25 Oct 2022 14:08:49 +0200
Subject: [PATCH] cleanup documentation (#2007)
---
doc/concepts/benchmark_cell.rst | 1 -
doc/concepts/decor.rst | 10 ++-
doc/concepts/interconnectivity.rst | 2 +-
doc/concepts/mechanisms.rst | 3 +-
doc/contrib/test.rst | 3 +
doc/cpp/morphology.rst | 2 +-
doc/dev/cable_cell.rst | 4 +-
doc/dev/communication.rst | 2 +
doc/dev/matrix_solver.rst | 2 +
doc/install/build_install.rst | 2 +-
doc/python/decor.rst | 1 +
doc/python/hardware.rst | 65 ++++++++++----------
doc/python/labels.rst | 1 +
doc/python/mechanisms.rst | 9 ++-
doc/python/probe_sample.rst | 1 +
doc/tutorial/network_ring_gpu.rst | 2 +-
doc/tutorial/single_cell_detailed_recipe.rst | 4 +-
17 files changed, 60 insertions(+), 54 deletions(-)
diff --git a/doc/concepts/benchmark_cell.rst b/doc/concepts/benchmark_cell.rst
index b3f30750..d443e180 100644
--- a/doc/concepts/benchmark_cell.rst
+++ b/doc/concepts/benchmark_cell.rst
@@ -10,4 +10,3 @@ API
---
* :ref:`Python <pybenchcell>`
-* :ref:`C++ <cppbenchcell>`
diff --git a/doc/concepts/decor.rst b/doc/concepts/decor.rst
index d1b7f9fa..5cc973f3 100644
--- a/doc/concepts/decor.rst
+++ b/doc/concepts/decor.rst
@@ -125,7 +125,7 @@ specialised on specific regions.
Regions can have density mechanisms defined over their extents.
:ref:`Density mechanisms <mechanisms-density>` are a kind of
-:ref:`NMODL mechanism <nmodl>` which describe biophysical processes.
+:ref:`NMODL mechanism <formatnmodl>` which describe biophysical processes.
These are processes that are distributed in space, but whose behaviour is
defined purely by the state of the cell and the process at any given point.
@@ -305,7 +305,7 @@ pile-up effects similar to reflective bounds.
The diffusive concentration is *separate* from the internal concentration for
reasons innate to the cable model, which require resetting it to its starting
point at every timestep. It can be accessed from NMODL density and point
-mechanisms as an independent quantity, see :ref:`NMODL mechanism <nmodl>`. It is
+mechanisms as an independent quantity, see :ref:`NMODL mechanism <formatnmodl>`. It is
present on the full morphology if its associated diffusivity is set to a
non-zero value on any subset of the morphology, ie ``region``. It is initialised
to the value of the internal concentration at time zero.
@@ -328,7 +328,7 @@ locset.
Similar to how regions can have density mechanisms defined over their extents,
locsets can have point mechanisms placed on their individual locations.
-:ref:`Point mechanisms <mechanisms-point>` are a kind of :ref:`NMODL mechanism <nmodl>`
+:ref:`Point mechanisms <mechanisms-point>` are a kind of :ref:`NMODL mechanism <formatnmodl>`
which describe synaptic processes such as the ``expsyn`` mechanism provided by
NEURON and Arbor, which models an exponential synapse.
@@ -384,7 +384,7 @@ See also :term:`threshold detector`.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Locsets can also have junction mechanisms placed on their individual locations.
-:ref:`Junction mechanisms <mechanisms-junction>` are a kind of :ref:`NMODL mechanism <nmodl>`
+:ref:`Junction mechanisms <mechanisms-junction>` are a kind of :ref:`NMODL mechanism <formatnmodl>`
which describe gap-junction processes such as the ``gj`` mechanism provided by Arbor,
which models a basic, linear, constant-conductance based gap-junction.
@@ -452,5 +452,3 @@ API
---
* :ref:`Python <pycablecell-decor>`
-* :ref:`C++ <cppcablecell-decor>`
-
diff --git a/doc/concepts/interconnectivity.rst b/doc/concepts/interconnectivity.rst
index 68cfa7d7..d4dd8d98 100644
--- a/doc/concepts/interconnectivity.rst
+++ b/doc/concepts/interconnectivity.rst
@@ -108,7 +108,7 @@ full recipe.
threshold detector
:ref:`Placed <cablecell-place>` on a cell. Possible source of a connection.
Detects crossing of a fixed threshold and generates corresponding events.
- Also used to :ref:`record spikes <>` for analysis. See :ref:`here
+ Also used to record spikes for analysis. See :ref:`here
<cablecell-threshold-detectors>` for more information.
spike source cell
diff --git a/doc/concepts/mechanisms.rst b/doc/concepts/mechanisms.rst
index d3125971..42518b71 100644
--- a/doc/concepts/mechanisms.rst
+++ b/doc/concepts/mechanisms.rst
@@ -6,7 +6,7 @@ Cable cell mechanisms
Mechanisms describe biophysical processes such as ion channels, synapses and gap-junctions.
Mechanisms are assigned to regions and locations on a cell morphology
through the process of :ref:`decoration <cablecell-decoration>`.
-Mechanisms are described using a dialect of the :ref:`NMODL <nmodl>` domain
+Mechanisms are described using a dialect of the :ref:`NMODL <formatnmodl>` domain
specific language that is similarly used in `NEURON <https://neuron.yale.edu/neuron/>`_.
Arbor supports mechanism descriptions using the NMODL language through our ``modcc``
@@ -321,4 +321,3 @@ API
---
* :ref:`Python <py_mechanisms>`
-* :ref:`C++ <cpp_mechanisms>`
diff --git a/doc/contrib/test.rst b/doc/contrib/test.rst
index f04eb6bc..7ccfa474 100644
--- a/doc/contrib/test.rst
+++ b/doc/contrib/test.rst
@@ -32,16 +32,19 @@ that you decided to add your own radix sort algorithm, since you expect it to be
faster for this particular usecase.
Thus, the tests added should be
+
1. sorting algorithm
- the application of `sort` sorts the given array. This seems trivial, but is
really the core of what you are doing!
- corner cases like: empty array, all elements equal, ... are treated greacefully
- if the sort is intended to be stable, check that equal elements do not switch order
+
2. local sorting
- spikes are -- after sorting -- ordered by their source id and in case of ties by time
- corner cases: NaN, negative numbers, ...
+
3. global sorting
- after MPI exchange, each sub-array is still sorted
diff --git a/doc/cpp/morphology.rst b/doc/cpp/morphology.rst
index ba0c2473..8800e02a 100644
--- a/doc/cpp/morphology.rst
+++ b/doc/cpp/morphology.rst
@@ -10,7 +10,7 @@ file formats; see :ref:`cppcablecell-morphology-construction` for details.
Segment tree
------------
-A ``segment_tree` is -- as the name implies -- a set of segments arranged in a
+A ``segment_tree`` is -- as the name implies -- a set of segments arranged in a
tree structure, ie each segment has exactly one parent and no child is the
parent of any of its ancestors. The tree starts at a *root* segment which has no
parent. Each segment comprises two points in 3d space together with the radii at
diff --git a/doc/dev/cable_cell.rst b/doc/dev/cable_cell.rst
index 248c0e8d..945b5078 100644
--- a/doc/dev/cable_cell.rst
+++ b/doc/dev/cable_cell.rst
@@ -103,11 +103,11 @@ axonal/synaptic delays. This works since we know that an event at time :math:`t`
can have an effect at time :math:`t + T_{min}` at the soonest. The factor of one
half stems from double-buffering to overlap communication and computation. So,
Arbor collects all events in an epoch and transmits them in bulk, see
-:ref:`Communication <mpi_comm>` for details.
+:ref:`Communication <communication>` for details.
Integration in Arbor is then split into three parts:
-1. apply effect of events to mechanisms :ref:`Event Handling <events>`
+1. apply effect of events to mechanisms :ref:`Event Handling <event_distribution>`
2. evolve mechanisms and apply currents :ref:`Mechanisms <mechanisms>`
3. solve voltage equations, see :ref:`Solver <matrix_solver>`
diff --git a/doc/dev/communication.rst b/doc/dev/communication.rst
index 5ac1c5f3..b283e9db 100644
--- a/doc/dev/communication.rst
+++ b/doc/dev/communication.rst
@@ -103,6 +103,8 @@ each sub-array of spikes is sorted, ie between ``offsets[ix]`` and
and its ``i``'th element gives the position of the first spike sent by
task ``i``.
+.. _event_distribution:
+
Distribution of Events to Targets
=================================
diff --git a/doc/dev/matrix_solver.rst b/doc/dev/matrix_solver.rst
index 5733f1b2..92b0d0a8 100644
--- a/doc/dev/matrix_solver.rst
+++ b/doc/dev/matrix_solver.rst
@@ -3,6 +3,8 @@
Matrix Solvers
==============
+.. _cable_equation:
+
Cable Equation
--------------
diff --git a/doc/install/build_install.rst b/doc/install/build_install.rst
index a7486fbe..6584dc27 100644
--- a/doc/install/build_install.rst
+++ b/doc/install/build_install.rst
@@ -556,7 +556,7 @@ component ``neuroml``. The corresponding CMake library target is ``arbor::arbori
# ...
target_link_libraries(myapp arbor::arborio)
-.. install-profiling:
+.. _install-profiling:
Profiling
---------
diff --git a/doc/python/decor.rst b/doc/python/decor.rst
index bf7fe413..c405b3d9 100644
--- a/doc/python/decor.rst
+++ b/doc/python/decor.rst
@@ -169,6 +169,7 @@ Cable cell decoration
:type policy: :py:class:`cv_policy`
.. method:: discretization(policy)
+ :noindex:
Set the cv_policy used to discretise the cell into control volumes for simulation.
diff --git a/doc/python/hardware.rst b/doc/python/hardware.rst
index 76969f73..af51f6b2 100644
--- a/doc/python/hardware.rst
+++ b/doc/python/hardware.rst
@@ -51,14 +51,14 @@ Helper functions for checking cmake or environment variables, as well as configu
.. class:: mpi_comm
- .. function:: mpi_comm()
+ .. method:: mpi_comm()
By default sets MPI_COMM_WORLD as communicator.
- .. function:: mpi_comm(object)
+ .. method:: mpi_comm(object)
:noindex:
- Converts a Python object to an MPI Communicator.
+ :param object: Converts a Python object to an MPI Communicator.
.. function:: mpi_finalize()
@@ -67,6 +67,7 @@ Helper functions for checking cmake or environment variables, as well as configu
.. function:: mpi_is_finalized()
Check if MPI is finalized.
+ :rtype: bool
Env: Helper functions
---------------------
@@ -97,13 +98,15 @@ The Python wrapper provides an API for:
Enumerates the computational resources on a node to be used for a simulation,
specifically the number of threads and identifier of a GPU if available.
- .. function:: proc_allocation([threads=1, gpu_id=None])
+ .. method:: proc_allocation([threads=1, gpu_id=None])
- Constructor that sets the number of :attr:`threads` and the id :attr:`gpu_id` of the available GPU.
+ :param int threads: Number of threads.
+ :param int gpu_id: Device ID.
.. attribute:: threads
The number of CPU threads available, 1 by default. Must be set to 1 at minimum.
+
.. attribute:: gpu_id
The identifier of the GPU to use.
@@ -115,7 +118,7 @@ The Python wrapper provides an API for:
See ``cudaSetDevice`` and ``cudaDeviceGetAttribute`` provided by the
`CUDA API <https://docs.nvidia.com/cuda/cuda-runtime-api/group__CUDART__DEVICE.html>`_.
- .. cpp:function:: has_gpu()
+ .. method:: has_gpu()
Indicates whether a GPU is selected (i.e., whether :attr:`gpu_id` is ``None``).
@@ -145,43 +148,37 @@ The Python wrapper provides an API for:
provided by :class:`context`, instead they configure contexts, which are passed to
Arbor interfaces for domain decomposition and simulation.
- .. function:: context(threads, gpu_id, mpi)
- :noindex:
-
- Create a context that uses a set number of :attr:`threads` and gpu identifier :attr:`gpu_id` and MPI communicator :attr:`mpi` for distributed calculation.
-
- .. attribute:: threads
-
- The number of threads available locally for execution. Must be set to 1 at minimum. 1 by default.
- Passing ``"avail_threads"`` (as string) will query and use the maximum number of threads the system makes available.
-
- .. attribute:: gpu_id
-
- The identifier of the GPU to use, ``None`` by default.
- Must be ``None``, or a non-negative integer.
+ .. method:: context(threads, gpu_id, mpi)
+
+ Create a distributed context.
+
+ :param int threads:
+ The number of threads available locally for execution.
+ Must be set to 1 at minimum. 1 by default.
+ Passing ``"avail_threads"`` (as string) will query and use the maximum number
+ of threads the system makes available.
+ :param int gpu_id:
+ The non-negative identifier of the GPU to use, ``None`` by default.
Can only be set when Arbor was built with GPU support.
-
- .. attribute:: mpi
-
- The MPI communicator (see :class:`mpi_comm`), ``None`` by default.
- Must be ``None``, or an MPI communicator.
+ :type gpu_id: int or None
+ :param mpi:
+ The MPI communicator, ``None`` by default for distributed calculation.
Can only be set when Arbor was built with MPI support.
+ :type mpi: :py:class:`arbor.mpi_comm` or None.
.. function:: context(alloc, mpi)
:noindex:
- Create a distributed context, that uses the local resources described by :class:`proc_allocation`, and
- uses the MPI communicator for distributed calculation.
-
- .. attribute:: alloc
+ Create a distributed context.
+ :param alloc:
The computational resources, one thread and no GPU by default.
-
- .. attribute:: mpi
-
- The MPI communicator (see :class:`mpi_comm`). ``None`` by default.
- mpi must be ``None``, or an MPI communicator.
+ :type alloc: :py:class:`proc_allocation`
+ :param mpi:
+ The MPI communicator, ``None`` by default for distributed calculation.
Can only be set when Arbor was built with MPI support.
+ :type mpi: :py:class:`arbor.mpi_comm` or None.
+
Contexts can be queried for information about which features a context has enabled,
whether it has a GPU, how many threads are in its thread pool.
diff --git a/doc/python/labels.rst b/doc/python/labels.rst
index 86e7cad3..f85c0b45 100644
--- a/doc/python/labels.rst
+++ b/doc/python/labels.rst
@@ -14,6 +14,7 @@ Cable cell labels
Create an empty label dictionary
.. method:: label_dict(dictionary)
+ :noindex:
Initialize a label dictionary from a ``dictionary`` with string labels as keys,
and corresponding string definitions as values.
diff --git a/doc/python/mechanisms.rst b/doc/python/mechanisms.rst
index 97b9312c..9634a0dd 100644
--- a/doc/python/mechanisms.rst
+++ b/doc/python/mechanisms.rst
@@ -126,7 +126,6 @@ Cable cell mechanisms
The underlying mechanism.
.. method:: density(name)
- :noindex:
constructs :attr:`mech` with *name* and default parameters.
@@ -134,6 +133,7 @@ Cable cell mechanisms
:type name: str
.. method:: density(name, params)
+ :noindex:
constructs :attr:`mech` with *name* and range parameter overrides *params*.
for example: ``arbor.density('pas', {'g': 0.01})``.
@@ -152,6 +152,7 @@ Cable cell mechanisms
:type mech: :py:class:`mechanism`
.. method:: density(mech, params)
+ :noindex:
constructs :attr:`mech` from *mech* and sets the range parameter overrides *params*.
@@ -171,7 +172,6 @@ Cable cell mechanisms
The underlying mechanism.
.. method:: synapse(name)
- :noindex:
constructs :attr:`mech` with *name* and default parameters.
@@ -179,6 +179,7 @@ Cable cell mechanisms
:type name: str
.. method:: synapse(name, params)
+ :noindex:
constructs :attr:`mech` with *name* and range parameter overrides *params*.
for example: ``arbor.synapse('expsyn', {'tau': 0.01})``.
@@ -197,6 +198,7 @@ Cable cell mechanisms
:type mech: :py:class:`mechanism`
.. method:: synapse(mech, params)
+ :noindex:
constructs :attr:`mech` from *mech* and sets the range parameter overrides *params*.
@@ -217,7 +219,6 @@ Cable cell mechanisms
The underlying mechanism.
.. method:: junction(name)
- :noindex:
constructs :attr:`mech` with *name* and default parameters.
@@ -225,6 +226,7 @@ Cable cell mechanisms
:type name: str
.. method:: junction(name, params)
+ :noindex:
constructs :attr:`mech` with *name* and range parameter overrides *params*.
for example: ``arbor.junction('gj', {'g': 2})``.
@@ -243,6 +245,7 @@ Cable cell mechanisms
:type mech: :py:class:`mechanism`
.. method:: junction(mech, params)
+ :noindex:
constructs :attr:`mech` from *mech* and sets the range parameter overrides *params*.
diff --git a/doc/python/probe_sample.rst b/doc/python/probe_sample.rst
index a6625298..da12e17a 100644
--- a/doc/python/probe_sample.rst
+++ b/doc/python/probe_sample.rst
@@ -4,6 +4,7 @@ Cable cell probing and sampling
===============================
.. module:: arbor
+ :noindex:
.. figure:: probe_sample-diag.svg
:width: 800
diff --git a/doc/tutorial/network_ring_gpu.rst b/doc/tutorial/network_ring_gpu.rst
index 1f649ac7..834a6fb8 100644
--- a/doc/tutorial/network_ring_gpu.rst
+++ b/doc/tutorial/network_ring_gpu.rst
@@ -1,4 +1,4 @@
-.. _tutorialmpi:
+.. _tutorialgpu:
GPU and profiling
=================
diff --git a/doc/tutorial/single_cell_detailed_recipe.rst b/doc/tutorial/single_cell_detailed_recipe.rst
index 66f694ac..7391f69a 100644
--- a/doc/tutorial/single_cell_detailed_recipe.rst
+++ b/doc/tutorial/single_cell_detailed_recipe.rst
@@ -105,12 +105,12 @@ This was handled by the :class:`arbor.single_cell_model` object in the original
We would like to get a list of the spikes on the cell during the runtime of the simulation, and we would like
to plot the voltage registered by the probe on the "custom_terminal" locset.
-The lines handling probe sampling warrant a second look. First, we declared :term:`probe_id` to be a
+The lines handling probe sampling warrant a second look. First, we declared ``probeset_id`` to be a
:class:`arbor.cell_member`, with :class:`arbor.cell_member.gid` = 0 and :class:`arbor.cell_member.index` = 0.
This variable serves as a global identifier of a probe on a cell, namely the first declared probe on the
cell with ``gid = 0``, which is id of the only probe we created on the only cell in the model.
-Next, we instructed the simulation to sample :term:`probe_id` at a frequency of 50 kHz. That function returns a
+Next, we instructed the simulation to sample ``probeset_id`` at a frequency of 50 kHz. That function returns a
:term:`handle` which we will use to :ref:`extract the results <pycablecell-probesample>` of the sampling after running the simulation.
We can now run the simulation we just instantiated for a duration of 100 ms with a time step of 0.025 ms.
--
GitLab