# sparcians/map architecture

> Architecture diagram of the GitHub repository sparcians/map, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sparcians/map
- Repository: https://github.com/sparcians/map

## Overview

- Sparta – a C++ modeling framework for building, binding, and executing full simulation designs.
- Helios – a Python-based visualization and data analysis toolset (also called Argos in some parts) that is used to view and deep dive into the results generated by Sparta.

##### Main Components
a. Sparta Framework:
– Represent this as a core simulation engine. It consists of a large set of C++ classes (organized under directories such as “sparta”, “sparta/src”, “sparta/test”, etc.) that handle simulation models, event scheduling, report generation (output to text, databases, HDF5) and resource management.
b. Helios/Argos Viewer:
– Represent this as the visualization/analysis layer. Helios (found under directories “helios” and “helios/pipeViewer”) processes simulation outputs from Sparta for graphical display and analysis.
c. Build & Integration Infrastructure:
– Include CI/CD pipelines (with configurations in .circleci, .github, .azure-pipelines, etc.) showing how automated test and build scripts are integrated.
d. Packaging and Environment Management:
– Show the Conda recipes (“conda.recipe” and associated scripts) and other build scripts located in “.scripts” and “scripts” which help in setting up the environment for both Sparta and Helios.
e. Support Libraries and External Dependencies:

##### Establish Relationships and Interactions
a. Data Flow:
– Include directional flows where the Helios component “consumes” simulation results.
b. Build Dependency & Integration:
– Show integration points with CI/CD components, which are configured to build and test both parts.
– Include connections with external systems such as conda environments, indicating that developers can trigger builds and tests.
c. External Dependencies:
– Illustrate how the build system uses CMake and underlying OS package managers to incorporate the needed libraries for Sparta.

##### Architectural Patterns and Design Principles
a. Separation of Concerns:
– Emphasize that the simulation (Sparta) and visualization (Helios) parts are decoupled. Sparta is a lower-level C++ engine that produces plain data, while Helios is a higher-level Python tool that processes and visualizes this data.
b. Modularity:
– Indicate the modularity of the system through distinct directories and submodules. For example, within Sparta there are dedicated areas for event triggers, simulation configuration, and reporting.
c. Build & Test Driven Development:
– Reflect the CI configuration files and testing directories to demonstrate the modern software engineering practice of continuous integration and thorough testing.

##### Relevant Technologies, Frameworks, and Libraries
a. Under Sparta: C++17, CMake, Boost, YAML-CPP, RapidJSON, SQLite, HDF5, and Clang.
b. Under Helios: Python (with related build and installation details) along with its integration via CMake.
c. CI/CD Scripts and Integration: Usage of CircleCI, Azure Pipelines, GitHub actions, and conda environment management.
d. Packaging Tools: Conda recipes and additional helper scripts that help in managing dependencies.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CI/CD Pipeline Subgraph
    subgraph "CI/CD Pipeline"
        C1[".azure-pipelines"]:::cicd
        C2[".circleci"]:::cicd
        C3[".github"]:::cicd
        C4[".ci_support"]:::cicd
        C5["azure-pipelines.yml"]:::cicd
    end

    %% Conda & Build Infrastructure Subgraph
    subgraph "Conda & Build Infrastructure"
        B1["conda.recipe"]:::build
        B2[".scripts"]:::build
        B3["scripts"]:::build
    end

    %% Simulation Engine Subgraph
    subgraph "Simulation Layer"
        S1["Sparta Simulation Engine"]:::backend
    end

    %% Visualization Layer Subgraph
    subgraph "Visualization Layer"
        H1["Helios Visualization/Analysis Toolset"]:::frontend
    end

    %% External Libraries & Dependencies Subgraph
    subgraph "External Libraries & Dependencies"
        E1["sparta/cmake"]:::ext
    end

    %% Connections
    %% CI/CD triggers build infrastructure and directly interfaces with simulation and visualization
    C1 --> B1
    C1 --> S1
    C1 --> H1

    %% Build Infrastructure builds both simulation engine and visualization toolset
    B1 --> S1
    B1 --> H1

    %% Simulation Engine produces output consumed by Visualization Layer
    S1 -->|"simulation_output"| H1

    %% External libraries are used by the simulation engine
    E1 --> S1

    %% Styles
    classDef backend fill:#FFCDD2,stroke:#C62828,stroke-width:2px;
    classDef frontend fill:#C8E6C9,stroke:#2E7D32,stroke-width:2px;
    classDef cicd fill:#FFF9C4,stroke:#F9A825,stroke-width:2px,stroke-dasharray: 5 5;
    classDef build fill:#BBDEFB,stroke:#1565C0,stroke-width:2px;
    classDef ext fill:#D1C4E9,stroke:#512DA8,stroke-width:2px;

    %% Click Events
    click S1 "https://github.com/sparcians/map/tree/master/sparta"
    click H1 "https://github.com/sparcians/map/tree/master/helios"
    
    click C1 "https://github.com/sparcians/map/blob/master/.azure-pipelines"
    click C2 "https://github.com/sparcians/map/blob/master/.circleci"
    click C3 "https://github.com/sparcians/map/blob/master/.github"
    click C4 "https://github.com/sparcians/map/blob/master/.ci_support"
    click C5 "https://github.com/sparcians/map/blob/master/azure-pipelines.yml"
    
    click B1 "https://github.com/sparcians/map/blob/master/conda.recipe"
    click B2 "https://github.com/sparcians/map/blob/master/.scripts"
    click B3 "https://github.com/sparcians/map/tree/master/scripts"
    
    click E1 "https://github.com/sparcians/map/tree/master/sparta/cmake"
```
