How aperijake/aperi-mech works
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