CoreNeuron Inputs
================

Premise
-------

This document provides a best-effort overview of the inputs used by CoreNeuron. 
I do not claim complete knowledge of all internal workings; sections marked 
with ``TODO`` indicate areas where further clarification is needed.

Input Categories
----------------

CoreNeuron inputs can be divided into two main categories:

1. **Additional configuration values/files**:

   - **sim.conf**: A general configuration file. All values defined here 
     can also be passed as command-line parameters.

   - **report.conf**: A configuration file specifying the reports that 
     CoreNeuron needs to emit. This file is used only if Direct Mode is 
     not enabled. The output routines rely on ``libsonatareport`` and 
     comply with the Sonata standard: 
     `Sonata Documentation <https://sonata-extension.readthedocs.io/en/latest/>`_.

2. **Data passed from NEURON to CoreNeuron**:

   NEURON passes input data to CoreNeuron via files located in the 
   ``datpath`` specified in ``sim.conf`` (or passed as a CLI argument). 
   These files include:

   - **gid_1.dat, gid_2.dat, gid_3.dat**: Data for each GID passed in three 
     phases.
   - **bbcore_mech.dat**: Information about mechanisms.
   - **files.dat**: TODO — description needed.
   - **globals.dat**: TODO — description needed.

sim.conf
--------

The ``sim.conf`` file is a general configuration file used by CoreNeuron. 
It can be provided either via the CLI option ``--read-config`` or by setting 
the ``sim_config`` attribute in Python:

.. code-block:: python

    from neuron import coreneuron
    coreneuron.sim_config = "<path to sim.conf>"

Example ``sim.conf``:

.. code-block:: ini

    outpath='<path where simulation outputs (i.e., reports) are written>'
    datpath='<path where NEURON writes input data files for CoreNeuron (usually build/coreneuron_input)>'
    tstop=100.0
    dt=0.025
    prcellgid=-1
    celsius=34.0
    voltage=-65.0
    cell-permute=0
    mpi=1
    seed=767740
    report-conf='<path to report.conf file>'

**Parameters explained**:

- ``outpath``: Path where simulation outputs (i.e., reports) are written.
- ``datpath``: Path where NEURON writes input data files for CoreNeuron.
- ``tstop``: Total simulation time in milliseconds.
- ``dt``: Integration time step in milliseconds.
- ``prcellgid``: If >=0, print state of this GID during simulation.
- ``celsius``: Temperature of the simulation in °C.
- ``voltage``: Initial membrane voltage in mV.
- ``cell-permute``: Index controlling the permutation of cells:

  - 0 — No permutation
  - 1 — Optimize node adjacency (CPU, GPU)
  - 2 — Optimize parent adjacency (GPU)

- ``mpi``: Number of MPI ranks (if using parallel execution).
- ``seed``: Random seed for reproducibility.
- ``report-conf``: Path to ``report.conf`` file for simulation reports.


report.conf
-----------

The ``report.conf`` file specifies the reports that CoreNeuron will emit. 
It is partially binary and typically generated by `Neurodamus <https://github.com/openbraininstitute/neurodamus>`_.  

**Format overview**:

1. The file starts with a single number indicating the **total number of reports**.
2. Each report has a **metadata line** with a few key values (see below).  
3. Following the metadata line, there is a **binary line** with a list of gids. 
4. (Optional) If the report is of type ``compartment_set``, there are 2 **additional binary lines**:

     - Section IDs (integers)
     - Compartment IDs (integers)  

All these binary lines (list of integers) have the same length. It is specified by ``num_gids`` in the metadata line (see below).

**Example entries (simplified)**:

.. code-block:: text

    2
    compartment_set_pas.h5 Mini5 compartment_set pas mV SONATA invalid invalid 1.0 0.0 40.0 8 8 none
    <binary data for GIDs>
    <binary data for section IDs>
    <binary data for compartment IDs>

    summation_v.h5 Mosaic summation v mV SONATA soma center 1.0 0.0 40.0 5 8 none
    <binary data for GIDs>

**Metadata line fields**


Each report in ``report.conf`` starts with a metadata line describing its properties. 

.. code-block:: text

    report_name target_name report_type report_variable unit report_format sections compartments dt start_time end_time buffer_size scaling num_gids

The various variables are described in detail in the `SONATA report documentation <https://sonata-extension.readthedocs.io/en/latest/sonata_report.html>`_.

Field descriptions:

1. ``report_name`` — Name of the output
2. ``target_name`` — Name of node set (group of gids)
3. ``report_type`` — Type of report

   - ``compartment``  
   - ``compartment_set``  
   - ``summation``  
   - ``synapse``  
   - ``lfp``  

4. ``report_variable`` — The variable to be reported (e.g., ``v``, ``i_membrane``, ``pas.i``, ``pas``). Any point-process or mechanism variable is allowed. The variable should be specified as ``<mechanism>.<variable>``. If the variable is ``i``, it can be omitted; in that case, the code assumes ``i`` by default.
5. ``unit`` — Physical unit of the reported variable (e.g., ``mV``, ``nS``)  
6. ``report_format`` — Format of the report (currently only ``SONATA`` remains)  
7. ``sections`` — Target sections of the cells:  

   - ``Cell``, ``Soma``, ``Axon``, ``Dend`` (Dendrite), ``Apic`` (Apical),  
     ``Ais``, ``Node``, ``Myelin``, ``All``, ``Invalid`` (used for `compartment_set` reports)

8. ``compartments`` — Specific compartments:  

   - ``All``, ``Center``, ``Invalid`` (used for `compartment_set` reports)

9. ``dt`` — Sampling interval for the report in milliseconds  
10. ``start_time`` — Start time of the report in milliseconds  
11. ``end_time`` — End time of the report in milliseconds  
12. ``num_gids`` — Number of GIDs included in the report (used to read the following binary lines)
13. ``buffer_size`` — Size of the buffer used to store report values  
14. ``scaling`` — Scaling applied to reported values:  

    - ``None``, ``Area``  


**Notes**:

- Following the metadata line, binary lines store the actual data: 

  - GIDs (all reports)  
  - Section IDs and compartment IDs (for ``compartment_set`` reports only)  

- All binary lines have length ``num_gids``.  
- The order of the fields in the metadata line corresponds exactly to the order above.