# gridoptics/gridpack architecture

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

- Interactive diagram: https://gitdiagram.com/gridoptics/gridpack
- Repository: https://github.com/gridoptics/gridpack

## Overview

##### And highlight the main components
- HPC Core & Framework: Since GridPACK is built for distributed (parallel) computing, include a core block representing the “core simulation engine” which incorporates many of the distributed computing utilities. This includes components under directories like “src/parallel,” “src/math/petsc,” and “src/utilities.”
- Simulation & Analysis Modules: Show separate subcomponents for simulation applications (found in “src/applications” and “src/modules”). Within these, note modules for AC power flow, dynamic simulation, contingency analysis, state estimation, and others. It is also useful to indicate the building blocks (e.g., bus/branch models, network partitioning, mapping) often used to develop these simulations.
- Mathematical & Solver Libraries: Represent the math libraries and solver implementations, including the linear and nonlinear solvers implemented in “src/math” and interfaced with PETSc. This is the computational workhorse responsible for executing the numerical simulation.
- Data Input/Output & Parsing: Include the I/O and parser components (found in “src/parser,” “src/serial_io,” “src/export”) which handle reading grid data from various formats (e.g., PSSE, PTI formats) and streaming simulation results.
- Infrastructure & Configuration: Components in “src/configuration,” “src/factory,” “src/mapper,” “src/network,” and “src/partition” should be identified as essential parts of the framework that handle graph partitioning, network mapping, factory methods for module instantiation, and overall configuration management.
- Documentation & Examples: Although not part of runtime, note that extensive docs (in “docs”) and examples (in “src/applications/examples” and “python/src/example”) help understand and demonstrate GridPACK’s usage.

##### Interactions and relationships between components
- The core simulation engine must interface with solver libraries to process the equations arising from the grid network.
- Data flows from input modules (parsers and file I/O) into network creation and partitioning (via “src/partition” and “src/mapper”) before being fed into the simulation modules.
- Simulation applications (or “apps”) leverage building blocks from the “modules” directory to compute the simulation’s results, which are then exported through I/O and visualization components.
- The python wrappers serve as a high-level interface layer calling into the C++ backend, allowing for scripting of simulation setups and analyses.

##### Architectural patterns and design principles
- Modular and Layered: The project’s structure is very modular – separating concerns among data input, computational core (solvers and math libraries), and application-level simulations.
- Extensible Framework: GridPACK is designed as a framework with clearly identifiable building blocks (e.g., component factories, configuration modules) so that developers can plug in new components without reworking the entire system.
- Parallel and Distributed Processing: With dedicated directories (e.g., “src/parallel,” “src/partition”), the design emphasizes efficient distributed computing typical in HPC frameworks.

##### Relevant tools and technologies
- C++ (core engine) with extensive use of HPC libraries like PETSc.
- Python wrappers, which enable a high-level interface.
- Build and configuration tools (CMake is used extensively as seen in many CMakeLists.txt files).
- External libraries (Boost, Doxygen for documentation, and other numerical libraries as referenced in “docs/markdown/required”).

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% Data I/O & Parsing Layer
    subgraph "Data I/O & Parsing"
        DP["Data Parsers"]:::io
        SI["Serial I/O"]:::io
        ER["Export Routines"]:::io
    end

    %% Infrastructure & Configuration Layer
    subgraph "Infrastructure & Configuration"
        CM["Configuration Management"]:::infra
        MF["Module Factory"]:::infra
        NM["Network Mapping"]:::infra
        NT["Network Topology"]:::infra
        GP["Graph Partitioning"]:::infra
    end

    %% HPC Core & Framework Layer
    subgraph "HPC Core & Framework"
        CSE["Core Simulation Engine"]:::core
        PMI["PETSc Math Infrastructure"]:::core
        GU["General Utilities"]:::core
    end

    %% Mathematical & Solver Libraries Layer
    subgraph "Mathematical & Solver Libraries"
        MSL["Math & Solver Libraries"]:::solver
        PSI["PETSc Solver Implementations"]:::solver
    end

    %% Simulation & Analysis Modules Layer
    subgraph "Simulation & Analysis Modules"
        SA["Simulation Applications"]:::sim
        SBM["Simulation Modules & Building Blocks"]:::sim
    end

    %% Python Wrappers & Interfaces Layer
    subgraph "Python Wrappers & Interfaces"
        PY["Python Interface"]:::python
    end

    %% Documentation & Examples Layer
    subgraph "Documentation & Examples"
        DG["Documentation & Guides"]:::doc
        EA["Example Applications"]:::doc
        PE["Python Examples"]:::doc
    end

    %% Connections from Data I/O to Infrastructure
    DP -->|"parsed_data"| NM
    SI -->|"raw_data"| GP

    %% Infrastructure to HPC Core
    CM --> CSE
    MF --> CSE
    NM --> CSE
    NT --> CSE
    GP --> CSE

    %% Internal HPC Core dependencies (internal aggregation)
    PMI --> CSE
    GU --> CSE

    %% HPC Core to Mathematical & Solver Libraries and Simulation Modules
    CSE -->|"computes"| MSL
    CSE -->|"feeds"| SA

    %% Mathematical & Solver Libraries internal flow
    PSI --> MSL
    MSL -->|"supports"| SA

    %% Simulation Applications exporting results
    SA -->|"results"| ER

    %% Python Interface interacting with core and simulation
    PY --> CSE
    PY --> SA

    %% Documentation links (non-runtime, informational)
    SA --> DG
    SA --> EA
    PY --> PE

    %% Styles
    classDef io fill:#ffdead,stroke:#d2691e,stroke-width:2px;
    classDef infra fill:#98fb98,stroke:#228b22,stroke-width:2px;
    classDef core fill:#add8e6,stroke:#1e90ff,stroke-width:2px;
    classDef solver fill:#d3d3d3,stroke:#696969,stroke-width:2px;
    classDef sim fill:#ffb6c1,stroke:#ff69b4,stroke-width:2px;
    classDef python fill:#dda0dd,stroke:#9932cc,stroke-width:2px;
    classDef doc fill:#fffacd,stroke:#ffd700,stroke-width:2px;

    %% Click Events
    click CSE "https://github.com/gridoptics/gridpack/tree/develop/src/parallel"
    click PMI "https://github.com/gridoptics/gridpack/tree/develop/src/math/petsc"
    click GU "https://github.com/gridoptics/gridpack/tree/develop/src/utilities"
    click SA "https://github.com/gridoptics/gridpack/tree/develop/src/applications"
    click SBM "https://github.com/gridoptics/gridpack/tree/develop/src/applications/modules"
    click MSL "https://github.com/gridoptics/gridpack/tree/develop/src/math"
    click DP "https://github.com/gridoptics/gridpack/tree/develop/src/parser"
    click SI "https://github.com/gridoptics/gridpack/tree/develop/src/serial_io"
    click ER "https://github.com/gridoptics/gridpack/tree/develop/src/export"
    click PY "https://github.com/gridoptics/gridpack/tree/develop/python"
    click CM "https://github.com/gridoptics/gridpack/tree/develop/src/configuration"
    click MF "https://github.com/gridoptics/gridpack/tree/develop/src/factory"
    click NM "https://github.com/gridoptics/gridpack/tree/develop/src/mapper"
    click NT "https://github.com/gridoptics/gridpack/tree/develop/src/network"
    click GP "https://github.com/gridoptics/gridpack/tree/develop/src/partition"
    click DG "https://github.com/gridoptics/gridpack/tree/develop/docs"
    click EA "https://github.com/gridoptics/gridpack/tree/develop/src/applications/examples"
    click PE "https://github.com/gridoptics/gridpack/tree/develop/python/src/example"
```
