# rafael-fuente/diffractsim architecture

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

- Interactive diagram: https://gitdiagram.com/rafael-fuente/diffractsim
- Repository: https://github.com/rafael-fuente/diffractsim

## Overview

##### Main Components
- Core Simulation Engine (the diffractsim package): This is the nucleus of your project. Within this package, several submodules implement the optical simulation functionalities:
- diffractsim/diffractive_elements: Contains various modules that define apertures, gratings, lenses, and other diffractive optical elements (e.g., circular_aperture, axial and hexagonal apertures, Fresnel zone plate, etc.).
- diffractsim/holography: Implements phase retrieval techniques including both Fourier and custom solutions for holographic reconstruction.
- diffractsim/light_sources: Provides modules for different light sources including plane waves, Gaussian beams, and spatial noise.
- diffractsim/polynomials: Contains modules for Hermite-Gaussian, Laguerre-Gaussian modes, and Zernike polynomials, important for repre­senting beam characteristics.
- diffractsim/propagation_methods: Includes several methods for simulating light propagation (e.g., angular spectrum, Bluestein, two-steps Fresnel), forming the computational backbone.
- diffractsim/util: Provides utility functions for backend computations, file and image handling, FFT optimizations with Bluestein and Chirp-Z transforms, and constant definitions.
- diffractsim/visualization: Offers modules to process simulation outputs into visual representations such as intensity plots, phase plots, and longitudinal intensity profiles.
- Simulation Interfaces: Entry points like “diffractsim/monochromatic_simulator.py” and “diffractsim/polychromatic_simulator.py” indicate different simulation setups.
- Examples: The “examples” directory demonstrates end-to-end usage of the simulation engine. Each script (e.g., “hexagon_monochromatic.py”, “bahtinov_mask.py”) serves as a practical use case, highlighting how the different modules come together.
- GPU Acceleration & Differentiable Programming: The README describes the use of JAX or CuPy, which are integrated via a backend switch (e.g., diffractsim.set_backend("JAX")). This supports high-performance computations and optimization workflows.

##### Relationships and Interactions
- Architectural layers:
- At the top, you have the simulation interface modules (entry points in examples and main simulation scripts).
- The next layer is the core engine (the diffractsim package) segmented into its various logical submodules.
- Between these modules, denote the data flow: for example, Light Source → Diffractive Elements → Propagation (via chosen propagation method) → Visualization.
- Link the GPU acceleration component to the “util” module and overall simulation engine, indicating that the backend (JAX/CuPy) affects performance and differentiability.
- That configuration, spectrum data (files in the “data” folder), and optical components (diffractive_elements) feed into the simulation computations performed by propagation_methods.

##### Architectural Patterns and Technologies
- Modularity: Each optical element and computational method is encapsulated in its own module. Emphasize separation of concerns.
- Extensibility: The presence of different diffractive elements, light sources, and propagation methods indicates plugin-style extensibility.
- Performance Considerations: Highlight the optional GPU acceleration integration (CuPy, JAX) and potential for parallel computation when generating longitudinal profiles.
- Reusability: Utility functions and backend abstraction allow the simulator to operate in different computational contexts.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Simulation Interfaces Layer
    subgraph "Simulation Interfaces"
        SIM1("Monochromatic Simulator"):::interface
        SIM2("Polychromatic Simulator"):::interface
        EX("Example Applications"):::interface
    end

    %% Core Simulation Engine Layer
    subgraph "Core Simulation Engine (diffractsim)"
        CF("Colour Functions"):::core
        DE("Diffractive Elements"):::core
        HO("Holography"):::core
        LS("Light Sources"):::core
        PO("Polynomials"):::core
        PM("Propagation Methods"):::core
        UT("Utility Functions & GPU Backend"):::core
        VI("Visualization"):::core
    end

    %% Data Resources Node
    DATA("Data Resources"):::data

    %% GPU Acceleration Node
    GPU("GPU Acceleration (JAX/CuPy)"):::gpu

    %% Relationships between Simulation Interfaces and Core Engine
    SIM1 -->|"triggers"| LS
    SIM2 -->|"triggers"| LS
    EX -->|"demonstrates"| LS

    %% Data Resources feeding into relevant modules
    DATA -->|"provides spectral data"| LS
    DATA -->|"supplies color data"| CF
    DATA -->|"supports utilities"| UT

    %% Core Simulation Engine internal data flow
    LS -->|"defines illumination"| DE
    LS -->|"informs beam profiles"| PO
    LS -->|"enables phase reconstruction"| HO

    DE -->|"outputs optical field"| PM
    PO -->|"characterizes beam"| PM
    HO -->|"contributes phase info"| PM

    PM -->|"generates simulation output"| VI
    CF -->|"computes color mapping"| VI

    %% Backend/GPU acceleration influences
    GPU -->|"accelerates computations"| UT
    GPU -->|"optimizes propagation"| PM
    UT -->|"supports numerical methods"| PM

    %% Styling Definitions
    classDef interface fill:#a8e6cf,stroke:#379683,stroke-width:2px,color:#000;
    classDef core fill:#8ecae6,stroke:#1c4966,stroke-width:2px,color:#000;
    classDef data fill:#ffcc80,stroke:#bf360c,stroke-width:2px,color:#000;
    classDef gpu fill:#ff8a80,stroke:#d32f2f,stroke-width:2px,color:#000;

    %% Click Events for Component Mapping
    click SIM1 "https://github.com/rafael-fuente/diffractsim/blob/main/diffractsim/monochromatic_simulator.py"
    click SIM2 "https://github.com/rafael-fuente/diffractsim/blob/main/diffractsim/polychromatic_simulator.py"
    click EX "https://github.com/rafael-fuente/diffractsim/tree/main/examples/"
    click CF "https://github.com/rafael-fuente/diffractsim/blob/main/diffractsim/colour_functions.py"
    click DE "https://github.com/rafael-fuente/diffractsim/tree/main/diffractsim/diffractive_elements/"
    click HO "https://github.com/rafael-fuente/diffractsim/tree/main/diffractsim/holography/"
    click LS "https://github.com/rafael-fuente/diffractsim/tree/main/diffractsim/light_sources/"
    click PO "https://github.com/rafael-fuente/diffractsim/tree/main/diffractsim/polynomials/"
    click PM "https://github.com/rafael-fuente/diffractsim/tree/main/diffractsim/propagation_methods/"
    click UT "https://github.com/rafael-fuente/diffractsim/tree/main/diffractsim/util/"
    click VI "https://github.com/rafael-fuente/diffractsim/tree/main/diffractsim/visualization/"
    click DATA "https://github.com/rafael-fuente/diffractsim/tree/main/diffractsim/data/"
```
