Output and Restart

output

Controls how and when pyGOTM writes results to NetCDF files. The output block is a mapping of output stream names to schedule configurations. Multiple named streams can be defined simultaneously, each producing a separate NetCDF file.

output:
  my_results:                  # name of this output stream (= output filename stem)
    time_unit: dt              # time unit for the interval
    time_step: 30              # write every 30 time units
    time_method: point         # instantaneous snapshot
    variables:
      - source: /*             # include all registered variables

output:
  hourly:
    time_unit: hour
    time_step: 1
    variables:
      - source: /temp          # temperature only

Output is implemented in pygotm.gotm.runtime_output and scheduled via pygotm.gotm.runtime_params.RuntimeParams.

NetCDF Global Attributes

Every real output and empty output=False dataset carries the same kernel provenance contract. The attributes are stable machine-readable metadata; use pygotm schema netcdf-attrs --json for the JSON form.

Attribute	Type	Meaning
title	string	Simulation title.
source_yaml	string	Source YAML path recorded for the run.
nlev	integer	Number of vertical layers.
dt	float	Integration time step in seconds.
runtime	string	Runtime backend, currently compiled.
pygotm_version	string	Installed pyGOTM package version.
pygotm_git_commit	string	Short Git commit or unavailable.
pygotm_config_schema_version	string	Config contract version.
pygotm_output_schema_version	string	Output contract version.
python_version	string	Python runtime version.
numpy_version	string	NumPy version.
numba_version	string	Numba version.
xarray_version	string	xarray version.
netcdf4_version	string	netCDF4 package version or unavailable.
gsw_version	string	GSW package version.
pyfabm_version	string	pyfabm package version or unavailable.
platform	string	Operating system and machine architecture.
source_yaml_sha256	string	SHA-256 of raw source YAML bytes, or unavailable.
effective_yaml_sha256	string	SHA-256 of canonical materialized YAML, portable across paths.
fabm_yaml_sha256	string	SHA-256 of resolved FABM YAML bytes, or unavailable.
started_at	string	UTC ISO-8601 run start timestamp.
finished_at	string	UTC ISO-8601 run finish timestamp.
wall_clock_seconds	float	End-to-end driver wall-clock duration.
turbulence_method	string	Raw normalized GOTM turbulence method token.
tke_method	string	Raw normalized TKE method token.
len_scale_method	string	Raw normalized length-scale method token.
turbulence_closure	string	Derived closure label such as k-epsilon, k-omega, or GLS.
ice_model	string	Raw normalized ice model token, or off.
fabm_active	string	true or false.
fabm_models	string	JSON-encoded list of FABM instances.*.model paths.

Stream Name

The key under output (e.g., my_results) is both the name of the output stream and the stem of the output NetCDF filename. The file is written to the working directory as <name>.nc.

output.<name>.time_unit

Type	string
Valid values	second, hour, day, month, year, dt
Default	"day"

The time unit for the output interval.

dt

Model time steps. A time_step of 30 with time_unit: dt means write output every 30 integration time steps. This is the most flexible option and is independent of the actual time-step length.

second / hour / day / month / year

Calendar-based intervals. A time_step of 1 with time_unit: hour writes every hour regardless of dt.

output.<name>.time_step

Type	integer
Range	≥ 1
Default	1

Number of time_unit intervals between output writes. For example, time_step: 6 with time_unit: hour writes every 6 hours.

output.<name>.time_method

Type	string
Valid values	point, mean, integrated
Default	"point"

How the output quantity is temporally aggregated over the output interval.

point

Instantaneous snapshot at the output time. This is the only method currently supported by the compiled Numba runtime.

mean

Time-average of the variable over the output interval. [unsupported in compiled runtime].

integrated

Time-integral of the variable. [unsupported in compiled runtime].

output.<name>.variables

A list of variable selector records that controls which model fields are written.

variables:
  - source: /*              # all registered variables
  - source: /temp           # temperature profile
  - source: /salt           # salinity profile
  - source: /u              # U-velocity
  - source: /tke            # turbulent kinetic energy

Each entry has a source key that is a path into the field registry. Use /* to select all registered variables. Individual variable names use the GOTM field-registry convention (see pygotm.gotm.register_all_variables.do_register_all_variables() for the full list of available names).

Registered output variables

The following variables are registered in the compiled runtime and available for output:

Name	Units	Description
temp	°C	Conservative temperature (cell centres)
salt	g kg−1	Absolute salinity (cell centres)
u	m s−1	West–East velocity (cell centres)
v	m s−1	South–North velocity (cell centres)
tke	m2 s−2	Turbulent kinetic energy (cell interfaces)
eps	m2 s−3	Dissipation rate ε (cell interfaces)
num	m2 s−1	Eddy viscosity (cell interfaces)
nuh	m2 s−1	Heat diffusivity (cell interfaces)
nus	m2 s−1	Salinity diffusivity (cell interfaces)
L	m	Turbulent length scale (cell interfaces)
P	m2 s−3	Shear production (cell interfaces)
G	m2 s−3	Buoyancy production/destruction (cell interfaces)
cmue1 / cmue2	dimensionless	Stability functions (cell interfaces)
as / an	dimensionless	Dimensionless shear/stratification (cell interfaces)
h	m	Layer thickness (cell centres)
z	m	Layer centre depth (negative below surface)
SS	s−2	Shear frequency squared (cell interfaces)
xP	W m−2	Internal absorbed shortwave radiation (cell centres)
avh	m2 s−1	Biological light attenuation (cell centres)

When fabm.use: true, additional FABM variables are discovered from the resolved fabm.yaml through pyfabm and written automatically. Interior state variables and output-enabled interior diagnostics are profiles with dimensions (time, z, lat, lon); surface state, bottom state, and horizontal diagnostics are scalar fields with dimensions (time, lat, lon). Variable names use FABM output_name metadata, with / normalized to _. For example, gotm/npzd configured under an instance named npzd writes npzd_nut, npzd_phy, npzd_zoo, npzd_det, npzd_PAR, npzd_PPR, npzd_NPR, and total_nitrogen.

Use pygotm schema output --config gotm.yaml --json to inspect the exact output variable list for a FABM-active configuration before running it. FABM-active runs also retain the host feedback placeholders surface_albedo, surface_drag_coefficient_in_air, and attenuation_coefficient_of_photosynthetic_radiative_flux for compatibility with existing validation outputs.

restart

Controls restart/checkpoint behaviour.

restart:
  load: false

restart.load

Type	boolean
Default	false

If true, initialise the model state from a restart file restart.nc located in the same directory as gotm.yaml. The restart file must have been produced by a previous pyGOTM run with identical grid dimensions.

When load: false (default), the model is initialised from the temperature and salinity profile specifications.

Note

The restart file format is compatible with Fortran GOTM’s restart.nc convention. A restart can therefore be used to continue a Fortran GOTM run in pyGOTM or vice versa, provided the grid is identical.

seagrass

Seagrass canopy drag parameterisation.

seagrass:
  method: 0
  file: seagrass.dat
  alpha: 0.0

seagrass.method

Type	integer
Valid values	0 (off), 1 (from file)
Default	0

0

No seagrass parameterisation.

1

Seagrass canopy geometry and density are read from seagrass.file. The canopy drag is added to the bottom boundary layer of the turbulence model. Implemented in pygotm.extras.seagrass.seagrass. [unsupported in compiled runtime] in the current release.

seagrass.file

Path to the seagrass specification file. Default: "seagrass.dat".

The seagrass file is a static (non-timeseries) ASCII file that describes the canopy geometry. Unlike the input files used by forcing fields, it contains no timestamps. The format is:

N                        ← integer: number of canopy levels
z_1   excursion_1   friction_1
z_2   excursion_2   friction_2
...
z_N   excursion_N   friction_N

• Column 1 — z (m): height above the bottom of this canopy element (positive upward).

• Column 2 — excursion (m): maximum lateral displacement of the Lagrangian leaf tip. When the leaf displacement exceeds this limit, drag is applied to the current. Set to 0.0 for a rigid element.

• Column 3 — friction: canopy drag coefficient (leaf friction coefficient) applied to the current when the excursion limit is reached.

Blank lines and lines beginning with # or ! are treated as comments and skipped. Extra columns beyond column 3 are ignored.

See also

Seagrass Canopy File for the complete file format specification and reference case example.

seagrass.alpha

Efficiency of leaf-level turbulence production. Default: 0.0.