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/:

Core modules in src/core/
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.