Location, Time, and Grid

These three top-level sections define where the simulation is located on Earth, the time span to integrate, and the vertical grid structure.

location

Geographic metadata for the simulation column. These values affect Coriolis forcing, solar angle calculations, and are written to NetCDF output attributes.

Parsed by pygotm.config.settings.LocationSettings.

location:
  name: FLEX Experiment 1976
  latitude: 58.92
  longitude: 0.32
  depth: 145.0

location.name

Type	string
Default	"GOTM site"

Station or site name. Used as a label in output files and reports only; has no effect on the numerical solution.

location.latitude

Type	float
Units	degrees North
Range	−90.0 to 90.0
Default	0.0

Geographic latitude of the simulated water column. Controls the Coriolis parameter via \(f = 2\Omega\sin(\phi)\) (implemented in pygotm.meanflow.coriolis.coriolis()) and solar zenith angle for shortwave radiation computations.

location.longitude

Type	float
Units	degrees East
Range	−360.0 to 360.0
Default	0.0

Geographic longitude. Used for solar zenith angle computations and is written to the output NetCDF as a coordinate attribute.

location.depth

Type	float
Units	metres (positive downward)
Range	> 0.0
Default	100.0

Total water depth. The vertical grid spans from the surface (z = 0) to z = −depth. Layer thicknesses are derived from this value when grid.method: analytical.

time

Controls the temporal span and numerical time-stepping parameters.

Parsed by pygotm.config.settings.TimeSettings.

time:
  start: 1976-04-06 06:00:00
  stop:  1976-06-07 00:00:00
  dt: 360.0
  cnpar: 1.0

time.start

Type	string
Format	yyyy-mm-dd HH:MM:SS
Default	"2017-01-01 00:00:00"

Simulation start date and time. pyGOTM accepts ISO-8601 datetime strings; the YAML parser coerces Python datetime objects to this format automatically.

time.stop

Type	string
Format	yyyy-mm-dd HH:MM:SS
Default	"2018-01-01 00:00:00"

Simulation end date and time. The total number of time steps is computed as \(N = \lfloor (t_{stop} - t_{start}) / \Delta t \rfloor\).

time.dt

Type	float
Units	seconds
Range	> 0.0
Default	3600.0

Integration time step \(\Delta t\). Typical values range from 10 s (idealized turbulence cases) to 3600 s (long climate simulations).

Warning

Stability of the implicit Crank–Nicolson solver degrades for very large dt combined with sharp stratification. Use cnpar: 1.0 (fully implicit) for coarse time steps; reduce cnpar only after verifying stability.

time.cnpar

Type	float
Range	0.5 to 1.0
Default	1.0

Crank–Nicolson weighting parameter \(\theta\). A value of 1.0 gives a fully implicit (backward-Euler) scheme, which is unconditionally stable but first-order accurate in time. The value 0.5 gives second-order (Crank– Nicolson) accuracy but may be oscillatory near sharp gradients. GOTM default is 1.0 for robustness.

This parameter is passed directly to the diffusion solvers in pygotm.util.diff_center and pygotm.util.diff_face.

grid

Defines the number and distribution of vertical layers.

Parsed by pygotm.config.settings.GridSettings.

grid:
  nlev: 145
  method: analytical
  ddu: 0.0
  ddl: 0.0
  file: ""

grid.nlev

Type	integer
Range	≥ 1
Default	100

Number of vertical layers \(N\). The model uses \(N+1\) cell interfaces (including surface and bottom) and \(N\) cell centres. Arrays inside pyGOTM are allocated with shape (nlev+1,); index 0 is the bottom interface and index nlev is the surface interface.

Practical guidance: use one layer per metre of water depth (nlev == depth) as a starting point. Increase for fine-scale surface-layer dynamics.

grid.method

Type	string
Valid values	analytical, file_sigma, file_h
Default	"analytical"

How the layer thickness profile is constructed.

analytical

Layers are equally spaced by default, with optional zooming toward the surface and/or bottom controlled by ddu and ddl. Implemented in pygotm.meanflow.updategrid.updategrid().

file_sigma

Layer thicknesses are read as normalised fractions (sigma coordinates) from the file specified in grid.file. The fractions must sum to 1.

file_h

Layer thicknesses (in metres) are read directly from grid.file.

grid.ddu

Type	float
Units	dimensionless
Range	≥ 0.0
Default	0.0

Surface zooming coefficient. Larger values concentrate layers near the surface. Only used when grid.method: analytical. A value of 0.0 gives equal spacing.

grid.ddl

Type	float
Units	dimensionless
Range	≥ 0.0
Default	0.0

Bottom zooming coefficient. Larger values concentrate layers near the bottom. Only used when grid.method: analytical.

grid.file

Type	string (file path)
Default	"" (empty — not used)

Path to the file containing prescribed layer thicknesses or sigma fractions. Required when grid.method is file_sigma or file_h; ignored otherwise. Relative paths are resolved relative to the directory containing gotm.yaml.

See also

Grid Layer File for the complete file format specification, including exact column layout, layer ordering, and sum-constraint requirements.