From 8e63d492d0aedb97bd797d81cdb6798caaed14ee Mon Sep 17 00:00:00 2001 From: filimarc Date: Fri, 11 Oct 2024 09:57:36 +0200 Subject: [PATCH] docs: update top-level guide --- docs/components/scaffold.rst | 12 +++++ docs/components/storage.rst | 5 ++ .../getting-started/_empty_config_example.rst | 52 +++++++++++++++++++ docs/getting-started/top-level-guide.rst | 32 ++++++++---- docs/index.rst | 2 + 5 files changed, 94 insertions(+), 9 deletions(-) create mode 100644 docs/components/scaffold.rst create mode 100644 docs/components/storage.rst create mode 100644 docs/getting-started/_empty_config_example.rst diff --git a/docs/components/scaffold.rst b/docs/components/scaffold.rst new file mode 100644 index 00000000..c080b3fb --- /dev/null +++ b/docs/components/scaffold.rst @@ -0,0 +1,12 @@ +######## +Scaffold +######## + +Main object of the BSB infrastructure. + +Using the scaffold object, you can inspect the data in the storage by using the +:class:`~.storage.interfaces.PlacementSet` and +:class:`~.storage.interfaces.ConnectivitySet` APIs. PlacementSets can be obtained with +:meth:`scaffold.get_placement_set <.core.Scaffold.get_placement_set>`, and +ConnectivitySets with :meth:`scaffold.get_connectivity_set +<.core.Scaffold.get_placement_set>`. \ No newline at end of file diff --git a/docs/components/storage.rst b/docs/components/storage.rst new file mode 100644 index 00000000..a6ddefe9 --- /dev/null +++ b/docs/components/storage.rst @@ -0,0 +1,5 @@ +####### +Storage +####### + +**to do** \ No newline at end of file diff --git a/docs/getting-started/_empty_config_example.rst b/docs/getting-started/_empty_config_example.rst new file mode 100644 index 00000000..1b0e77a2 --- /dev/null +++ b/docs/getting-started/_empty_config_example.rst @@ -0,0 +1,52 @@ +.. tab-set-code:: + + .. code-block:: json + + { + "storage": { + + }, + "network": { + + }, + "morphologies": [ + ], + "regions": { + + }, + "partitions": { + + }, + "cell_types": { + + }, + "placement": { + + }, + "after_placement": { + + }, + "connectivity": { + + }, + "after_connectivity": { + + }, + "simulations": { + + } + } + + .. code-block:: yaml + + storage: {} + network: {} + morphologies: [] + regions: {} + partitions: {} + cell_types: {} + placement: {} + after_placement: {} + connectivity: {} + after_connectivity: {} + simulations: {} diff --git a/docs/getting-started/top-level-guide.rst b/docs/getting-started/top-level-guide.rst index 6059877f..b3f5811c 100644 --- a/docs/getting-started/top-level-guide.rst +++ b/docs/getting-started/top-level-guide.rst @@ -12,9 +12,9 @@ Top Level Guide :figwidth: 90% :figclass: only-dark -The Brain **Scaffold** Builder revolves around the :class:`~.core.Scaffold` object. A -scaffold ties together all the information in the :class:`~.config.Configuration` with the -:class:`~.storage.Storage`. The configuration contains your model description, while the +The Brain **Scaffold** Builder revolves around the :doc:`Scaffold ` object. A +scaffold ties together all the information in the ``Configuration`` with the +:doc:`Storage `. The configuration contains your model description, while the storage contains your model data, like concrete cell positions or connections. Using the scaffold object one can turn the abstract model configuration into a concrete @@ -25,12 +25,6 @@ those cells and connections. All of these configurable objects can be accessed f scaffold object, under ``network.placement``, ``network.connectivity``, ``network.simulations``, ... -Using the scaffold object, you can inspect the data in the storage by using the -:class:`~.storage.interfaces.PlacementSet` and -:class:`~.storage.interfaces.ConnectivitySet` APIs. PlacementSets can be obtained with -:meth:`scaffold.get_placement_set <.core.Scaffold.get_placement_set>`, and -ConnectivitySets with :meth:`scaffold.get_connectivity_set -<.core.Scaffold.get_placement_set>`. Ultimately this is the goal of the entire framework: To let you explicitly define every component and parameter that is a part of your model, and all its parameters, in such a @@ -53,6 +47,12 @@ Workflow Configuration ============= +The ``Configuration`` object is organized as a hierarchical tree. +From the root, the main blocks branch off, consisting of nine required components: :guilabel:`network`, +:guilabel:`storage`, :guilabel:`regions`, :guilabel:`partitions`, :guilabel:`morphologies`, :guilabel:`cell types`, :guilabel:`placement`, :guilabel:`connectivity`, and :guilabel:`simulation`. +These blocks contain nested sub-blocks that form the network. +Additionally, there are two optional blocks: :guilabel:`after_placement` and :guilabel:`after_connectivity`, where users can define specific hooks to run within the workflow. + .. figure:: /images/configuration.png :figwidth: 90% :figclass: only-light @@ -60,3 +60,17 @@ Configuration .. figure:: /images/configuration_dark.png :figwidth: 90% :figclass: only-dark + +Configuration File +------------------ + +A configuration file describes the components of a scaffold model. It contains the +instructions to place and connect neurons, how to represent the cells and connections as +models in simulators and what to stimulate and record in simulations. + +The default configuration format is JSON, but YAML is also supported. +A standard configuration file is structured as follows: + +.. include:: _empty_config_example.rst + + diff --git a/docs/index.rst b/docs/index.rst index be5d67c1..88060f5f 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -95,6 +95,7 @@ human-readable, multi-scale models! :caption: Components components/intro + components/scaffold config/configuration-toc topology/topology-toc cells/cells-toc @@ -102,6 +103,7 @@ human-readable, multi-scale models! placement/placement-toc connectivity/connectivity-toc simulation/simulation-toc + components/storage .. toctree::