From 3538999515ee8f134b462e8c9fed01cfc02109ef Mon Sep 17 00:00:00 2001
From: Luc Grosheintz <luc.grosheintz@gmail.com>
Date: Tue, 8 Oct 2024 11:05:02 +0200
Subject: [PATCH] Add developer documentation.

---
 docs/contents/longitudinal_diffusion.rst | 33 ++++++++++++++++++++++++
 docs/index.rst                           |  1 +
 2 files changed, 34 insertions(+)
 create mode 100644 docs/contents/longitudinal_diffusion.rst

diff --git a/docs/contents/longitudinal_diffusion.rst b/docs/contents/longitudinal_diffusion.rst
new file mode 100644
index 000000000..305ddc2d1
--- /dev/null
+++ b/docs/contents/longitudinal_diffusion.rst
@@ -0,0 +1,33 @@
+Longitudinal Diffusion
+======================
+
+The idea behind ``LONGITUDINAL_DIFFUSION`` is to allow a ``STATE`` variable to
+diffuse along a section, i.e. from one segment into a neighbouring segment.
+
+This problem is solved by registering callbacks. In particular, NEURON needs to
+be informed of the volume and diffusion rate. Additionally, the implicit
+time-stepping requires information about certain derivatives.
+
+Implementation in NMODL
+-----------------------
+
+The following ``KINETIC`` block
+
+  .. code-block::
+
+    KINETIC state {
+        COMPARTMENT vol {X}
+        LONGITUDINAL_DIFFUSION mu {X}
+
+        ~ X << (ica)
+    }
+
+Will undergo two transformations. The first is to create a system of ODEs that
+can be solved. This consumed the AST node. However, to print the code for
+longitudinal diffusion we require information from the ``COMPARTMENT`` and
+``LONGITUDINAL_DIFFUSION`` statements. This is why there's a second
+transformation, that runs before the other transformation, to extract the
+required information and store it a AST node called
+``LONGITUDINAL_DIFFUSION_BLOCK``. This block can then be converted into an
+"info" object, which is then used to print the callbacks.
+
diff --git a/docs/index.rst b/docs/index.rst
index 9c4b0105e..06574b8ce 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -24,6 +24,7 @@ About NMODL
    contents/pointers
    contents/cable_equations
    contents/globals
+   contents/longitudinal_diffusion
 
 .. toctree::
    :maxdepth: 3