How fnemina/pyosoaa works
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