From f91f45b1c91f50299b5683ad274c1e66512ea087 Mon Sep 17 00:00:00 2001
From: "Ankur Sinha (Ankur Sinha Gmail)" <sanjay.ankur@gmail.com>
Date: Tue, 5 Dec 2023 12:02:39 +0000
Subject: [PATCH] feat: add page on HDF5o

Fixes #180
---
 source/Userdocs/HDF5.md | 23 +++++++++++++++++++++++
 source/_toc.yml         |  1 +
 2 files changed, 24 insertions(+)
 create mode 100644 source/Userdocs/HDF5.md

diff --git a/source/Userdocs/HDF5.md b/source/Userdocs/HDF5.md
new file mode 100644
index 00000000..b95e2f1a
--- /dev/null
+++ b/source/Userdocs/HDF5.md
@@ -0,0 +1,23 @@
+(userdocs:hdf5)=
+# HDF5 support
+
+The XML serializations of large NeuroML models can be prohibitive to store.
+For such cases, NeuroML also includes support for saving models in the binary [HDF5](https://www.hdfgroup.org/solutions/hdf5) format via the [NeuroMLhdf5Writer in libNeuroML](https://libneuroml.readthedocs.io/en/stable/userdocs/writers.html#neuroml.writers.NeuroMLHdf5Writer).
+The format of the export is documented below:
+
+
+- {ref}`Network <schema:network>` is exported as a `network` group with `id`, `notes`, and the `temperature` (optional) stored as attributes.
+- {ref}`Population <schema:population>` is exported as a group with id `population_<id of the population>` with `id`, `component`, `size`, `type`, and `property` tags stored as attributes.
+  - If the population is a {ref}`population list <schema:populationlist>` that includes {ref}`instances <schema:instance>` of cells, the locations of cells (x, y, z), these are stored in a 3 column table ("chunked array") with a row per instance.
+
+- {ref}`Projection <schema:projection>` is exported as a group with id `project_<id of the projection>` with `id`, `type`, `presynapticPopulation`, `postSynapticPopulation`, `synapse` as attributes.
+  - {ref}`Connection <schema:connection>` and {ref}`ConnectionWD <schema:connectionwd>` elements in projections are stored as rows in a table with the first two columns as the `pre_cell_id` and `post_cell_id` respectively, and the successive columns for the necessary attributes.
+
+- {ref}`ElectricalProjection <schema:electricalprojection>` is exported similar to Projection with the {ref}`ElectricalConnection <schema:electricalconnection>`, {ref}`ElectricalConnectionInstance <schema:electricalconnectioninstance>`, and {ref}`ElectricalConnectionInstanceW <schema:electricalconnectioninstancew>` entries stored in tables.
+- {ref}`ContinuousProjection <schema:continuousprojection>` is exported similar to Projection with the {ref}`ContinuousConnection <schema:continuousconnection>`, {ref}`ContinuousConnectionInstance <schema:continuousconnectioninstance>`, and {ref}`ContinuousConnectionInstanceW <schema:continuousconnectioninstancew>` entries stored in tables.
+- {ref}`InputList <schema:inputlist>` is exported similar to Projection with the {ref}`Input <schema:input>`, and {ref}`InputW <schema:inputw>` entries stored in tables.
+
+
+The source code of these export functions can be seen [here in the libNeuroML repository](https://github.com/NeuralEnsemble/libNeuroML/blob/2d8112178d8d82b07a20f8395ec22a23a6323a6c/neuroml/nml/helper_methods.py#L2548).
+
+HDF5 NeuroML files can also be passed to `jnml` like `XML` files.
diff --git a/source/_toc.yml b/source/_toc.yml
index e4d7a565..f56e9750 100644
--- a/source/_toc.yml
+++ b/source/_toc.yml
@@ -21,6 +21,7 @@ parts:
     - file: Userdocs/CreatingNeuroMLModels
       sections:
       - file: Userdocs/ImportingMorphologyFiles
+      - file: Userdocs/HDF5
     - file: Userdocs/ValidatingNeuroMLModels
     - file: Userdocs/VisualisingNeuroMLModels
       sections: