# virtualplanetarylaboratory/atmos architecture

> Architecture diagram of the GitHub repository virtualplanetarylaboratory/atmos, 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/virtualplanetarylaboratory/atmos
- Repository: https://github.com/virtualplanetarylaboratory/atmos

## Overview

##### Project type and purpose
- Atmos is an open-source, domain-specific scientific modeling package written mostly in Fortran (F77/F90) with Bash orchestration. It couples two standalone atmospheric models—“PHOTO” (photochemical) and “CLIMA” (climate/radiative transfer)—in an iterative feedback loop to find a self-consistent, steady-state planetary atmosphere.
- Key indicators: a top‐level README describing two models, CLIMA/ and PHOTOCHEM/ folders containing Fortran sources, data directories of absorption cross-sections, input templates, makefiles (ClimaMake, PhotoMake), and orchestration scripts (RunModels.sh).

##### File structure
- Top‐level modules:
- CLIMA/ – climate model code subdivided into functional areas (CONVEC, RADTRANS, RRTM, SETUP, COUPLE, IO, DATA, INCLUDE, OBJECT_CLIMA)
- PHOTOCHEM/ – photochemical model code subdivided into DATA (cross-sections, flux files), INPUTFILES (templates & parameters), SUBROUTINES (core physics/chemistry routines), LINPACK/QUADPACK (numerical libraries), OBJECTFILES
- COUPLE/ – scripts and placeholders for coupling logic (fromPhoto2Clima.dat, fromClima2Photo.dat)
- Root scripts: RunModels.sh (interactive orchestrator), TestModels.sh, Makefiles for building each model
- Build system: GNU makefiles compile each module into an executable (Clima.run, Photo.run).
- Deployment: purely file-based; no external services. All I/O uses flat text files in prescribed folders.

##### README for insights
- The two models run alternately: photochemical → output coupling files → climate → output coupling files → photochemical … until convergence.
- RunModels.sh automates input propagation, compilation, execution, and iteration.
- Users choose from input templates (in PHOTOCHEM/INPUTFILES/TEMPLATES and CLIMA/IO/TEMPLATES).
- Each model has its own makefile; coupling toggles via ICOUPLE flags in input files.

##### Detail & essential elements
- Where include files (.inc) live and how they feed into the build.
- Template selection, code compilation, model invocation, coupling file exchange, and iteration control.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Orchestration Layer
    subgraph "Orchestration Layer"
        RunModels["RunModels.sh"]:::orchestration
        TestModels["TestModels.sh"]:::orchestration
    end

    %% Build System
    subgraph "Build System"
        PhotoMake["PhotoMake"]:::build
        ClimaMake["ClimaMake"]:::build
        Compiler["gfortran"]:::build
    end

    %% Photochemical Model
    subgraph "Photochemical Model (PHOTO)"
        PhotoMain["PhotoMain.f"]:::runtime
        PhotoSub["SUBROUTINES/"]:::lib
        PhotoLin["LINPACK/"]:::lib
        PhotoQuad["QUADPACK/"]:::lib
        PhotoData["DATA/"]:::data
        PhotoInput["INPUTFILES/TEMPLATES/"]:::data
        PhotoOut["OUTPUT/"]:::data
        PhotoObj["OBJECTFILES/"]:::data
    end

    %% Climate Model
    subgraph "Climate Model (CLIMA)"
        ClimaMain["ClimaMain.f"]:::runtime
        Convec["CONVEC/"]:::lib
        Radtrans["RADTRANS/"]:::lib
        RRTM["RRTM/"]:::lib
        Setup["SETUP/"]:::lib
        Prtcl["PRTCL/"]:::lib
        Plume["PLUME/"]:::lib
        ClimaIO["IO/"]:::data
        ClimaIOTmpl["IO/TEMPLATES/"]:::data
        ClimaData["DATA/"]:::data
        ClimaInc["INCLUDE/"]:::data
        ClimaObj1["OBJECT_CLIMA/"]:::data
        ClimaObj2["OBJECT_RRTM/"]:::data
    end

    %% Coupling Module
    subgraph "Coupling Module"
        CoupleF["couple.f"]:::runtime
        CoupleDir["COUPLE/"]:::data
        ClimaCouple["CLIMA/COUPLE/"]:::runtime
    end

    %% Shared Includes & I/O
    subgraph "Shared Includes & I/O"
        SharedInc["INCLUDE/"]:::data
        SharedIO["IO/"]:::data
    end

    %% Documentation
    subgraph "Documentation"
        Readme["README.md"]:::doc
        RunTxt["RunModel.txt"]:::doc
        Todo["to_do.md"]:::doc
        Docs["DOCUMENTS/"]:::doc
    end

    %% Process Flow
    RunModels -->|"selects templates"| PhotoInput
    RunModels -->|"selects templates"| ClimaIOTmpl
    RunModels -->|"invokes build"| PhotoMake
    PhotoMake -->|"compiles"| Compiler
    Compiler -->|"produces"| PhotoMain
    PhotoMain -->|"reads from"| PhotoData
    PhotoMain -->|"reads from"| PhotoInput
    PhotoMain -->|"runs and writes"| CoupleDir
    CoupleDir -->|"provides fromPhoto2Clima.dat"| ClimaMain
    ClimaMake -->|"compiles"| Compiler
    Compiler -->|"produces"| ClimaMain
    ClimaMain -->|"reads from"| ClimaData
    ClimaMain -->|"reads from"| ClimaIOTmpl
    ClimaMain -->|"runs and writes"| CoupleDir
    CoupleDir -->|"provides fromClima2Photo.dat"| PhotoMain
    CoupleDir -. loop .-> PhotoMain

    %% Test script
    TestModels --> RunModels

    %% Click Events
    click RunModels "https://github.com/virtualplanetarylaboratory/atmos/blob/master/RunModels.sh"
    click TestModels "https://github.com/virtualplanetarylaboratory/atmos/blob/master/TestModels.sh"
    click PhotoMake "https://github.com/virtualplanetarylaboratory/atmos/tree/master/PhotoMake"
    click ClimaMake "https://github.com/virtualplanetarylaboratory/atmos/tree/master/ClimaMake"
    click PhotoMain "https://github.com/virtualplanetarylaboratory/atmos/blob/master/PhotoMain.f"
    click PhotoSub "https://github.com/virtualplanetarylaboratory/atmos/tree/master/PHOTOCHEM/SUBROUTINES/"
    click PhotoLin "https://github.com/virtualplanetarylaboratory/atmos/tree/master/PHOTOCHEM/LINPACK/"
    click PhotoQuad "https://github.com/virtualplanetarylaboratory/atmos/tree/master/PHOTOCHEM/QUADPACK/"
    click PhotoData "https://github.com/virtualplanetarylaboratory/atmos/tree/master/PHOTOCHEM/DATA/"
    click PhotoInput "https://github.com/virtualplanetarylaboratory/atmos/tree/master/PHOTOCHEM/INPUTFILES/TEMPLATES/"
    click PhotoOut "https://github.com/virtualplanetarylaboratory/atmos/tree/master/PHOTOCHEM/OUTPUT/"
    click PhotoObj "https://github.com/virtualplanetarylaboratory/atmos/tree/master/PHOTOCHEM/OBJECTFILES/"
    click ClimaMain "https://github.com/virtualplanetarylaboratory/atmos/blob/master/ClimaMain.f"
    click Convec "https://github.com/virtualplanetarylaboratory/atmos/tree/master/CLIMA/CONVEC/"
    click Radtrans "https://github.com/virtualplanetarylaboratory/atmos/tree/master/CLIMA/RADTRANS/"
    click RRTM "https://github.com/virtualplanetarylaboratory/atmos/tree/master/CLIMA/RRTM/"
    click Setup "https://github.com/virtualplanetarylaboratory/atmos/tree/master/CLIMA/SETUP/"
    click Prtcl "https://github.com/virtualplanetarylaboratory/atmos/tree/master/CLIMA/PRTCL/"
    click Plume "https://github.com/virtualplanetarylaboratory/atmos/tree/master/CLIMA/PLUME/"
    click ClimaIO "https://github.com/virtualplanetarylaboratory/atmos/tree/master/CLIMA/IO/"
    click ClimaIOTmpl "https://github.com/virtualplanetarylaboratory/atmos/tree/master/CLIMA/IO/TEMPLATES/"
    click ClimaData "https://github.com/virtualplanetarylaboratory/atmos/tree/master/CLIMA/DATA/"
    click ClimaInc "https://github.com/virtualplanetarylaboratory/atmos/tree/master/CLIMA/INCLUDE/"
    click ClimaObj1 "https://github.com/virtualplanetarylaboratory/atmos/tree/master/CLIMA/OBJECT_CLIMA/"
    click ClimaObj2 "https://github.com/virtualplanetarylaboratory/atmos/tree/master/CLIMA/OBJECT_RRTM/"
    click CoupleF "https://github.com/virtualplanetarylaboratory/atmos/blob/master/couple.f"
    click CoupleDir "https://github.com/virtualplanetarylaboratory/atmos/tree/master/COUPLE/"
    click ClimaCouple "https://github.com/virtualplanetarylaboratory/atmos/tree/master/CLIMA/COUPLE/"
    click SharedInc "https://github.com/virtualplanetarylaboratory/atmos/tree/master/INCLUDE/"
    click SharedIO "https://github.com/virtualplanetarylaboratory/atmos/tree/master/IO/"
    click Readme "https://github.com/virtualplanetarylaboratory/atmos/blob/master/README.md"
    click RunTxt "https://github.com/virtualplanetarylaboratory/atmos/blob/master/RunModel.txt"
    click Todo "https://github.com/virtualplanetarylaboratory/atmos/blob/master/to_do.md"
    click Docs "https://github.com/virtualplanetarylaboratory/atmos/tree/master/DOCUMENTS/"

    %% Styles
    classDef orchestration fill:#FFA500,stroke:#333,stroke-width:1px
    classDef build fill:#87CEEB,stroke:#333,stroke-width:1px
    classDef runtime fill:#90EE90,stroke:#333,stroke-width:1px
    classDef data fill:#FFD700,stroke:#333,stroke-width:1px
    classDef lib fill:#DDA0DD,stroke:#333,stroke-width:1px
    classDef doc fill:#F0E68C,stroke:#333,stroke-width:1px
```
