# snktshrma272/phiflow architecture

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

- Interactive diagram: https://gitdiagram.com/snktshrma272/phiflow
- Repository: https://github.com/snktshrma272/phiflow

## Overview

##### Project Type and Purpose
- ΦFlow is an open-source, full-stack Python library that provides end-to-end differentiable simulations of PDEs (primarily fluid dynamics) for machine learning and optimization workflows.
- It wraps core physics & geometry abstractions in a backend-agnostic API and plugs into NumPy, Jax, TensorFlow or PyTorch for computation and automatic differentiation.
- It also ships optional visualization layers (console, Matplotlib, Dash web UI), demos, examples, docs and CI pipelines for testing and deployment.

##### High-Level File Structure & Architectural Patterns
- Top-Level Directories
– phi/                ← Core Python package
– PhiML/              ← Submodule providing typed-dimension tensor abstractions
– demos/, examples/   ← Usage scripts & Jupyter notebooks grouped by domain (grids, mesh, particles, optim)
– docs/               ← Tutorials, API docs, specification, troubleshooting
– tests/              ← Unit tests (commit vs. release), CI scripts in .github/workflows
– setup.py, setup.cfg ← Packaging, dependencies, entry points
- Core Package Layout (phi/)
– field/     ← Field abstractions: grids, masks, resampling, I/O
– geom/      ← Geometric primitives and signed distance fields
– physics/   ← PDE operators: advect, diffuse, sph, fluid solvers
– math/      ← Backend-agnostic math utilities, extrapolation, backends switch
– flow.py    ← High-level simulation flows orchestration
– {jax, tf, torch}/
- flow.py ← Bindings of flow.py to Jax/TensorFlow/PyTorch compute graphs
- nets.py ← Neural network layers and integration points
– vis/       ← Visualization layers:
- _console   ← Terminal UI (text/ASCII plots)
- _matplotlib← Static plotting
- _dash      ← Interactive web UI (Dash + Plotly)
- Architectural Patterns
– Plugin architecture for backends: a single core API delegates compute to the active backend module (NumPy, Jax, TF or PyTorch).
– Layered separation of concerns:
- Core abstractions (fields, geometry, physics)
- Backend adapters (compute + autodiff)
- Visualization adapters
– Object-oriented, vectorized design enabling dimensional agnosticism and reuse.
– CI/CD via GitHub Actions, coverage reports, and submodule management.

##### Key Components & Interactions
a. Core API Layer (phi)
– Field Manager, Geometry Engine, Physics Solvers, Flow Orchestrator
b. Backend Adapter Layer
– NumPy (default), Jax Adapter, TensorFlow Adapter, PyTorch Adapter
– Each adapter exposes: tensor operations, autodiff, GPU acceleration
c. Visualization Layer
– Console UI ←→ Core (polls simulation state)
– Matplotlib ←→ Core (snapshot plots)
– Dash Web UI ←→ Core (real-time interactive controls & plots)
d. Submodule & External Dependencies
– ΦML for typed tensors
– Third-party libraries: NumPy, Jax, TensorFlow, PyTorch, Dash, Plotly, Matplotlib
– CI: GitHub Actions, coverage, publishing to PyPI
e. User Code & Examples
– demos/ and examples/ import the Core API and optionally choose a backend and visualization
– README and docs drive installation & usage

Data/Control Flow
1. User script or notebook calls phi.Flow simulation API
2. Core orchestrator composes Field + Geometry + Physics operations
3. Computation is dispatched to the selected backend module
4. Resulting state is returned to user or streamed to visualization adapters
5. Visualization layer pulls data via callbacks or direct API calls
6. CI pipelines run tests, coverage, update docs

##### Detailed Elements
- Clear component names (phi.field, phi.geom, phi.physics, phi.flow, phi.jax.flow, etc.)
- Backend selection mechanism in core (e.g., backend backend.py)
- Visual distinction between synchronous (console/matplotlib) vs. asynchronous (Dash) visualization
- Escape hatch to CUDA custom ops compilation (Installation instructions)
- Test harness and CI workflows as side-bar demonstrating quality gate

## Diagram (Mermaid)

```mermaid
graph TB

    subgraph "User Code & Consumption"
        direction TB
        UserScript["User Script/Notebook"]:::consumer
        Demos["demos/"]:::consumer
        Examples["examples/"]:::consumer
        Docs["docs/"]:::consumer
    end

    subgraph "Core API"
        direction TB
        FieldManager["phi/field"]:::core
        GeomEngine["phi/geom"]:::core
        PhysicsSolvers["phi/physics"]:::core
        FlowOrchestrator["phi/flow.py"]:::core
    end

    subgraph "Backend Adapters"
        direction TB
        NumpyAdapter["NumPy Adapter\n(phi/math/backend.py)"]:::backend
        subgraph "JAX Adapter"
            direction TB
            JaxFlow["phi/jax/flow.py"]:::backend
            JaxStaxFlow["phi/jax/stax/flow.py"]:::backend
            JaxStaxNets["phi/jax/stax/nets.py"]:::backend
        end
        subgraph "TensorFlow Adapter"
            direction TB
            TFAdapterFlow["phi/tf/flow.py"]:::backend
            TFAdapterNets["phi/tf/nets.py"]:::backend
        end
        subgraph "PyTorch Adapter"
            direction TB
            TorchAdapterFlow["phi/torch/flow.py"]:::backend
            TorchAdapterNets["phi/torch/nets.py"]:::backend
        end
    end

    subgraph "Visualization"
        direction TB
        ConsoleUI["phi/vis/_console/"]:::viz
        MatplotlibUI["phi/vis/_matplotlib/"]:::viz
        DashUI["phi/vis/_dash/"]:::viz
    end

    subgraph "External Dependencies"
        direction TB
        PhiML["PhiML/"]:::external
        ThirdParty["Third-party Libraries\n(NumPy, JAX, TF, PyTorch,\nDash, Plotly, Matplotlib)"]:::external
    end

    subgraph "CI & Testing"
        direction TB
        GHActions["GitHub Actions Workflows\n(.github/workflows/*.yml)"]:::external
        Tests["tests/"]:::external
        Coverage["Coverage & PyPI Publishing"]:::external
    end

    %% Data and control flow
    Demos -->|"import & run"| FlowOrchestrator
    Examples -->|"import & run"| FlowOrchestrator
    UserScript -->|"calls Simulation API"| FlowOrchestrator
    Docs -->|"guides & tutorials"| UserScript

    FlowOrchestrator -->|"compose operations"| FieldManager
    FlowOrchestrator -->|"compose operations"| GeomEngine
    FlowOrchestrator -->|"compose operations"| PhysicsSolvers

    FlowOrchestrator -->|"plugin/adapter pattern"| NumpyAdapter
    FlowOrchestrator -->|"plugin/adapter pattern"| JaxFlow
    FlowOrchestrator -->|"plugin/adapter pattern"| TFAdapterFlow
    FlowOrchestrator -->|"plugin/adapter pattern"| TorchAdapterFlow

    NumpyAdapter -->|"tensor ops & autodiff"| ThirdParty
    JaxFlow -->|"tensor ops & autodiff"| ThirdParty
    JaxStaxFlow -->|"tensor ops & autodiff"| ThirdParty
    JaxStaxNets -->|"tensor ops & autodiff"| ThirdParty
    TFAdapterFlow -->|"tensor ops & autodiff"| ThirdParty
    TFAdapterNets -->|"tensor ops & autodiff"| ThirdParty
    TorchAdapterFlow -->|"tensor ops & autodiff"| ThirdParty
    TorchAdapterNets -->|"tensor ops & autodiff"| ThirdParty

    FlowOrchestrator -->|"simulation state"| ConsoleUI
    FlowOrchestrator -->|"snapshot plots"| MatplotlibUI
    FlowOrchestrator -->|"real-time streams"| DashUI

    ConsoleUI -->|"ASCII plots"| UserScript
    MatplotlibUI -->|"static plots"| UserScript
    DashUI -->|"interactive UI"| UserScript

    GHActions -->|"trigger tests"| Tests
    Tests -->|"results & publish"| Coverage

    %% Click events
    click FieldManager "https://github.com/snktshrma272/phiflow/tree/master/phi/field/"
    click GeomEngine "https://github.com/snktshrma272/phiflow/tree/master/phi/geom/"
    click PhysicsSolvers "https://github.com/snktshrma272/phiflow/tree/master/phi/physics/"
    click FlowOrchestrator "https://github.com/snktshrma272/phiflow/blob/master/phi/flow.py"
    click NumpyAdapter "https://github.com/snktshrma272/phiflow/blob/master/phi/math/backend.py"
    click JaxFlow "https://github.com/snktshrma272/phiflow/blob/master/phi/jax/flow.py"
    click JaxStaxFlow "https://github.com/snktshrma272/phiflow/blob/master/phi/jax/stax/flow.py"
    click JaxStaxNets "https://github.com/snktshrma272/phiflow/blob/master/phi/jax/stax/nets.py"
    click TFAdapterFlow "https://github.com/snktshrma272/phiflow/blob/master/phi/tf/flow.py"
    click TFAdapterNets "https://github.com/snktshrma272/phiflow/blob/master/phi/tf/nets.py"
    click TorchAdapterFlow "https://github.com/snktshrma272/phiflow/blob/master/phi/torch/flow.py"
    click TorchAdapterNets "https://github.com/snktshrma272/phiflow/blob/master/phi/torch/nets.py"
    click ConsoleUI "https://github.com/snktshrma272/phiflow/tree/master/phi/vis/_console/"
    click MatplotlibUI "https://github.com/snktshrma272/phiflow/tree/master/phi/vis/_matplotlib/"
    click DashUI "https://github.com/snktshrma272/phiflow/tree/master/phi/vis/_dash/"
    click PhiML "https://github.com/snktshrma272/phiflow/tree/master/PhiML/"
    click GHActions "https://github.com/snktshrma272/phiflow/blob/master/.github/workflows/unit-tests.yml"
    click GHActions "https://github.com/snktshrma272/phiflow/blob/master/.github/workflows/update-gh-pages.yml"
    click Tests "https://github.com/snktshrma272/phiflow/tree/master/tests/"
    click Demos "https://github.com/snktshrma272/phiflow/tree/master/demos/"
    click Examples "https://github.com/snktshrma272/phiflow/tree/master/examples/"
    click Docs "https://github.com/snktshrma272/phiflow/tree/master/docs/"

    %% Styles
    classDef core fill:#a8d5a2,stroke:#333,stroke-width:1px
    classDef backend fill:#a2c4d5,stroke:#333,stroke-width:1px
    classDef viz fill:#f7c390,stroke:#333,stroke-width:1px
    classDef external fill:#d0d0d0,stroke:#333,stroke-width:1px
    classDef consumer fill:#ffffff,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
```
