# fnemina/pyosoaa architecture

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

- Interactive diagram: https://gitdiagram.com/fnemina/pyosoaa
- Repository: https://github.com/fnemina/pyosoaa

## Overview

##### Project type and purpose
- pyOSOAA is a scientific‐computing library: a Python wrapper (adapter/facade) around an external Fortran radiative‐transfer engine (OSOAA).
- Its purpose is to let users in Python build run‐scripts for OSOAA, launch the Fortran engine, and parse its outputs into Python data structures.

##### File structure
- Top‐level directories:
- `pyOSOAA/` – the Python package (modules: constants.py, osoaa.py, osoaahelpers.py, outputs.py)
- `test/` – unit tests plus a Fortran source example and expected OSOAA outputs
- `docs/` – Sphinx documentation source
- `casestudy/` – example Jupyter notebook and Python script demonstrating usage
- Config & build: `setup.py`, `pyproject.toml`, CI workflows (`.github/workflows/`, `.travis.yml`), coverage (`.coveralls.yml`), Doxygen config
- Patterns: The Python package is organized by functionality: constants definitions, core wrapper class, helper utilities, and output‐parsing.

##### README for additional insights
- The library implements a façade over OSOAA: methods to build input decks, run scenarios, and collect radiances/polarizations.
- It supports multiple aerosol/sea‐surface models and has helper routines for batching wavelengths or bands.
- Installation requires first installing the external OSOAA Fortran code, then installing pyOSOAA.

a. Main components:
- Python Client (user scripts, notebooks, application)
- pyOSOAA Python Package
– Constants module
– Core wrapper (builds input, invokes OSOAA)
– Helpers (batch runs, band conversions)
– Outputs parser (reads flux, radiance, polarization files)
- External OSOAA Engine (Fortran executable)
- File system (input deck files, output text/binary files)
- Test Harness & CI (pytest, Fortran example, expected outputs)
- Documentation Generator (Sphinx + Doxygen)
b. Relationships & interactions:
1. User code calls pyOSOAA API →
2. Wrapper builds input configuration files on disk →
3. Wrapper spawns OSOAA Fortran executable →
4. OSOAA runs radiative‐transfer computations →
5. OSOAA writes output files (fluxes, radiances, logs) →
6. Parser module reads these files into Python objects →
7. Results returned to user
8. CI runs test suite: invokes `pyOSOAA.test()`, compares parser output to expected files
c. Architectural patterns & principles:
- Façade/Adapter pattern: pyOSOAA hides complexity of file‐based Fortran interface behind a Python API
- Single Responsibility: separate modules for constants, core logic, helpers, and outputs
- Extensibility: helper modules and configuration constants make it easy to add new aerosol or sea models
d. Key technologies/frameworks:
- Python 3 packaging (setuptools, pyproject.toml)
- Fortran‐based OSOAA engine (external dependency)
- pytest for testing, GitHub Actions / Travis CI for CI/CD
- Sphinx & Doxygen for documentation

##### Essential elements to capture
- Boundary between Python wrapper and OSOAA engine
- File‐based interface (input deck → output files)
- Module decomposition within pyOSOAA
- CI/test integration verifying correct parsing
- Documentation pipeline

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Python Client"
        PC1["Notebook: Intercomparison.ipynb"]
        PC2["Script: rs12091445.py"]
    end

    subgraph "pyOSOAA Package"
        init["__init__.py"]
        const["constants.py"]
        core["osoaa.py"]
        help["osoaahelpers.py"]
        out["outputs.py"]
    end

    FS["File System I/O"]
    FE["External OSOAA Engine"]

    subgraph "Test & CI"
        UT["test_osoaa.py"]
        ForEx["LUM_SF.f95"]
        Results["OSOAA_RESULTS"]
        GH["GitHub Actions"]
        Travis["Travis CI"]
    end

    subgraph "Documentation"
        Sphinx["docs/"]
        Dox["doxygen.config"]
    end

    PC1 -->|"calls API"| core
    PC2 -->|"calls API"| core
    core -->|"writes input decks"| FS
    FS -->|"invokes executable"| FE
    FE -->|"writes outputs"| FS
    FS -->|"reads outputs"| out
    out -->|"returns results"| PC1
    out -->|"returns results"| PC2

    UT -->|"tests wrapper/parser"| core
    UT -->|"uses expected outputs"| Results
    ForEx -->|"example source for engine"| FE
    GH -->|"runs UT"| UT
    Travis -->|"runs UT"| UT

    Sphinx -->|"generates docs from"| const
    Sphinx -->|"generates docs from"| core
    Sphinx -->|"generates docs from"| help
    Sphinx -->|"generates docs from"| out
    Dox -->|"documents Fortran engine"| FE

    classDef python fill:#cce5ff,stroke:#3399ff,color:#003366
    classDef fortran fill:#d4edda,stroke:#28a745,color:#155724
    classDef fs fill:#e2e3e5,stroke:#6c757d,color:#343a40
    classDef client fill:#fff3cd,stroke:#ffc107,color:#856404
    classDef ci fill:#f8d7da,stroke:#dc3545,color:#721c24
    classDef docs fill:#d1ecf1,stroke:#17a2b8,color:#0c5460

    class init,const,core,help,out python
    class FE fortran
    class FS,Results fs
    class PC1,PC2 client
    class UT,GH,Travis ci
    class Sphinx,Dox docs

    click PC1 "https://github.com/fnemina/pyosoaa/blob/master/casestudy/Intercomparison between the different atmospheric components.ipynb"
    click PC2 "https://github.com/fnemina/pyosoaa/blob/master/casestudy/rs12091445.py"
    click init "https://github.com/fnemina/pyosoaa/blob/master/pyOSOAA/__init__.py"
    click const "https://github.com/fnemina/pyosoaa/blob/master/pyOSOAA/constants.py"
    click core "https://github.com/fnemina/pyosoaa/blob/master/pyOSOAA/osoaa.py"
    click help "https://github.com/fnemina/pyosoaa/blob/master/pyOSOAA/osoaahelpers.py"
    click out "https://github.com/fnemina/pyosoaa/blob/master/pyOSOAA/outputs.py"
    click ForEx "https://github.com/fnemina/pyosoaa/blob/master/test/LUM_SF.f95"
    click Results "https://github.com/fnemina/pyosoaa/tree/master/test/OSOAA_RESULTS/"
    click UT "https://github.com/fnemina/pyosoaa/blob/master/test/test_osoaa.py"
    click GH "https://github.com/fnemina/pyosoaa/blob/master/.github/workflows/python-publish.yml"
    click Travis "https://github.com/fnemina/pyosoaa/blob/master/.travis.yml"
    click Sphinx "https://github.com/fnemina/pyosoaa/tree/master/docs/"
    click Dox "https://github.com/fnemina/pyosoaa/blob/master/doxygen.config"
```
