# execlim/isca architecture

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

- Interactive diagram: https://gitdiagram.com/execlim/isca
- Repository: https://github.com/execlim/isca

## Overview

Isca is a framework for configuring and running idealized planetary-atmosphere simulations, with Python experiment definitions layered over model-build/run management and supporting diagnostics and post-processing. Users select or adapt a case, configure physics and diagnostics, run it, then analyze model output. The README documents these capabilities; sampled case scripts show experiment setup and calls to run, while the Experiment implementation and post-processing wiring were not sampled, so those connections are left unverified.

Main entry points: [`exp/test_cases`](https://github.com/execlim/isca/tree/master/exp/test_cases) (Case configurations), [`src/extra/python/isca/experiment.py`](https://github.com/execlim/isca/blob/master/src/extra/python/isca/experiment.py) (Experiment runner), [`postprocessing/plevel_interpolation`](https://github.com/execlim/isca/tree/master/postprocessing/plevel_interpolation) (Pressure interpolation), [`src/extra/python/isca/codebase.py`](https://github.com/execlim/isca/blob/master/src/extra/python/isca/codebase.py) (Codebase manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experiments["Experiment cases"]
  node_cases["Case configurations"]
  node_casecatalog["Planetary case variants"]
end

subgraph group_python["Python framework"]
  node_experiment["Experiment runner<br/>[experiment.py]"]
  node_codebase["Codebase manager<br/>[codebase.py]"]
  node_logging["Process logging<br/>[loghandler.py]"]
  node_utilities["Run utilities<br/>[util.py]"]
  node_diagtable["Diagnostic setup<br/>[diagtable.py]"]
  node_land["Land generation"]
end

subgraph group_model["Model runtime"]
  node_modelrun["Atmosphere simulation"]
  node_diagnostics["Model diagnostics"]
end

subgraph group_analysis["Output analysis"]
  node_qflux["Q-flux tools"]
  node_interpolation["Pressure interpolation"]
  node_combine["NetCDF combining<br/>[mppnccombine.c]"]
  node_grid["Grid remapping<br/>[create_xgrid.c]"]
end

node_user(("Model user"))

node_user -->|"selects and configures"| node_cases
node_cases -->|"runs experiment"| node_experiment
node_user -.->|"builds model"| node_codebase
node_experiment -.->|"launches run"| node_modelrun
node_modelrun -.->|"writes diagnostics"| node_diagnostics
node_diagnostics -.->|"supports interpolation"| node_interpolation
node_diagnostics -.->|"post-processes output"| node_combine
node_diagnostics -.->|"feeds analysis"| node_qflux
node_interpolation -.->|"uses grid remapping"| node_grid

click node_cases "https://github.com/execlim/isca/tree/master/exp/test_cases"
click node_experiment "https://github.com/execlim/isca/blob/master/src/extra/python/isca/experiment.py"
click node_codebase "https://github.com/execlim/isca/blob/master/src/extra/python/isca/codebase.py"
click node_logging "https://github.com/execlim/isca/blob/master/src/extra/python/isca/loghandler.py"
click node_utilities "https://github.com/execlim/isca/blob/master/src/extra/python/isca/util.py"
click node_diagtable "https://github.com/execlim/isca/blob/master/src/extra/python/isca/diagtable.py"
click node_land "https://github.com/execlim/isca/blob/master/src/extra/python/isca/land_generator_fn.py"
click node_qflux "https://github.com/execlim/isca/tree/master/src/extra/python/scripts/calculate_qflux"
click node_interpolation "https://github.com/execlim/isca/tree/master/postprocessing/plevel_interpolation"
click node_combine "https://github.com/execlim/isca/blob/master/postprocessing/mppnccombine.c"
click node_grid "https://github.com/execlim/isca/blob/master/src/shared/mosaic/create_xgrid.c"
click node_casecatalog "https://github.com/execlim/isca/tree/master/exp/test_cases"

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_cases,node_casecatalog,node_user toneBlue
class node_experiment,node_codebase,node_logging,node_utilities,node_diagtable,node_land toneAmber
class node_modelrun,node_diagnostics toneMint
class node_qflux,node_interpolation,node_combine,node_grid toneRose
```

## Components

### Experiment cases

- [Case configurations](https://github.com/execlim/isca/tree/master/exp/test_cases): `exp/test_cases`
- [Planetary case variants](https://github.com/execlim/isca/tree/master/exp/test_cases): `exp/test_cases`

### Python framework

- [Experiment runner](https://github.com/execlim/isca/blob/master/src/extra/python/isca/experiment.py): `src/extra/python/isca/experiment.py`
- [Codebase manager](https://github.com/execlim/isca/blob/master/src/extra/python/isca/codebase.py): `src/extra/python/isca/codebase.py`
- [Process logging](https://github.com/execlim/isca/blob/master/src/extra/python/isca/loghandler.py): `src/extra/python/isca/loghandler.py`
- [Run utilities](https://github.com/execlim/isca/blob/master/src/extra/python/isca/util.py): `src/extra/python/isca/util.py`
- [Diagnostic setup](https://github.com/execlim/isca/blob/master/src/extra/python/isca/diagtable.py): `src/extra/python/isca/diagtable.py`
- [Land generation](https://github.com/execlim/isca/blob/master/src/extra/python/isca/land_generator_fn.py): `src/extra/python/isca/land_generator_fn.py`

### Model runtime

- **Atmosphere simulation**
- **Model diagnostics**

### Output analysis

- [Q-flux tools](https://github.com/execlim/isca/tree/master/src/extra/python/scripts/calculate_qflux): `src/extra/python/scripts/calculate_qflux`
- [Pressure interpolation](https://github.com/execlim/isca/tree/master/postprocessing/plevel_interpolation): `postprocessing/plevel_interpolation`
- [NetCDF combining](https://github.com/execlim/isca/blob/master/postprocessing/mppnccombine.c): `postprocessing/mppnccombine.c`
- [Grid remapping](https://github.com/execlim/isca/blob/master/src/shared/mosaic/create_xgrid.c): `src/shared/mosaic/create_xgrid.c`

### Other components

- **Model user**

## Connections

- Model user → Case configurations: selects and configures
- Case configurations → Experiment runner: runs experiment
- Model user → Codebase manager: builds model
- Experiment runner → Atmosphere simulation: launches run
- Atmosphere simulation → Model diagnostics: writes diagnostics
- Model diagnostics → Pressure interpolation: supports interpolation
- Model diagnostics → NetCDF combining: post-processes output
- Model diagnostics → Q-flux tools: feeds analysis
- Pressure interpolation → Grid remapping: uses grid remapping
