# pkgpl/torchwi architecture

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

- Interactive diagram: https://gitdiagram.com/pkgpl/torchwi
- Repository: https://github.com/pkgpl/torchwi

## Overview

##### Project Type & Purpose
- The README clearly mentions “Full waveform inversion using PyTorch.” This tells us the project is a full-stack scientific package that models and inverts seismic waveforms.
- The project supports both forward modeling and inversion workflows, as evidenced by the examples in the “examples” directory (“inverse”, “time”, “tomo”).

##### Analysis of the File Structure
- The core functionality (inversion, simulation, and optimization) is encapsulated in the “torchwi” directory.
- Separate subdirectories under “torchwi” indicate a modular design:
- io – handles data loading, distributed data handling, logging, and parsing.
- loss – contains different loss functions (frequency loss, Laplacian loss) used in the inversion process.
- operator – defines forward modeling operators in both frequency and time domains as well as tomography operators to simulate wave propagation.
- propagator – contains both high-level Python wrappers and low-level (C++/CUDA) implementations for propagating wavefields. The “td2d” subdirectory, for instance, holds various CPU and GPU variants.
- solver – provides solvers for the inversion process, including interfaces for specialized solvers (e.g., using Pardiso or CuPy).
- source – module for generating wavelets and setting up source functions (again split into frequency and Laplacian variants).
- parameter – manages inversion parameters.
- utils – auxiliary functionalities such as plotting.
- The “examples” directory gives real-world or demonstrative usage, mapping higher-level workflows (inverse, time domain, tomography) to the underlying modules.

##### Key Architectural Components and Their Relationships
- External Dependencies: PyTorch and Horovod are highlighted, meaning that the inversion and propagation computations rely on these frameworks for deep learning and distributed computation. Also, standard libraries like NumPy, SciPy, and Matplotlib are used.
- Core Components and Data Flow:
- Input/Output (io): Acts as the entry and exit point for data (e.g., seismic data in RSF format). This module also provides logging and parsing functionalities.
- Source: Generates the seismic wavelets necessary for simulation.
- Propagator: This is the computational engine where forward simulation occurs. It directly uses the source and interacts with the operator.
- Operator: Applies the forward or inverse modeling operators, facilitating the simulation of the wave propagation based on current model parameters.
- Loss Modules: After simulating the wavefields, loss functions (e.g., frequency loss, Laplacian loss) compare the simulated data with observed seismic data.
- Solver: Uses the computed losses to iteratively update the inversion parameters via optimization techniques.
- Parameter: Stores and manages the current state of the inversion model.
- Utils: Offers plotting and other helper functions for visualization and debugging.
- These components interconnect in a typical inversion loop: load data → generate source → simulate propagation via the operator → compute loss → update parameters through solver → iterate until convergence.

##### Elements
- Each module should be represented with a block having a clear label (e.g., “IO Module”, “Propagator (CPU/GPU)”, “Operator (Forward/Inverse)”, “Loss Functions”, “Solver”, etc.).
- From IO to Source
- From Source to Propagator
- Propagator feeding into the Operator
- Operator output into Loss Computation
- Loss driving the Solver and then Parameter updates.
- Core Computational Modules (e.g., propagator, operator, loss, solver).
- Supporting Utilities (e.g., IO, utils).
- External Dependencies (e.g., PyTorch, Horovod).
- Annotations for performance-critical components (like the CUDA implementations in “td2d”) can be added for further clarity.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Dependencies
    subgraph "External Dependencies"
        PT["PyTorch"]:::external
        HV["Horovod"]:::external
        NP["NumPy"]:::external
        SP["SciPy"]:::external
        MM["Matplotlib"]:::external
    end

    %% Core Inversion Workflow
    subgraph "Core Inversion Workflow"
        IO["IO Module"]:::core
        SRC["Source (Wavelet Generation)"]:::core
        PROP["Propagator (CPU/GPU)"]:::core
        PROP_DETAIL["Prop Detail (td2d)"]:::core
        OPS["Operator (Forward/Inverse)"]:::core
        LOSS["Loss Functions"]:::core
        SOLVER["Solver (Inversion Algorithms)"]:::core
        PARAM["Parameter (Inversion Parameters)"]:::core
    end

    %% Supporting Modules
    subgraph "Supporting Modules"
        UTILS["Utils (Plotting & Aux)"]:::support
        EXAMPLES["Examples (Workflows)"]:::support
    end

    %% Core Flow Connections
    IO -->|"feeds"| SRC
    SRC -->|"initiates"| PROP
    PROP -->|"refines"| PROP_DETAIL
    PROP_DETAIL -->|"drives"| OPS
    OPS -->|"produces"| LOSS
    LOSS -->|"guides"| SOLVER
    SOLVER -->|"updates"| PARAM

    %% External Dependencies Connections
    PT -->|"compute"| PROP
    HV -->|"distributed"| PROP
    NP -->|"data-format"| IO
    SP -->|"scientific"| IO
    MM -->|"visualize"| UTILS

    %% Supporting Connections
    EXAMPLES -->|"demonstrates"| IO
    UTILS ---|"assists"| EXAMPLES

    %% Class Definitions
    classDef core fill:#BBDEFB,stroke:#039BE5,stroke-width:2px;
    classDef support fill:#C8E6C9,stroke:#2E7D32,stroke-width:2px;
    classDef external fill:#FFECB3,stroke:#FBC02D,stroke-width:2px;

    %% Click Events for Component Mapping
    click IO "https://github.com/pkgpl/torchwi/tree/main/torchwi/io"
    click SRC "https://github.com/pkgpl/torchwi/tree/main/torchwi/source"
    click PROP "https://github.com/pkgpl/torchwi/tree/main/torchwi/propagator"
    click PROP_DETAIL "https://github.com/pkgpl/torchwi/tree/main/torchwi/propagator/td2d"
    click OPS "https://github.com/pkgpl/torchwi/tree/main/torchwi/operator"
    click LOSS "https://github.com/pkgpl/torchwi/tree/main/torchwi/loss"
    click SOLVER "https://github.com/pkgpl/torchwi/tree/main/torchwi/solver"
    click PARAM "https://github.com/pkgpl/torchwi/tree/main/torchwi/parameter"
    click UTILS "https://github.com/pkgpl/torchwi/tree/main/torchwi/utils"
    click EXAMPLES "https://github.com/pkgpl/torchwi/tree/main/examples"
```
