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

    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.

Source

outputs.rst