# plaid-lib/plaid architecture

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

- Interactive diagram: https://gitdiagram.com/plaid-lib/plaid
- Repository: https://github.com/plaid-lib/plaid

## Overview

##### Project type and purpose
- PLAID is a Python library (package) providing a datamodel and workflows for machine‐learning on physics simulation data. It is not a full‐stack web app but a domain‐specific library with core modules, data adapters (“bridges”), container objects, problem definitions, post‐processing, utilities, and type definitions.

a. Core Package (src/plaid)
- constants.py – shared configuration values
- types/ – data type definitions (CGNS types, common types)
- containers/ – Dataset and Sample containers, plus utility methods
- problem_definition.py – problem metadata and splitting rules
- bridges/ – adapters for external frameworks (e.g. Huggingface)
- post/ – post‐processing modules (bisect, metrics)
- utils/ – supporting functions (IO helpers, interpolation, stats, split)
b. External Interfaces
- File System I/O (CGNS mesh files, CSV scalar data, YAML/JSON configs)
- External ML frameworks (Huggingface via huggingface_bridge)
- Muscat (optional dependency for advanced sampling)
c. Examples & Tests
- examples/ – demonstration scripts invoking the core package
- tests/ – unit tests organized by module, verifying end‐to‐end flows

##### Relationships and data flow
a. User code → bridges → containers (loading data)
b. containers → problem_definition (defining train/test splits and problem metadata)
c. containers + problem_definition → model training/inference (outside PLAID)
d. model outputs (predictions) → post modules → metrics and bisect analyses
e. utils and types are supporting layers: all modules import from utils and types

##### Architectural patterns and design principles
- Modular package structure with clear separation of concerns
- Adapters (“bridges”) encapsulate external dependencies
- Immutable data containers for Dataset and Sample
- Config‐driven workflows (environment.yml, pyproject.toml, JSON/YAML in benchmarks and examples)

##### Final recommendations
- Be precise: capture all six core subpackages under src/plaid
- External dependencies (Huggingface, Muscat) even if optional
- CI/Test and docs workflows optionally as side notes

## Diagram (Mermaid)

```mermaid
flowchart TB
    Title["PLAID Library Architecture\nv1.0\n2024-06-01"]:::title

    %% External Systems
    subgraph "External Systems" 
        direction TB
        FS["File System I/O\n(CGNS, CSV, JSON/YAML)"]:::external
        HF["Huggingface Framework"]:::external
        MS["Muscat (optional)"]:::external
    end

    %% Core Modules
    subgraph "Core Package (src/plaid)" 
        direction TB
        CONST["constants.py\n(shared config)"]:::core
        TYPES["types/\n(data type definitions)"]:::util
        CONTS["containers/\nDataset & Sample objects"]:::core
        PROB["problem_definition.py\n(problem metadata)"]:::core
        BRIDGES["bridges/\nadapters for external"]:::adapter
        POST["post/\nmetrics & bisect"]:::core
        UTILS["utils/\nsupporting functions"]:::util
    end

    %% Examples & Tests
    subgraph "Examples & Tests" 
        direction TB
        EX["examples/"]:::example
        TST["tests/"]:::example
    end

    %% External Data Flow
    FS -->|loads data| BRIDGES -->|provides data| CONTS
    HF -->|via bridge| BRIDGES
    MS -->|via bridge| BRIDGES

    %% Core Flow
    CONTS -->|defines splits| PROB
    CONTS -->|feeds external| EXT_MODEL["Model Training/\nInference (outside PLAID)"]:::external
    PROB -->|feeds external| EXT_MODEL
    EXT_MODEL -->|predictions| POST
    POST -->|reports| OUTPUTS["Outputs/Reports"]:::external

    %% Utility Dependencies (dashed)
    CONST ---|imports| UTILS
    CONST ---|imports| TYPES
    CONTS ---|imports| UTILS
    CONTS ---|imports| TYPES
    PROB ---|imports| UTILS
    PROB ---|imports| TYPES
    BRIDGES ---|imports| UTILS
    BRIDGES ---|imports| TYPES
    POST ---|imports| UTILS
    POST ---|imports| TYPES

    %% Context
    EX --> CONST
    EX --> CONTS
    EX --> PROB
    EX --> POST
    EX --> UTILS
    TST --> CONST
    TST --> CONTS
    TST --> PROB
    TST --> POST
    TST --> UTILS

    %% Legend
    subgraph "Legend"
        direction TB
        L1["■ Core Modules"]:::core
        L2["■ Adapters/Bridges"]:::adapter
        L3["■ Utilities/Types"]:::util
        L4["■ External Systems"]:::external
        L5["─ Solid arrow: Data flow"]
        L6["--- Dashed arrow: Dependency"]
    end

    %% Click Events
    click CONST "https://github.com/plaid-lib/plaid/blob/main/src/plaid/constants.py"
    click TYPES "https://github.com/plaid-lib/plaid/tree/main/src/plaid/types"
    click CONTS "https://github.com/plaid-lib/plaid/tree/main/src/plaid/containers"
    click PROB "https://github.com/plaid-lib/plaid/blob/main/src/plaid/problem_definition.py"
    click BRIDGES "https://github.com/plaid-lib/plaid/tree/main/src/plaid/bridges"
    click POST "https://github.com/plaid-lib/plaid/tree/main/src/plaid/post"
    click UTILS "https://github.com/plaid-lib/plaid/tree/main/src/plaid/utils"
    click EX "https://github.com/plaid-lib/plaid/tree/main/examples"
    click TST "https://github.com/plaid-lib/plaid/tree/main/tests"

    %% Styles
    classDef core fill:#cce5ff,stroke:#004085,color:#004085;
    classDef adapter fill:#d4edda,stroke:#155724,color:#155724;
    classDef util fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
    classDef external fill:#fff3cd,stroke:#856404,color:#856404;
    classDef example fill:#f8f9fa,stroke:#6c757d,color:#6c757d,stroke-dasharray: 2 2;
    classDef title fill:#ffffff,stroke:none,color:#000000,font-weight:bold,font-size:18px;
```
