# 2018uch0002/abeille architecture

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

- Interactive diagram: https://gitdiagram.com/2018uch0002/abeille
- Repository: https://github.com/2018uch0002/abeille

## Overview

##### Project Type and Purpose
- Abeille is a command-line, full-domain Monte-Carlo neutron transport simulation code written in C++20.
- It ingests a single YAML input file describing geometry, materials, sources, and simulation settings, then solves neutron transport (fixed-source, k-eigenvalue, or noise problems).
- Key features: multiple particle tracking strategies (surface, delta, Carter), weight cancellation, tallies, plotting, OpenMP/MPI parallelism.

##### High-Level Architectural Components
- CLI & Configuration Layer
- “abeille” executable (main.cpp)
- YAML Input File & Parser (utils/parser, yaml-cpp)
- Core Data Models
- Geometry Module (include/geometry, surfaces, lattices, universes)
- Materials Module (include/materials, nuclides, cross sections)
- Source Module (include/source, spatial/energy/direction distributions)
- Simulation Engine
- Simulation Orchestrator (simulation/simulation.hpp & .cpp)
- Particle Mover & Tracker (particle_mover, transport_operators: surface, delta, Carter)
- Collision Operators (branching, fission, noise variants, cancellation strategies in cancelator)
- Tally & Output
- Tallies (include/tallies: filters & estimators)
- Output (.npy via ndarray, GUI/text plotters)
- Plotting Module (include/plotting: slice, pixel, GUI)
- Utilities & Infrastructure
- RNG & PCG (utils/rng, pcg)
- MPI & OpenMP (utils/mpi + compiler flags)
- Settings, error handling, timers, logging, majorant calculations
- Build & External Dependencies
- CMake-based build (CMakeLists.txt, vendor downloads: papillon-ndl, yaml-cpp, docopt, ndarray, ImApp)
- Python scripts for preprocessing (abeille.py, input file generators)

##### Relationships and Data Flow
- The user invokes the CLI with a YAML file
→ Parser reads settings, geometry, materials, source specs
→ Core Data Models instantiated in memory
→ Simulation Orchestrator selects tracking strategy (strategy pattern)
→ Particle Mover loops over particles: invokes Transport Operator → Collision Operator → optionally Cancellation Module → updates tallies
→ When simulation completes, Tally Module aggregates results and writes .npy files
→ Optional Plotter reads mesh outputs and produces geometry or result visualizations
→ Logs, timers and statistics emitted via Utils

##### Architectural Patterns and Principles
- Modular design: each functional area is its own namespace/module (geometry, materials, source, simulation, tally, plotting, utils).
- Strategy pattern for tracking algorithms (surface, delta, Carter).
- Policy-based design for collision operators and cancellation techniques.
- Separation of concerns: parsing, data modeling, simulation logic, I/O, and visualization are decoupled.
- Parallelism layers: shared-memory (OpenMP) intrinsics in inner loops and optional distributed-memory (MPI) in utils/mpi.

- Clear labels for each module (e.g., “Geometry Module”, “Collision Operators”).
- Core simulation (blue rectangles)
- External libs & build (gray).

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "I/O & Configuration Layer"
        Yaml["YAML Input File"]:::io
        PythonCLI["Python CLI Wrapper"]:::io
        CliExe["abeille Executable"]:::data
        ParserLib["YAML Input Parser"]:::data
    end

    subgraph "Core Data Models"
        Geometry["Geometry Module"]:::data
        Materials["Materials Module"]:::data
        Source["Source Module"]:::data
    end

    subgraph "Simulation Engine"
        Orchestrator["Simulation Orchestrator"]:::core
        Mover["Particle Mover"]:::core
        subgraph "Particle Tracking Strategies"
            Surface["Surface Tracker"]:::core
            Delta["Delta Tracker"]:::core
            Carter["Carter Tracker"]:::core
            Implicit["Implicit Leakage Delta Tracker"]:::core
        end
        subgraph "Collision Operators & Cancellation"
            CollOps["Collision Operators"]:::core
            Cancelator["Cancelator Policies"]:::core
        end
    end

    subgraph "Tally & Output"
        Tallies["Tallies & Filters"]:::core
        OutputDS[".npy Output"]:::io
        Plotting["Plotting Module"]:::core
    end

    subgraph "Utilities & Infrastructure"
        RNG["RNG & PCG"]:::data
        MPI["MPI & OpenMP"]:::data
        UtilsSettings["Settings & Logging & Timers"]:::data
        Majorant["Majorant Calculations"]:::data
    end

    subgraph "Build & External Deps"
        CMake["CMake Build Scripts"]:::ext
        Vendor["Vendor Libraries"]:::ext
        Docs["Documentation"]:::ext
        PythonPre["Preprocessing Scripts"]:::io
    end

    Yaml --> ParserLib
    PythonCLI --> CliExe
    CliExe --> ParserLib
    ParserLib --> Geometry
    ParserLib --> Materials
    ParserLib --> Source

    Geometry --> Orchestrator
    Materials --> Orchestrator
    Source --> Orchestrator

    Orchestrator --> Mover
    Mover --> Surface
    Mover --> Delta
    Mover --> Carter
    Mover --> Implicit

    Surface --> CollOps
    Delta --> CollOps
    Carter --> CollOps
    Implicit --> CollOps

    CollOps --> Cancelator
    Cancelator --> Tallies
    CollOps --> Tallies

    Tallies --> OutputDS
    OutputDS --> Plotting

    Orchestrator --> UtilsSettings
    Orchestrator --> RNG
    Orchestrator --> MPI
    Orchestrator --> Majorant

    CMake --> CliExe
    Vendor --> ParserLib
    Vendor --> Geometry
    Vendor --> Materials
    Vendor --> OutputDS
    Docs --> CliExe
    PythonPre --> ParserLib

    classDef core fill:#ADD8E6,stroke:#000
    classDef data fill:#90EE90,stroke:#000
    classDef io fill:#FFD700,stroke:#000
    classDef ext fill:#D3D3D3,stroke:#000

    click CliExe "https://github.com/2018uch0002/abeille/blob/develop/src/main.cpp"
    click ParserLib "https://github.com/2018uch0002/abeille/blob/develop/include/utils/parser.hpp"
    click PythonCLI "https://github.com/2018uch0002/abeille/blob/develop/abeille.py"
    click Geometry "https://github.com/2018uch0002/abeille/tree/develop/include/geometry/"
    click Materials "https://github.com/2018uch0002/abeille/tree/develop/include/materials/"
    click Source "https://github.com/2018uch0002/abeille/tree/develop/include/source/"
    click Orchestrator "https://github.com/2018uch0002/abeille/blob/develop/include/simulation/simulation.hpp"
    click Mover "https://github.com/2018uch0002/abeille/blob/develop/include/simulation/particle_mover.hpp"
    click Surface "https://github.com/2018uch0002/abeille/blob/develop/include/simulation/transport_operators/surface_tracker.hpp"
    click Delta "https://github.com/2018uch0002/abeille/blob/develop/include/simulation/transport_operators/delta_tracker.hpp"
    click Carter "https://github.com/2018uch0002/abeille/blob/develop/include/simulation/transport_operators/carter_tracker.hpp"
    click Implicit "https://github.com/2018uch0002/abeille/blob/develop/include/simulation/transport_operators/implicit_leakage_delta_tracker.hpp"
    click CollOps "https://github.com/2018uch0002/abeille/tree/develop/include/simulation/collision_operators/"
    click Cancelator "https://github.com/2018uch0002/abeille/tree/develop/include/cancelator/"
    click Tallies "https://github.com/2018uch0002/abeille/tree/develop/include/tallies/"
    click OutputDS "https://github.com/2018uch0002/abeille/blob/develop/include/utils/output.hpp"
    click Plotting "https://github.com/2018uch0002/abeille/tree/develop/include/plotting/"
    click RNG "https://github.com/2018uch0002/abeille/blob/develop/include/utils/rng.hpp"
    click MPI "https://github.com/2018uch0002/abeille/blob/develop/include/utils/mpi.hpp"
    click UtilsSettings "https://github.com/2018uch0002/abeille/blob/develop/include/utils/settings.hpp"
    click Majorant "https://github.com/2018uch0002/abeille/blob/develop/include/utils/majorant.hpp"
    click CMake "https://github.com/2018uch0002/abeille/blob/develop/CMakeLists.txt"
    click Vendor "https://github.com/2018uch0002/abeille/tree/develop/vendor/"
    click Docs "https://github.com/2018uch0002/abeille/tree/develop/docs/"
    click PythonPre "https://github.com/2018uch0002/abeille/blob/develop/mcnp_to_abeille_xsdir.py"
```
