# hycom/hycom-src architecture

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

- Interactive diagram: https://gitdiagram.com/hycom/hycom-src
- Repository: https://github.com/hycom/hycom-src

## Overview

HYCOM-src is the source for a layered ocean general-circulation model. The documented scientific workflow is primitive-equation horizontal dynamics with layered continuity, using an ALE vertical-coordinate approach; the tree also identifies initialization, time integration, physics, and restart/archive code. Parallel tiled communication and array I/O are substantial internal layers, and coupling interfaces are present as separate branches. The excerpts establish behavior for selected communication and I/O helpers, but not their callers or most model-module interactions, so those connections are omitted or marked unverified.

Main entry points: [`hycom.F90`](https://github.com/hycom/hycom-src/blob/master/hycom.F90) (HYCOM driver), [`mod_za.F90`](https://github.com/hycom/hycom-src/blob/master/mod_za.F90) (Array I/O interface), [`mod_momtum.F90`](https://github.com/hycom/hycom-src/blob/master/mod_momtum.F90) (Momentum dynamics), [`mod_tsadvc.F90`](https://github.com/hycom/hycom-src/blob/master/mod_tsadvc.F90) (Tracer advection)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_model["Ocean Model"]
  node_hycom["HYCOM driver<br/>[hycom.F90]"]
  node_init["Model initialization<br/>[inicon.F90]"]
  node_continuity["Layer continuity<br/>[cnuity.F90]"]
  node_vertical["ALE layers<br/>[hybgen.F90]"]
  node_momentum["Momentum dynamics<br/>[mod_momtum.F90]"]
  node_tracers["Tracer advection<br/>[mod_tsadvc.F90]"]
end

subgraph group_physics["Ocean Physics"]
  node_thermo["Equation of state<br/>[stmt_fns.h]"]
  node_mixing["Convection<br/>[convec.F90]"]
  node_kpp["KPP mixing<br/>[inikpp.F90]"]
  node_tides["Tidal forcing<br/>[mod_tides.F90]"]
  node_stokes["Stokes forcing<br/>[mod_stokes.F90]"]
end

subgraph group_compute["Parallel Runtime"]
  node_domain["Grid dimensions<br/>[dimensions.h]"]
  node_xc["MPI communication<br/>[mod_xc_mp.h]"]
  node_xcsm["Shared-memory communication<br/>[mod_xc_sm.h]"]
end

subgraph group_storage["Model I/O"]
  node_za["Array I/O interface<br/>[mod_za.F90]"]
  node_za_mpi["MPI array I/O<br/>[mod_za_mp.h]"]
  node_za_mp1["Message-passing I/O<br/>[mod_za_mp1.h]"]
  node_za_sm["Single-process I/O<br/>[mod_za_sm.h]"]
  node_za_tile["Per-tile I/O<br/>[mod_za_zt.h]"]
  node_restart[("Restart state<br/>[mod_restart.F90]")]
  node_archive["Model archive<br/>[mod_archiv.F90]"]
end

subgraph group_coupling["Coupling Interfaces"]
  node_nuopc["NUOPC coupling"]
  node_mct["MCT coupling<br/>[ocn_comp_mct.F90]"]
  node_navyespc["NAVYESPC coupling"]
end

node_user(("Model operator"))

node_user -.->|"runs model"| node_hycom
node_hycom -.->|"initializes"| node_init
node_hycom -.->|"advances layers"| node_continuity
node_hycom -.->|"updates coordinates"| node_vertical
node_hycom -.->|"computes dynamics"| node_momentum
node_hycom -.->|"advances tracers"| node_tracers
node_hycom -.->|"applies mixing"| node_mixing
node_hycom -.->|"uses mixing"| node_kpp
node_hycom -.->|"applies forcing"| node_tides
node_hycom -.->|"applies forcing"| node_stokes
node_momentum -.->|"uses constants"| node_thermo
node_tracers -.->|"uses constants"| node_thermo
node_hycom -.->|"uses communication"| node_xc
node_hycom -.->|"uses communication"| node_xcsm
node_hycom -.->|"uses dimensions"| node_domain
node_hycom -.->|"uses array I/O"| node_za
node_za -.->|"selects backend"| node_za_mpi
node_za -.->|"selects backend"| node_za_mp1
node_za -.->|"selects backend"| node_za_sm
node_za -.->|"selects backend"| node_za_tile
node_hycom -.->|"saves state"| node_restart
node_hycom -.->|"archives fields"| node_archive
node_hycom -.->|"couples through"| node_nuopc
node_hycom -.->|"couples through"| node_mct
node_hycom -.->|"couples through"| node_navyespc

click node_hycom "https://github.com/hycom/hycom-src/blob/master/hycom.F90"
click node_init "https://github.com/hycom/hycom-src/blob/master/inicon.F90"
click node_continuity "https://github.com/hycom/hycom-src/blob/master/cnuity.F90"
click node_vertical "https://github.com/hycom/hycom-src/blob/master/hybgen.F90"
click node_momentum "https://github.com/hycom/hycom-src/blob/master/mod_momtum.F90"
click node_tracers "https://github.com/hycom/hycom-src/blob/master/mod_tsadvc.F90"
click node_thermo "https://github.com/hycom/hycom-src/blob/master/stmt_fns.h"
click node_mixing "https://github.com/hycom/hycom-src/blob/master/convec.F90"
click node_kpp "https://github.com/hycom/hycom-src/blob/master/inikpp.F90"
click node_tides "https://github.com/hycom/hycom-src/blob/master/mod_tides.F90"
click node_stokes "https://github.com/hycom/hycom-src/blob/master/mod_stokes.F90"
click node_domain "https://github.com/hycom/hycom-src/blob/master/dimensions.h"
click node_xc "https://github.com/hycom/hycom-src/blob/master/mod_xc_mp.h"
click node_xcsm "https://github.com/hycom/hycom-src/blob/master/mod_xc_sm.h"
click node_za "https://github.com/hycom/hycom-src/blob/master/mod_za.F90"
click node_za_mpi "https://github.com/hycom/hycom-src/blob/master/mod_za_mp.h"
click node_za_mp1 "https://github.com/hycom/hycom-src/blob/master/mod_za_mp1.h"
click node_za_sm "https://github.com/hycom/hycom-src/blob/master/mod_za_sm.h"
click node_za_tile "https://github.com/hycom/hycom-src/blob/master/mod_za_zt.h"
click node_restart "https://github.com/hycom/hycom-src/blob/master/mod_restart.F90"
click node_archive "https://github.com/hycom/hycom-src/blob/master/mod_archiv.F90"
click node_nuopc "https://github.com/hycom/hycom-src/blob/master/CESMBETA/ocn_comp_nuopc_mod.F90"
click node_mct "https://github.com/hycom/hycom-src/blob/master/CESMBETA/ocn_comp_mct.F90"
click node_navyespc "https://github.com/hycom/hycom-src/blob/master/NAVYESPC/HYCOM_OceanComp.F90"

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_hycom,node_init,node_continuity,node_vertical,node_momentum,node_tracers toneBlue
class node_thermo,node_mixing,node_kpp,node_tides,node_stokes toneAmber
class node_domain,node_xc,node_xcsm toneMint
class node_za,node_za_mpi,node_za_mp1,node_za_sm,node_za_tile,node_restart,node_archive toneRose
class node_nuopc,node_mct,node_navyespc,node_user toneIndigo
```

## Components

### Ocean Model

- [HYCOM driver](https://github.com/hycom/hycom-src/blob/master/hycom.F90): `hycom.F90`
- [Model initialization](https://github.com/hycom/hycom-src/blob/master/inicon.F90): `inicon.F90`
- [Layer continuity](https://github.com/hycom/hycom-src/blob/master/cnuity.F90): `cnuity.F90`
- [ALE layers](https://github.com/hycom/hycom-src/blob/master/hybgen.F90): `hybgen.F90`
- [Momentum dynamics](https://github.com/hycom/hycom-src/blob/master/mod_momtum.F90): `mod_momtum.F90`
- [Tracer advection](https://github.com/hycom/hycom-src/blob/master/mod_tsadvc.F90): `mod_tsadvc.F90`

### Ocean Physics

- [Equation of state](https://github.com/hycom/hycom-src/blob/master/stmt_fns.h): `stmt_fns.h`
- [Convection](https://github.com/hycom/hycom-src/blob/master/convec.F90): `convec.F90`
- [KPP mixing](https://github.com/hycom/hycom-src/blob/master/inikpp.F90): `inikpp.F90`
- [Tidal forcing](https://github.com/hycom/hycom-src/blob/master/mod_tides.F90): `mod_tides.F90`
- [Stokes forcing](https://github.com/hycom/hycom-src/blob/master/mod_stokes.F90): `mod_stokes.F90`

### Parallel Runtime

- [Grid dimensions](https://github.com/hycom/hycom-src/blob/master/dimensions.h): `dimensions.h`
- [MPI communication](https://github.com/hycom/hycom-src/blob/master/mod_xc_mp.h): `mod_xc_mp.h`
- [Shared-memory communication](https://github.com/hycom/hycom-src/blob/master/mod_xc_sm.h): `mod_xc_sm.h`

### Model I/O

- [Array I/O interface](https://github.com/hycom/hycom-src/blob/master/mod_za.F90): `mod_za.F90`
- [MPI array I/O](https://github.com/hycom/hycom-src/blob/master/mod_za_mp.h): `mod_za_mp.h`
- [Message-passing I/O](https://github.com/hycom/hycom-src/blob/master/mod_za_mp1.h): `mod_za_mp1.h`
- [Single-process I/O](https://github.com/hycom/hycom-src/blob/master/mod_za_sm.h): `mod_za_sm.h`
- [Per-tile I/O](https://github.com/hycom/hycom-src/blob/master/mod_za_zt.h): `mod_za_zt.h`
- [Restart state](https://github.com/hycom/hycom-src/blob/master/mod_restart.F90): `mod_restart.F90`
- [Model archive](https://github.com/hycom/hycom-src/blob/master/mod_archiv.F90): `mod_archiv.F90`

### Coupling Interfaces

- [NUOPC coupling](https://github.com/hycom/hycom-src/blob/master/CESMBETA/ocn_comp_nuopc_mod.F90): `CESMBETA/ocn_comp_nuopc_mod.F90`
- [MCT coupling](https://github.com/hycom/hycom-src/blob/master/CESMBETA/ocn_comp_mct.F90): `CESMBETA/ocn_comp_mct.F90`
- [NAVYESPC coupling](https://github.com/hycom/hycom-src/blob/master/NAVYESPC/HYCOM_OceanComp.F90): `NAVYESPC/HYCOM_OceanComp.F90`

### Other components

- **Model operator**

## Connections

- Model operator → HYCOM driver: runs model
- HYCOM driver → Model initialization: initializes
- HYCOM driver → Layer continuity: advances layers
- HYCOM driver → ALE layers: updates coordinates
- HYCOM driver → Momentum dynamics: computes dynamics
- HYCOM driver → Tracer advection: advances tracers
- HYCOM driver → Convection: applies mixing
- HYCOM driver → KPP mixing: uses mixing
- HYCOM driver → Tidal forcing: applies forcing
- HYCOM driver → Stokes forcing: applies forcing
- Momentum dynamics → Equation of state: uses constants
- Tracer advection → Equation of state: uses constants
- HYCOM driver → MPI communication: uses communication
- HYCOM driver → Shared-memory communication: uses communication
- HYCOM driver → Grid dimensions: uses dimensions
- HYCOM driver → Array I/O interface: uses array I/O
- Array I/O interface → MPI array I/O: selects backend
- Array I/O interface → Message-passing I/O: selects backend
- Array I/O interface → Single-process I/O: selects backend
- Array I/O interface → Per-tile I/O: selects backend
- HYCOM driver → Restart state: saves state
- HYCOM driver → Model archive: archives fields
- HYCOM driver → NUOPC coupling: couples through
- HYCOM driver → MCT coupling: couples through
- HYCOM driver → NAVYESPC coupling: couples through
