# boschresearch/torchphysics architecture

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

- Interactive diagram: https://gitdiagram.com/boschresearch/torchphysics
- Repository: https://github.com/boschresearch/torchphysics

## Overview

##### Overall Project Purpose
- TorchPhysics is designed as a modular, maintainable, and expandable library for applying deep learning (e.g., PINNs, DeepONets, QRes, Deep Ritz) to solve differential equations and related inverse problems.
- The library builds on PyTorch (and PyTorch Lightning for training) and offers robust domain generation, various differential operators, and many advanced neural network models.

##### Main Components
– Library Core (“src/torchphysics”)
- Models: Contains various deep learning architectures (FNO, DeepONet, DeepRitz, FCN, etc.). Located in src/torchphysics/models.
- Problem Definition:
- Conditions: Defines how differential conditions are imposed (e.g., PINN, variational, etc.) – found in src/torchphysics/problem/conditions.
- Domains: Provides mesh-free domain structures with classes for Point, Interval, Circle, Triangle, Sphere, etc. Also includes domain operations (Union, Cut, Intersection) under src/torchphysics/problem/domains and its operations folder.
- Function Sets: Implements function sets (such as harmonic function sets) under src/torchphysics/problem/domains/functionsets.
- Samplers: Houses various sampling strategies for data generation (grid, random, etc.) located in src/torchphysics/problem/samplers.
- Spaces: Contains abstract representations of function spaces and their discretizations.
- Solver: The module (src/torchphysics/solver.py) that drives the training and evaluation pipeline using models and leveraging the PyTorch framework.
- Utilities: A collection of helper functions including callbacks, plotting, evaluation routines – see src/torchphysics/utils.

– Testing and Documentation:
- Tests: Extensive unit tests (in the tests folder) ensure each module works correctly.
- Docs and Examples: Detailed notebooks and written tutorials (found in docs/ and examples/) assist users in applying the library to vary applications.

##### Relationships and Interactions
– The “Problem” component (conditions, domains, samplers, and spaces) is central, as it describes the mathematical/deep learning problem.
– The “Models” module implements various network architectures that are used to approximate solutions on these problem formulations.
– The “Solver” acts as the orchestrator bringing together the model, problem setup, and training process. It also integrates utilities such as callbacks and evaluation functions.
– External Dependencies: The system relies on PyTorch, PyTorch Lightning, and other Python scientific libraries. These should be marked clearly as external systems.
– Examples and batch scripts (outside the core src tree) show how end users interact with the library (through Jupyter notebooks or command-line utilities).

##### Architectural Patterns and Design Principles
– Modularity: Each logical concept (model, problem-defining elements, solver, utilities) is separated into its own folder and submodules.
– Expandability: New architectures or problem conditions can be added by extending the modular components.
– Testability: A comprehensive tests suite ensures reliability.

– Use clear labels for each module/component.
- From Problem (conditions/domains) to Solver (indicating that problem definitions feed into the solver for training)
- From Models to Solver (indicating that the network architectures are instantiated and trained by the solver)
- From Utilities to both Models and Solver (for evaluation, callbacks, and plotting).
- Core modules (e.g., rectangles for Models, ellipses for Problem elements)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "TorchPhysics Library"
        LIB_CORE["Library Core"] 
        subgraph "Models"
            MODELS["Deep Learning Models"]
        end
        subgraph "Problem Definition"
            P_COND["Conditions"]
            P_DOM["Domains"]
            P_DOMOPS["Domain Operations"]
            P_FUNC["Function Sets"]
            P_SAMPLERS["Samplers"]
            P_SPACES["Spaces"]
        end
        SOLVER["Solver"]
        UTIL["Utilities"]
    end

    EX1["PyTorch"]
    EX2["PyTorch Lightning"]
    EX3["Matplotlib"]
    TESTS["Testing Suite"]
    DOCS["Documentation"]
    EXAMPLES["Examples"]

    %% Relationships within TorchPhysics Library
    P_COND -->|"feeds"| SOLVER
    P_DOM -->|"feeds"| SOLVER
    P_DOMOPS -->|"feeds"| SOLVER
    P_FUNC -->|"feeds"| SOLVER
    P_SAMPLERS -->|"feeds"| SOLVER
    P_SPACES -->|"feeds"| SOLVER

    MODELS -->|"provides models to"| SOLVER
    UTIL -->|"supports"| MODELS
    UTIL -->|"supports"| SOLVER

    %% External Dependencies
    EX1 -->|"used by"| SOLVER
    EX1 -->|"used by"| MODELS
    EX2 -->|"orchestrates"| SOLVER
    EX3 -->|"aids in visualization for"| UTIL

    %% Testing and Documentation
    TESTS ---|"verifies"| LIB_CORE
    DOCS ---|"guides usage of"| LIB_CORE
    EXAMPLES ---|"demonstrates"| LIB_CORE

    %% Click Events for Component Mappings
    click LIB_CORE "https://github.com/boschresearch/torchphysics/tree/main/src/torchphysics"
    click MODELS "https://github.com/boschresearch/torchphysics/tree/main/src/torchphysics/models"
    click P_COND "https://github.com/boschresearch/torchphysics/tree/main/src/torchphysics/problem/conditions"
    click P_DOM "https://github.com/boschresearch/torchphysics/tree/main/src/torchphysics/problem/domains"
    click P_DOMOPS "https://github.com/boschresearch/torchphysics/tree/main/src/torchphysics/problem/domains/domainoperations"
    click P_FUNC "https://github.com/boschresearch/torchphysics/tree/main/src/torchphysics/problem/domains/functionsets"
    click P_SAMPLERS "https://github.com/boschresearch/torchphysics/tree/main/src/torchphysics/problem/samplers"
    click P_SPACES "https://github.com/boschresearch/torchphysics/tree/main/src/torchphysics/problem/spaces"
    click SOLVER "https://github.com/boschresearch/torchphysics/blob/main/src/torchphysics/solver.py"
    click UTIL "https://github.com/boschresearch/torchphysics/tree/main/src/torchphysics/utils"
    click TESTS "https://github.com/boschresearch/torchphysics/tree/main/tests"
    click DOCS "https://github.com/boschresearch/torchphysics/tree/main/docs"
    click EXAMPLES "https://github.com/boschresearch/torchphysics/tree/main/examples"

    %% Styling Classes
    class LIB_CORE core
    class MODELS models
    class P_COND,P_DOM,P_DOMOPS,P_FUNC,P_SAMPLERS,P_SPACES problem
    class SOLVER solver
    class UTIL utils
    class EX1,EX2,EX3 external
    class DOCS,EXAMPLES docs
    class TESTS tests

    %% Class Definitions
    classDef core fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef models fill:#D6EAF8,stroke:#2874A6,stroke-width:2px;
    classDef problem fill:#D5F5E3,stroke:#196F3D,stroke-width:2px;
    classDef solver fill:#FADBD8,stroke:#CB4335,stroke-width:2px;
    classDef utils fill:#FCF3CF,stroke:#B7950B,stroke-width:2px;
    classDef external fill:#EBDEF0,stroke:#8E44AD,stroke-width:2px;
    classDef docs fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef tests fill:#F5CBA7,stroke:#A04000,stroke-width:2px;
```
