# inlnano/pymoe architecture

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

- Interactive diagram: https://gitdiagram.com/inlnano/pymoe
- Repository: https://github.com/inlnano/pymoe

## Overview

##### Project type and purpose
- This is a pure-Python, open-source scientific library (“pyMOE”) for designing and producing masks for micro-optical elements. It exposes functions and classes (under the `pyMOE/` package) that implement mask generation, mask operations, CAD conversion, hologram computation, and field propagation. Users interact with it via Python scripts or Jupyter notebooks, and it provides documentation via Sphinx.

##### File structure
- Top-level directories and files:
- `pyMOE/` – the core Python package containing all functional modules
- `notebooks/` and `docs/notebooks/` – example Jupyter notebooks demonstrating use
- `docs/` and `docs/source/` – Sphinx configuration and documentation source
- `tests/` – pytest unit tests exercising each module
- config files (`requirements.txt`, `.readthedocs.yaml`, Sphinx makefiles)
- Key modules in `pyMOE/`:
– `generate.py`, `dither.py`, `metas.py`, `holograms.py`, `propagate.py` – core algorithms
– `importing.py`, `export.py`, `gdsconverter.py`, `gds_klops.py` – file I/O and CAD integration
– `plotting.py`, `utils.py` – visualization and utilities
- Build/deploy: standard Python packaging, ReadTheDocs integration for docs.

##### Read README for additional insights
- Features: mask design (analytical/numerical), dithering, metasurfaces, propagation, CAD I/O
- Usage: notebooks under `notebooks/`; tests via pytest
- Dependencies: scientific stack (likely `numpy`, `scipy`, `matplotlib`, `gdstk` or similar)

a. Main components
- Library core modules (grouped by functionality):
- Mask generation layer (generate.py, dither.py)
- Metasurfaces design (metas.py)
- Hologram routines (holograms.py)
- Field propagation (propagate.py)
- I/O layer: CAD conversion and file import/export (importing.py, export.py, gdsconverter.py, gds_klops.py)
- Utility layer: plotting, common helpers (plotting.py, utils.py, sag_functions.py)
- External dependencies: NumPy/SciPy, Matplotlib, GDS libraries
- Users & integration:
- Jupyter notebooks and Python scripts call the API
- Sphinx docs generation
- Test harness: pytest suite

b. Relationships and interactions
- Data flow: analytical input → generate → dither → final mask → export → CAD file
- Propagation functions consume mask data arrays, pass through numerical solvers, return field objects
- Plotting functions take outputs from any processing stage to render figures
- Tests invoke modules in isolation to verify behavior

c. Important architectural patterns
- Modular, layered design: separate algorithmic, I/O, and utility concerns
- Functional API: stateless functions returning data structures
- Notebook-driven examples: documentation and usage examples co-located with code
- Test-first quality: one test per major module

d. Key technologies/frameworks
- Python 3.7+ runtime
- NumPy/SciPy for array and numerical operations
- Matplotlib (or similar) for plotting
- GDSII handling library (e.g., `gdsconverter`, possibly `gdspy`/`gdstk`)
- Sphinx for docs (`docs/`, ReadTheDocs integration)
- pytest for testing

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Users & Notebooks
    subgraph "Documentation & Examples"
        NB1["1 Generate_masks.ipynb"]:::docs
        NB2["2 Metasurfaces_masks.ipynb"]:::docs
        NB3["3 Import_export.ipynb"]:::docs
        NB4["4 GDS_operations.ipynb"]:::docs
        NB5["5 Hologram_masks.ipynb"]:::docs
        NB6["6 Propagate_masks.ipynb"]:::docs
        DROOT["docs/"]:::docs
        DSRC["docs/source/"]:::docs
        DCFG["conf.py"]:::docs
        DIRST["index.rst"]:::docs
    end

    %% Core pyMOE Package
    subgraph "pyMOE Package"
        subgraph "Algorithmic Modules"
            GEN["generate.py"]:::algorithm
            DIT["dither.py"]:::algorithm
            APR["aperture.py"]:::algorithm
            MET["metas.py"]:::algorithm
            HOG["holograms.py"]:::algorithm
            PRO["propagate.py"]:::algorithm
            FLD["field.py"]:::algorithm
            SAG["sag_functions.py"]:::algorithm
        end
        subgraph "I/O Modules"
            IMP["importing.py"]:::io
            EXP["export.py"]:::io
            GDSC["gdsconverter.py"]:::io
            GDSK["gds_klops.py"]:::io
        end
        subgraph "Utility Modules"
            PLO["plotting.py"]:::util
            UTL["utils.py"]:::util
        end
    end

    %% Test Suite
    subgraph "Test Suite"
        TG["test_generate.py"]:::tests
        TH["test_holograms.py"]:::tests
        TC["test_gdsconverter.py"]:::tests
        TI["test_imports.py"]:::tests
        TA["test_aperture.py"]:::tests
        TB["test_basic.py"]:::tests
    end

    %% External Dependencies
    subgraph "External Dependencies"
        NP["NumPy/SciPy"]:::external
        MP["Matplotlib"]:::external
        GDSLIB["GDSII Library"]:::external
    end

    %% Control flows from notebooks
    NB1 -.->|calls| GEN
    NB2 -.->|calls| MET
    NB3 -.->|calls| IMP
    NB4 -.->|calls| GDSC
    NB5 -.->|calls| HOG
    NB6 -.->|calls| PRO

    %% Data flows in Algorithmic Modules
    GEN -->|mask array| DIT
    DIT -->|dithered mask| APR
    APR -->|aperture data| MET
    MET -->|surface design| HOG
    HOG -->|hologram mask| PRO
    PRO -->|field object| FLD
    SAG -.->|helper functions| PRO

    %% I/O interactions
    APR -->|mask data| EXP
    MET -->|metasurface| EXP
    HOG -->|hologram| EXP
    EXP -->|CAD file| GDSC
    GDSC -->|GDS file| GDSLIB

    IMP -->|reads CAD| APR

    %% Utilities usage
    DIT -->|visualize| PLO
    PRO -->|plot field| PLO
    UTL -.-> GEN
    UTL -.-> DIT
    UTL -.-> APR
    UTL -.-> MET
    UTL -.-> HOG
    UTL -.-> PRO

    %% Dependencies links
    NP -.-> GEN
    NP -.-> DIT
    NP -.-> MET
    NP -.-> HOG
    NP -.-> PRO
    MP -.-> PLO
    GDSLIB -.-> GDSC
    GDSLIB -.-> GDSK

    %% Tests invoking modules
    TG -.->|tests| GEN
    TH -.->|tests| HOG
    TC -.->|tests| GDSC
    TI -.->|tests| IMP
    TA -.->|tests| APR
    TB -.->|tests| UTL

    %% Click Events
    click GEN "https://github.com/inlnano/pymoe/blob/main/pyMOE/generate.py"
    click DIT "https://github.com/inlnano/pymoe/blob/main/pyMOE/dither.py"
    click APR "https://github.com/inlnano/pymoe/blob/main/pyMOE/aperture.py"
    click MET "https://github.com/inlnano/pymoe/blob/main/pyMOE/metas.py"
    click HOG "https://github.com/inlnano/pymoe/blob/main/pyMOE/holograms.py"
    click PRO "https://github.com/inlnano/pymoe/blob/main/pyMOE/propagate.py"
    click FLD "https://github.com/inlnano/pymoe/blob/main/pyMOE/field.py"
    click SAG "https://github.com/inlnano/pymoe/blob/main/pyMOE/sag_functions.py"
    click IMP "https://github.com/inlnano/pymoe/blob/main/pyMOE/importing.py"
    click EXP "https://github.com/inlnano/pymoe/blob/main/pyMOE/export.py"
    click GDSC "https://github.com/inlnano/pymoe/blob/main/pyMOE/gdsconverter.py"
    click GDSK "https://github.com/inlnano/pymoe/blob/main/pyMOE/gds_klops.py"
    click PLO "https://github.com/inlnano/pymoe/blob/main/pyMOE/plotting.py"
    click UTL "https://github.com/inlnano/pymoe/blob/main/pyMOE/utils.py"
    click NB1 "https://github.com/inlnano/pymoe/blob/main/notebooks/1 - Generate_masks/Generate_masks.ipynb"
    click NB2 "https://github.com/inlnano/pymoe/blob/main/notebooks/2 - Metasurfaces/Metasurfaces_masks.ipynb"
    click NB3 "https://github.com/inlnano/pymoe/blob/main/notebooks/3 - Import_export/Import_export.ipynb"
    click NB4 "https://github.com/inlnano/pymoe/blob/main/notebooks/4 - GDS_operations/GDS_operations.ipynb"
    click NB5 "https://github.com/inlnano/pymoe/blob/main/notebooks/5 - Holograms/Hologram_masks.ipynb"
    click NB6 "https://github.com/inlnano/pymoe/blob/main/notebooks/6 - Propagation/Propagate_masks.ipynb"
    click DROOT "https://github.com/inlnano/pymoe/tree/main/docs/"
    click DSRC "https://github.com/inlnano/pymoe/tree/main/docs/source/"
    click DCFG "https://github.com/inlnano/pymoe/blob/main/docs/conf.py"
    click DIRST "https://github.com/inlnano/pymoe/blob/main/docs/index.rst"
    click TG "https://github.com/inlnano/pymoe/blob/main/tests/test_generate.py"
    click TH "https://github.com/inlnano/pymoe/blob/main/tests/test_holograms.py"
    click TC "https://github.com/inlnano/pymoe/blob/main/tests/test_gdsconverter.py"
    click TI "https://github.com/inlnano/pymoe/blob/main/tests/test_imports.py"
    click TA "https://github.com/inlnano/pymoe/blob/main/tests/test_aperture.py"
    click TB "https://github.com/inlnano/pymoe/blob/main/tests/test_basic.py"

    %% Styles
    classDef algorithm fill:#D0E6FF,stroke:#000
    classDef io fill:#D0FFD0,stroke:#000
    classDef util fill:#FFF4C1,stroke:#000
    classDef docs fill:#FFE0B2,stroke:#000
    classDef tests fill:#E0E0E0,stroke:#666
    classDef external fill:#F0F0F0,stroke:#000
```
