# cselab/odil architecture

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

- Interactive diagram: https://gitdiagram.com/cselab/odil
- Repository: https://github.com/cselab/odil

## Overview

##### Main project components
- Core Engine: Represented by modules such as core.py, core_min.py, optimizer.py, runtime.py, and linsolver.py. These are responsible for problem formulation (discrete loss), optimization methods (gradient-based optimizers like Adam, L-BFGS, and Newton’s method), and solving the PDEs.
- Utility and I/O: Modules like io.py, cache.py, util.py, and history.py support workflow operations. They handle file input/output, result caching, logging of history, and general utilities.
- Visualization: Plotting modules (plot.py, plotutil.py, and the provided mplstyle file) indicate built-in data/field visualization for debugging and interpreting results.
- Examples/Demo Applications: The multiple examples directories (basic, heat, heat_tmax, infer_constant, poisson, velocity_from_tracer, wave) serve as concrete use cases and demos. They show how the framework is applied to different PDE cases.
- Testing: The tests directory shows unit tests and integration tests that ensure correct functionality.

##### Relationships and interactions between components
- Data Flow: Input PDE models, boundary conditions, and discretization data are fed into the core engine. These components then call the backend for automatic differentiation and numerical evaluations.
- Optimization Loop: The core modules interact with the optimizer and linear solver to iteratively minimize the loss function while updating system state.
- I/O and Logging: Data throughout the optimization iterations are managed by the I/O utilities and logger/history modules, with results possibly sent to the visualization modules.
- External Integration: Clearly mark the dependency on external libraries (TensorFlow/JAX) that provide the automatic differentiation engine, and note optional GPU support via CUDA_VISIBLE_DEVICES configurations.
- Demo and Test Bifurcation: Show that the framework’s modular design permits separate demo applications (in the examples directory) and a suite of tests (in tests).

##### Architectural patterns and design principles
- Modular Design: Each major functionality (core computations, optimizers, plotting, and I/O) is encapsulated in its own module, making the system easy to extend.
- Abstraction of Backends: The “backend” module abstracts the automatic differentiation engine, allowing seamless switching between frameworks like TensorFlow and JAX.
- Separation of Concerns: The examples act as isolated demonstrations that interact with, but are separated from, the core mechanics. This illustrates a clear separation between library functionality and application/demonstration code.
- Reusability and Extensibility: The framework is designed for solving a class of optimization problems with PDEs, making it reusable across different domains.

##### Relevant technologies, frameworks, or libraries
- Python (the main language)
- TensorFlow / JAX (for automatic differentiation)
- Standard plotting libraries (e.g., Matplotlib inferred from the mplstyle)
- C++ with autodiff and Emscripten for interactive web demos (as noted in the README demos)

##### Final Assembly
- Modular interactions to capture how the framework is both extendible and testable.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Input
    PDE["Input PDE Models"]:::external

    %% ODIL Framework Container
    subgraph "ODIL Framework"
        
        %% Core Engine Subgraph
        subgraph "Core Engine"
            Core1["core.py"]:::core
            Core2["core_min.py"]:::core
            Core3["optimizer.py"]:::core
            Core4["runtime.py"]:::core
            Core5["linsolver.py"]:::core
        end

        %% Backend & Automatic Differentiation
        subgraph "Backend (TensorFlow/JAX)"
            Backend["backend.py"]:::backend
        end

        %% Utility and I/O
        subgraph "Utility & I/O"
            IO1["io.py"]:::io
            IO2["cache.py"]:::io
            IO3["util.py"]:::io
            IO4["history.py"]:::io
        end

        %% Visualization
        subgraph "Visualization"
            Viz1["plot.py"]:::viz
            Viz2["plotutil.py"]:::viz
            Viz3["mplstyle"]:::viz
        end

        %% Examples/Demo Applications
        subgraph "Examples/Demo Apps"
            Ex1["basic"]:::examples
            Ex2["heat"]:::examples
            Ex3["heat_tmax"]:::examples
            Ex4["infer_constant"]:::examples
            Ex5["poisson"]:::examples
            Ex6["velocity_from_tracer"]:::examples
            Ex7["wave"]:::examples
        end

        %% Testing
        Test["Tests"]:::tests
    end

    %% Connections
    PDE -->|"data"| Core1
    Core1 -->|"callsAD"| Backend
    Core1 -->|"I/O_log"| IO1
    IO1 -->|"results"| Viz1
    Ex1 -->|"demo_usage"| Core1
    Test -->|"verify"| Core1

    %% Styles
    classDef core fill:#ffe6b3,stroke:#ff9933,stroke-width:2px;
    classDef backend fill:#e6ffe6,stroke:#33cc33,stroke-width:2px;
    classDef io fill:#e6f7ff,stroke:#3399ff,stroke-width:2px;
    classDef viz fill:#f9e6ff,stroke:#cc33ff,stroke-width:2px;
    classDef examples fill:#f0e68c,stroke:#b8860b,stroke-width:2px;
    classDef tests fill:#ffcccc,stroke:#ff6666,stroke-width:2px;
    classDef external fill:#d3d3d3,stroke:#696969,stroke-width:2px;

    %% Click Events for Core Engine modules
    click Core1 "https://github.com/cselab/odil/blob/main/src/odil/core.py"
    click Core2 "https://github.com/cselab/odil/blob/main/src/odil/core_min.py"
    click Core3 "https://github.com/cselab/odil/blob/main/src/odil/optimizer.py"
    click Core4 "https://github.com/cselab/odil/blob/main/src/odil/runtime.py"
    click Core5 "https://github.com/cselab/odil/blob/main/src/odil/linsolver.py"

    %% Click Event for Backend
    click Backend "https://github.com/cselab/odil/blob/main/src/odil/backend.py"

    %% Click Events for Utility & I/O modules
    click IO1 "https://github.com/cselab/odil/blob/main/src/odil/io.py"
    click IO2 "https://github.com/cselab/odil/blob/main/src/odil/cache.py"
    click IO3 "https://github.com/cselab/odil/blob/main/src/odil/util.py"
    click IO4 "https://github.com/cselab/odil/blob/main/src/odil/history.py"

    %% Click Events for Visualization modules
    click Viz1 "https://github.com/cselab/odil/blob/main/src/odil/plot.py"
    click Viz2 "https://github.com/cselab/odil/blob/main/src/odil/plotutil.py"
    click Viz3 "https://github.com/cselab/odil/blob/main/src/odil/odil.mplstyle"

    %% Click Events for Examples/Demo Applications
    click Ex1 "https://github.com/cselab/odil/tree/main/examples/basic"
    click Ex2 "https://github.com/cselab/odil/tree/main/examples/heat"
    click Ex3 "https://github.com/cselab/odil/tree/main/examples/heat_tmax"
    click Ex4 "https://github.com/cselab/odil/tree/main/examples/infer_constant"
    click Ex5 "https://github.com/cselab/odil/tree/main/examples/poisson"
    click Ex6 "https://github.com/cselab/odil/tree/main/examples/velocity_from_tracer"
    click Ex7 "https://github.com/cselab/odil/tree/main/examples/wave"

    %% Click Event for Testing
    click Test "https://github.com/cselab/odil/tree/main/tests"
```
