# pmeal/openpnm architecture

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

- Interactive diagram: https://gitdiagram.com/pmeal/openpnm
- Repository: https://github.com/pmeal/openpnm

## Overview

##### Project Type and Purpose
- Project Type: A domain-specific simulation framework for porous materials that provides a collection of algorithms, models, and tools to perform pore network modeling.
- Purpose: To offer researchers and developers a comprehensive toolkit for simulating transport phenomena and other physical processes in porous media, with support for various geometrical, network, phase, and physics models.

##### Breakdown of the Main Components
- Core Library (OpenPNM Package):
– This is the heart of the system, located primarily in the “openpnm” directory.
– It contains numerous submodules such as:
▪ Core: (e.g., openpnm/core) base classes and mixins that form the foundation.
▪ Models: (e.g., openpnm/models) which is further subdivided into domain-specific areas like geometry, network, phase, and physics.
▪ Algorithms: (e.g., openpnm/algorithms) that implement simulation techniques (advection-diffusion, drainage, transport, etc.).
▪ IO: (e.g., openpnm/io) handling file import/export for multiple formats.
▪ Network: (e.g., openpnm/network) dealing with the generation and manipulation of pore network structures.
▪ Solvers: (e.g., openpnm/solvers) providing integrations with different numerical libraries.
▪ Integrators, Visualization, and Util modules: (e.g., openpnm/integrators, openpnm/visualization, openpnm/utils) for additional functionality like integration with SciPy and plotting.
- Additional Frameworks/Extensions:
– Beta and Contrib directories: These hint at experimental features or extension modules that may be evolving.
- Examples and Tutorials:
– The “examples” folder offers multiple Jupyter notebooks and scripts that demonstrate how the framework is used in real-world scenarios—from basic tutorials to advanced simulation case studies.
- Tests and Validation:
– The “tests” directory, with its unit and integration testing suites, underscores the framework’s emphasis on reliability and reproducibility.
- Documentation:
– The “docs” directory holds configuration files, templates, and examples that help generate the online documentation.
- CI/CD and Developer Tools:
– The .github directory and related workflow scripts (e.g., for version bumps, style checks, and tests) illustrate the mature development process supporting continuous integration.

##### Detailing Relationships and Interactions
– Link the “Models” submodule to “Algorithms” since simulation methods directly use geometrical and physical models.
– Represent “IO” as a data gateway for both importing experimental/test data and exporting simulation results.
– Show “Solvers” as dependent on external numerical libraries (e.g., SciPy, pypardiso) and connecting to “Algorithms” to execute computations.
- Data Flow and Dependencies:
– Illustrate that the “Core” provides common functionality and settings (found in modules like openpnm/utils/_settings.py) supporting all operations.
- Developer Support and Testing:
– Include components for “Tests,” “Docs,” and “CI Pipelines,” which ensure quality and documentation.

##### Emphasizing Architectural Patterns and Design Principles
- Modular Design: The clear separation into domains (models, algorithms, IO, etc.) underscores a modular strategy where each component is interchangeable and testable.
- Extensibility: Modules like “beta” and “contrib” hint at designed extension points where new features or models can be integrated.
- Test-Driven and CI/CD Practices: The extensive tests and GitHub workflows indicate that robustness and continuous integration are architectural priorities.

## Diagram (Mermaid)

```mermaid
graph TD
    PKG["OpenPNM Core Library"]:::core_lib

    subgraph "OpenPNM Core Library Components"
        CORE["Core Module"]:::core
        UTILITIES["Utilities Module"]:::utilities
        MODELS["Models Module"]:::models
        ALGORITHMS["Algorithms Module"]:::algorithms
        IO["IO Module"]:::io
        NETWORK["Network Module"]:::network
        SOLVERS["Solvers Module"]:::solvers
        INTEGRATORS["Integrators Module"]:::integrators
        VISUALIZATION["Visualization Module"]:::visualization
        BETA["Beta/Experimental Features"]:::beta
        CONTRIB["Contrib/Extension Modules"]:::contrib
    end

    subgraph "Developer Support"
        DOC["Documentation"]:::dev
        TEST["Testing Suite"]:::dev
        CI["CI/CD and Developer Tools"]:::dev
    end

    subgraph "User Examples"
        EX["Examples and Tutorials"]:::example
    end

    %% Relationships within OpenPNM Core Library
    PKG --> CORE
    CORE --> UTILITIES
    IO -->|"InputData"| MODELS
    MODELS -->|"ModelsUsed"| ALGORITHMS
    NETWORK -->|"NetworkData"| ALGORITHMS
    IO -->|"NetworkImport"| NETWORK
    ALGORITHMS -->|"Compute"| SOLVERS
    ALGORITHMS -->|"Integrate"| INTEGRATORS
    ALGORITHMS -->|"Results"| VISUALIZATION
    CORE -->|"Supports"| MODELS
    CORE -->|"Supports"| ALGORITHMS
    CORE -->|"Supports"| IO

    %% Interactions with Developer Support and Examples
    DOC -->|"Guides"| EX
    TEST -->|"Verifies"| CORE
    CI -->|"Automates"| TEST

    %% Click Events
    click PKG "https://github.com/pmeal/openpnm/tree/dev/openpnm/"
    click CORE "https://github.com/pmeal/openpnm/tree/dev/openpnm/core/"
    click MODELS "https://github.com/pmeal/openpnm/tree/dev/openpnm/models/"
    click ALGORITHMS "https://github.com/pmeal/openpnm/tree/dev/openpnm/algorithms/"
    click IO "https://github.com/pmeal/openpnm/tree/dev/openpnm/io/"
    click NETWORK "https://github.com/pmeal/openpnm/tree/dev/openpnm/network/"
    click SOLVERS "https://github.com/pmeal/openpnm/tree/dev/openpnm/solvers/"
    click INTEGRATORS "https://github.com/pmeal/openpnm/tree/dev/openpnm/integrators/"
    click VISUALIZATION "https://github.com/pmeal/openpnm/tree/dev/openpnm/visualization/"
    click UTILITIES "https://github.com/pmeal/openpnm/tree/dev/openpnm/utils/"
    click BETA "https://github.com/pmeal/openpnm/tree/dev/openpnm/beta/"
    click CONTRIB "https://github.com/pmeal/openpnm/tree/dev/openpnm/contrib/"
    click EX "https://github.com/pmeal/openpnm/tree/dev/examples/tutorials/"
    click DOC "https://github.com/pmeal/openpnm/tree/dev/docs/"
    click TEST "https://github.com/pmeal/openpnm/tree/dev/tests/"
    click CI "https://github.com/pmeal/openpnm/tree/dev/.github/"

    %% Styles
    classDef core_lib fill:#aqua,stroke:#333,stroke-width:2px;
    classDef core fill:#87CEFA,stroke:#333,stroke-width:2px;
    classDef models fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef algorithms fill:#6495ED,stroke:#333,stroke-width:2px;
    classDef io fill:#00CED1,stroke:#333,stroke-width:2px;
    classDef network fill:#40E0D0,stroke:#333,stroke-width:2px;
    classDef solvers fill:#20B2AA,stroke:#333,stroke-width:2px;
    classDef integrators fill:#5F9EA0,stroke:#333,stroke-width:2px;
    classDef visualization fill:#1E90FF,stroke:#333,stroke-width:2px;
    classDef utilities fill:#B0E0E6,stroke:#333,stroke-width:2px;
    classDef beta fill:#FFD700,stroke:#333,stroke-width:2px;
    classDef contrib fill:#FFA500,stroke:#333,stroke-width:2px;
    classDef dev fill:#98FB98,stroke:#333,stroke-width:2px;
    classDef example fill:#FFB6C1,stroke:#333,stroke-width:2px;
```
