File Map
========

The main directory contains subdirectories that provide the structural
framework for code maintenance and compilation:

* build-dev / build-rel-cpu
* cmake
* CMakeLists.txt
* docs
* resources
* src
* tests
* tools
* vendor


build-dev / build-rel-cpu
-------------------------

Out-of-source build directories generated by CMake. ``build-dev`` is for debug
builds with development tools, while ``build-rel-cpu`` contains release builds
optimized for CPU execution.

cmake
-----

Contains custom CMake module files in the ``modules/`` subdirectory and
configuration templates. The root ``CMakeLists.txt`` is the entry point that
initializes the build environment and orchestrates compilation.

docs
----

Documentation source files including Sphinx configuration, Doxygen settings,
and reStructuredText content for user and developer guides.

resources
---------

Desktop integration files and application resources.

tests
-----

Unit tests for validating individual components. Tests are integrated with
CMake/CTest and built to ``build-*/bin/tests/``. Currently includes:

* ``unit_broadcast.cpp`` - Tests for MPI broadcast functionality
* ``unit_triangulation.cpp`` - Tests for triangulation algorithms
* ``waterdyn4/`` - Test data package with database, configuration files,
  MD simulation data, and reference outputs for validation

Tests link against ``SassenaCore`` library and run with the waterdyn4 directory
as working directory to access test fixtures.

The test suite also includes integration tests under ``tests/integration/``
that run the full Sassena binary on the ``waterdyn4`` dataset and compare
outputs against reference HDF5 files. Integration tests are built when
CMake is configured with ``-DUSE_DEVELOPER_MODE=ON`` and require an MPI runtime.

tools
-----

Python utility scripts for post-processing and analysis:

* ``pdb_analyzer.py`` - PDB file analysis tool
* ``signal_plot.py`` - Signal visualization and plotting

vendor
------

Third-party dependencies bundled with Sassena:

* ``boost/`` - Boost C++ libraries subset
* ``pybind11/`` - Python bindings generation
* ``taskflow/`` - Parallel task programming framework
* ``xdrfile-1.1.1/`` - XDR trajectory file I/O library

src
---

The source directory is organized into two main areas:

* ``src/app/`` - Application entry points (executables)
* ``src/core/`` - Core library modules (headers and implementation)

Unlike traditional separation of headers and implementation, Sassena colocates
.hpp and .cpp files within their respective module directories in ``src/core/``.
This strongly compartmentalized structure organizes code into functional modules
that may be independent or have dependencies on other modules. Module dependencies
can be traced through the ``CMakeLists.txt`` files using ``target_link_libraries``.

Core modules in ``src/core/``:

.. list-table:: Core modules in src/core/
   :widths: 25 75
   :header-rows: 1

   * - Module
     - Directory
   * - MATH
     - math/
   * - LOG
     - log/
   * - CONTROL
     - control/
   * - IO
     - io/
   * - MPI
     - mpi/
   * - REPORT
     - report/
   * - SAMPLE
     - sample/
   * - DECOMPOSITION
     - decomposition/
   * - SERVICES
     - services/
   * - STAGER
     - stager/
   * - SCATTER_DEVICES
     - scatter_devices/
   * - EXCEPTIONS
     - exceptions/


The ``src/app/`` directory contains entry points for binary executables:

* ``sassena.cpp`` - Main Sassena application
* ``s_stage.cpp`` - Staging utility
* ``s_maketnx.cpp`` - Generates a ``.tnx`` trajectory index file. Some trajectory
  formats (e.g. DCD) do not store per-frame byte offsets, so Sassena cannot seek
  directly to a given frame without reading the whole file first. Running
  ``s_maketnx`` pre-computes and stores those offsets, allowing efficient random
  access during a scattering calculation.

These files initialize the software environment and orchestrate module execution.
All modules include ``src/core/common.hpp`` and ``src/core/common.cpp``, which
provide shared type definitions and common functionality across the codebase.
Additionally, ``src/core/platform.hpp`` contains platform-specific definitions.

**MATH**
  Provides mathematical routines (element-wise operations, autocorrelation,
  reduction), coordinate system types, and trigonometric operations.

**LOG**
  Contains singleton classes for formatted console output (Information, Warnings,
  Errors).

**CONTROL**
  Singleton classes for software configuration management. Includes ``database.hpp``
  for global state and ``parameters.hpp`` for computation parameters. Maps input
  from XML configuration files and initializes defaults.

**IO**
  File format interfaces. Contains ``xml_interface.hpp`` for XML parsing and
  XDR trajectory file I/O integration.

**SAMPLE**
  Classes for initializing trajectory data and structural information.

**MPI**
  Wrapper functions to facilitate broadcasting of data structures across nodes.

**REPORT**
  Analysis tools for timer information aggregated during execution, presented to
  the user at calculation completion.

**DECOMPOSITION**
  Partitioning logic that determines optimal partition sizes for distributed
  computation.

**SERVICES**
  Asynchronous internal services including the monitoring service (progress
  tracking) and file writer service (asynchronous result output).

**STAGER**
  Trajectory data staging routines. Uses the SAMPLE module to initialize
  trajectories and distributes data across available partitions.

**SCATTER_DEVICES**
  Class hierarchy implementing runtime logic for computing scattering functions.

**EXCEPTIONS**
  Custom exception classes for error handling throughout the application.