diff --git a/full/docs/FLUX.md b/full/docs/FLUX.md new file mode 100644 index 00000000..2c923444 --- /dev/null +++ b/full/docs/FLUX.md @@ -0,0 +1,560 @@ +# Flux Exchange + +Authors for initial documentation: Bruce Wyman, V. Balaji, Sergey Malyshev + +## Overview + +Six modules couple the atmosphere, ocean, land, and sea-ice components through flux exchange: + +| Module | Purpose | +|---|---| +| atm_land_ice_flux_exchange | Exchange fluxes between atmosphere, land, and ice | +| atmos_ocean_fluxes_calc | Compute non-deposition gas fluxes between atmosphere and ocean | +| atmos_ocean_dep_fluxes_calc | Compute deposition gas fluxes between atmosphere and ocean | +| ice_ocean_flux_exchange | Exchange fluxes between ice and ocean | +| land_ice_flux_exchange | Exchange fluxes between land and ice | +| flux_exchange | Top-level module that initializes the flux-exchange modules and contains subroutines for stock computation | + +## Design Principles + +1. The flux exchange supports physically independent atmosphere, land, and sea-ice grids. + Ice and ocean must share the same physical grid but their MPI domain decompositions may differ. +2. The masked region of the land grid and the ice-ocean grid must tile each other, i.e., + every atmosphere grid cell is covered by either land or ice-ocean, but not both) +3. The masked regions of the ice and ocean grids must be identical. +4. The atmosphere, land, and ice grids exchange information through the surface exchange grid `xmap_sfc` using conservative interpolation (REGRID). +5. The land and ice grids exchange runoff data using the exchange grid `xmap_runoff`. +6. Ice-bottom to ocean transfer does not require an exchange grid because those grids are physically identical. Flux data are moved between PE layouts using `mpp_redistribute` when decompositions differ (REDIST), or copied directly when the decomposition is the same (DIRECT). +7. Atmospheric fluxes reach the ocean through the ice model: first atmosphere to ice via `flux_down_from_atmos`, then ice to ocean via `flux_ice_to_ocean`. +8. Each component model must expose a public data type containing the boundary fields needed by the coupler +(see [AtmosDataType.md](AtmosDataType.md), [LandDataType.md](LandDataType.md), [IceDataType.md](IceDataType.md), [OceanPublicType.md](OceanPublicType.md)). +9. Sensible heat flux and surface evaporation can depend implicitly on surface temperature. + Thus, land and sea-ice temperature updates must run on the atmospheric timestep. +10. Surface fluxes for all other tracers and for momentum are treated as explicit functions of the surface state. +11. The module is designed to support simultaneous implicit time integration on both sides of the surface interface. +12. Because of that implicit coupling, the diffusion part of the land and ice models must also run on the atmospheric timestep. +13. Additional tracer and gas-exchange fluxes are configured through `field_table` and named boundary-condition fields in the coupler boundary types. +14. Any field exchanged between components can be replaced by a constant or file-based value using FMS `data_override` and `data_table`. +15. `update_land_model_fast` and `update_ice_model_fast` must update the surface temperature each atmospheric timestep for the implicit diffusion scheme to be correct. + +## Grid Layout + +The three component grids tile the sphere. `|xxx|` marks a masked (inactive) grid point: + +``` + ATMOSPHERE |----|----|----|----|----|----|----|----| + LAND |---|---|---|---|xxx|xxx|xxx|xxx|xxx|xxx| + ICE |xxx|xxx|xxx|xxx|---|---|---|---|---|---| + OCEAN |xxx|xxx|xxx|xxx|---|---|---|---|---|---| +``` + +## Transfer Types + +There are three transfer modes used internally by the flux exchange: + +| Mode | When used | +|---|---| +| REGRID (xtype=1) | Physically distinct grids (atmosphere↔land, atmosphere↔ice); uses the exchange grid with conservative interpolation | +| REDIST (xtype=2) | Same physical grid, different MPI decomposition (ice↔ocean when slow_ice_with_ocean=.true.); uses mpp_redistribute | +| DIRECT (xtype=3) | Same physical grid, same MPI decomposition (ice↔ocean when not using slow_ice_with_ocean); data are copied directly | + +--- + +## Namelist Parameters (`flux_exchange_nml`) + +The following parameters can be set in `input.nml` under `&flux_exchange_nml`: + +| Parameter | Type | Default | Description | +|---|---|---|---| +| z_ref_heat | real | 2.0 | Reference height [m] for temperature and relative-humidity diagnostics (t_ref, rh_ref, del_h, del_q) | +| z_ref_mom | real | 10.0 | Reference height [m] for momentum diagnostics (u_ref, v_ref, del_m) | +| do_area_weighted_flux | logical | .false. | When .true., fluxes passed to the ocean are multiplied by the ice area fraction before redistribution, so the ocean receives the grid-cell-mean flux rather than the per-ice-area flux | +| debug_stocks | logical | .false. | Enables additional stock-conservation debug output | +| divert_stocks_report | logical | .false. | Redirects stock reporting to stocks.out rather than the standard log | +| do_runoff | logical | .true. | Enables interpolation of land runoff to the ocean; set to .false. to disable | +| do_forecast | logical | .false. | Enables forecast-mode behavior in the flux coupler | +| nblocks | integer | 1 | Number of blocks used to divide n_xgrid_sfc for OpenMP parallelism. In practice this is often set to match coupler_nml%atmos_nthreads; if left at 1 when threading is active, the model will emit a warning and reset it automatically | +| partition_fprec_from_lprec | logical | .false. | For atmosphere-override experiments where liquid and frozen precipitation are combined, converts liquid precipitation to snow when t_ref < tfreeze | +| scale_precip_2d | logical | .false. | Rescales Atm%lprec by a 2-D field read from data_table | + +--- + +## Data Override Capabilities + +> **Warning:** The original authors strongly advise against using data override capabilities for "non-experts". + +Any field in the lists below can be replaced at runtime with a constant or file-based value by adding a matching entry to `data_table`. A data override is applied only when a matching entry exists; otherwise the model-computed value is used unchanged. See [DATAOVERRIDE.md](DATAOVERRIDE.md) for the complete field listing organized by subroutine. + +### `sfc_boundary_layer` — atmosphere boundary to exchange grid + +| Field | Description | +|---|---| +| Atm%t_bot | Temperature at the lowest atmospheric level [K] | +| Atm%z_bot | Height of the lowest atmospheric level [m] | +| Atm%p_bot | Pressure at the lowest atmospheric level [Pa] | +| Atm%u_bot | Zonal wind at the lowest atmospheric level [m/s] | +| Atm%v_bot | Meridional wind at the lowest atmospheric level [m/s] | +| Atm%p_surf | Surface pressure [Pa] | +| Atm%slp | Sea-level pressure [Pa] | +| Atm%gust | Gustiness velocity added in quadrature to the resolved wind for surface flux calculations [m/s] | +| atm%fields%bc(n)%field(m)%values | Per-tracer atmospheric surface fields (e.g., tracer concentrations at the lowest model level); iterated over all entries in Atm%fields | + +### `sfc_boundary_layer` — ice boundary to exchange grid + +| Field | Description | +|---|---| +| Ice%t_surf | Ice/ocean surface skin temperature [K] | +| Ice%rough_mom | Surface roughness length for momentum over ice [m] | +| Ice%rough_heat | Surface roughness length for heat over ice [m] | +| Ice%rough_moist | Surface roughness length for moisture over ice [m] | +| Ice%albedo | Broadband surface albedo over ice [dimensionless] | +| Ice%albedo_vis_dir | Direct-beam visible-band albedo over ice [dimensionless] | +| Ice%albedo_nir_dir | Direct-beam near-infrared albedo over ice [dimensionless] | +| Ice%albedo_vis_dif | Diffuse visible-band albedo over ice [dimensionless] | +| Ice%albedo_nir_dif | Diffuse near-infrared albedo over ice [dimensionless] | +| Ice%u_surf | Zonal surface current/ice velocity [m/s] | +| Ice%v_surf | Meridional surface current/ice velocity [m/s] | +| Ice%ocean_fields | Coupler boundary-condition type holding ocean/ice-top gas and tracer fields used in atmosphere-ocean flux calculations | + +### `sfc_boundary_layer` — land boundary to exchange grid + +| Field | Description | +|---|---| +| Land%t_surf | Land surface (radiative) temperature [K] | +| Land%t_ca | Canopy air temperature — near-surface air temperature within the plant canopy [K] | +| Land%rough_mom | Surface roughness length for momentum over land [m] | +| Land%rough_heat | Surface roughness length for heat over land [m] | +| Land%albedo | Broadband surface albedo over land [dimensionless] | +| Land%tr | Surface tracer mixing ratio over land; one entry per exchanged tracer | +| Land%albedo_vis_dir | Direct-beam visible-band albedo over land [dimensionless] | +| Land%albedo_nir_dir | Direct-beam near-infrared albedo over land [dimensionless] | +| Land%albedo_vis_dif | Diffuse visible-band albedo over land [dimensionless] | +| Land%albedo_nir_dif | Diffuse near-infrared albedo over land [dimensionless] | + +### `sfc_boundary_layer` — exchange grid to `Land_Ice_Atmos_Boundary` + +These are the aggregated surface properties returned from land and ice to the atmosphere. + +| Field | Description | +|---|---| +| Land_Ice_Atmos_Boundary%t | Surface temperature (area-weighted over land and ice fractions) seen by the atmosphere [K] | +| Land_Ice_Atmos_Boundary%albedo | Broadband surface albedo [dimensionless] | +| Land_Ice_Atmos_Boundary%albedo_vis_dir | Direct-beam visible-band surface albedo [dimensionless] | +| Land_Ice_Atmos_Boundary%albedo_nir_dir | Direct-beam near-infrared surface albedo [dimensionless] | +| Land_Ice_Atmos_Boundary%albedo_vis_dif | Diffuse visible-band surface albedo [dimensionless] | +| Land_Ice_Atmos_Boundary%albedo_nir_dif | Diffuse near-infrared surface albedo [dimensionless] | +| Land_Ice_Atmos_Boundary%land_frac | Fraction of the atmospheric grid cell covered by land [dimensionless] | +| Land_Ice_Atmos_Boundary%dt_t | Implicit temperature correction applied to the atmosphere by the surface flux scheme [K] | +| Land_Ice_Atmos_Boundary%dt_tr | Implicit tracer mixing-ratio correction; one entry per exchanged tracer | +| Land_Ice_Atmos_Boundary%u_flux | Zonal wind stress on the atmosphere [Pa] | +| Land_Ice_Atmos_Boundary%v_flux | Meridional wind stress on the atmosphere [Pa] | +| Land_Ice_Atmos_Boundary%dtaudu | d(wind stress)/d(u) — implicit coupling coefficient for zonal momentum [Pa·s/m] | +| Land_Ice_Atmos_Boundary%dtaudv | d(wind stress)/d(v) — implicit coupling coefficient for meridional momentum [Pa·s/m] | +| Land_Ice_Atmos_Boundary%u_star | Friction velocity (surface turbulent velocity scale) [m/s] | +| Land_Ice_Atmos_Boundary%b_star | Buoyancy scale used in Monin-Obukhov similarity theory [m/s²] | +| Land_Ice_Atmos_Boundary%rough_mom | Roughness length for momentum [m] | + +### `flux_down_from_atmos` — atmosphere boundary to exchange grid + +| Field | Description | +|---|---| +| Atm%flux_sw | Total net shortwave flux at the surface [W/m²] | +| Atm%flux_sw_dir | Direct-beam component of the net shortwave flux [W/m²] | +| Atm%flux_sw_dif | Diffuse component of the net shortwave flux [W/m²] | +| Atm%flux_sw_down_vis_dir | Downward direct-beam visible shortwave flux [W/m²] | +| Atm%flux_sw_down_vis_dif | Downward diffuse visible shortwave flux [W/m²] | +| Atm%flux_sw_down_total_dir | Downward direct-beam broadband shortwave flux [W/m²] | +| Atm%flux_sw_down_total_dif | Downward diffuse broadband shortwave flux [W/m²] | +| Atm%flux_sw_vis | Net visible-band shortwave flux at the surface [W/m²] | +| Atm%flux_sw_vis_dir | Direct-beam component of the net visible shortwave flux [W/m²] | +| Atm%flux_sw_vis_dif | Diffuse component of the net visible shortwave flux [W/m²] | +| Atm%flux_lw | Net downward longwave flux at the surface [W/m²] | +| Atm%lprec | Liquid precipitation rate [kg/m²/s] | +| frac_precip | 2-D scaling field for liquid precipitation; applied when scale_precip_2d = .true. [dimensionless] | +| Atm%fprec | Frozen (solid) precipitation rate [kg/m²/s] | +| Atm%coszen | Cosine of the solar zenith angle [dimensionless] | +| Atm%Surf_Diff%dtmass | dt/mass — ratio of the timestep to the surface-layer air mass used in the implicit diffusion scheme [s·m²/kg] | +| Atm%Surf_Diff%delta_t | Forward-elimination temperature coefficient from the implicit vertical diffusion scheme [K] | +| Atm%Surf_Diff%dflux_t | d(sensible heat flux)/d(T_surf) — linearization coefficient for the implicit heat flux scheme [W/m²/K] | +| Atm%Surf_Diff%delta_tr | Forward-elimination coefficient for each tracer from the implicit diffusion scheme | +| Atm%Surf_Diff%dflux_tr | d(tracer flux)/d(tracer_surf) — linearization coefficient for the implicit tracer flux scheme | + +### `flux_down_from_atmos` — exchange grid to land boundary + +| Field | Description | +|---|---| +| Land_boundary%drag_q | Drag coefficient for moisture [dimensionless] | +| Land_boundary%lwdn_flux | Downward longwave radiation flux at the land surface [W/m²] | +| Land_boundary%cd_m | Drag coefficient for momentum over land [dimensionless] | +| Land_boundary%cd_t | Drag coefficient for heat over land [dimensionless] | +| Land_boundary%bstar | Buoyancy scale passed to the land model [m/s²] | +| Land_boundary%ustar | Friction velocity passed to the land model [m/s] | +| Land_boundary%wind | Wind speed at the lowest atmospheric level [m/s] | +| Land_boundary%z_bot | Height of the lowest atmospheric level above the land surface [m] | +| Land_boundary%t_flux | Sensible heat flux into the land surface [W/m²] | +| Land_boundary%lw_flux | Net longwave flux at the land surface [W/m²] | +| Land_boundary%sw_flux | Net shortwave flux at the land surface [W/m²] | +| Land_boundary%sw_flux_down_vis_dir | Downward direct-beam visible shortwave flux over land [W/m²] | +| Land_boundary%sw_flux_down_total_dir | Downward direct-beam broadband shortwave flux over land [W/m²] | +| Land_boundary%sw_flux_down_vis_dif | Downward diffuse visible shortwave flux over land [W/m²] | +| Land_boundary%sw_flux_down_total_dif | Downward diffuse broadband shortwave flux over land [W/m²] | +| Land_boundary%lprec | Liquid precipitation rate over land [kg/m²/s] | +| Land_boundary%fprec | Frozen precipitation rate over land [kg/m²/s] | +| Land_boundary%dhdt | d(sensible heat flux)/d(T_surf) — implicit coupling coefficient for land heat flux [W/m²/K] | +| Land_boundary%drdt | d(longwave flux)/d(T_surf) — implicit coupling coefficient for land longwave flux [W/m²/K] | +| Land_boundary%p_surf | Surface pressure over land [Pa] | +| Land_boundary%tr_flux | Flux of each exchanged tracer into the land surface [kg/m²/s] | +| Land_boundary%dfdtr | d(tracer flux)/d(tracer_surf) — implicit coupling coefficient for each land tracer flux | + +### `flux_down_from_atmos` — exchange grid to ice boundary + +| Field | Description | +|---|---| +| Ice_boundary%u_flux | Zonal wind stress on the ice surface [Pa] | +| Ice_boundary%v_flux | Meridional wind stress on the ice surface [Pa] | +| Ice_boundary%t_flux | Sensible heat flux into the ice surface [W/m²] | +| Ice_boundary%q_flux | Latent heat (moisture) flux into the ice surface [W/m²] | +| Ice_boundary%lw_flux | Net longwave flux at the ice surface [W/m²] | +| Ice_boundary%sw_flux_nir_dir | Direct-beam near-infrared shortwave flux over ice [W/m²] | +| Ice_boundary%sw_flux_vis_dir | Direct-beam visible shortwave flux over ice [W/m²] | +| Ice_boundary%sw_flux_nir_dif | Diffuse near-infrared shortwave flux over ice [W/m²] | +| Ice_boundary%sw_flux_vis_dif | Diffuse visible shortwave flux over ice [W/m²] | +| Ice_boundary%sw_down_vis_dir | Downward direct-beam visible shortwave flux over ice [W/m²] | +| Ice_boundary%sw_down_vis_dif | Downward diffuse visible shortwave flux over ice [W/m²] | +| Ice_boundary%sw_down_nir_dir | Downward direct-beam near-infrared shortwave flux over ice [W/m²] | +| Ice_boundary%sw_down_nir_dif | Downward diffuse near-infrared shortwave flux over ice [W/m²] | +| Ice_boundary%lprec | Liquid precipitation rate over ice [kg/m²/s] | +| Ice_boundary%fprec | Frozen precipitation rate over ice [kg/m²/s] | +| Ice_boundary%dhdt | d(sensible heat flux)/d(T_surf) — implicit coupling coefficient for ice heat flux [W/m²/K] | +| Ice_boundary%dedt | d(latent heat flux)/d(T_surf) — implicit coupling coefficient for ice moisture flux [W/m²/K] | +| Ice_boundary%drdt | d(longwave flux)/d(T_surf) — implicit coupling coefficient for ice longwave flux [W/m²/K] | +| Ice_boundary%coszen | Cosine of the solar zenith angle over ice [dimensionless] | +| Ice_boundary%p | Surface pressure over ice [Pa] | +| Ice_boundary%fluxes | Coupler boundary-condition type holding all per-tracer gas and deposition fluxes from atmosphere to ice | + +### `flux_up_to_atmos` — ice boundary to atmosphere + +| Field | Description | +|---|---| +| Ice%t_surf | Updated ice surface temperature after the ice model step [K] | + +### `flux_up_to_atmos` — land boundary to atmosphere + +| Field | Description | +|---|---| +| Land%t_ca | Updated canopy air temperature after the land model step [K] | +| Land%t_surf | Updated land surface temperature after the land model step [K] | +| Land%tr | Updated surface tracer mixing ratio over land; one entry per exchanged tracer | + +### `flux_land_to_ice` — land boundary to ice boundary + +Land runoff and calving are interpolated from the land grid onto the ice grid using the `xmap_runoff` exchange grid, then passed to the ocean via `flux_ice_to_ocean`. The `do_runoff` namelist flag must be `.true.` for this exchange to occur. + +| Field | Description | +|---|---| +| Land_Ice_Boundary%runoff | Liquid runoff (river discharge) from land [kg/m²/s] | +| Land_Ice_Boundary%calving | Solid calving flux (iceberg/glacier discharge) from land [kg/m²/s] | +| Land_Ice_Boundary%runoff_hflx | Sensible heat flux carried by liquid runoff [W/m²] | +| Land_Ice_Boundary%calving_hflx | Sensible heat flux carried by calving discharge [W/m²] | + +### `flux_ice_to_ocean` — ice boundary to ocean boundary + +All fluxes listed below are passed from the ice model to the ocean. When the ice and ocean PE decompositions differ (`slow_ice_with_ocean = .true.`), these fields are moved using `mpp_redistribute` (REDIST); otherwise they are copied directly (DIRECT). + +| Field | Description | +|---|---| +| Ice_Ocean_Boundary%u_flux | Zonal wind/ice stress on the ocean surface [Pa] | +| Ice_Ocean_Boundary%v_flux | Meridional wind/ice stress on the ocean surface [Pa] | +| Ice_Ocean_Boundary%t_flux | Sensible heat flux into the ocean [W/m²] | +| Ice_Ocean_Boundary%q_flux | Latent heat (freshwater) flux into the ocean [W/m²] | +| Ice_Ocean_Boundary%salt_flux | Salt flux from sea ice to the ocean (brine rejection/melting) [kg/m²/s] | +| Ice_Ocean_Boundary%lw_flux | Net longwave flux at the ocean surface [W/m²] | +| Ice_Ocean_Boundary%sw_flux_nir_dir | Direct-beam near-infrared shortwave flux into the ocean [W/m²] | +| Ice_Ocean_Boundary%sw_flux_nir_dif | Diffuse near-infrared shortwave flux into the ocean [W/m²] | +| Ice_Ocean_Boundary%sw_flux_vis_dir | Direct-beam visible shortwave flux into the ocean [W/m²] | +| Ice_Ocean_Boundary%sw_flux_vis_dif | Diffuse visible shortwave flux into the ocean [W/m²] | +| Ice_Ocean_Boundary%lprec | Liquid precipitation reaching the ocean surface [kg/m²/s] | +| Ice_Ocean_Boundary%fprec | Frozen precipitation reaching the ocean surface [kg/m²/s] | +| Ice_Ocean_Boundary%runoff | Liquid runoff from land routed to the ocean [kg/m²/s] | +| Ice_Ocean_Boundary%calving | Solid calving flux routed to the ocean [kg/m²/s] | +| Ice_Ocean_Boundary%runoff_hflx | Sensible heat flux carried by liquid runoff [W/m²] | +| Ice_Ocean_Boundary%calving_hflx | Sensible heat flux carried by calving [W/m²] | +| Ice_Ocean_Boundary%p | Surface atmospheric pressure at the ocean surface [Pa] | +| Ice_Ocean_Boundary%mi | Sea-ice mass per unit area; used for ice-pressure loading on the ocean [kg/m²] | +| Ice_Ocean_Boundary%ustar_berg | Friction velocity beneath icebergs [m/s]; present only when the iceberg module is active | +| Ice_Ocean_Boundary%area_berg | Fractional area of ocean cell covered by icebergs [dimensionless]; present only when the iceberg module is active | +| Ice_Ocean_Boundary%mass_berg | Iceberg mass per unit area [kg/m²]; present only when the iceberg module is active | +| Ice_Ocean_Boundary%fluxes | Coupler boundary-condition type holding all per-tracer gas fluxes from ice/atmosphere to ocean | + +### `flux_ocean_to_ice` — ocean boundary to ice boundary + +| Field | Description | +|---|---| +| Ocean_Ice_Boundary%u | Zonal ocean surface current velocity [m/s] | +| Ocean_Ice_Boundary%v | Meridional ocean surface current velocity [m/s] | +| Ocean_Ice_Boundary%t | Sea-surface temperature seen by the ice model [K] | +| Ocean_Ice_Boundary%s | Sea-surface salinity seen by the ice model [psu] | +| Ocean_Ice_Boundary%frazil | Frazil ice heat flux from the ocean to the ice [J/m²] | +| Ocean_Ice_Boundary%sea_level | Sea-surface height [m] | +| Ocean_Ice_Boundary%fields | Coupler boundary-condition type holding per-tracer ocean surface fields passed to the ice model | + +--- + +## Diagnostic Fields + +All fields below are registered in `atm_land_ice_flux_exchange.F90` inside `diag_field_init`. +The "Sent in" column identifies the subroutine that calls `send_data` for each field. + +### Static fields + +| Field | Description | Units | Sent in | +|---|---|---|---| +| land_mask | Fractional amount of land | — | sfc_boundary_layer | +| height2m | Height of the 2 m reference level (scalar axis) | m | sfc_boundary_layer | +| height10m | Height of the 10 m reference level (scalar axis) | m | sfc_boundary_layer | +| sftlf | Fraction of the grid cell occupied by land | 1 | sfc_boundary_layer | + +### Atmosphere grid fields + +| Field | Description | Units | Sent in | +|---|---|---|---| +| ice_mask | Fractional amount of sea ice | — | diag_sic | +| wind | Wind speed for flux calculations | m/s | sfc_boundary_layer | +| drag_moist | Drag coefficient for moisture | — | sfc_boundary_layer | +| drag_heat | Drag coefficient for heat | — | sfc_boundary_layer | +| drag_mom | Drag coefficient for momentum | — | sfc_boundary_layer | +| rough_moist | Surface roughness length for moisture | m | sfc_boundary_layer | +| rough_heat | Surface roughness length for heat | m | sfc_boundary_layer | +| rough_mom | Surface roughness length for momentum | m | sfc_boundary_layer | +| u_star | Friction velocity | m/s | sfc_boundary_layer | +| b_star | Buoyancy scale | m/s² | sfc_boundary_layer | +| q_star | Moisture scale | kg water/kg air | sfc_boundary_layer | +| thv_atm | Surface air virtual potential temperature | K | sfc_boundary_layer | +| thv_surf | Surface virtual potential temperature | K | sfc_boundary_layer | +| tau_x | Zonal wind stress | Pa | flux_down_from_atmos | +| tau_y | Meridional wind stress | Pa | flux_down_from_atmos | +| t_ocean | Surface temperature from ocean output | K | flux_up_to_atmos | +| t_surf | Surface temperature | K | flux_up_to_atmos | +| t_ca | Canopy air temperature | K | flux_up_to_atmos | +| z_atm | Height of the lowest atmospheric level | m | sfc_boundary_layer | +| p_atm | Pressure at the lowest atmospheric level | Pa | sfc_boundary_layer | +| slp | Sea-level pressure | Pa | sfc_boundary_layer | +| gust | Gustiness scale | m/s | sfc_boundary_layer | +| shflx | Sensible heat flux | W/m² | flux_up_to_atmos | +| lwflx | Net downward longwave flux | W/m² | flux_up_to_atmos | +| t_atm | Temperature at the lowest atmospheric level | K | sfc_boundary_layer | +| u_atm | Zonal wind component at the lowest atmospheric level | m/s | sfc_boundary_layer | +| v_atm | Meridional wind component at the lowest atmospheric level | m/s | sfc_boundary_layer | +| t_ref | Temperature at reference height (z_ref_heat) | K | sfc_boundary_layer | +| rh_ref | Relative humidity at reference height (z_ref_heat) | % | sfc_boundary_layer | +| rh_ref_cmip | Relative humidity at reference height (CMIP name) | % | sfc_boundary_layer | +| u_ref | Zonal wind component at reference height (z_ref_mom) | m/s | sfc_boundary_layer | +| v_ref | Meridional wind component at reference height (z_ref_mom) | m/s | sfc_boundary_layer | +| wind_ref | Wind speed at reference height (z_ref_mom) | m/s | sfc_boundary_layer | +| del_h | Reference-height interpolation factor for heat | — | sfc_boundary_layer | +| del_m | Reference-height interpolation factor for momentum | — | sfc_boundary_layer | +| del_q | Reference-height interpolation factor for moisture | — | sfc_boundary_layer | +| q_ref | Specific humidity at reference height (z_ref_heat) | kg/kg | sfc_boundary_layer | +| rough_scale | Topographic scaling factor for momentum drag | — | sfc_boundary_layer | +| evap | Evaporation rate | kg/m²/s | flux_up_to_atmos | +| co2_bot | CO₂ mixing ratio at the lowest level (from data_override) | ppmv | sfc_boundary_layer | + +### Per-tracer atmosphere grid fields + +The following fields are registered in a loop over all exchanged tracers (`n_exch_tr`). +`*` denotes the tracer name from the tracer table. + +| Field | Description | Units | Sent in | +|---|---|---|---| +| *_tot_con_atm | Deposition velocity of tracer at the atmosphere level | m/s | flux_up_to_atmos | +| *_tot_con_ref | Deposition velocity of tracer at reference height | m/s | flux_up_to_atmos | +| *_atm | Tracer mixing ratio at the lowest atmospheric level | tracer units | sfc_boundary_layer | +| *_surf | Tracer mixing ratio at the surface | tracer units | flux_up_to_atmos | +| *_flux | Surface flux of tracer | tracer units · kg air/(m²·s) | flux_up_to_atmos | +| *_ref | Tracer mixing ratio at reference height (skipped for sphum) | tracer units | sfc_boundary_layer | +| *_mol_flux | Molar flux of tracer | mol CO₂/(m²·s) or mol/(m²·s) | flux_up_to_atmos | +| *_atm_dvmr | CO₂ mixing ratio at lowest level in dry volume mixing ratio (CO₂ only) | mol CO₂/mol air | sfc_boundary_layer | +| *_surf_dvmr | CO₂ mixing ratio at the surface in dry volume mixing ratio (CO₂ only) | mol CO₂/mol air | flux_up_to_atmos | +| *_mol_flux_atm0 | Gross (one-way) molar flux of tracer | mol/(m²·s) | sfc_boundary_layer | + +### CMIP fields + +These fields follow CMIP variable naming conventions and are registered via +`register_cmip_diag_field_2d` (or `fms_diag_register_diag_field` when `use_AM3_physics` is defined). + +| Field | Description | Units | Sent in | +|---|---|---|---| +| tas | Near-surface air temperature | K | sfc_boundary_layer | +| uas | Eastward near-surface wind | m/s | sfc_boundary_layer | +| vas | Northward near-surface wind | m/s | sfc_boundary_layer | +| sfcWind | Near-surface wind speed | m/s | sfc_boundary_layer | +| huss | Near-surface specific humidity | 1 | sfc_boundary_layer | +| hurs | Near-surface relative humidity | % | sfc_boundary_layer | +| rhs | Near-surface relative humidity (alternate name) | % | sfc_boundary_layer | +| ts | Surface temperature | K | flux_up_to_atmos | +| psl | Sea-level pressure | Pa | sfc_boundary_layer | +| tauu | Surface downward eastward wind stress | Pa | flux_down_from_atmos | +| tauv | Surface downward northward wind stress | Pa | flux_down_from_atmos | +| hfss | Surface upward sensible heat flux | W/m² | flux_up_to_atmos | +| hfls | Surface upward latent heat flux | W/m² | flux_up_to_atmos | +| evspsbl | Evaporation | kg/m²/s | flux_up_to_atmos | +| tslsi | Surface temperature over land or sea ice | K | flux_up_to_atmos | +| tos | Sea-surface temperature | K | flux_up_to_atmos | +| sic | Sea ice area fraction | 1 | diag_sic | + +### Global integral fields + +These fields produce globally averaged scalar time-series output and are registered with +`register_global_diag_field` (only when `use_AM3_physics` is not defined). + +| Field | Description | Units | Sent in | +|---|---|---|---| +| evspsbl | Evaporation | mm/day | flux_up_to_atmos | +| ts | Surface temperature | K | flux_up_to_atmos | +| tas | Near-surface air temperature | K | sfc_boundary_layer | +| tasl | Near-surface air temperature (land only) | K | sfc_boundary_layer | +| hfss | Surface upward sensible heat flux | W/m² | flux_up_to_atmos | +| hfls | Surface upward latent heat flux | W/m² | flux_up_to_atmos | +| rls | Net longwave surface radiation | W/m² | flux_up_to_atmos | + +### Tiled land fields + +These fields are registered on the land axes (only on land PEs) using `register_tiled_diag_field` or, +in the legacy land path, `fms_diag_register_diag_field`. + +| Field | Description | Units | Sent in | +|---|---|---|---| +| t_ref | Temperature at reference height over land | K | sfc_boundary_layer | +| q_ref | Specific humidity at reference height over land | kg/kg | sfc_boundary_layer | +| rh_ref | Relative humidity at reference height over land | % | sfc_boundary_layer | +| u_ref | Zonal wind component at reference height over land | m/s | sfc_boundary_layer | +| v_ref | Meridional wind component at reference height over land | m/s | sfc_boundary_layer | +| evap | Evaporation rate over land | kg/m²/s | flux_up_to_atmos | +| shflx | Sensible heat flux over land | W/m² | flux_up_to_atmos | +| tasLut | Near-surface air temperature on land-use tile (reference height above displacement height) | K | sfc_boundary_layer | +| hussLut | Near-surface specific humidity on land-use tile | 1 | sfc_boundary_layer | +| *_tot_con_atm | Deposition velocity of tracer (new-land path only) | m/s | flux_up_to_atmos | +| *_tot_con_ref | Deposition velocity of tracer at reference height (new-land path only) | m/s | flux_up_to_atmos | +| *_flux | Surface flux of tracer over land | tracer units · kg air/(m²·s) | flux_up_to_atmos | +| *_mol_flux | Molar flux of tracer over land | mol CO₂/(m²·s) or mol/(m²·s) | flux_up_to_atmos | +| *_ref | Tracer mixing ratio at reference height over land (skipped for sphum; new-land path only) | tracer units | sfc_boundary_layer | + +--- + +## Required Variables in Component Data Types + +The sections below list the minimum fields each component must provide to the flux exchange. +See the linked data-type documentation for full field descriptions. + +### Atmosphere (`atmos_data_type`) + +```fortran +type(atmos_data_type) :: Atm +real, dimension(:) :: Atm%lon_bnd, Atm%lat_bnd ! grid-box corner coordinates [radians] +real, dimension(:,:) :: Atm%t_bot, Atm%q_bot, Atm%z_bot, Atm%p_bot, & + Atm%u_bot, Atm%v_bot, & ! lowest-level state + Atm%p_surf, Atm%slp, Atm%gust, & + Atm%flux_sw, Atm%flux_lw, Atm%lprec, Atm%fprec, Atm%coszen +integer, dimension(4) :: Atm%axes ! diag_manager axis IDs: x, y, z_full, z_half +``` + +- `Atm%lon_bnd`, `Atm%lat_bnd`: Grid-box corner coordinates in radians; must be monotonic. +- `Atm%t_bot` … `Atm%v_bot`: State at the lowest atmospheric model level; primary inputs to `sfc_boundary_layer`. +- `Atm%p_surf`, `Atm%slp`, `Atm%gust`: Surface pressure, sea-level pressure, and gustiness factor. +- `Atm%flux_sw`, `Atm%flux_lw`, `Atm%lprec`, `Atm%fprec`, `Atm%coszen`: Surface radiative and precipitation forcing passed to land and ice by `flux_down_from_atmos`. +- `Atm%axes`: Axis IDs returned by `diag_axis_init`; required for diagnostic registration. + +The following fields support implicit time-stepping between the atmosphere and the surface models: + +```fortran +type(surf_diff_type) :: Atm%Surf_Diff +real, dimension(:,:) :: Atm%Surf_Diff%dtmass, & ! dt/mass [s·m²/kg] + Atm%Surf_Diff%delta_t, & ! forward-elim temperature coefficient [K] + Atm%Surf_Diff%delta_q, & ! forward-elim moisture coefficient [kg/kg] + Atm%Surf_Diff%dflux_t, & ! d(heat flux)/d(T_surf) [W/m²/K] + Atm%Surf_Diff%dflux_q ! d(moisture flux)/d(q_surf) [kg/m²/s / (kg/kg)] +``` + +### Land (`land_data_type`) + +```fortran +type(land_data_type) :: Land +real, dimension(:) :: Land%lon_bnd, Land%lat_bnd +logical, dimension(:,:,:) :: Land%mask, Land%glacier +real, dimension(:,:,:) :: Land%tile_size, Land%t_surf, Land%t_ca, Land%q_ca, & + Land%albedo, Land%rough_mom, Land%rough_heat, & + Land%stomatal, Land%snow, Land%water, Land%max_water +``` + +- `Land%lon_bnd`, `Land%lat_bnd`: Grid-box corner coordinates in radians; must be monotonic. +- `Land%mask`: Land-sea mask; `.true.` over land points. +- `Land%glacier`: Glacier mask; `.true.` over glacier points. +- `Land%tile_size`: Fractional area of each land tile within the atmospheric grid cell [0–1]. +- `Land%t_surf`, `Land%albedo`, `Land%rough_mom`, `Land%rough_heat`: Surface state used for turbulent flux and radiation calculations. +- `Land%t_ca`, `Land%q_ca`: Canopy air temperature and specific humidity; returned to the atmosphere by `flux_up_to_atmos`. +- `Land%stomatal`, `Land%snow`, `Land%water`, `Land%max_water`: Additional surface properties used in flux parameterizations. + +### Ice (`ice_data_type`) + +```fortran +type(ice_data_type) :: Ice +real, dimension(:) :: Ice%lon_bnd, Ice%lat_bnd, Ice%lon_bnd_uv, Ice%lat_bnd_uv +logical, dimension(:,:,:) :: Ice%mask, Ice%mask_uv, Ice%ice_mask +real, dimension(:,:,:) :: Ice%part_size, Ice%part_size_uv +``` + +- All boundary arrays are in radians and must be monotonic. +- `Ice%mask`, `Ice%mask_uv`: Ocean-land masks for tracer and momentum points, respectively. +- `Ice%ice_mask`: Optional explicit sea-ice mask. +- `Ice%part_size`, `Ice%part_size_uv`: Fractional area of each ice thickness category. + +Fields on the ice **top** (atmosphere–ice interface), provided to the atmosphere each fast timestep: + +```fortran +real, dimension(:,:,:) :: Ice%t_surf, Ice%albedo, Ice%rough_mom, & + Ice%rough_heat, Ice%rough_moist, Ice%u_surf, Ice%v_surf +``` + +Fields on the ice **bottom** (ice–ocean interface), populated by `flux_down_from_atmos` and `flux_land_to_ice`, then passed to the ocean by `flux_ice_to_ocean`: + +```fortran +real, dimension(:,:,:) :: Ice%flux_u, & ! zonal wind stress [Pa] + Ice%flux_v, & ! meridional wind stress [Pa] + Ice%flux_t, & ! sensible heat flux [W/m²] + Ice%flux_q, & ! moisture flux [kg/m²/s] + Ice%flux_salt, & ! salt flux [kg/m²/s] + Ice%flux_lw, & ! net longwave flux [W/m²] + Ice%flux_sw_vis_dir, & ! direct visible SW [W/m²] + Ice%flux_sw_vis_dif, & ! diffuse visible SW [W/m²] + Ice%flux_sw_nir_dir, & ! direct near-IR SW [W/m²] + Ice%flux_sw_nir_dif, & ! diffuse near-IR SW [W/m²] + Ice%lprec, & ! liquid precipitation [kg/m²/s] + Ice%fprec, & ! frozen precipitation [kg/m²/s] + Ice%runoff, & ! liquid runoff from land [kg/m²/s] + Ice%calving, & ! solid discharge from land [kg/m²/s] + Ice%runoff_hflx, & ! heat flux carried by runoff [W/m²] + Ice%calving_hflx, & ! heat flux carried by calving [W/m²] + Ice%p_surf ! atmospheric surface pressure [Pa] +``` + +Optional iceberg fields, allocated only when the iceberg module is active: + +```fortran +real, dimension(:,:) :: Ice%ustar_berg, & ! iceberg friction velocity [m/s] + Ice%area_berg, & ! iceberg area fraction [dimensionless] + Ice%mass_berg ! iceberg mass per unit area [kg/m²] +``` + +### Ocean (`ocean_public_type`) + +```fortran +type(ocean_public_type) :: Ocean +real, dimension(:,:) :: Ocean%t_surf, Ocean%s_surf, & + Ocean%u_surf, Ocean%v_surf, & + Ocean%frazil, Ocean%sea_lev +``` + +- `Ocean%t_surf`, `Ocean%s_surf`: Sea-surface temperature [K] and salinity [ppt]; passed to the ice model as `Ocean_Ice_Boundary%t` and `%s`. +- `Ocean%u_surf`, `Ocean%v_surf`: Surface ocean currents [m/s]; passed to ice as `Ocean_Ice_Boundary%u`, `%v`. Staggering relative to tracer points is indicated by `Ocean%stagger`. +- `Ocean%frazil`: Accumulated heating from frazil ice formation since the last coupling step [J/m²]; passed to ice as `Ocean_Ice_Boundary%frazil`. +- `Ocean%sea_lev`: Sea level corrected for surface pressure [m]; passed to ice as `Ocean_Ice_Boundary%sea_level`. diff --git a/full/docs/README.md b/full/docs/README.md new file mode 100644 index 00000000..20909c7b --- /dev/null +++ b/full/docs/README.md @@ -0,0 +1,297 @@ +# FMSCoupler — Full Coupled Model + +## Introduction + +`coupler_main` (`coupler_main.F90`) is the top-level driver for the fully coupled Earth-system model that contains +the main time-stepping loops and calls to exchange fluxes between the atmosphere, ocean, land, and sea-ice components. +Each component can be modeled on an independent grid with a different MPI domain decomposition. + +--- + +## Model Component State Types + +The following derived types hold the instantaneous state for each component: + +| Variable | Type | Description | +|---|---|---| +| Atm | atmos_data_type | Atmosphere model state at the current timestep | +| Land | land_data_type | Land model (LM4) state at the current timestep | +| Ice | ice_data_type | Sea-ice model (SIS2) state at the current timestep | +| Ocean | ocean_public_type | Public ocean model (MOM6) state; target for the Ocean_state pointer | +| Ocean_state | ocean_state_type (pointer) | Opaque pointer to the full MOM6 interior state | + +See [AtmosDataType.md](AtmosDataType.md), +[LandDataType.md](LandDataType.md), +[IceDataType.md](IceDataType.md), +[OceanPublicType.md](OceanPublicType.md), and +[OceanStateType.md](OceanStateType.md) for detailed field-level documentation. + +--- + +## Boundary Exchange Types + +These derived types hold the fields exchanged at each component interface: + +| Variable | Type | Description | +|---|---|---| +| Atmos_land_boundary | atmos_land_boundary_type | Fields exchanged between atmosphere and land | +| Atmos_ice_boundary | atmos_ice_boundary_type | Fields exchanged between atmosphere and sea ice | +| Land_Ice_Atmos_Boundary | land_ice_atmos_boundary_type | Aggregated surface state returned from land and ice to the atmosphere | +| Land_ice_boundary | land_ice_boundary_type | Runoff and calving fields passed from land to ice | +| Ice_ocean_boundary | ice_ocean_boundary_type | All fluxes passed from ice to the ocean | +| Ocean_ice_boundary | ocean_ice_boundary_type | Ocean surface state (SST, currents, frazil) passed up to the ice model | +| ice_ocean_driver_CS | ice_ocean_driver_type (pointer) | Control parameters for the combined ice–ocean driver | + +See [FLUX.md](FLUX.md) for details on flux exchange. + +--- + +## Time Integration + +There are two nested time-integration loops in coupler_main: + +- **Slow (coupled) loop** (`nc = 1 … num_cpld_calls`): +advances the ocean by one coupled timestep `dt_cpld`. +- **Fast (atmospheric) loop** (`na = 1 … num_atmos_calls`): +advances the atmosphere, land surface, and fast sea ice by one atmospheric timestep `dt_atmos`. +The fast loop is nested inside the slow loop. + +### Fast Loop + +Heat and moisture are exchanged between the atmosphere and the surface (land/ice) +using a tridiagonal scheme for implicit vertical diffusion. The main calls are: + +1. `coupler_update_atmos_model_down` — forward (downward) sweep from the atmospheric top to the surface. +2. `coupler_update_atmos_model_radiation` - call the radiation driver (see below for do_concurrent_radiation) +3. `coupler_flux_down_from_atmos` — transfer forward-elimination coefficients to the land and ice models. +4. `coupler_update_land_model_fast` and `coupler_update_ice_model_fast` — in addition to updating hydrology + and canopy physics, update surface temperature. +5. `coupler_flux_up_to_atmos` — apply implicit surface-flux corrections using the updated surface temperatures. +6. `coupler_update_atmos_model_up` — back-substitution (upward sweep), update convection and large-scale condensation. + +When `do_concurrent_radiation = .true.`, steps 1 with steps 3-6 will run simultaneously with +`coupler_update_atmos_model_radiation` using OpenMP threading. +(see the `atmos_nthreads` and `radiation_nthreads` namelist variables). + +### Slow Loop + +When `concurrent = .true.`, the ocean model is updated concurrently with the atmosphere and is one coupling step behind. +With MOM6 model, it is recommended to set `use_lag_fluxes = .false.` so that `flux_ice_to_ocean` +is called after `update_ocean_model`. For older ocean models, it is recommended to set `use_lag_fluxes = .true.` +to call `flux_ice_to_ocean` before the ocean model update. + +** Miscellaneous +Sea-ice physics can be split into two timescales that can run on different MPI PE sets: + +- **Fast ice** (`Ice%fast_ice_pe`): +thermodynamics and surface-flux coupling at the atmospheric timestep. Fast ice always runs on a subset of the atmosphere PEs. +- **Slow ice** (`Ice%slow_ice_pe`): +dynamics, freezing/melting, and transport at the coupled (ocean) timestep. The placement of the +slow-ice PEs depends on the `slow_ice_with_ocean` namelist variable: + - `slow_ice_with_ocean = .false.` (default): slow and fast ice share the same PEs. + - `slow_ice_with_ocean = .true.`: slow ice runs on the ocean PEs. In this case, `Ice%pelist` is the union + of the fast (atmosphere) and slow (ocean) PE sets. + +The flag `concurrent_ice = .true.` runs fast- and slow-ice processes concurrently and requires `slow_ice_with_ocean = .true.`. +The flag `combine_ice_and_ocean = .true.` advances the slow ice and ocean together on the ocean PEs. +Both `concurrent_ice` and `slow_ice_with_ocean` must be `.true.` to use `combine_ice_and_ocean`. + +These options are not commonly used. + +--- + +## Pseudocode + +For the most common setting where `concurrent = .true.`, `use_lag_forces = .false.`, +`concurrent_ice = .false.`, `do_concurrent_radiation = .false.`, `do_atm = .true.`, +`do_land = .true.`, `do_ice = .true.`, and `do_ocean = .true.`: + +```fortran +call initialization routines + +do nc = 1, num_cpld_calls + + ! Redistribute Ocean surface states to Ocean_ice_boundary + if (Ocean%is_ocean_pe) then + synchronize ice and ocean pes + call flux_ocean_to_ice(...) + end if + + ! Map Ocean_ice_boundary to Ice + call unpack_ocean_ice_boundary(...) + + ! Map Ice%sCS (slow control structure) to Ice%fCS (fast constrol structure) + call exchange_slow_to_fast_ice(...) + + ! Prepare ice surface fields (albedo, T, etc.) + call set_ice_surface_fields(...) + + ! generate suface exchange grid between land, ice, and atm + call generate_sfc_xgrid(...) + + do na = 1, num_atmos_calls + + ! Copy Atm%tr_bot -> Atm%fields for gas-exchange tracers + call atmos_tracer_driver_gather_data(Atm%fields, Atm%tr_bot) + + ! Compute surface exchange coefficients and turbulent fluxes on the exchange grid + call sfc_boundary_layer(...) + + ! Atmosphere dynamical core (FV3) + call update_atmos_model_dynamics(...) + + ! Update radiation + call update_atmos_model_radiation(...) + + ! Downward sweep of the implicit tridiagonal diffusion + call update_atmos_model_down(...) + + ! Apply implicit atmosphere diffusion correction; pass updated surface fluxes + ! (heat, moisture, momentum) to land and ice boundary types + call flux_down_from_atmos(...) + + ! Fast land physics (hydrology, canopy, soil temperature) + call update_land_model_fast(...) + + ! Fast ice thermodynamics (surface energy balance, melt ponds) + call update_ice_model_fast(...) + + ! Recompute surface fluxes using updated land/ice surface temperatures + call flux_up_to_atmos(...) + + ! Back-substitution (upward) sweep; convection; large-scale condensation + call update_atmos_model_up(...) + + ! Remap atmosphere gas/tracer fields onto exchange grid; + ! compute air-sea deposition fluxes; deallocate exchange-grid arrays + call flux_atmos_to_ocean(...) + call flux_ex_arrays_dealloc() + + ! Advance atmosphere diagnostics and tracer state + call update_atmos_model_state(...) + + end do ! fast loop + + ! Slow land physics (routing, carbon, DGVM) + call update_land_model_slow(...) + + ! Interpolate land runoff, calving, and heat fluxes onto ice grid + call flux_land_to_ice(...) + + ! Reset fast-ice accumulators; copy Land_ice_boundary into Ice + call ice_model_fast_cleanup(...) + call unpack_land_ice_boundary(...) + + ! Exchange fast-ice averages to slow-ice side + call exchange_fast_to_slow_ice(...) + + ! Slow ice physics (dynamics, freezing/melting, transport) + call update_ice_model_slow(...) + + if (Ocean%is_ocean_pe) then + + ! Interpolate ice-bottom fluxes onto the ocean grid -> Ice_ocean_boundary + call flux_ice_to_ocean(...) + + ! Advance ocean state by dt_cpld using Ice_ocean_boundary forcing + call update_ocean_model(...) + endif + +end do + +call ending routines +``` + +--- + +## Setting the Model Start Time + +The model start time (`Time_start`) is determined in `coupler_init` by the following priority: + +1. If `date_init` exists in the `diag_table`, it is used to set the model start time. +2. If `date_init` is not found in the `diag_table` and `INPUT/coupler.res` exists, + the start date and calendar type are read from that file. These values can be overridden if + `force_date_from_namelist = .true.` and `current_date` with `calendar_type` are defined in `coupler_nml`. +3. If neither source is available, the start date is taken from `current_date` and `calendar` in `coupler_nml`. + +--- + +## MPI Parallelization + +The number of MPI processing elements (PEs) for each model component is specified in `coupler_nml`: + +```fortran +&coupler_nml + atmos_npes = 10 + ocean_npes = 10 + ice_npes = 10 + land_npes = 10 +/ +``` + +Constraints: +- At least one of `atmos_npes` or `ocean_npes` must be specified. +- `land_npes <= atmos_npes` +- `ice_npes <= atmos_npes` +- `atmos_npes + ocean_npes = npes` (total PE count determined by FMS) + +When `concurrent = .true.`, +- The atmosphere and ocean have distinct PE lists. +- `land%pelist` is a subset of `atm%pelist`. +- `ice%pelist = ice%slow_pelist = ice%fast_pelist`, which are a subset of `atm%pelist`. + +--- + +## OpenMP Parallelization + +OpenMP thread counts are also configured in `coupler_nml`: + +```fortran +&coupler_nml + do_concurrent_radiation = .true. + use_hyper_thread = .true. + conc_nthreads = 2 + atmos_nthreads = 1 + radiation_nthreads = 1 + ocean_nthreads = 1 +/ +``` + +The model must be compiled with OpenMP for OpenMP threading. +When using the FRE build system, the model will compile with OpenMP +if the target contains the `-openmp` suffix (e.g., `prod-openmp`). + +When `do_concurrent_radiation = .true.`, `conc_nthreads` is set to 2: +thread 0 on the atmosphere PEs runs atmosphere dynamics and physics, while thread 1 runs the radiation code. +When `do_concurrent_radiation = .false.`, radiation runs sequentially after the atmosphere update. +The `atmos_nthreads` variable controls the number of threads used within the atmosphere dynamics itself. + +--- + +## Time Variables + +| Variable | Type | Description | +|---|---|---| +| Time_step_atmos | FmsTime_type | timestep for the fast-loop (atmospheric) | +| Time_step_cpld | FmsTime_type | timestep for the one slow-loop (coupled) | +| Time_atmos | FmsTime_type | Current model time tracked in the fast loop | +| Time_ocean | FmsTime_type | Current model time tracked for the ocean | +| Time_flux_ice_to_ocean | FmsTime_type | Time when flux was exchanged from ice to ocean | +| Time_flux_ocean_to_ice | FmsTime_type | Time when flux was exchange ocean to ice | +| Time_restart | FmsTime_type | Next scheduled time for writing intermediate restarts | +| Time_restart_current | FmsTime_type | Time at which the most recent intermediate restart was written | +| Time_start | FmsTime_type | Model start time | +| Time_end | FmsTime_type | Model end time | + +--- + +## Loop Counters + +| Variable | Type | Description | +|---|---|---| +| num_atmos_calls | integer | Number of iterations in the fast loop | +| na | integer | Do-loop counter for the fast loop | +| num_cpld_calls | integer | Number of coupled timesteps in the run | +| nc | integer | Do-loop counter for the slow loop | +| current_timestep | integer | Total number of fast-loop iterations during runtime, + equal to `(nc-1)*num_atmos_calls + na` | diff --git a/full/docs/atmos_data_type.md b/full/docs/atmos_data_type.md new file mode 100644 index 00000000..21144bb9 --- /dev/null +++ b/full/docs/atmos_data_type.md @@ -0,0 +1,115 @@ +# `atmos_data_type` +is the main derived type holding fields and states of the atmosphere. Below are all the fields in atmos_data_type: + +## Grid metadata + +| Field | Type | Description | +|---|---|---| +| Atm%domain | type(domain2d) | FMS domain decomposition object for the atmosphere; defines the MPI tile layout and halo widths | +| Atm%axes | integer(4) | Diag-manager axis indices for x, y, pfull, and phalf; used when registering and sending diagnostic fields | +| Atm%lon_bnd | real(:,:) | Longitude of grid-box corners on the local compute domain [radians] | +| Atm%lat_bnd | real(:,:) | Latitude of grid-box corners on the local compute domain [radians] | +| Atm%lon | real(:,:) | Longitude of grid-box centres on the local compute domain [radians] | +| Atm%lat | real(:,:) | Latitude of grid-box centres on the local compute domain [radians] | +| Atm%grid | type(grid_box_type) | Grid geometry needed for second-order conservative remapping on the cubic-sphere exchange grid (see below) | +| Atm%maskmap | logical(:,:) | Pointer to a mask indicating which logical processors are active for ocean code; processors covering all-land points may not be assigned to physical PEs. Dummy field — must be present for compilation but need not be set | + +## Atmospheric state at the bottom-most level + +| Field | Type | Description | +|---|---|---| +| Atm%t_bot | real(:,:) | Temperature at the lowest model level [K] | +| Atm%tr_bot | real(:,:,:) | Tracer mixing ratios at the lowest model level; third dimension indexes the tracer table (specific humidity sphum is always present) | +| Atm%z_bot | real(:,:) | Height of the lowest model level above the surface [m] | +| Atm%p_bot | real(:,:) | Pressure at the lowest model level [Pa] | +| Atm%u_bot | real(:,:) | Zonal wind component at the lowest model level [m/s] | +| Atm%v_bot | real(:,:) | Meridional wind component at the lowest model level [m/s] | +| Atm%p_surf | real(:,:) | Surface pressure [Pa] | +| Atm%slp | real(:,:) | Sea-level pressure [Pa] | +| Atm%gust | real(:,:) | Gustiness factor — a minimum wind speed added in quadrature to the resolved wind to account for sub-grid convective gusts in surface flux calculations [m/s] | +| Atm%coszen | real(:,:) | Cosine of the solar zenith angle; used to weight shortwave fluxes and partition direct vs. diffuse radiation [dimensionless] | + +### Shortwave and longwave fluxes + +| Field | Type | Description | +|---|---|---| +| Atm%flux_sw | real(:,:) | Total net shortwave flux at the surface (absorbed by the surface) [W/m²] | +| Atm%flux_sw_dir | real(:,:) | Direct-beam component of the net shortwave flux [W/m²] | +| Atm%flux_sw_dif | real(:,:) | Diffuse component of the net shortwave flux [W/m²] | +| Atm%flux_sw_down_vis_dir | real(:,:) | Downward direct-beam flux in the visible band (0.2–0.7 µm) [W/m²] | +| Atm%flux_sw_down_vis_dif | real(:,:) | Downward diffuse flux in the visible band [W/m²] | +| Atm%flux_sw_down_total_dir | real(:,:) | Downward direct-beam broadband shortwave flux [W/m²] | +| Atm%flux_sw_down_total_dif | real(:,:) | Downward diffuse broadband shortwave flux [W/m²] | +| Atm%flux_sw_vis | real(:,:) | Net (downward minus reflected) visible-band shortwave flux at the surface [W/m²] | +| Atm%flux_sw_vis_dir | real(:,:) | Direct-beam component of the net visible shortwave flux [W/m²] | +| Atm%flux_sw_vis_dif | real(:,:) | Diffuse component of the net visible shortwave flux [W/m²] | +| Atm%flux_lw | real(:,:) | Net downward longwave flux at the surface [W/m²] | + +### Precipitation +| Atm%lprec | real(:,:) | Mass of liquid precipitation accumulated since the last time step [kg/m²]; equivalent to a rate in kg/m²/s when divided by dt_atm | +| Atm%fprec | real(:,:) | Mass of frozen (solid) precipitation accumulated since the last time step [kg/m²] | + +## Generic exchange fields + +| Field | Type | Description | +|---|---|---| +| Atm%gex_atm2lnd | real(:,:,:) | Generic exchange fields sent from the atmosphere to the land model; the field table defines which quantities are exchanged (e.g. CO₂, aerosol deposition); third dimension indexes the exchange field list | +| Atm%gex_lnd2atm | real(:,:,:) | Generic exchange fields returned from the land model to the atmosphere (e.g. surface emission fluxes); third dimension indexes the exchange field list | +| Atm%fields | type(coupler_2d_bc_type) | Array of additional tracer boundary-condition fields used for atmosphere-ocean gas exchange (CO₂, O₂, CFCs, etc.); registered and populated by atmos_tracer_flux_init | + +--- + +## Implicit surface diffusion coefficients — `Surf_diff` + +`Surf_diff` is of type `surf_diff_type` (defined in +`atmos_phys/atmos_param/vert_diff/vert_diff.F90:44`). It carries the +forward-elimination coefficients from the implicit vertical diffusion +scheme that couples the atmosphere to the surface models. + +| Field | Type | Description | +|---|---|---| +| Atm%Surf_diff%dtmass | real(:,:) | dt/mass — ratio of the atmospheric timestep to the surface-layer air mass [s·m²/kg]; scales flux tendencies to temperature/tracer tendencies | +| Atm%Surf_diff%dflux_t | real(:,:) | d(sensible heat flux)/d(T_surf) — linearisation of the surface heat flux with respect to surface temperature; used to form the implicit coupling term [W/m²/K] | +| Atm%Surf_diff%delta_t | real(:,:) | Forward-elimination coefficient for temperature from the implicit tridiagonal scheme; represents the accumulated atmospheric temperature forcing at the bottom level waiting for the surface response [K] | +| Atm%Surf_diff%delta_u | real(:,:) | Forward-elimination coefficient for zonal wind from the implicit scheme [m/s] | +| Atm%Surf_diff%delta_v | real(:,:) | Forward-elimination coefficient for meridional wind from the implicit scheme [m/s] | +| Atm%Surf_diff%dflux_tr | real(:,:,:) | d(tracer flux)/d(tracer_surf) — linearisation of tracer surface fluxes with respect to surface tracer concentration; third dimension indexes tracers | +| Atm%Surf_diff%delta_tr | real(:,:,:) | Forward-elimination coefficient for each tracer from the implicit scheme; third dimension indexes tracers | +| Atm%Surf_diff%tdt_dyn | real(:,:,:) | Temperature tendency from dynamics (advection, etc.) passed through the diffusion scheme | +| Atm%Surf_diff%qdt_dyn | real(:,:,:) | Moisture tendency from dynamics | +| Atm%Surf_diff%dgz_dyn | real(:,:,:) | Geopotential height tendency from dynamics | +| Atm%Surf_diff%ddp_dyn | real(:,:,:) | Pressure-thickness tendency from dynamics | +| Atm%Surf_diff%tdt_rad | real(:,:,:) | Temperature tendency from radiation; used in the MIZ (marginal ice zone) forecast mode | + +--- + +## Grid geometry — `grid` + +`grid` is of type `grid_box_type` (defined in `FMS/exchange/xgrid.F90:287`). +It holds the geometric quantities needed for second-order conservative flux +remapping between the atmosphere and surface component grids on a +cubic-sphere mesh. + +| Field | Type | Description | +|---|---|---| +| Atm%grid%dx | real(:,:) | Grid-box width in the x-direction [m] | +| Atm%grid%dy | real(:,:) | Grid-box width in the y-direction [m] | +| Atm%grid%area | real(:,:) | Grid-box area [m²] | +| Atm%grid%edge_w | real(:) | Western edge lengths of grid boxes along the boundary [m] | +| Atm%grid%edge_e | real(:) | Eastern edge lengths [m] | +| Atm%grid%edge_s | real(:) | Southern edge lengths [m] | +| Atm%grid%edge_n | real(:) | Northern edge lengths [m] | +| Atm%grid%en1 | real(:,:,:) | First unit normal vector at grid-box edges; used to project vector fields (winds, stresses) during remapping | +| Atm%grid%en2 | real(:,:,:) | Second unit normal vector at grid-box edges | +| Atm%grid%vlon | real(:,:,:) | Unit vector in the local longitude direction at each grid point; used to rotate between geographic and local coordinate frames during exchange | +| Atm%grid%vlat | real(:,:,:) | Unit vector in the local latitude direction at each grid point | + +## Bookkeeping and time + +| Field | Type | Description | +|---|---|---| +| Atm%Time | type(time_type) | Current model time; passed to diag_manager send_data calls and to fms_data_override | +| Atm%Time_step | type(time_type) | Atmospheric model timestep duration | +| Atm%Time_init | type(time_type) | Reference (initial) time for the model run | +| Atm%pelist | integer(:) | List of MPI PE numbers on which the atmosphere is running | +| Atm%pe | logical | .true. on PEs that are part of the atmosphere pelist; used to gate atmosphere-only code blocks | diff --git a/full/docs/atmos_ice_boundary_type.md b/full/docs/atmos_ice_boundary_type.md new file mode 100644 index 00000000..b3dc1da4 --- /dev/null +++ b/full/docs/atmos_ice_boundary_type.md @@ -0,0 +1,79 @@ +# `atmos_ice_boundary_type` + +Defined in `sis2/src/ice_boundary_types.F90:51`. + +`atmos_ice_boundary_type` holds data passed between atmosphere and the sea-ice model (SIS2). + +--- + +## Wind stress + +| Field | Type | Description | +|---|---|---| +| u_flux | real(:,:,:) | True-eastward wind stress from the atmosphere to the ocean or ice in each thickness category, on an A-grid and not rotated to the model grid [Pa] | +| v_flux | real(:,:,:) | True-northward wind stress from the atmosphere to the ocean or ice in each thickness category, on an A-grid and not rotated to the model grid [Pa] | +| u_star | real(:,:,:) | Atmospheric friction velocity on an A-grid [Pa] | + +--- + +## Turbulent heat and moisture fluxes + +| Field | Type | Description | +|---|---|---| +| t_flux | real(:,:,:) | Net sensible heat flux from the ocean or ice surface into the atmosphere [W/m²] | +| q_flux | real(:,:,:) | Moisture flux from the ice or ocean to the atmosphere due to evaporation or sublimation [kg/m²/s] | + +--- + +## Implicit coupling coefficients + +These are the linearization (derivative) terms needed to close the implicit tridiagonal surface diffusion scheme between the atmosphere and ice. + +| Field | Type | Description | +|---|---|---| +| dhdt | real(:,:,:) | d(upward sensible heat flux)/d(T_surf) — derivative of sensible heat flux with respect to surface temperature [W/m²/°C] | +| dedt | real(:,:,:) | d(sublimation+evaporation rate)/d(T_surf) — derivative of the moisture flux with respect to surface temperature [kg/m²/s/°C] | +| drdt | real(:,:,:) | d(net upward longwave flux)/d(T_surf) — derivative of the net upward longwave flux (i.e. -lw_flux) with respect to surface temperature [W/m²/°C] | + +--- + +## Radiative fluxes + +| Field | Type | Description | +|---|---|---| +| lw_flux | real(:,:,:) | Net downward longwave radiation flux from the atmosphere into the ice or ocean [W/m²] | +| sw_flux_vis_dir | real(:,:,:) | Net direct visible shortwave radiation flux into the ice or ocean [W/m²] | +| sw_flux_vis_dif | real(:,:,:) | Net diffuse visible shortwave radiation flux into the ice or ocean [W/m²] | +| sw_flux_nir_dir | real(:,:,:) | Net direct near-infrared shortwave radiation flux into the ice or ocean [W/m²] | +| sw_flux_nir_dif | real(:,:,:) | Net diffuse near-infrared shortwave radiation flux into the ice or ocean [W/m²] | +| sw_down_vis_dir | real(:,:,:) | Downward direct visible shortwave radiation flux from the atmosphere [W/m²] | +| sw_down_vis_dif | real(:,:,:) | Downward diffuse visible shortwave radiation flux from the atmosphere [W/m²] | +| sw_down_nir_dir | real(:,:,:) | Downward direct near-infrared shortwave radiation flux from the atmosphere [W/m²] | +| sw_down_nir_dif | real(:,:,:) | Downward diffuse near-infrared shortwave radiation flux from the atmosphere [W/m²] | +| coszen | real(:,:,:) | Cosine of the solar zenith angle averaged over the next radiation timestep (not the timestep used to compute the sw_flux fields) [dimensionless, ≤ 1] | + +--- + +## Precipitation + +| Field | Type | Description | +|---|---|---| +| lprec | real(:,:,:) | Liquid precipitation (rain) from the atmosphere onto the ice or ocean in each thickness category [kg/m²/s]; rain falling on snow is currently assumed to drain directly through the ice into the ocean | +| fprec | real(:,:,:) | Frozen precipitation (snowfall, sleet, hail, graupel) from the atmosphere to the ice or ocean [kg/m²/s]; all forms of frozen precipitation are treated as snow in SIS2 | + +--- + +## Atmospheric state + +| Field | Type | Description | +|---|---|---| +| p | real(:,:,:) | Atmospheric surface pressure [Pa]; typically ~1×10⁵ Pa | + +--- + +## Bookkeeping + +| Field | Type | Description | +|---|---|---| +| xtype | integer | Transfer mode for the atmosphere-to-ice exchange: REGRID (1), REDIST (2), or DIRECT (3) | +| fluxes | type(coupler_3d_bc_type) | Array of additional per-tracer gas and deposition fluxes from the atmosphere to the ice | diff --git a/full/docs/atmos_land_boundary_type.md b/full/docs/atmos_land_boundary_type.md new file mode 100644 index 00000000..76c68420 --- /dev/null +++ b/full/docs/atmos_land_boundary_type.md @@ -0,0 +1,58 @@ +# `atmos_land_boundary_type` + +`atmos_land_boundary_type` carries all data passed from the coupler to the land model (LM4). +All fields are pointers with dimension (grid_idex, tile_number) + +## Radiative and precipitation forcing + +| Field | Type | Description | +|---|---|---| +| Atmos_land_boundary%t_flux | real(:,:) | Sensible heat flux into the land surface [W/m²] | +| Atmos_land_boundary%lw_flux | real(:,:) | Net longwave radiation flux at the land surface [W/m²] | +| Atmos_land_boundary%lwdn_flux | real(:,:) | Downward longwave radiation flux at the land surface [W/m²] | +| Atmos_land_boundary%sw_flux | real(:,:) | Net shortwave radiation flux at the land surface [W/m²] | +| Atmos_land_boundary%swdn_flux | real(:,:) | Downward shortwave radiation flux at the land surface [W/m²] | +| Atmos_land_boundary%sw_flux_down_vis_dir | real(:,:) | Downward direct-beam visible shortwave flux [W/m²] | +| Atmos_land_boundary%sw_flux_down_total_dir | real(:,:) | Downward direct-beam total (broadband) shortwave flux [W/m²] | +| Atmos_land_boundary%sw_flux_down_vis_dif | real(:,:) | Downward diffuse visible shortwave flux [W/m²] | +| Atmos_land_boundary%sw_flux_down_total_dif | real(:,:) | Downward diffuse total (broadband) shortwave flux [W/m²] | +| Atmos_land_boundary%lprec | real(:,:) | Liquid precipitation rate [kg/m²/s] | +| Atmos_land_boundary%fprec | real(:,:) | Frozen precipitation rate [kg/m²/s] | +| Atmos_land_boundary%tprec | real(:,:) | Temperature of precipitation [K] | + +## Implicit coupling coefficients + +These are the derivatives needed to close the implicit tridiagonal surface diffusion scheme between the atmosphere and land. + +| Field | Type | Description | +|---|---|---| +| Atmos_land_boundary%dhdt | real(:,:) | d(sensible heat flux)/d(T_surf) — derivative of sensible heat flux with respect to surface temperature [W/m²/K] | +| Atmos_land_boundary%dhdq | real(:,:) | d(sensible heat flux)/d(q_surf) — derivative of sensible heat flux with respect to surface specific humidity [W/m²/(kg/kg)] | +| Atmos_land_boundary%drdt | real(:,:) | d(longwave flux)/d(T_surf) — derivative of longwave flux with respect to surface radiative temperature [W/m²/K] | + +## Turbulence and boundary-layer state + +| Field | Type | Description | +|---|---|---| +| Atmos_land_boundary%cd_m | real(:,:) | Drag coefficient for momentum [dimensionless] | +| Atmos_land_boundary%cd_t | real(:,:) | Drag coefficient for tracers (heat and moisture) [dimensionless] | +| Atmos_land_boundary%ustar | real(:,:) | Turbulent wind scale (friction velocity) [m/s] | +| Atmos_land_boundary%bstar | real(:,:) | Turbulent buoyancy scale [m/s] | +| Atmos_land_boundary%wind | real(:,:) | Absolute wind speed at the bottom of the atmospheric layer [m/s] | +| Atmos_land_boundary%z_bot | real(:,:) | Height of the bottom atmospheric layer above the land surface [m] | +| Atmos_land_boundary%drag_q | real(:,:) | Product of the moisture drag coefficient and wind speed (cd_q × wind); used in land surface moisture flux calculations [m/s] | +| Atmos_land_boundary%p_surf | real(:,:) | Surface pressure [Pa] | + +## Tracer fluxes +dimension (grid_index, tile_number, tracer_index) + +| Field | Type | Description | +|---|---|---| +| Atmos_land_boundary%tr_flux | real(:,:,:) | Flux of each tracer into the land surface, including water vapor flux; dimensioned (grid_index, tile, tracer) [tracer units · kg air / (m²·s)] | +| Atmos_land_boundary%dfdtr | real(:,:,:) | d(tracer flux)/d(tracer_surf) — derivative of the tracer flux with respect to the surface tracer value, including evaporation over surface specific humidity; dimensioned (grid_index, tile, tracer) | + +## Bookkeeping + +| Field | Type | Description | +|---|---|---| +| Atmos_land_boundary%xtype | integer | Transfer mode for the atmosphere-to-land exchange: REGRID (1), REDIST (2), or DIRECT (3) | diff --git a/full/docs/ice_data_type.md b/full/docs/ice_data_type.md new file mode 100644 index 00000000..e6d35de6 --- /dev/null +++ b/full/docs/ice_data_type.md @@ -0,0 +1,138 @@ +# `ice_data_type` + +`ice_data_type` is the publicly visible face of the SIS2 sea-ice model. +It carries the surface state, inter-component fluxes, and PE/domain metadata that the coupler needs. + All internal SIS2 state is accessed through the private control structures `fCS` (fast ice) and `sCS` (slow ice), + which are opaque to the coupler. + +The type supports a split fast-ice / slow-ice architecture. Fast processes (surface thermodynamics, atmosphere–ice flux coupling) run on the atmospheric timestep on atmosphere PEs; slow processes (ice dynamics, freezing/melting, transport) run on the coupled timestep and may run on ocean PEs when `slow_ice_with_ocean = .true.`. See [README-new.md](README-new.md) for a description of how this affects the PE layout. + +--- + +## PE and domain bookkeeping + +| Field | Type | Description | +|---|---|---| +| pe | logical | .true. on any PE that participates in ice computation (fast or slow) | +| fast_ice_pe | logical | .true. on PEs in the fast-ice pelist; these PEs handle atmosphere-timestep ice processes | +| slow_ice_pe | logical | .true. on PEs in the slow-ice pelist; these PEs handle coupled-timestep ice dynamics and ice-ocean exchange | +| shared_slow_fast_PEs | logical | .true. when fast and slow ice use the same PE set and domain decomposition (i.e. slow_ice_with_ocean=.false.); .false. when slow ice runs on the ocean PEs | +| pelist | integer(:) | Combined list of all ice PEs (union of fast and slow pelists); used for flux exchange | +| fast_pelist | integer(:) | MPI PE numbers for fast-ice processes | +| slow_pelist | integer(:) | MPI PE numbers for slow-ice processes | +| Domain | type(domain2D) | Copy of the fast-ice FMS domain without halos; used for exchange-grid setup | +| slow_Domain_NH | type(domain2D) | Copy of the slow-ice FMS domain without halos; used for ice-ocean flux redistribution | +| fast_domain | type(domain2D) pointer | Pointer to the fast-ice MPI domain (or an allocated copy on slow-ice PEs) | +| slow_domain | type(domain2D) pointer | Pointer to the slow-ice MPI domain (or an allocated copy on fast-ice PEs) | +| ocean_pt | logical(:,:) | Mask array; .true. at ocean (non-land) points | +| xtype | integer | Transfer mode for ice-ocean flux exchange: DIRECT (3) when ice and ocean share the same decomposition, REDIST (2) when they differ | +| axes | integer(3) | Diag-manager axis IDs for the ice surface grid | +| Time | type(time_type) | The sea-ice model's current clock time | + +--- + +## Surface state fields (fast-ice grid) +These fields are dimensioned `(:, :, n_categories)` and provide per-ice-thickness-category information to the atmosphere each fast timestep. Category 1 is open ocean; the sum of `part_size` over all categories equals 1. + +| Field | Type | Description | +|---|---|---| +| part_size | real(:,:,:) | Fractional coverage of the grid cell by each ice thickness category [dimensionless, 0–1]; category 1 is open ocean | +| t_surf | real(:,:,:) | Surface temperature of the ocean (category 1) or each ice thickness category [K] | +| albedo | real(:,:,:) | Broadband surface albedo averaged across all wavelength and orientation bands within each ice category [dimensionless, 0–1] | +| albedo_vis_dir | real(:,:,:) | Surface albedo for direct visible shortwave radiation in each ice category [dimensionless] | +| albedo_nir_dir | real(:,:,:) | Surface albedo for diffuse visible shortwave radiation in each ice category [dimensionless] | +| albedo_vis_dif | real(:,:,:) | Surface albedo for direct near-infrared shortwave radiation in each ice category [dimensionless] | +| albedo_nir_dif | real(:,:,:) | Surface albedo for diffuse near-infrared shortwave radiation in each ice category [dimensionless] | +| rough_mom | real(:,:,:) | Surface roughness length for momentum at the ocean/ice surface, as provided by ocean_rough_mod [m] | +| rough_heat | real(:,:,:) | Surface roughness length for heat at the ocean/ice surface [m] | +| rough_moist | real(:,:,:) | Surface roughness length for moisture at the ocean/ice surface [m] | +| u_surf | real(:,:,:) | Eastward surface velocity of the ocean (category 1, :,:,1) or sea ice [m/s]; used as a lower boundary condition for wind stress | +| v_surf | real(:,:,:) | Northward surface velocity of the ocean (category 1, :,:,1) or sea ice [m/s] | +| flux_uv_stagger | integer | Staggering of u_surf/v_surf relative to tracer points; valid values are AGRID, BGRID_NE, CGRID_NE, BGRID_SW, CGRID_SW (Arakawa notation). Initialized to -999 so that a global max across all PEs propagates the correct value to non-ice PEs | + +--- + +## Ocean surface state (from ocean-to-ice exchange) + +| Field | Type | Description | +|---|---|---| +| s_surf | real(:,:) | Ocean surface salinity [g salt / kg seawater]; populated by flux_ocean_to_ice | +| SST_C | real(:,:) | Ocean surface temperature [°C]; used in forecast mode | + +--- + +## Grid and area fields + +| Field | Type | Description | +|---|---|---| +| area | real(:,:) | Area of each ocean cell [m²]; land cells have area = 0 and this field can double as a mask | +| mi | real(:,:) | Total ice + snow mass per unit area [kg/m²]; passed to the ocean for pressure loading and to the wave model | + +--- + +## Fluxes passed from ice to ocean (slow-ice side) + +These fields are computed by the slow-ice model. + +| Field | Type | Description | +|---|---|---| +| flux_u | real(:,:) | Flux of x-momentum into the ocean (zonal wind/ice stress) [Pa] | +| flux_v | real(:,:) | Flux of y-momentum into the ocean (meridional wind/ice stress) [Pa] | +| flux_t | real(:,:) | Sensible heat flux out of the ocean [W/m²] | +| flux_q | real(:,:) | Evaporative moisture flux out of the ocean [kg/m²/s] | +| flux_lh | real(:,:) | Latent heat flux out of the ocean [W/m²] | +| flux_lw | real(:,:) | Net longwave flux out of the ocean [W/m²] | +| flux_sw_vis_dir | real(:,:) | Direct visible shortwave heat flux into the ocean [W/m²] | +| flux_sw_vis_dif | real(:,:) | Diffuse visible shortwave heat flux into the ocean [W/m²] | +| flux_sw_nir_dir | real(:,:) | Direct near-infrared shortwave heat flux into the ocean [W/m²] | +| flux_sw_nir_dif | real(:,:) | Diffuse near-infrared shortwave heat flux into the ocean [W/m²] | +| flux_salt | real(:,:) | Salt flux out of the ocean (brine rejection / melting) [kg/m²/s] | +| salt_left_behind | real(:,:) | Salt remaining in the ocean during ice growth (not ejected as brine) [kg/m²/s] | +| lprec | real(:,:) | Liquid precipitation flux into the ocean [kg/m²] | +| fprec | real(:,:) | Frozen precipitation flux into the ocean [kg/m²] | +| runoff | real(:,:) | Liquid runoff from land into the ocean [kg/m²] | +| runoff_hflx | real(:,:) | Heat flux associated with liquid runoff, relative to a reference temperature [W/m²] | +| runoff_carbon | real(:,:) | Carbon content of liquid runoff into the ocean [kg/m²] | +| calving | real(:,:) | Calving of ice or frozen freshwater runoff into the ocean [kg/m²] | +| calving_hflx | real(:,:) | Heat flux associated with calving, relative to a reference temperature [W/m²] | +| p_surf | real(:,:) | Pressure at the ocean surface [Pa]; may or may not include atmospheric pressure depending on configuration | +| stress_mag | real(:,:) | Time-mean magnitude of the ice-ocean stress [Pa]; passed to the ocean when pass_stress_mag = .true. in SIS_slow_CS | + +--- + +## Iceberg fields + +Present only when the iceberg module is active (`sCS%do_icebergs = .true.`). + +| Field | Type | Description | +|---|---|---| +| ustar_berg | real(:,:) | Friction velocity contribution beneath icebergs [m/s]; used for iceberg-ocean drag | +| area_berg | real(:,:) | Fraction of the grid cell covered by icebergs [m²/m²] | +| mass_berg | real(:,:) | Mass of icebergs per unit area [kg/m²] | + +--- + +## Gas and tracer flux boundary conditions + +| Field | Type | Description | +|---|---|---| +| ocean_fields | type(coupler_3d_bc_type) | Named surface-state fields shared with the atmosphere (SST, SSS, piston velocities, etc.) for atmosphere-ocean gas exchange; populated by flux_ocean_to_ice | +| ocean_fluxes | type(coupler_2d_bc_type) | Computed gas fluxes from the ice to the ocean for additional tracers | +| ocean_fluxes_top | type(coupler_3d_bc_type) | Gas flux boundary conditions at the top of the ice (atmosphere side); archaic and flagged for eventual removal | + +--- + +## Internal SIS2 control structures + +The following fields are private to SIS2 and are not used by other FMS modules. The coupler holds them opaquely and passes them back to SIS2 routines. + +| Field | Type | Description | +|---|---|---| +| fCS | type(SIS_fast_CS) pointer | Control structure for the SIS2 fast ice thermodynamics; lives on atmosphere PEs; contains the fast-ice grid (fCS%G), diagnostics, and all fast-timestep state | +| sCS | type(SIS_slow_CS) pointer | Control structure for the SIS2 slow ice dynamics and thermodynamics; may live on ocean PEs when slow_ice_with_ocean=.true.; contains the slow-ice grid (sCS%G), dynamics, tracer registry, and all slow-timestep state | +| icebergs | type(icebergs) pointer | Control structure for the Lagrangian iceberg module; null when do_icebergs=.false. | +| US | type(unit_scale_type) pointer | SIS2 dimensional unit-scaling factors; used to convert between external MKS values and SIS2 internal non-dimensionalized units | +| Ice_restart | type(SIS_restart_CS) pointer | Control structure for writing and reading slow-ice restart files | +| Ice_fast_restart | type(SIS_restart_CS) pointer | Control structure for writing and reading fast-ice restart files | +| OBC | type(ice_OBC_type) pointer | Control structure for ice open boundary conditions; null when OBCs are not configured | +| restart_output_dir | character(240) | Directory path for restart file output; default is './RESTART/' | diff --git a/full/docs/ice_ocean_boundary_type.md b/full/docs/ice_ocean_boundary_type.md new file mode 100644 index 00000000..4a2fc743 --- /dev/null +++ b/full/docs/ice_ocean_boundary_type.md @@ -0,0 +1,160 @@ +# `ice_ocean_boundary_type` + +Defined in two driver-specific files: +- FMS cap: `mom6/config_src/drivers/FMS_cap/MOM_surface_forcing_gfdl.F90:180` +- NUOPC cap: `mom6/config_src/drivers/nuopc_cap/mom_surface_forcing_nuopc.F90:166` + +`ice_ocean_boundary_type` holds all surface forcing passed from the sea-ice model to MOM6 each coupled timestep. + +The two cap implementations share a common set of core fields but differ in the additional fields supported. Fields present only in one cap are noted below. + +--- + +## Wind stress + +| Field | Type | Description | +|---|---|---| +| u_flux | real(:,:) | i-direction wind/ice stress on the ocean surface [Pa] | +| v_flux | real(:,:) | j-direction wind/ice stress on the ocean surface [Pa] | +| stress_mag | real(:,:) | Time-mean magnitude of the stress on the ocean [Pa]; present when pass_stress_mag=.true. in SIS_slow_CS. FMS cap only. | +| wind_stagger | integer | Spatial discretization of the wind stresses; may be set by the flux-exchange code based on what the sea-ice model provides, otherwise taken from the surface forcing control structure | +| u10_sqr | real(:,:) | Wind speed squared at 10 m height [m²/s²]. NUOPC cap only. | + +--- + +## Heat fluxes + +| Field | Type | Description | +|---|---|---| +| t_flux | real(:,:) | Sensible heat flux into the ocean [W/m²] | +| lw_flux | real(:,:) | Net longwave radiation flux into the ocean [W/m²] | +| sw_flux_vis_dir | real(:,:) | Direct visible shortwave radiation into the ocean [W/m²] | +| sw_flux_vis_dif | real(:,:) | Diffuse visible shortwave radiation into the ocean [W/m²] | +| sw_flux_nir_dir | real(:,:) | Direct near-infrared shortwave radiation into the ocean [W/m²] | +| sw_flux_nir_dif | real(:,:) | Diffuse near-infrared shortwave radiation into the ocean [W/m²] | +| seaice_melt_heat | real(:,:) | Heat flux from sea ice and snow melting [W/m²]. NUOPC cap only. | +| swnet_afracr | real(:,:) | Net shortwave radiation multiplied by the atmosphere fraction, positive into the ocean [W/m²]. NUOPC cap only. | +| swpen_ifrac_n | real(:,:,:) | Net shortwave radiation penetrating into ice and ocean, multiplied by ice fraction per thickness category; positive into the ocean [W/m²]; third dimension indexes ice categories. NUOPC cap only. | + +--- + +## Heat content of freshwater fluxes + +| Field | Type | Description | +|---|---|---| +| hrofl | real(:,:) | Heat content from liquid runoff [W/m²] | +| hrofi | real(:,:) | Heat content from frozen runoff (calving) [W/m²] | +| hrofl_glc | real(:,:) | Heat content from liquid glacier runoff via the river-routing model [W/m²] | +| hrofi_glc | real(:,:) | Heat content from frozen glacier runoff via the river-routing model [W/m²] | +| hrain | real(:,:) | Heat content from liquid precipitation [W/m²] | +| hsnow | real(:,:) | Heat content from frozen precipitation [W/m²] | +| hevap | real(:,:) | Heat content from evaporation [W/m²] | +| hcond | real(:,:) | Heat content from condensation [W/m²] | + +--- + +## Freshwater and salt fluxes + +| Field | Type | Description | +|---|---|---| +| q_flux | real(:,:) | Specific humidity (freshwater) flux into the ocean [kg/m²/s] | +| salt_flux | real(:,:) | Salt flux from sea ice into the ocean (brine rejection / melting) [kg/m²/s] | +| excess_salt | real(:,:) | Salt left behind in the ocean by brine rejection rather than ejected as a salt flux [kg/m²/s]. FMS cap only. | +| seaice_melt | real(:,:) | Water flux due to sea ice and snow melting [kg/m²/s]. NUOPC cap only. | +| lprec | real(:,:) | Mass flux of liquid precipitation into the ocean [kg/m²/s] | +| fprec | real(:,:) | Mass flux of frozen precipitation into the ocean [kg/m²/s] | + +--- + +## Runoff and calving + +The FMS cap uses `runoff` / `calving` naming; the NUOPC cap uses `lrunoff` / `frunoff` and additionally carries glacier-sourced fluxes. + +| Field | Type | Cap | Description | +|---|---|---|---| +| runoff | real(:,:) | FMS | Mass flux of liquid runoff from land into the ocean [kg/m²/s] | +| runoff_carbon | real(:,:) | FMS | Mass flux of carbon carried by liquid runoff [kg/m²/s] | +| runoff_hflx | real(:,:) | FMS | Heat content of liquid runoff relative to 0 °C [W/m²] | +| calving | real(:,:) | FMS | Mass flux of frozen runoff (calving) into the ocean [kg/m²/s]; offered first to icebergs if active | +| calving_hflx | real(:,:) | FMS | Heat content of frozen runoff relative to 0 °C [W/m²] | +| lrunoff | real(:,:) | NUOPC | Liquid runoff [kg/m²/s] | +| frunoff | real(:,:) | NUOPC | Frozen (ice) runoff [kg/m²/s] | +| lrunoff_glc | real(:,:) | NUOPC | Liquid glacier runoff delivered via the river-routing model [kg/m²/s] | +| frunoff_glc | real(:,:) | NUOPC | Frozen glacier runoff delivered via the river-routing model [kg/m²/s] | + +--- + +## Pressure and ice loading + +| Field | Type | Description | +|---|---|---| +| p | real(:,:) | Pressure of overlying ice and atmosphere on the ocean surface [Pa] | +| mi | real(:,:) | Mass of sea ice per unit ocean area [kg/m²]; used for ice-pressure loading | +| ice_rigidity | real(:,:) | Rigidity of sea ice and ice shelves expressed as a divergence-damping coefficient [m³/s]; determined outside the ocean model | +| ice_fraction | real(:,:) | Fractional ice area [dimensionless]. NUOPC cap only. | +| ifrac_n | real(:,:,:) | Ice fraction per ice thickness category [dimensionless]; third dimension indexes categories. NUOPC cap only. | +| ice_ncat | integer | Number of ice categories provided by the coupler; 1 means per-category data is not used. NUOPC cap only. | +| afracr | real(:,:) | Fractional atmosphere coverage relative to the ocean grid cell [dimensionless]. NUOPC cap only. | + +--- + +## Iceberg fields + +Present only when the iceberg module is active. + +| Field | Type | Description | +|---|---|---| +| ustar_berg | real(:,:) | Frictional velocity beneath icebergs [m/s] | +| area_berg | real(:,:) | Fractional area of the ocean cell covered by icebergs [m²/m²] | +| mass_berg | real(:,:) | Mass of icebergs per unit ocean area [kg/m²] | + +--- + +## Ice-shelf fields + +FMS cap only. + +| Field | Type | Description | +|---|---|---| +| shelf_sfc_mass_flux | real(:,:) | Mass flux to the surface of the ice sheet [kg/m²/s] | + +--- + +## Biogeochemistry and aerosol deposition + +NUOPC cap only. These fields support ocean biogeochemistry modules that require atmospheric deposition forcing. + +| Field | Type | Description | +|---|---|---| +| nhx_dep | real(:,:) | Reduced nitrogen (NHx) deposition flux [kg/m²/s] | +| noy_dep | real(:,:) | Oxidized nitrogen (NOy) deposition flux [kg/m²/s] | +| atm_co2_prog | real(:,:) | Prognostic atmospheric CO₂ concentration [ppm] | +| atm_co2_diag | real(:,:) | Diagnostic atmospheric CO₂ concentration [ppm] | +| atm_fine_dust_flux | real(:,:) | Fine dust deposition flux from the atmosphere [kg/m²/s] | +| atm_coarse_dust_flux | real(:,:) | Coarse dust deposition flux from the atmosphere [kg/m²/s] | +| seaice_dust_flux | real(:,:) | Dust flux released from sea ice [kg/m²/s] | +| atm_bc_flux | real(:,:) | Black carbon deposition flux from the atmosphere [kg/m²/s] | +| seaice_bc_flux | real(:,:) | Black carbon flux released from sea ice [kg/m²/s] | + +--- + +## Surface wave coupling + +NUOPC cap only. These fields support Langmuir turbulence and wave-driven mixing parameterizations in MOM6. + +| Field | Type | Description | +|---|---|---| +| lamult | real(:,:) | Langmuir turbulence enhancement factor [dimensionless] | +| stk_wavenumbers | real(:) | Central wavenumber of each Stokes drift band [rad/m]; dimensioned (num_stk_bands) | +| ustkb | real(:,:,:) | Stokes drift spectrum, zonal component, at u-points [m/s]; third dimension indexes wavenumber bands | +| vstkb | real(:,:,:) | Stokes drift spectrum, meridional component, at v-points [m/s]; third dimension indexes wavenumber bands | +| num_stk_bands | integer | Number of Stokes drift wavenumber bands passed through the coupler | + +--- + +## Bookkeeping + +| Field | Type | Description | +|---|---|---| +| xtype | integer | Transfer mode for the ice-to-ocean exchange: REGRID (1), REDIST (2), or DIRECT (3) | +| fluxes | type(coupler_2d_bc_type) | Named array of additional per-tracer passive tracer fluxes from ice/atmosphere to ocean | diff --git a/full/docs/ice_ocean_driver_type.md b/full/docs/ice_ocean_driver_type.md new file mode 100644 index 00000000..76e750bb --- /dev/null +++ b/full/docs/ice_ocean_driver_type.md @@ -0,0 +1,28 @@ +# `ice_ocean_driver_type` + +Defined in `sis2/src/combined_ice_ocean_driver.F90:38`. + +`ice_ocean_driver_type` is the control structure for the combined ice-ocean driver module (`combined_ice_ocean_driver`). It is used only when `combine_ice_and_ocean = .true.` in `coupler_nml`, which requires both `concurrent_ice = .true.` and `slow_ice_with_ocean = .true.`. In this mode, the coupler makes a single call to `update_slow_ice_and_ocean` rather than separate calls to `update_ice_model_slow` and `update_ocean_model`. + +An instance (conventionally named `ice_ocean_driver_CS`) is held as a pointer in the coupler state and passed opaquely to `update_slow_ice_and_ocean`, `ice_ocean_driver_init`, and `ice_ocean_driver_end`. All members are private to the module. + +This module provides a platform for tighter integration between SIS2 and MOM6 and is expected to evolve as coupled ice-ocean numerics develop. + +--- + +## Control flags + +| Field | Type | Description | +|---|---|---| +| CS_is_initialized | logical | .true. once ice_ocean_driver_init has completed successfully; guards against use before initialization | +| single_MOM_call | logical | If .true. (default), MOM6 dynamics and thermodynamics are advanced together in a single call to update_ocean_model. If .false., separate calls are made for the two phases | +| intersperse_ice_ocn | logical | If .true., ice and ocean thermodynamic and dynamic updates are interspersed rather than sequential. Requires single_MOM_call=.false. The default is .false. | +| use_intersperse_bug | logical | If .true., retains a bug in the intersperse option where the ocean state was not being passed back to the sea ice between interspersed steps; exists for backward compatibility | + +--- + +## Timestepping + +| Field | Type | Description | +|---|---|---| +| dt_coupled_dyn | real | Timestep [s] for coupling ice and ocean dynamics when intersperse_ice_ocn=.true.; set to <0 (default: -1) to use the standard coupled timestep dt_cpld | diff --git a/full/docs/land_data_type.md b/full/docs/land_data_type.md new file mode 100644 index 00000000..c37be75c --- /dev/null +++ b/full/docs/land_data_type.md @@ -0,0 +1,64 @@ +# `land_data_type` + +`land_data_type` carries land surface states passed to the couper. +The land model uses an unstructured tile representation where +multiple land-cover types (soil, vegetation, +lakes, etc.) can co-exist within a single atmospheric grid cell. + +--- + +## Surface state fields +dimension (grid_index,tile_number) + +| Field | Description | +|---|---| +| Land%tile_size | Fractional coverage of the atmospheric grid cell by this tile [dimensionless, 0–1]; used to area-weight tile quantities back onto the atmosphere grid | +| Land%t_surf | Ground (radiative) surface temperature [K]; used in longwave radiation and sensible heat flux calculations | +| Land%t_ca | Canopy air temperature — near-surface air temperature within the plant canopy layer [K]; differs from t_surf over vegetated tiles | +| Land%albedo | Broadband surface albedo [dimensionless]; legacy field, per-band albedos below are preferred | +| Land%albedo_vis_dir | Surface albedo for direct-beam visible radiation (0.2–0.7 µm) [dimensionless] | +| Land%albedo_nir_dir | Surface albedo for direct-beam near-infrared radiation [dimensionless] | +| Land%albedo_vis_dif | Surface albedo for diffuse visible radiation [dimensionless] | +| Land%albedo_nir_dif | Surface albedo for diffuse near-infrared radiation [dimensionless] | +| Land%rough_mom | Surface roughness length for momentum [m]; used in Monin-Obukhov flux calculations | +| Land%rough_heat | Surface roughness length for heat and tracers [m] | +| Land%rough_scale | Topographic form-drag scaling factor for momentum [dimensionless]; accounts for sub-grid orographic drag | + +--- + +## Tracer fields +dimension (grid_index, tile_number, tracer_index) + +| Field | Description | +|---|---| +| Land%tr | Surface tracer mixing ratios on each tile, including canopy air specific humidity as the first tracer; additional tracers (e.g. CO₂) follow the tracer table order | + +--- + +## Discharge fields +dimension(lon, lat) + + +These fields carry freshwater and heat leaving the land surface and routed +to the ocean/ice via `flux_land_to_ice`. + +| Field | Description | +|---|---| +| Land%discharge | Liquid water discharge (river runoff) from land to ocean [kg/m²/s] | +| Land%discharge_heat | Sensible heat carried by liquid discharge, using 0 °C as datum [W/m²] | +| Land%discharge_snow | Solid water (snow/ice) discharge from land to ocean [kg/m²/s] | +| Land%discharge_snow_heat | Sensible heat carried by solid discharge, using 0 °C as datum [W/m²] | + +--- + +## Grid and domain bookkeeping + +| Field | Type | Description | +|---|---|---| +| Land%mask | logical(:,:) | .true. where the grid cell contains land; used to gate land-only computations | +| Land%axes(1) | integer | Diag-manager axis ID for the unstructured land grid; used when registering tiled land diagnostics | +| Land%domain | type(domain2D) | FMS structured-grid domain for the land model; used for halo exchanges and exchange-grid setup | +| Land%ug_domain | type(domainUG) | FMS unstructured-grid domain for the land model; carries the tile-based decomposition used by LM4 | +| Land%pelist | integer(:) | List of MPI PE numbers on which the land model is running | +| Land%pe | logical | .true. on PEs that are part of the land pelist; used to gate land stock calculations | + diff --git a/full/docs/land_ice_atmos_boundary_type.md b/full/docs/land_ice_atmos_boundary_type.md new file mode 100644 index 00000000..113c0da5 --- /dev/null +++ b/full/docs/land_ice_atmos_boundary_type.md @@ -0,0 +1,65 @@ +# `land_ice_atmos_boundary_type` + +`land_ice_atmos_boundary_type` contains surface quantities going from land and ice to the atmosphere. +All quantities are on the exchange grid. + +## Surface state returned to the atmosphere + +| Field | Type | Description | +|---|---|---| +| Land_ice_atmos_boundary%t | real(:,:) | Area-weighted surface temperature seen by the atmosphere for radiation calculations [K]; weighted over land and ice fractions | +| Land_ice_atmos_boundary%t_ocean | real(:,:) | Ocean surface temperature for radiation calculations; sourced from Ice%t_surf through the exchange grid [K] | +| Land_ice_atmos_boundary%albedo | real(:,:) | Broadband surface albedo [dimensionless] | +| Land_ice_atmos_boundary%albedo_vis_dir | real(:,:) | Direct-beam visible-band surface albedo [dimensionless] | +| Land_ice_atmos_boundary%albedo_nir_dir | real(:,:) | Direct-beam near-infrared surface albedo [dimensionless] | +| Land_ice_atmos_boundary%albedo_vis_dif | real(:,:) | Diffuse visible-band surface albedo [dimensionless] | +| Land_ice_atmos_boundary%albedo_nir_dif | real(:,:) | Diffuse near-infrared surface albedo [dimensionless] | +| Land_ice_atmos_boundary%land_frac | real(:,:) | Fraction of the atmospheric grid cell covered by land [dimensionless] | +| Land_ice_atmos_boundary%frac_open_sea | real(:,:) | Non-sea-ice fraction of the grid cell [dimensionless]; complement of the sea-ice concentration | +| Land_ice_atmos_boundary%rough_mom | real(:,:) | Area-weighted surface roughness length for momentum [m] | +| Land_ice_atmos_boundary%rough_heat | real(:,:) | Area-weighted surface roughness length for heat [m] | + +## Reference-height diagnostics + +These fields are interpolated from the surface-layer profile to the reference heights z_ref_heat and z_ref_mom configured in flux_exchange_nml. + +| Field | Type | Description | +|---|---|---| +| Land_ice_atmos_boundary%u_ref | real(:,:) | Zonal wind at the momentum reference height (z_ref_mom) [m/s] | +| Land_ice_atmos_boundary%v_ref | real(:,:) | Meridional wind at the momentum reference height (z_ref_mom) [m/s] | +| Land_ice_atmos_boundary%t_ref | real(:,:) | Air temperature at the heat reference height (z_ref_heat) [K] | +| Land_ice_atmos_boundary%q_ref | real(:,:) | Specific humidity at the heat reference height (z_ref_heat) [kg/kg] | +| Land_ice_atmos_boundary%wind | real(:,:) | Absolute wind speed at the lowest atmospheric model level including gust corrections [m/s] | +| Land_ice_atmos_boundary%thv_atm | real(:,:) | Virtual potential temperature at the lowest atmospheric model level [K] | +| Land_ice_atmos_boundary%thv_surf | real(:,:) | Virtual potential temperature at the surface [K] | + +## Implicit flux corrections applied to the atmosphere + +These fields are the outputs of the tridiagonal back-substitution step. They correct the atmospheric temperature and tracer tendencies for the implicit surface coupling. + +| Field | Type | Description | +|---|---|---| +| Land_ice_atmos_boundary%dt_t | real(:,:) | Temperature tendency correction at the lowest atmospheric level from the implicit surface flux scheme [K/s] | +| Land_ice_atmos_boundary%dt_tr | real(:,:,:) | Tracer mixing-ratio tendency correction at the lowest level; third dimension indexes tracers [tracer units/s] | + +## Surface stress and turbulence scales + +| Field | Type | Description | +|---|---|---| +| Land_ice_atmos_boundary%u_flux | real(:,:) | Zonal wind stress on the atmosphere [Pa] | +| Land_ice_atmos_boundary%v_flux | real(:,:) | Meridional wind stress on the atmosphere [Pa] | +| Land_ice_atmos_boundary%dtaudu | real(:,:) | d(zonal wind stress)/d(u) — implicit coupling coefficient for zonal momentum [Pa·s/m] | +| Land_ice_atmos_boundary%dtaudv | real(:,:) | d(meridional wind stress)/d(v) — implicit coupling coefficient for meridional momentum [Pa·s/m] | +| Land_ice_atmos_boundary%u_star | real(:,:) | Friction velocity (surface turbulent velocity scale) [m/s] | +| Land_ice_atmos_boundary%b_star | real(:,:) | Buoyancy scale used in Monin-Obukhov similarity theory [m/s²] | +| Land_ice_atmos_boundary%q_star | real(:,:) | Moisture scale used in Monin-Obukhov similarity theory [kg/kg] | +| Land_ice_atmos_boundary%shflx | real(:,:) | Sensible heat flux at the surface [W/m²]; not compiled when use_AM3_physics is defined | +| Land_ice_atmos_boundary%lhflx | real(:,:) | Latent heat flux at the surface [W/m²]; not compiled when use_AM3_physics is defined | + +## Generic and bookkeeping fields + +| Field | Type | Description | +|---|---|---| +| Land_ice_atmos_boundary%data | real(:,:,:) | Collective array providing named access to the scalar fields above; used internally for data-override and exchange-grid operations | +| Land_ice_atmos_boundary%gex_lnd2atm | real(:,:,:) | Generic exchange fields returned from the land model to the atmosphere (e.g., surface emission fluxes); third dimension indexes the exchange field list | +| Land_ice_atmos_boundary%xtype | integer | Transfer mode for the exchange-grid-to-atmosphere remap: REGRID (1), REDIST (2), or DIRECT (3) | diff --git a/full/docs/ocean_ice_boundary_type.md b/full/docs/ocean_ice_boundary_type.md new file mode 100644 index 00000000..ea4faccc --- /dev/null +++ b/full/docs/ocean_ice_boundary_type.md @@ -0,0 +1,43 @@ +# `ocean_ice_boundary_type` + +`ocean_ice_boundary_type` carries ocean surface state passed from MOM6 to the sea-ice model (SIS2) + +--- + +## Ocean surface velocities + +| Field | Type | Description | +|---|---|---| +| u | real(:,:) | x-direction ocean surface velocity at a position determined by stagger [m/s] | +| v | real(:,:) | y-direction ocean surface velocity at a position determined by stagger [m/s] | +| stagger | integer | Spatial staggering of u and v relative to tracer points; default is BGRID_NE | + +--- + +## Thermodynamic state + +| Field | Type | Description | +|---|---|---| +| t | real(:,:) | Ocean surface temperature [K] | +| s | real(:,:) | Ocean surface salinity [g salt / kg seawater] | +| frazil | real(:,:) | Frazil heat rejected by the ocean since the last coupling step [J/m²]; delivered to SIS2 so it can account for ocean-side freezing | +| sea_level | real(:,:) | Sea level after adjustment for any surface pressure that the ocean allows to be expressed [m] | + +--- + +## Calving + +| Field | Type | Description | +|---|---|---| +| calving | real(:,:) | Mass flux per unit area of ice-shelf flux to be converted to icebergs [kg/m²/s] | +| calving_hflx | real(:,:) | Heat flux associated with calving [W/m²] | + +--- + +## Bookkeeping + +| Field | Type | Description | +|---|---|---| +| data | real(:,:,:) | Collective array providing named access to the scalar fields above; used internally for data-override and exchange-grid operations | +| xtype | integer | Transfer mode for the ocean-to-ice exchange: REGRID (1), REDIST (2), or DIRECT (3) | +| fields | type(coupler_2d_bc_type) | Named array of additional per-tracer ocean surface fields (e.g., pCO₂, SSS for gas exchange) passed to the ice model | diff --git a/full/docs/ocean_public_type.md b/full/docs/ocean_public_type.md new file mode 100644 index 00000000..889c04ef --- /dev/null +++ b/full/docs/ocean_public_type.md @@ -0,0 +1,56 @@ +# `ocean_public_type` + +`ocean_public_type` is the publicly visible face of the MOM6 ocean model. +It contains only the surface fields and domain metadata for the coupler. + +--- + +## Domain and PE bookkeeping + +| Field | Type | Description | +|---|---|---| +| Domain | type(domain2d) | FMS domain decomposition for the ocean surface fields; defines the MPI tile layout used for coupler remapping | +| is_ocean_pe | logical | .true. on processors that run the ocean model; used throughout the coupler to gate ocean-only code paths | +| pelist | integer(:) | List of MPI PE numbers assigned to the ocean model | +| maskmap | logical(:,:) | Pointer to a mask indicating which logical processors are active for ocean computation; logical processors covering all-land points may not be mapped to physical PEs. Need not be set if all processors are used | +| instance_name | character(32) | Optional name identifying this ocean model instance; used in ensemble runs to disambiguate log messages | + +--- + +## Surface state fields + +These fields are set by the ocean model after each update and read by the +coupler to construct the `ocean_ice_boundary_type` passed to the sea-ice +model via `flux_ocean_to_ice`. + +| Field | Description | +|---|---| +| t_surf | Sea-surface temperature (SST) on tracer (T) cells [K] | +| s_surf | Sea-surface salinity (SSS) on T cells [ppt] | +| u_surf | Surface current i-velocity at the locations indicated by stagger [m/s] | +| v_surf | Surface current j-velocity at the locations indicated by stagger [m/s] | +| sea_lev | Sea level corrected for surface pressure: dzt(1) + η + p_atm/(ρ₀g) [m]; passed to the ice model as sea_level | +| frazil | Accumulated heating from frazil ice formation in the ocean since the last coupling step [J/m²]; delivered to the ice model so it can account for ocean-side freezing | +| melt_potential | Instantaneous heat available to melt sea ice from below [J/m²]; computed when the ocean boundary layer depth exceeds HFrz | +| OBLD | Ocean boundary layer depth [m]; used to determine the depth over which melt potential is computed | +| area | Grid-cell area of each ocean surface cell [m²]; used for conservative flux remapping | +| calving | Mass per unit area of ice-shelf flux to be converted to icebergs [kg/m²]; passed to the iceberg module | +| calving_hflx | Heat flux associated with calving [W/m²] | + +--- + +## Grid staggering + +| Field | Type | Description | +|---|---|---| +| stagger | integer | Arakawa staggering of the surface velocity components (u_surf, v_surf) relative to tracer points. Valid values: AGRID, BGRID_NE, CGRID_NE, BGRID_SW, CGRID_SW. Set to -999 before initialization so a global max can propagate the value to non-ocean PEs | + +--- + +## Tracer gas fields and diagnostics + +| Field | Type | Description | +|---|---|---| +| fields | type(coupler_2d_bc_type) | Named arrays of tracer-related ocean surface fields (e.g. pCO₂, O₂ saturation) used in atmosphere-ocean gas flux calculations; populated by atmos_ocean_fluxes_calc | +| avg_kount | integer | Counter tracking the number of contributions accumulated in the running averages stored in this type; used externally by FMSCoupler to manage time averaging | +| axes(2) | integer(2) | Diag-manager axis IDs available for I/O using this surface data | diff --git a/full/docs/ocean_state_type.md b/full/docs/ocean_state_type.md new file mode 100644 index 00000000..4409da46 --- /dev/null +++ b/full/docs/ocean_state_type.md @@ -0,0 +1,110 @@ +# `ocean_state_type` + +`ocean_state_type` contains information about the state of the ocean. +Its members are private and are not accessible outside `ocean_model_MOM.F90`. +The coupler holds only a pointer to it (`type(ocean_state_type), pointer :: Ocean_state`). + +--- + +## PE flag + +| Field | Type | Description | +|---|---|---| +| is_ocean_PE | logical | .true. if this PE is part of the ocean pelist; initialised to .false. so non-ocean PEs that hold the pointer do nothing | + +--- + +## Time + +| Field | Type | Description | +|---|---|---| +| Time | type(time_type) | The ocean model's master clock; advanced each call to update_ocean_model | +| Time_dyn | type(time_type) | The ocean model's dynamics time; equals Time after a complete timestep but may lag during a split dynamics/thermodynamics step | + +--- + +## Timestepping control + +| Field | Type | Description | +|---|---|---| +| nstep | integer | Counter for the number of update_ocean calls that advanced the dynamics | +| nstep_thermo | integer | Counter for the number of update_ocean calls that advanced the thermodynamics | +| single_step_call | logical | If .true. (default), dynamics and thermodynamics are advanced together in a single call. If .false., separate calls are made and dt/dt_therm below are used | +| dt | real | Baroclinic dynamics timestep [T ~> s]; only used when single_step_call=.false. | +| dt_therm | real | Thermodynamics timestep [T ~> s]; only used when single_step_call=.false. | +| thermo_spans_coupling | logical | If .true., thermodynamic and tracer timesteps can span multiple coupled timesteps | +| diabatic_first | logical | If .true., diabatic and thermodynamic processes are applied before the dynamics step | + +--- + +## Restart control + +| Field | Type | Description | +|---|---|---| +| Restart_control | integer | Bit-field controlling restart file writing: bit 0 (+1) saves generic restart files; bit 1 (+2) saves time-stamped files. A negative value suppresses restart writing at run end | + +--- + +## Physics switches + +| Field | Type | Description | +|---|---|---| +| use_ice_shelf | logical | If .true., the MOM6 ice shelf model (MOM_ice_shelf) is enabled | +| use_waves | logical | If .true., surface wave coupling is active | +| icebergs_alter_ocean | logical | If .true., icebergs can modify ocean dynamics and forcing fluxes | +| calve_ice_shelf_bergs | logical | If .true., icebergs are seeded from ice-shelf flux through the ice front | +| offline_tracer_mode | logical | If .false. (default), full prognostic dynamics and thermodynamics are integrated. If .true., only tracer advection/diffusion is integrated using velocity fields read from a previous run | + +--- + +## Physical constants + +| Field | Type | Description | +|---|---|---| +| C_p | real | Specific heat capacity of seawater [J degC⁻¹ kg⁻¹] | +| press_to_z | real | Conversion factor from pressure to ocean depth, typically 1/(ρ₀g) [Z T² R⁻¹ L⁻² ~> m Pa⁻¹] | + +--- + +## Forcing and surface state structures + +These nested types carry the mechanical and thermodynamic forcing fields +assembled by the coupler and consumed by `update_ocean_model`. + +| Field | Type | Description | +|---|---|---| +| forces | type(mech_forcing) | Mechanical surface forcing: wind stress, sea-level pressure, and wave-related fields | +| fluxes | type(forcing) | Primary thermodynamic ocean forcing: heat flux, freshwater flux, salt flux, shortwave penetration, etc. | +| flux_tmp | type(forcing) | Secondary forcing structure used when multiple coupled timesteps are taken per thermodynamic step; accumulates forcing between thermodynamic updates | +| sfc_state | type(surface) | Ocean surface state fields (SST, SSS, surface currents, boundary layer depth) returned to the coupler after each update | + +--- + +## Grid and vertical coordinate structures + +| Field | Type | Description | +|---|---|---| +| grid | type(ocean_grid_type), pointer | MOM6 horizontal grid structure: cell areas, distances, coordinates, metric terms, and land masks | +| GV | type(verticalGrid_type), pointer | MOM6 vertical grid structure: layer thicknesses, target densities (for isopycnal coordinates), and ALE remapping parameters | +| US | type(unit_scale_type), pointer | MOM6 dimensional unit-scaling factors used to convert between external MKS units and MOM6's internal non-dimensionalised units | + +--- + +## Model control structures + +| Field | Type | Description | +|---|---|---| +| MOM_CSp | type(MOM_control_struct) | MOM6 master control structure; holds all module-level control structures, parameter settings, and diagnostic handles for the ocean model | +| Ice_shelf_CSp | type(ice_shelf_CS), pointer | Control structure for the MOM6 ice shelf model; null if use_ice_shelf=.false. | +| marine_ice_CSp | type(marine_ice_CS), pointer | Control structure for the marine ice effects module (e.g. iceberg melt parameterisation) | +| Waves | type(wave_parameters_cs), pointer | Control structure for surface wave coupling; null if use_waves=.false. | +| forcing_CSp | type(surface_forcing_CS), pointer | MOM6 surface forcing control structure; handles the translation from coupler boundary conditions to internal MOM6 forcing arrays | +| diag | type(diag_ctrl), pointer | MOM6 diagnostic control structure; manages registration and posting of all ocean diagnostics to the FMS diag_manager | + +--- + +## I/O paths + +| Field | Type | Description | +|---|---|---| +| dirs | type(directories) | Structure containing relevant directory paths for input, output, and restart files |