# ashiklom/rrtm architecture

> Architecture diagram of the GitHub repository ashiklom/rrtm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ashiklom/rrtm
- Repository: https://github.com/ashiklom/rrtm

## Overview

1. **What this repository is**
   - `rrtm` is an R package for vegetation radiative transfer modeling. Its core purpose is to compute wavelength-resolved reflectance/transmittance spectra for leaves, canopies, and soils, and to combine those into higher-level remote-sensing models.

2. **Primary user-facing layer**
   - The main API lives in `R/*.R` and is exported through `NAMESPACE`.
   - Key entry points include `prospect*`, `foursail`, `pro4sail_*`, `liberty`, `gpm`, `edr`, `hapke_soil`, and spectral-response helpers. These are the functions a caller uses directly from R.

3. **Model subsystem boundaries**
   - The code is organized by physical model rather than by application layer.
   - Leaf optics are handled by PROSPECT-family code; canopy radiative transfer is handled by SAIL/4SAIL; soil/background reflectance is handled by Hapke-based logic; additional vegetation models include LIBERTY, GPM, and EDR-related routines.

4. **Composition of models into end-to-end workflows**
   - The package’s main architectural pattern is model chaining: leaf spectra feed canopy scattering/transfer models, which then combine with soil/background reflectance.
   - The README’s `pro4sail_5()` example illustrates this: PROSPECT-derived leaf spectra are coupled with 4SAIL canopy calculations and a soil model to produce multiple directional reflectance outputs.

5. **Compiled numerical core**
   - The `src/` directory contains the C++ implementation, with `solvearray.cpp` as the main compiled numerical routine and `RcppExports.cpp`/`RcppExports.R` providing the R-to-C++ bridge.
   - This is the package’s performance boundary: higher-level model orchestration is in R, while the heavy numerical solving is pushed into compiled code.

6. **Shared utilities and internal math**
   - `R/utils.R`, `R/lidf.R`, `R/sail-volscatt.R`, and related files hold reusable mathematical helpers and geometry/scattering calculations.
   - These functions support multiple models rather than representing separate public workflows.

7. **Data and parameter assets**
   - The package ships with precomputed/internal datasets in `data/` and `sysdata.rda`, including sensor response data.
   - `extdata/` contains fixed reference tables used by models, such as soil and wood reflectance files.

8. **Data preparation pipeline**
   - `data-raw/` is the reproducible source for generated package data.
   - Scripts there convert raw spectra, sensor descriptions, and reference tables into packaged `.RData` assets, separating ingestion/preprocessing from runtime model execution.

9. **Validation and regression coverage**
   - `tests/testthat/` contains model-specific tests for PROSPECT, LIBERTY, EDR, SAIL, spectral response, and an integration-style `pecanrtm` test.
   - This indicates the package is validated both at the individual model level and across model combinations.

10. **Documentation and reproducibility surface**
   - `README.Rmd`, the generated `README.md`, `man/` Rd files, and the `vignettes/inversion.Rmd` vignette form the main documentation layer.
   - The vignette suggests at least one higher-level workflow around parameter inversion, not just forward simulation.

11. **Build and quality tooling**
   - The package uses standard R package tooling plus compiled-code build files (`src/Makevars`, `src/Makevars.win`).
   - CI is run via GitHub Actions (`.github/workflows/R-CMD-check.yaml`), and `.lintr` indicates linting/static style checks are part of the repo’s quality boundary.

12. **Likely architectural diagram framing**
   - A useful diagram would show: external user input parameters and sensor/soil reference data on the left; R model modules in the center; compiled C++ solver underneath as the performance layer; packaged datasets as a supporting store; and outputs as spectra/reflectance products returned to R callers.

Main entry points: [`NAMESPACE`](https://github.com/ashiklom/rrtm/tree/master/NAMESPACE) (R API), [`tests/testthat`](https://github.com/ashiklom/rrtm/tree/master/tests/testthat) (Tests), [`R/prosail.R`](https://github.com/ashiklom/rrtm/blob/master/R/prosail.R) (PRO4SAIL), [`R/prospect.R`](https://github.com/ashiklom/rrtm/blob/master/R/prospect.R) (PROSPECT)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_r_models["R models"]
  node_n_api["R API<br/>exports"]
  node_n_prospect["PROSPECT<br/>leaf optics<br/>[prospect.R]"]
  node_n_foursail["4SAIL<br/>canopy RT<br/>[foursail.R]"]
  node_n_prosail["PRO4SAIL<br/>composition<br/>[prosail.R]"]
  node_n_soil["Hapke soil<br/>soil reflectance<br/>[hapke-soil.R]"]
  node_n_veg_misc["Other veg models<br/>auxiliary models<br/>[liberty.R]"]
  node_n_utils["Shared math<br/>helpers<br/>[utils.R]"]
  node_n_sr["Spectral response<br/>sensor helpers"]
end

subgraph group_grp_native["Native core"]
  node_n_bridge["Rcpp bridge<br/>interop<br/>[RcppExports.R]"]
  node_n_cpp["Solve core<br/>C++ solver<br/>[solvearray.cpp]"]
end

subgraph group_grp_data["Data assets"]
  node_n_packed_data[("Package data<br/>RData assets<br/>[sysdata.rda]")]
  node_n_extdata["Reference tables<br/>fixed inputs<br/>[hapke-soil.dat]"]
  node_n_rawprep["Data prep<br/>generation scripts<br/>[dataspec.R]"]
end

subgraph group_grp_tooling["Tooling"]
  node_n_tests["Tests<br/>validation"]
  node_n_docs["Docs<br/>documentation<br/>[README.Rmd]"]
  node_n_ci["CI/Lint<br/>quality<br/>[R-CMD-check.yaml]"]
end

node_n_api -->|"exports"| node_n_prospect
node_n_api -->|"exports"| node_n_foursail
node_n_api -->|"exports"| node_n_prosail
node_n_api -->|"exports"| node_n_soil
node_n_api -->|"exports"| node_n_veg_misc
node_n_api -->|"exports"| node_n_sr
node_n_prosail -->|"uses"| node_n_prospect
node_n_prosail -->|"uses"| node_n_foursail
node_n_prosail -->|"uses"| node_n_soil
node_n_prospect -->|"shares math"| node_n_utils
node_n_foursail -->|"shares math"| node_n_utils
node_n_sr -->|"loads"| node_n_packed_data
node_n_rawprep -->|"builds"| node_n_packed_data
node_n_rawprep -->|"converts"| node_n_extdata
node_n_bridge -->|"bridges to"| node_n_cpp
node_n_prospect -->|"computes via"| node_n_bridge
node_n_foursail -->|"computes via"| node_n_bridge
node_n_tests -->|"covers"| node_n_prospect
node_n_tests -->|"covers"| node_n_foursail
node_n_tests -->|"covers"| node_n_sr
node_n_tests -->|"covers"| node_n_veg_misc
node_n_docs -->|"documents"| node_n_prosail
node_n_ci -->|"runs"| node_n_tests

click node_n_api "https://github.com/ashiklom/rrtm/tree/master/NAMESPACE"
click node_n_prospect "https://github.com/ashiklom/rrtm/blob/master/R/prospect.R"
click node_n_foursail "https://github.com/ashiklom/rrtm/blob/master/R/foursail.R"
click node_n_prosail "https://github.com/ashiklom/rrtm/blob/master/R/prosail.R"
click node_n_soil "https://github.com/ashiklom/rrtm/blob/master/R/hapke-soil.R"
click node_n_veg_misc "https://github.com/ashiklom/rrtm/blob/master/R/liberty.R"
click node_n_utils "https://github.com/ashiklom/rrtm/blob/master/R/utils.R"
click node_n_sr "https://github.com/ashiklom/rrtm/blob/master/R/spectral-response.R"
click node_n_bridge "https://github.com/ashiklom/rrtm/blob/master/R/RcppExports.R"
click node_n_cpp "https://github.com/ashiklom/rrtm/blob/master/src/solvearray.cpp"
click node_n_packed_data "https://github.com/ashiklom/rrtm/blob/master/R/sysdata.rda"
click node_n_extdata "https://github.com/ashiklom/rrtm/blob/master/extdata/hapke-soil.dat"
click node_n_rawprep "https://github.com/ashiklom/rrtm/blob/master/data-raw/dataspec.R"
click node_n_tests "https://github.com/ashiklom/rrtm/tree/master/tests/testthat"
click node_n_docs "https://github.com/ashiklom/rrtm/blob/master/README.Rmd"
click node_n_ci "https://github.com/ashiklom/rrtm/blob/master/.github/workflows/R-CMD-check.yaml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n_api,node_n_prospect,node_n_foursail,node_n_prosail,node_n_soil,node_n_veg_misc,node_n_utils,node_n_sr toneBlue
class node_n_bridge,node_n_cpp toneAmber
class node_n_packed_data,node_n_extdata,node_n_rawprep toneMint
class node_n_tests,node_n_docs,node_n_ci toneRose
```

## Components

### R models

Public R-facing model layer and shared helpers

- [R API](https://github.com/ashiklom/rrtm/tree/master/NAMESPACE): exports · Main user-facing entry points exported through NAMESPACE · `NAMESPACE`
- [PROSPECT](https://github.com/ashiklom/rrtm/blob/master/R/prospect.R): leaf optics · Leaf reflectance/transmittance family · `R/prospect.R`
- [4SAIL](https://github.com/ashiklom/rrtm/blob/master/R/foursail.R): canopy RT · Canopy scattering and transfer model · `R/foursail.R`
- [PRO4SAIL](https://github.com/ashiklom/rrtm/blob/master/R/prosail.R): composition · Chains leaf and canopy models into end-to-end spectra · `R/prosail.R`
- [Hapke soil](https://github.com/ashiklom/rrtm/blob/master/R/hapke-soil.R): soil reflectance · Soil and background reflectance model · `R/hapke-soil.R`
- [Other veg models](https://github.com/ashiklom/rrtm/blob/master/R/liberty.R): auxiliary models · LIBERTY, GPM, and EDR-related model routines · `R/liberty.R`
- [Shared math](https://github.com/ashiklom/rrtm/blob/master/R/utils.R): helpers · Reusable utilities, leaf angle, and scattering math · `R/utils.R`
- [Spectral response](https://github.com/ashiklom/rrtm/blob/master/R/spectral-response.R): sensor helpers · Sensor response and band integration helpers · `R/spectral-response.R`

### Native core

Compiled numerical boundary

- [Rcpp bridge](https://github.com/ashiklom/rrtm/blob/master/R/RcppExports.R): interop · R-to-C++ bindings generated by Rcpp · `R/RcppExports.R`
- [Solve core](https://github.com/ashiklom/rrtm/blob/master/src/solvearray.cpp): C++ solver · Compiled numerical routine for heavy radiative-transfer calculations · `src/solvearray.cpp`

### Data assets

Packaged reference data and generation sources

- [Package data](https://github.com/ashiklom/rrtm/blob/master/R/sysdata.rda): RData assets · Bundled internal datasets such as sensor responses · `R/sysdata.rda`
- [Reference tables](https://github.com/ashiklom/rrtm/blob/master/extdata/hapke-soil.dat): fixed inputs · External data files for soil, wood, and other references · `extdata/hapke-soil.dat`
- [Data prep](https://github.com/ashiklom/rrtm/blob/master/data-raw/dataspec.R): generation scripts · Reproducible scripts that build packaged data from raw sources · `data-raw/dataspec.R`

### Tooling

Tests, docs, and CI

- [Tests](https://github.com/ashiklom/rrtm/tree/master/tests/testthat): validation · Model and integration tests under testthat · `tests/testthat`
- [Docs](https://github.com/ashiklom/rrtm/blob/master/README.Rmd): documentation · README, manuals, and vignette workflow documentation · `README.Rmd`
- [CI/Lint](https://github.com/ashiklom/rrtm/blob/master/.github/workflows/R-CMD-check.yaml): quality · GitHub Actions checks and linting configuration · `.github/workflows/R-CMD-check.yaml`

## Connections

- R API → PROSPECT: exports · User calls reach leaf optics functions
- R API → 4SAIL: exports · User calls reach canopy model functions
- R API → PRO4SAIL: exports · User calls reach composition workflows
- R API → Hapke soil: exports · User calls reach soil reflectance functions
- R API → Other veg models: exports · User calls reach auxiliary vegetation models
- R API → Spectral response: exports · User calls reach spectral-response helpers
- PRO4SAIL → PROSPECT: uses · PRO4SAIL chains leaf spectra into canopy simulation
- PRO4SAIL → 4SAIL: uses · PRO4SAIL combines canopy transfer calculations
- PRO4SAIL → Hapke soil: uses · PRO4SAIL incorporates soil/background reflectance
- PROSPECT → Shared math: shares math · Leaf optics reuse shared numerical helpers
- 4SAIL → Shared math: shares math · Canopy model reuses geometry and scattering helpers
- Spectral response → Package data: loads · Sensor response helpers consume packaged response curves
- Data prep → Package data: builds · Data-raw scripts generate packaged RData assets
- Data prep → Reference tables: converts · Raw preparation ingests fixed reference tables
- Rcpp bridge → Solve core: bridges to · Rcpp exports call the compiled solver
- PROSPECT → Rcpp bridge: computes via · Leaf model delegates heavy numerics to native code
- 4SAIL → Rcpp bridge: computes via · Canopy model delegates heavy numerics to native code
- Tests → PROSPECT: covers · Tests exercise PROSPECT family behavior
- Tests → 4SAIL: covers · Tests exercise canopy scattering behavior
- Tests → Spectral response: covers · Tests exercise spectral response behavior
- Tests → Other veg models: covers · Tests exercise auxiliary model behavior
- Docs → PRO4SAIL: documents · README and vignette explain composed workflows
- CI/Lint → Tests: runs · CI executes package validation tests