# opm/opm-simulators architecture

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

- Interactive diagram: https://gitdiagram.com/opm/opm-simulators
- Repository: https://github.com/opm/opm-simulators

## Overview

##### Main Components Identification

The system should be divided into these major components:
- Flow Simulator Core
- Linear Solver System
- Models Framework
- Well Management System
- Time Stepping System
- Parallel Computing Infrastructure
- I/O Handling

##### Component Relationships

a) Core Layer (Center):
- Flow Simulator (BlackoilModel)
- Automatic Differentiation Engine
- Property System

b) Numerical Layer (Surrounding Core):
- Linear Solvers (ISTL-based)
- Preconditioners
- Time Stepping Controllers
- Convergence Handling

c) Physics Layer:
- Black Oil Model
- Compositional Models
- Well Models
- Aquifer Models

d) Infrastructure Layer (Outer):
- Parallel Computing Framework
- I/O Handlers
- Grid Management
- Restart Capability

##### Specific Implementation Details

- Rectangles: Main components
- Hexagons: Interfaces

##### Key Subsystems to Highlight

a) Simulator Core:
**BlackoilModel <-> AutoDiff Engine <-> Property System**
- ↕               ↕                    ↕
**Linear Solvers <-> Preconditioners <-> Time Stepping**

b) Well System:
**WellModel <-> WellState <-> WellControls**
- ↕            ↕             ↕
**Constraints <-> Equations <-> Properties**

c) Parallel Computing:
**MPI Layer <-> Load Balancing <-> Domain Decomposition**
- ↕              ↕                    ↕
**Data Exchange <-> Synchronization <-> Gathering**

##### Additional Elements

Important aspects:
- External dependencies (DUNE, MPI, etc.)
- File I/O formats (Eclipse format support)
- Configuration interfaces
- Logging and monitoring systems

##### Performance Critical Paths

- Linear solver iterations
- Well management
- Property calculations
- Parallel synchronization points

##### Version/Configuration Management

A section showing:
- Configuration management
- Runtime parameters
- Model selection
- Solver options

- Multiple layers
- Export to high-resolution formats
- Easy maintenance and updates

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph Core
        FS[Flow Simulator]:::core
        ADE[AutoDiff Engine]:::core
        PS[Property System]:::core
        
        FS <--> ADE
        ADE <--> PS
    end

    subgraph Numerical
        LS[Linear Solvers]:::numerical
        PC[Preconditioners]:::numerical
        TS[Time Stepping]:::numerical
        CH[Convergence Handling]:::numerical
        
        LS <--> PC
        PC <--> TS
        TS <--> CH
        CH <--> LS
    end

    subgraph Physics
        BOM[Black Oil Model]:::physics
        CM[Compositional Models]:::physics
        WM[Well Models]:::physics
        AM[Aquifer Models]:::physics
        
        BOM <--> CM
        CM <--> WM
        WM <--> AM
    end

    subgraph Infrastructure
        PCF[Parallel Computing]:::infra
        IO[I/O Handlers]:::infra
        GM[Grid Management]:::infra
        RC[Restart Capability]:::infra
        
        PCF <--> IO
        IO <--> GM
        GM <--> RC
    end

    %% Core Layer Connections
    Core <--> Numerical
    Core <--> Physics
    
    %% Numerical Layer Connections
    Numerical <--> Physics
    Numerical <--> Infrastructure
    
    %% Physics Layer Connections
    Physics <--> Infrastructure

    %% Critical Paths
    FS <==>|Critical Path| LS
    WM <==>|Critical Path| PCF
    PS <==>|Critical Path| BOM

    %% Styling
    classDef core fill:#3498db,stroke:#2980b9,stroke-width:2px
    classDef numerical fill:#e67e22,stroke:#d35400,stroke-width:2px
    classDef physics fill:#2ecc71,stroke:#27ae60,stroke-width:2px
    classDef infra fill:#9b59b6,stroke:#8e44ad,stroke-width:2px

    %% Click Events
    click FS "https://github.com/OPM/opm-simulators/blob/master/opm/models/blackoil/blackoilmodel.hh"
    click LS "https://github.com/OPM/opm-simulators/tree/master/opm/simulators/linalg"
    click WM "https://github.com/OPM/opm-simulators/blob/master/opm/simulators/wells/BlackoilWellModel.hpp"
    click TS "https://github.com/OPM/opm-simulators/blob/master/opm/simulators/timestepping/AdaptiveTimeStepping.hpp"
    click PCF "https://github.com/OPM/opm-simulators/blob/master/opm/simulators/linalg/ParallelIstlInformation.hpp"
    click IO "https://github.com/OPM/opm-simulators/blob/master/opm/models/io/baseoutputmodule.hh"
    click PS "https://github.com/OPM/opm-simulators/blob/master/opm/models/utils/propertysystem.hh"
    click Numerical "https://github.com/OPM/opm-simulators/tree/master/opm/models/discretization"
    click BOM "https://github.com/OPM/opm-simulators/blob/master/opm/models/blackoil/blackoilproperties.hh"
    click Physics "https://github.com/OPM/opm-simulators/tree/master/opm/models"

    %% Legend
    subgraph Legend
        L1[Core Components]:::core
        L2[Numerical Components]:::numerical
        L3[Physics Components]:::physics
        L4[Infrastructure Components]:::infra
    end
```
