Surface Forcing

The surface section controls all atmospheric and surface boundary conditions: heat and momentum fluxes, meteorological inputs, and sea-surface nudging. It maps directly to the air-sea interaction layer implemented in pygotm.airsea.

When any surface forcing field uses method: file, the data file must follow the Timeseries (Scalar) File format. Multiple variables can share a single file using different column: indices — this is the standard pattern for combined meteorological files (meteo.dat).

See also

Input Data File Formats for complete specifications and examples of all supported input file formats.

surface:
  fluxes:
    method: fairall
    heat:   { method: file, file: heat_flux.dat }
    tx:     { method: file, file: momentum_flux.dat, column: 1 }
    ty:     { method: file, file: momentum_flux.dat, column: 2 }
  u10:    { method: file, file: meteo.dat, column: 1 }
  v10:    { method: file, file: meteo.dat, column: 2 }
  ssuv_method: absolute
  airp:   { method: file, file: meteo.dat, column: 3 }
  airt:   { method: file, file: meteo.dat, column: 4 }
  hum:
    method: file
    file: meteo.dat
    column: 5
    type: wet_bulb
  cloud:  { method: file, file: meteo.dat, column: 6 }
  precip: { method: constant, constant_value: 0.0 }
  swr:    { method: file, file: swr.dat }
  longwave: { method: file, file: lw.dat }
  sst:    { method: off }
  sss:    { method: off }

surface.fluxes

surface.fluxes.method

Type	string
Valid values	off, kondo, fairall
Default	"off"

Selects how heat and momentum fluxes at the sea surface are computed.

off

Prescribed fluxes are read directly from heat, tx, and ty inputs. No bulk formula is applied. Use this when you have observed flux values.

kondo

Heat and momentum fluxes are computed from meteorological variables (wind speed, air temperature, humidity) using the bulk formula of Kondo (1975). Implemented in pygotm.airsea.kondo. Requires u10, v10, airp, airt, and hum to be provided.

fairall

COARE 3.0 bulk algorithm (Fairall et al. 1996/2003). More accurate than Kondo for open-ocean conditions with high wind speeds. Implemented in pygotm.airsea.fairall. Requires the same meteorological inputs as kondo.

Note

The compiled Numba runtime currently supports fairall for the profile path. The kondo method is currently [unsupported in compiled runtime].

surface.fluxes.heat

Prescribed non-solar surface heat flux (sensible + latent + net longwave).

Follows the InputSetting pattern (method: constant | file). When method: file: single-column timeseries file; see Timeseries (Scalar) File.

Units	W m−2
Default	0.0
Sign convention	Atmospheric convention: positive = ocean loses heat (upward).

Warning

GOTM uses the atmospheric sign convention for hflux: a positive value means the ocean is losing heat to the atmosphere. This is the opposite of the physical-oceanography convention. In pygotm.meanflow.temperature.temperature(), the flux enters as DiffTup = -hflux / (rho0 * cp), so a positive heat loss produces a negative (cooling) Neumann boundary condition.

surface.fluxes.tx

Prescribed wind stress in the West–East direction.

Units	Pa
Default	0.0

Used directly as the upper boundary condition for the U-momentum equation when fluxes.method: off or to provide a fallback when bulk methods are active.

When method: file: tx and ty can share a single two-column timeseries file using column: 1 and column: 2 respectively. See Timeseries (Scalar) File for format details.

surface.fluxes.ty

Prescribed wind stress in the South–North direction.

Units	Pa
Default	0.0

Wind Speed

surface.u10

West–East wind speed at 10 m height.

Units	m s−1
Default	0.0

Required when fluxes.method: kondo or fairall.

surface.v10

South–North wind speed at 10 m height.

Units	m s−1
Default	0.0

surface.ssuv_method

Type	string
Valid values	absolute, relative
Default	"relative"

Treatment of the wind vector used in bulk formula.

absolute

Wind components u10 and v10 are interpreted as absolute wind speed (relative to the ground).

relative

Wind speed used in the bulk formula is the wind velocity relative to the surface ocean current: \((u_{10} - u_s,\; v_{10} - v_s)\). This is more physically correct but requires surface currents.

Meteorological Inputs

These inputs are required by the Kondo and Fairall bulk algorithms. All follow the InputSetting pattern (method: constant | file).

When method: file, these inputs are read from a timeseries file (see Timeseries (Scalar) File). The standard pattern is to store all meteorological variables in a single multi-column file and select each variable by its column: index. The conventional six-column layout expected by most reference cases is:

Conventional meteo.dat column layout

Column	Variable	Units	YAML key
1	u10	m s−1	surface.u10
2	v10	m s−1	surface.v10
3	airp	Pa (or hPa — see note below)	surface.airp
4	airt	°C	surface.airt
5	hum	type-dependent (see hum.type)	surface.hum
6	cloud	fraction (0–1)	surface.cloud

Note

The reference cases store air pressure in hPa (hectopascals). The GOTM bulk formulae expect Pa. If your meteo.dat is in hPa, set airp: { scale_factor: 100.0 } in gotm.yaml to convert automatically.

surface.airp

Air pressure at the surface.

Units	Pa
Default	0.0

Used in humidity calculations and to correct sea-level pressure.

surface.airt

Air temperature at 2 m height.

Units	°C or K (detected automatically)
Default	0.0

surface.hum

Humidity at 2 m height. Follows the InputSetting pattern plus an additional type key.

surface.hum.type

Type	string
Valid values	relative, wet_bulb, dew_point, specific
Default	"relative"

Humidity measurement type. The conversion to specific humidity is implemented in pygotm.airsea.humidity.

relative

Relative humidity (%).

wet_bulb

Wet-bulb temperature (°C).

dew_point

Dew-point temperature (°C).

specific

Specific humidity (kg kg⁻¹).

surface.cloud

Cloud cover fraction.

Units	dimensionless (0–1)
Range	0.0 to 1.0
Default	0.0

Used in longwave radiation bulk formulae.

surface.precip

Precipitation rate.

Units	m s−1
Default	0.0

Applied as a freshwater flux at the surface (affects salinity) and as a latent-heat equivalent in bulk schemes.

Radiation

surface.swr

Incident shortwave radiation at the sea surface.

Units	W m−2
Default	0.0

Used when fluxes.method: off. When a bulk algorithm (kondo, fairall) is selected, shortwave radiation can still be prescribed here and added to the computed heat budget. Penetration into the water column is controlled by the light_extinction section.

When method: file: single-column timeseries file (see Timeseries (Scalar) File). Example: 1976-04-06 06:00:00   13.6887.

surface.longwave

Incident or net longwave (infrared) radiation at the surface.

Units	W m−2
Default	0.0

Whether this represents downward or net flux depends on the longwave radiation method configured in the surface block (longwave_method in the underlying runtime, see pygotm.gotm.runtime_params.RuntimeParams.airsea_longwave_method).

Sea-Surface Nudging

surface.sst

Sea-surface temperature nudging target.

Follows the InputSetting pattern. When method: file, model SST is nudged toward the observed values on a configurable time scale.

When method: file: single-column timeseries file (see Timeseries (Scalar) File). Each record is one SST observation: YYYY-MM-DD HH:MM:SS   temperature_celsius.

surface.sss

Sea-surface salinity nudging target.

Follows the InputSetting pattern. Used to represent evaporation/ precipitation corrections or constrain surface salinity in long simulations.

When method: file: single-column timeseries file; one SSS observation per record: YYYY-MM-DD HH:MM:SS   salinity_psu.

Wave Forcing (Stokes Drift)

These inputs are under the surface section but also interact with the waves top-level block (see waves).

surface.tx_method / ty_method

Alternative wave-state-dependent momentum flux methods (Stokes drift contribution). These are passed through to the Stokes drift module pygotm.stokes_drift.

Note

Full Stokes drift integration (Craig–Banner wave-breaking BC) is [unsupported in compiled runtime] in the current release.