Simulator Outputs
=================

This page describes the outputs generated by the simulator. All output files are placed relative to the directory where the simulation is executed. This section explains the content and purpose of each file or folder created by the simulator.

Base Directory
--------------

After a successful run, the base directory (i.e., where the simulation was launched) will contain the following files:

- **Simulation log file**  
  A file named ``pydamus_<date>_<time>.log`` is created during the simulation. It contains runtime information, including progress updates, warnings, and error messages (if any). This log is essential for debugging and performance diagnostics.

- **Completion flag**  
  If the simulation completes successfully, an empty file named ``simulation_config.json.SUCCESS`` is written. This is used by the Blue Brain Project (BBP) workflow system to detect successful execution. The presence of this file indicates the run ended without errors.

``output/``
-----------

This folder contains the simulation results, including all reports requested in ``simulation_config.json``. The exact location of the ``output`` folder is specified within the configuration file.

**Contents:**

- **Reports**  
  All the time series or scalar reports explicitly configured in ``simulation_config.json`` are saved here. The format and structure depend on the report type and backend.

- **Spike files**  
  The final spike output is written in two formats:

  - ``out.dat``: Plain text file listing spike events (only present when using CoreNEURON)
  - ``out.h5``: HDF5 version of the same data for efficient access

  More info: `SONATA Developer Guide – Spike File <https://github.com/AllenInstitute/sonata/blob/master/docs/SONATA_DEVELOPER_GUIDE.md#spike-file>`_

  Both contain a table with two columns:

  1. **gid** – the global identifier of the neuron that spiked  
  2. **time** – the time (in ms) at which the spike occurred

- **populations_offset.dat**  
  This file contains the offset indices for each neuron population. It is primarily used for visualization and internal processing. It helps map GIDs back to their corresponding populations.

``save/`` or ``build/``
-----------------------

This feature is available **only in CoreNEURON** and is related to preserving internal simulator state for potential restoration. By default, CoreNEURON uses a folder named 'build'

- If ``--keep-build`` is specified (without ``--save``), the files in the 'build' folder will not be deleted (see note below for more details)
- If ``--save=<path>`` is specified, the CoreNEURON internal data files are instead stored in the given path. This provides a simpler bundle  which allows explicit control over where to persist the simulation state for a possible restore in the future.

Note: These files are normally deleted at the end of a successful simulation run—unless either ``--keep-build`` or ``--save`` is used. However, if the simulation terminates abnormally, the temporary files in ``build/`` may remain and will need to be manually managed.


**Contents:**

- ``<pop>_2.dat`` and ``time.dat``  
  Binary files required to resume simulations, storing simulator state and time-related metadata.

- ``populations_offset.dat``  
  Duplicated from the output path. Maps GIDs to their populations.

- **CoreNEURON data**.  
  Internal transient data for switching from NEURON to CoreNEURON simulation mode

  - **coreneuron_input/**  
    Subfolder containing various CoreNEURON model state files. Not intended for direct user manipulation. When running with multiple ranks, this folder may contain a large number of files. Contents include:

    - ``<rank>_1.dat``, ``<rank>_2.dat``, ``<rank>_3.dat``:  
      Binary files, one set for each MPI rank, holding internal CoreNEURON data structures.

    - ``bbcore_mech.dat``  
      Describes mechanisms used in the simulation (e.g., ion channels, synapses), including implementation details.

    - ``globals.dat``  
      Text file storing values of global variables required by mechanisms or model components.

    - ``files.dat``  
      Lists or maps internal data files used by CoreNEURON.

  - ``sim.conf``  
    Plain-text configuration file preserving internal state and runtime parameters at save time.

  - ``report.conf``  
    Hybrid binary/text file with GID lists and metadata required to resume report generation after restore.

``restore/``
------------

The simulator can resume a previously saved state using the ``--restore=<path>`` option (CoreNEURON only).

The provided path must point to a folder created with ``--save`` and must include all files described in the ``save/`` section.

Upon restoring, the simulator will:

- Load internal state from binary files like ``1_2.dat`` and ``time.dat``
- Re-initialize report generation using ``report.conf``
- Resume simulation from the saved timestamp

.. note::

   If any file is missing or inconsistent in the restore folder, the simulation may fail to start or behave incorrectly.