# ries-lab/uipsf architecture

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

- Interactive diagram: https://gitdiagram.com/ries-lab/uipsf
- Repository: https://github.com/ries-lab/uipsf

## Overview

##### Main System Components
a. User Interface Layer
- Jupyter Notebooks (demo/*.ipynb)
- Tutorial PDFs (tutorial/*.pdf)
- CLI/`pip install -e .` entry point (psflearning/psflearninglib.py)
b. Configuration Layer
- YAML config files (config/*/*.yaml, config/config_base.yaml, config/config_user.yaml)
- Parameter description docs (config/parameter description.md)
- Omegaconf loader
c. Data I/O Layer
- Raw data readers (psflearning/io/h5.py, io/param.py)
- czifile, tif, mat parsers
d. Core PSF Learning Library
- Data loader & interfaces (dataloader.py, data_representation/*)
- PSF model interfaces & implementations (learning/psfs/*)
- Fitters (learning/fitters/*)
- Optimizers & loss functions (learning/optimizers.py, learning/loss_functions.py)
- Utilities & image tools (imagetools.py, loclib.py, utilities.py)
e. Native Compute Layer
- Precompiled binaries for maximum-likelihood fitting (source/mleFit_LM_dylib/*.dylib, source/mleFit_LM_so)
- Python wrappers (ctypes/cffi) invoked by PSFInterface implementations
f. External Dependencies
- Python runtime & packages (TensorFlow, numpy, scipy, omeagconf, hdfdict, etc.)
- GPU hardware (CUDA, cuDNN) or CPU fallback
g. Output & Visualization
- PSF model files (.h5 via hdfdict)
- Generated plots (makeplots.py)
- Demo “output parameters” docs (demo/Description of output parameters.md)

##### Relationships & Data Flows
- Notebooks/CLI load a user-provided config via Omegaconf.
- Config → Data I/O layer: determines data paths and parameters (e.g. channel counts, ROI sizes).
- Data I/O → Core Library: raw image stacks flow into DataRepresentation classes, then into Fitters.
- Core Library ↔ Native Compute: some fitters call the mleFit_LM dynamic libraries for heavy compute.
- Core Library → TensorFlow: deep-learning-based PSF fitters invoke TensorFlow/TF-Probability.
- Core Library → Output: learned PSF models are serialized to .h5; makeplots generates figures.
- Demo notebooks / Tutorial consume output PSF models for downstream localization.

##### Architectural Patterns & Design Principles
- Modular Plugin-style Interfaces: PSFInterface, FitterInterface allow new PSF types or fitting methods to be dropped into learning/psfs or learning/fitters.
- Config-Driven Execution: Omegaconf loads hierarchical YAMLs to parameterize every aspect (systemtype, channeltype, psftype).
- Separation of Concerns: clear layers for I/O, data representation, modeling, compute, and visualization.
- Cross-Platform Build: Python wrappers decouple high-performance C/C++ binaries from the pure-Python logic.

##### Essential Detail Checklist
- Every top-level directory as a logical component.
- How config_base.yaml and config_user.yaml combine.
- Call out the demo/ folder as driving examples.
- Test/unit/io as verification of the I/O layer.
- Cross-platform solver selection (GPU vs CPU).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface Layer
    subgraph "User Interface Layer"
        style UI fill:#cce5ff,stroke:#333,stroke-width:1px
        JN["Jupyter Notebooks (demo/*.ipynb)"]:::user
        Tutorial["Tutorial PDFs (tutorial/*.pdf)"]:::user
        CLI["CLI Entry Point (psflearning/psflearninglib.py)"]:::user
    end

    %% Configuration Layer
    subgraph "Configuration Layer"
        style CFG fill:#e0e0e0,stroke:#333,stroke-width:1px
        ConfigBase["config_base.yaml"]:::config
        ConfigUser["config_user.yaml"]:::config
        SysType["systemtype/*.yaml"]:::config
        ChannelType["channeltype/*.yaml"]:::config
        PSFType["psftype/*.yaml"]:::config
        PathConfig["config_path.yaml"]:::config
        ParamDoc["parameter description.md"]:::config
    end

    %% Data I/O Layer
    subgraph "Data I/O Layer"
        style IO fill:#ccffcc,stroke:#333,stroke-width:1px
        HDF5Reader["h5.py"]:::python
        ParamIO["param.py"]:::python
        TestParam["test_param.py (unit tests)"]:::python
    end

    %% Core PSF Learning Library
    subgraph "Core PSF Learning Library"
        style CORE fill:#ccffcc,stroke:#333,stroke-width:1px
        DataLoader["dataloader.py"]:::python
        DataRep["data_representation/*.py"]:::python
        PSFs["psfs/*.py"]:::python
        Fitters["fitters/*.py"]:::python
        Optimizers["optimizers.py"]:::python
        Loss["loss_functions.py"]:::python
        ImTools["imagetools.py"]:::python
        LocLib["loclib.py"]:::python
        Utilities["utilities.py"]:::python
    end

    %% Native Compute Layer
    subgraph "Native Compute Layer"
        style NATIVE fill:#ffddcc,stroke:#333,stroke-width:1px
        MLEdylib["mleFit_LM_dylib/*.dylib"]:::native
        MLEso["mleFit_LM_so"]:::native
        Wrappers["Python Wrappers (ctypes/cffi)"]:::native
    end

    %% External Dependencies
    subgraph "External Dependencies"
        style EXT fill:#ffddcc,stroke:#333,stroke-width:1px
        TF["TensorFlow/TF-Probability"]:::external
        CUDA["CUDA/cuDNN"]:::external
        PythonPkgs["numpy, scipy, omegaconf, hdfdict, etc."]:::external
    end

    %% Output & Visualization
    subgraph "Output & Visualization"
        style OUT fill:#ccffcc,stroke:#333,stroke-width:1px
        PSFModel["PSF Models (.h5)"]:::storage
        MakePlots["makeplots.py"]:::python
        DemoOutDoc["Output Description (demo)"]:::user
    end

    %% Connections
    JN -->|"loads config"| ConfigBase
    CLI -->|"loads config"| ConfigUser
    Tutorial -->|"references"| DemoOutDoc
    ConfigBase -->|"+ ConfigUser"| SysType
    ConfigBase -->|"+ ConfigUser"| ChannelType
    ConfigBase -->|"+ ConfigUser"| PSFType
    PathConfig -->|provides paths| DataLoader
    SysType --> DataLoader
    ChannelType --> DataLoader
    PSFType --> DataLoader
    ParamDoc --> ConfigBase
    ConfigUser --> DataLoader
    DataLoader -->|"raw images → ndarray"| DataRep
    HDF5Reader --> DataRep
    ParamIO --> DataLoader
    DataRep --> PSFs
    PSFs --> Fitters
    Fitters --> Optimizers
    Fitters --> Loss
    Fitters --> ImTools
    Fitters --> LocLib
    Fitters --> Utilities
    Fitters --> NativeCompute
    NativeCompute --> MLEdylib
    NativeCompute --> MLEso
    NativeCompute --> Wrappers
    Fitters --> TF
    Fitters --> PSFModel
    PSFModel -->|"hdfdict"| PythonPkgs
    MakePlots --> PSFModel
    MakePlots -->|"plots"| DemoOutDoc
    CLI --> DataLoader
    JN --> DataLoader
    TestParam --> HDF5Reader
    TestParam --> ParamIO

    %% Click Events
    click JN "https://github.com/ries-lab/uipsf/blob/main/demo/demo_beadPSF_1ch.ipynb"
    click Tutorial "https://github.com/ries-lab/uipsf/blob/main/tutorial/Tutorial for FD_aberrations.pdf"
    click CLI "https://github.com/ries-lab/uipsf/blob/main/psflearning/psflearninglib.py"
    click ConfigBase "https://github.com/ries-lab/uipsf/blob/main/config/config_base.yaml"
    click ConfigUser "https://github.com/ries-lab/uipsf/blob/main/config/config_user.yaml"
    click SysType "https://github.com/ries-lab/uipsf/tree/main/config/systemtype/"
    click ChannelType "https://github.com/ries-lab/uipsf/tree/main/config/channeltype/"
    click PSFType "https://github.com/ries-lab/uipsf/tree/main/config/psftype/"
    click PathConfig "https://github.com/ries-lab/uipsf/blob/main/config/path/config_path.yaml"
    click ParamDoc "https://github.com/ries-lab/uipsf/blob/main/config/parameter description.md"
    click HDF5Reader "https://github.com/ries-lab/uipsf/blob/main/psflearning/io/h5.py"
    click ParamIO "https://github.com/ries-lab/uipsf/blob/main/psflearning/io/param.py"
    click TestParam "https://github.com/ries-lab/uipsf/blob/main/test/unit/io/test_param.py"
    click DataLoader "https://github.com/ries-lab/uipsf/blob/main/psflearning/dataloader.py"
    click DataRep "https://github.com/ries-lab/uipsf/tree/main/psflearning/learning/data_representation/"
    click PSFs "https://github.com/ries-lab/uipsf/tree/main/psflearning/learning/psfs/"
    click Fitters "https://github.com/ries-lab/uipsf/tree/main/psflearning/learning/fitters/"
    click Optimizers "https://github.com/ries-lab/uipsf/blob/main/psflearning/learning/optimizers.py"
    click Loss "https://github.com/ries-lab/uipsf/blob/main/psflearning/learning/loss_functions.py"
    click ImTools "https://github.com/ries-lab/uipsf/blob/main/psflearning/learning/imagetools.py"
    click LocLib "https://github.com/ries-lab/uipsf/blob/main/psflearning/learning/loclib.py"
    click Utilities "https://github.com/ries-lab/uipsf/blob/main/psflearning/learning/utilities.py"
    click MLEdylib "https://github.com/ries-lab/uipsf/tree/main/source/mleFit_LM_dylib/"
    click MLEso "https://github.com/ries-lab/uipsf/tree/main/source/mleFit_LM_so/"
    click MakePlots "https://github.com/ries-lab/uipsf/blob/main/psflearning/makeplots.py"
    click DemoOutDoc "https://github.com/ries-lab/uipsf/blob/main/demo/Description of output parameters.md"

    %% Styles
    classDef user fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef python fill:#ccffcc,stroke:#333,stroke-width:1px
    classDef native fill:#ffddcc,stroke:#333,stroke-width:1px
    classDef external fill:#ffddcc,stroke:#333,stroke-width:1px
    classDef config fill:#e0e0e0,stroke:#333,stroke-width:1px
    classDef storage fill:#e0e0e0,stroke:#333,stroke-width:1px,shape:cylinder
```
