# iaea-nds/endf-parserpy architecture

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

- Interactive diagram: https://gitdiagram.com/iaea-nds/endf-parserpy
- Repository: https://github.com/iaea-nds/endf-parserpy

## Overview

##### Project type and purpose
- This is an open-source Python toolkit (“endf-parserpy”) for reading, writing, validating, converting, and manipulating ENDF-6 nuclear data files. It exposes both a command-line interface (CLI) and a programmatic API. Internally it uses an interpreter for pure-Python parsing, a compiler layer to generate high-performance C++ parsers, and a factory pattern to select between implementations.

##### File structure
- Top-level:
- endf_parserpy/cli – CLI entry points (“compare”, “convert”, “validate”, etc.)
- endf_parserpy/interpreter – pure-Python parsing logic, mapping ENDF records to dictionaries
- endf_parserpy/compiler – code-generation engine that emits C++ parser/writer modules from high-level recipes
- endf_parserpy/cpp_parsers – hand-written and generated C++ sources, plus Python bindings
- endf_parserpy/endf_recipes – recipe definitions for each ENDF-6 section (MF/MT), driving both interpreter and compiler
- endf_parserpy/utils & compat_wrappers – helper util functions and back-compatibility shims
- setup.py / pyproject.toml – packaging and dependency configuration
- docs/ & tests/ – documentation and automated test suites

##### README for additional insights
- Confirms a dual-mode parser (Python & C++), a “ParserFactory” for instantiating either, and core use cases (read, modify, write, compare, etc.). The README mentions endf_parserpy.EndfParserFactory.create(), parser.parsefile(), parser.writefile().

##### Detail and essential elements
- Don’t just group everything under “library”: break out interpreter, compiler, recipes, utils
- Factory pattern, the two parsing paths (Python vs. C++), and how recipes feed both paths
- How code_generator_parsing & code_generator_writing produce C++ boilerplate and templates
- That adding a new ENDF-6 recipe is a straightforward plugin by dropping a module under endf_recipes/

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CLI Layer
    subgraph "CLI Layer"
        CLI["CLI Layer"]:::cli
    end

    %% API Layer
    subgraph "API Layer"
        PF["ParserFactory"]:::api
        BP["Base Parser Interface"]:::api
    end

    %% Core Library
    subgraph "Core Library"
        subgraph "Interpreter Module"
            IM["Interpreter"]:::core
        end
        subgraph "Compiler Module"
            CM["Compiler"]:::codegen
        end
        subgraph "Recipe Engine"
            RE["Recipe Engine"]:::core
        end
        subgraph "C++ Parser Module"
            CPP["C++ Parser Extension"]:::core
        end
        subgraph "Utilities"
            UT["Utilities"]:::core
        end
        subgraph "Compatibility Wrappers"
            CW["Compatibility Wrappers"]:::core
        end
    end

    %% Code Generation Pipeline
    CM -->|"generates C++ code"| CPP
    CM -->|"consumes recipes"| RE

    %% Interpreter Path
    PF -->|"selects Python parser"| IM
    IM -->|"uses recipes"| RE
    IM -->|"uses utilities"| UT
    IM -->|"uses compatibility"| CW

    %% C++ Path
    PF -->|"selects C++ parser"| CPP
    CPP -->|"uses recipes"| RE
    CPP -->|"uses utilities"| UT
    CPP -->|"uses compatibility"| CW

    %% CLI to API
    CLI -->|"invokes"| PF
    CLI -->|"invokes"| BP

    %% Support Infrastructure
    SPack["Packaging (setup.py, pyproject.toml)"]:::support
    SDocs["Documentation (docs/)"]:::support
    STests["Tests (tests/)"]:::support

    SPack -.-> CLI
    SPack -.-> PF
    SDocs -.-> CLI
    STests -.-> CLI
    STests -.-> PF

    %% Click Events
    click CLI "https://github.com/iaea-nds/endf-parserpy/tree/main/endf_parserpy/cli"
    click IM "https://github.com/iaea-nds/endf-parserpy/blob/main/endf_parserpy/interpreter/endf_parser.py"
    click CM "https://github.com/iaea-nds/endf-parserpy/blob/main/endf_parserpy/compiler/compiler.py"
    click CPP "https://github.com/iaea-nds/endf-parserpy/blob/main/endf_parserpy/cpp_parsers/endf6.cpp"
    click RE "https://github.com/iaea-nds/endf-parserpy/blob/main/endf_parserpy/endf_recipes/catalogue.py"
    click UT "https://github.com/iaea-nds/endf-parserpy/blob/main/endf_parserpy/utils/math_utils.py"
    click CW "https://github.com/iaea-nds/endf-parserpy/blob/main/endf_parserpy/compat_wrappers/import_resources_new.py"
    click PF "https://github.com/iaea-nds/endf-parserpy/blob/main/endf_parserpy/endf_parser_factory.py"
    click BP "https://github.com/iaea-nds/endf-parserpy/blob/main/endf_parserpy/endf_parser_base.py"
    click SPack "https://github.com/iaea-nds/endf-parserpy/blob/main/setup.py"
    click SDocs "https://github.com/iaea-nds/endf-parserpy/tree/main/docs/"
    click STests "https://github.com/iaea-nds/endf-parserpy/tree/main/tests/"

    %% Styles
    classDef cli fill:#f9e79f,stroke:#b7950b
    classDef api fill:#aed6f1,stroke:#2874a6
    classDef core fill:#d6eaf8,stroke:#2e86c1
    classDef codegen fill:#d5f5e3,stroke:#28b463
    classDef support fill:#fdebd0,stroke:#d68910
```
