# aperijake/aperi-mech architecture

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

- Interactive diagram: https://gitdiagram.com/aperijake/aperi-mech
- Repository: https://github.com/aperijake/aperi-mech

## Overview

##### Project type and purpose
- aperi-mech is an open-source, high-performance computational mechanics platform written in C++ with Python tooling, targeting CPU (MPI/OpenMP) and GPU (Kokkos) execution.
- It provides a core simulation engine (meshing, force computations, time integration), command-line interfaces (executables), and a rich suite of tests and automation (unit, regression, performance, scaling).
- It relies on external libraries: Trilinos (STK, Kokkos, Exodus), Eigen, yaml-cpp, googletest, Python packages (NumPy, SciPy, pytest, jupyter), plus Docker and Spack/Conda for build environments.

##### File structure
Top-level directories and their roles:
- cmake, CMakeLists.txt, do_configure: Build configuration and targets
- docker/: Dockerfiles and scripts for containerized builds
- /, src/: Core C++ headers and implementation of simulation engine
- protego-mech/: (private submodule) additional build tools
- test/: Python and C++ test drivers for unit, regression, performance, and scaling tests
- tools/python/: Python CLI tools and Spack wrappers for environment setup
- .github/: CI/CD pipelines and custom GitHub Actions definitions

A. Build & Configuration Layer
– CMake orchestrator (cmake/ + do_configure)
– Docker build recipes
– Spack/Conda environment definitions (tools/python/spackx, pyproject.toml)
– GitHub Actions workflows (CI/CD, performance pipelines)
B. Core Simulation Engine
– Preprocessor: parses YAML input, mesh I/O (IoInputFile, IoMesh)
– Mesh Data Structures: MeshData, NgpMeshData, FlattenedRaggedArray
– Field & Material Models: FieldData, Materials Factory (DruckerPrager, NeoHooke, etc.)
– Force & Integration Modules:
- ExternalForceContribution (Gravity, Traction)
- InternalForceContribution (Gaussian, SmoothedCell)
- TimeStepping & Solver (ExplicitTimeIntegrator, Scheduler, TimeStepper)
– Utility Components: NeighborSearchProcessor, MeshLabeler, ManualScopeTimer
– Command-line Executables: main.cpp (general sim), material_driver_main.cpp
C. Testing & Automation
– Unit Tests (test/unit_tests/*.cpp) using googletest
– Regression & Performance Tests (test/regression_tests/, test/performance_tests/) driven by Python scripts
– Scaling Tests (test/scaling_tests/) for batch runs and plotting
– Utility scripts (test/utils/, tools/python/aperi-mech) for post-processing and CI reporting
D. External Dependencies
– Trilinos stack (MPI, Kokkos, STK, Exodus)
– Eigen, yaml-cpp
– Python ecosystem (pytest, jupyter, numpy, scipy)

##### Relationships and data flow
- Build & Configuration Layer → Core Engine: configures and compiles the C++ code into executables and libraries
- Core Engine at run time:
Input file (YAML) → Preprocessor → Mesh & Field Initialization → Material & Force Factories → TimeStepper/Scheduler → Solver → Output (Exodus files, logs)
- Testing Layer invokes executables with predefined inputs, compares outputs (gold files), collects performance metrics
- Python tools post-process logs/results and integrate with CI dashboards
- CI/CD pipelines orchestrate build → unit tests → regression/performance tests → code coverage reports → Docker image publication

##### Architectural patterns & principles
- Factory pattern for force and material contributions (decoupling models from engine)
- Functor‐based processors for entity loops (mesh traversal, neighbor search)
- Clear separation of concerns: I/O, data models, physics kernels, solver, utilities
- Modular build via CMake targets and optional GPU support via Kokkos backends

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build & Configuration Layer
    subgraph "Build & Configuration Layer"
        direction TB
        CMakeOrch["CMake Orchestrator"]:::build
        DockerRec["Docker Build Recipes"]:::build
        SpackEnv["Spack Environment Definitions"]:::build
        PythonPack["Python Packaging (pyproject.toml)"]:::build
        CIWorkflows["CI/CD Workflows"]:::build
    end

    %% Core Simulation Engine
    subgraph "Core Simulation Engine"
        direction TB
        subgraph "Preprocessor & I/O"
            Preprocessor["Preprocessor & YAML I/O"]:::core
            IoInput["Mesh Input File I/O"]:::core
            IoMesh["Mesh I/O"]:::core
        end
        subgraph "Mesh Data Structures"
            MeshData["MeshData"]:::core
            NgpMesh["NgpMeshData"]:::core
            FlatArray["FlattenedRaggedArray"]:::core
        end
        subgraph "Field & Material Models"
            FieldData["FieldData & Utils"]:::core
            Materials["Material Models & Factory"]:::core
            MatDriver["Material Driver Executable"]:::core
        end
        subgraph "Force Contributions"
            ExtForce["ExternalForceContribution"]:::core
            IntForce["InternalForceContribution"]:::core
        end
        subgraph "Time Integration & Solver"
            TimeStepper["TimeStepper & Scheduler"]:::core
            Solver["Solver & ExplicitTimeIntegrator"]:::core
            MainExe["Main Executable (main.cpp)"]:::core
        end
        subgraph "Utility Processors & Timers"
            Neighbor["NeighborSearchProcessor"]:::core
            MeshLabeler["MeshLabeler"]:::core
            Timer["ManualScopeTimer"]:::core
        end
    end

    %% Testing & Automation
    subgraph "Testing & Automation"
        direction TB
        UnitTests["Unit Tests (GoogleTest)"]:::test
        RegTests["Regression Tests"]:::test
        PerfTests["Performance Tests"]:::test
        ScaleTests["Scaling Tests"]:::test
        TestUtils["Test Utilities & Scripts"]:::test
        PyTestDriver["Python Test Driver"]:::test
    end

    %% Command-Line Tools & Python Wrappers
    subgraph "Python CLI & Wrappers"
        direction TB
        PyCLI["aperi-mech Python CLI & env setup"]:::scripts
    end

    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        TrilinosDep["Trilinos, Kokkos, STK"]:::ext
        EigenYaml["Eigen & yaml-cpp"]:::ext
        PythonDeps["Python Ecosystem"]:::ext
    end

    %% Build to Core
    CMakeOrch -->|"configures & builds"| MainExe
    DockerRec -->|"containerized builds"| MainExe
    SpackEnv -->|"provides environments"| MainExe
    PythonPack -->|"packaging definitions"| PyCLI
    CIWorkflows -->|"orchestrates build & tests"| CMakeOrch

    %% Core Data Flow
    IoInput -->|"reads YAML mesh"| Preprocessor
    Preprocessor -->|"initializes mesh"| MeshData
    MeshData --> NgpMesh
    MeshData --> FlatArray
    MeshData --> FieldData
    FieldData --> Materials
    Materials --> ExtForce
    Materials --> IntForce
    ExtForce --> TimeStepper
    IntForce --> TimeStepper
    TimeStepper --> Solver
    Solver --> MainExe
    MainExe -->|"writes Exodus & logs"| MeshData

    %% Utilities
    Neighbor --> MeshData
    MeshLabeler --> MeshData
    Timer --> Solver

    %% Testing relationships
    UnitTests -->|"invoke executables"| MainExe
    RegTests --> MainExe
    PerfTests --> MainExe
    ScaleTests --> MainExe
    TestUtils --> UnitTests
    PyTestDriver --> UnitTests

    %% Python CLI & CI
    PyCLI -->|"post-process & reporting"| CIWorkflows

    %% External dependencies links
    TrilinosDep --> CMakeOrch
    EigenYaml --> CMakeOrch
    PythonDeps --> PythonPack

    %% Click Events
    click CMakeOrch "https://github.com/aperijake/aperi-mech/tree/main/cmake/"
    click DockerRec "https://github.com/aperijake/aperi-mech/tree/main/docker/"
    click SpackEnv "https://github.com/aperijake/aperi-mech/tree/main/tools/python/spackx/"
    click PythonPack "https://github.com/aperijake/aperi-mech/blob/main/tools/python/aperi-mech/pyproject.toml"
    click CIWorkflows "https://github.com/aperijake/aperi-mech/blob/main/.github/workflows/ci-cd-pipeline.yaml"
    click Preprocessor "https://github.com/aperijake/aperi-mech/blob/main/include/Preprocessor.h"
    click IoInput "https://github.com/aperijake/aperi-mech/blob/main/include/IoInputFile.h"
    click IoMesh "https://github.com/aperijake/aperi-mech/blob/main/include/IoMesh.h"
    click MeshData "https://github.com/aperijake/aperi-mech/blob/main/include/MeshData.h"
    click NgpMesh "https://github.com/aperijake/aperi-mech/blob/main/include/NgpMeshData.h"
    click FlatArray "https://github.com/aperijake/aperi-mech/blob/main/include/FlattenedRaggedArray.h"
    click FieldData "https://github.com/aperijake/aperi-mech/blob/main/include/FieldData.h"
    click Materials "https://github.com/aperijake/aperi-mech/blob/main/include/Materials/Factory.h"
    click MatDriver "https://github.com/aperijake/aperi-mech/blob/main/src/material_driver_main.cpp"
    click ExtForce "https://github.com/aperijake/aperi-mech/blob/main/include/ExternalForceContribution/Base.h"
    click IntForce "https://github.com/aperijake/aperi-mech/blob/main/include/InternalForceContribution.h"
    click Solver "https://github.com/aperijake/aperi-mech/blob/main/src/Solver.cpp"
    click MainExe "https://github.com/aperijake/aperi-mech/blob/main/src/main.cpp"
    click Neighbor "https://github.com/aperijake/aperi-mech/blob/main/include/NeighborSearchProcessor.h"
    click UnitTests "https://github.com/aperijake/aperi-mech/tree/main/test/unit_tests/"
    click RegTests "https://github.com/aperijake/aperi-mech/tree/main/test/regression_tests/"
    click PerfTests "https://github.com/aperijake/aperi-mech/tree/main/test/performance_tests/"
    click ScaleTests "https://github.com/aperijake/aperi-mech/tree/main/test/scaling_tests/"
    click TestUtils "https://github.com/aperijake/aperi-mech/tree/main/test/utils/"
    click PyTestDriver "https://github.com/aperijake/aperi-mech/blob/main/test/material_tests/python_test_driver.py"
    click PyCLI "https://github.com/aperijake/aperi-mech/tree/main/tools/python/aperi-mech/src/aperi_mech/"

    %% Styles
    classDef build fill:#D6EAF8,stroke:#1B4F72;
    classDef core fill:#D5F5E3,stroke:#186A3B;
    classDef test fill:#FCF3CF,stroke:#B9770E;
    classDef ext fill:#E5E8E8,stroke:#566573;
    classDef scripts fill:#FADBD8,stroke:#922B21;
```
