pygetm.simulation module

class pygetm.simulation.BaseSimulation(domain: Domain, *, log_level: int | None = None, tiling: Tiling | None = None)[source]

Bases: object

advance(check_finite: bool = False)[source]

Advance the model state by one microtimestep. If this completes the current macrotimestep, the part of the state associated with that timestep will be advanced too.

Parameters:: check_finite – after the state update, verify that all fields only contain finite values

check_finite(macro_active: bool = True, dump: bool = True) → bool[source]

Verify that all fields available for output contain finite values. Fields with non-finite values are reported in the log as error messages. Finally, if any non-finite values were found, an exception is raised.

Parameters:: macro_active – also check fields updated on the 3d (macro) timestep

default_time_reference: datetime | None

finish()[source]: Clean-up after simulation: save profiling result (if any), write output where appropriate (restarts), and close output files

input_manager

istep

load_restart(path: str | PathLike[str], time: datetime | None = None, **kwargs) → datetime[source]

Load the model state from a restart file. This must be called before start().

Parameters:

path – NetCDF file to load restart state from
time – time coordinate to take restart information from. This is only relevant of the restart file contains the model state at multiple times. If not provided, the last time from the file will be used.
**kwargs – additional keyword arguments passed to xarray.open_dataset()

Returns:

The time from which the restart information was taken.

logger

macrotimestep

output_manager

report

report_totals

split_factor

Start a simulation by configuring the time, zeroing velocities, updating diagnostics to match the start time, and optionally saving output.

This should be called after the output configuration is complete (because we need to know when variables need to be saved), and after the FABM model has been provided with all dependencies.

Parameters:

time (cftime.datetime) – start time
timestep – micro time step (s) used for 2D barotropic processes
split_factor – number of microtimesteps per macrotimestep
report – time interval or number of microtimesteps between reporting of the current time, used as indicator of simulation progress
report_totals – time interval or number of microtimesteps between reporting of integrals over the global domain
profile – base name for the file to write profiling results to. The process rank and extension .prof will be appended, so that the final name becomes <profile>-<rank>.prof. If the argument is not provided, profiling is disabled.
dump_on_error – if True, when non-finite values are detected in the model state or forcing, the current state will be saved to a NetCDF file for debugging purposes.

tiling

time

timedelta

timestep

Bases: BaseSimulation

Parameters:

domain – simulation domain
runtype – simulation run type
Dmin – minimum depth (m) for wet points. At this depth, all hydrodynamic terms except the pressure gradient and bottom friction are switched off.
Dcrit – depth (m) at which tapering off of hydrodynamic processes (all except pressure gradient and bottom friction) begins.
delay_slow_ip – let slow internal pressure terms lag one macrotimestep behind the 3d internal pressure terms. This can help stabilize density-driven flows in deep water
tiling – subdomain decomposition. If not provided, an optimal subdomain division is determined automatically based on the land-sea mask and the number of active CPU cores

D_halo_update

Dcrit

Dmin

property Ekin

NN

T

U

V

X

add_freshwater_inputs(timestep: float)[source]: Update layer thicknesses and tracer concentrations to account for precipitation, evaporation and river inflow.

advance_surface_elevation(timestep: float, U: Array, V: Array, fwf: Array)[source]

Advance surface elevation (T grid only)

Parameters:

timestep – time step (s)
U – depth-integrated velocity in x-direction (m2 s-1)
V – depth-integrated velocity in y-direction (m2 s-1)
fwf – freshwater flux (m s-1)

This method does not update elevation on the U, V, X grids, nor water depths, layer thicknesses or vertical coordinates. This is done by update_depth() instead.

airsea: Provider of air-water fluxes of heat and momentum. This must inherit from pygetm.airsea.Fluxes and should be provided as argument airsea to Simulation.

airsea_halo_update

buoy

delay_slow_ip

density

depth

dpdx

dpdxo

dpdy

dpdyo

fabm

fwf

ice

initialize_depth(keep_all_z: bool = False, keep_ho: bool = False, keep_hn: bool = False)[source]

Initialize elevations, water depths, layer thicknesses and vertical coordinates on all grids, and where applicable, on old and new time levels. By default, these are all derived from the current surface elevation on the T grid (self.T.z).

For 3D simulations (runtype > RunType.BAROTROPIC_2D) runs, all metrics (notably total water depth and U/V dampening factors) are for the macro timestep. They are thus are based on self.T.zin and - for U and V grids - self.T.zio. At simulation start, an initial call to _update_forcing_and_diagnostics() will call update_depth() to replace these metrics with values based on self.T.z and self.T.zo to prepare for the first micro timestep.

Parameters:

keep_all_z – if True, preserve values of elevation for the old micro time level (self.T.zo), and old and new elevations for the old macro time level (self.T.zio, self.T.zin)
keep_ho – if True, preserve values of layer thickness at the old macro time level (self.T.ho)
keep_hn – if True, preserve values of layer thickness at the new macro time level (self.T.hn)

internal_pressure

momentum

nuh_ct

open_boundaries

par

par0

pres

rad

radiation

report_domain_integrals()[source]: Write totals of selected variables over the global domain (those in tracer_totals) to the log.

rho

rivers

runtype

salt

salt_sf

sst

ssu

ssu_U

ssv

ssv_V

tausx

tausxo

tausy

tausyo

temp

temp_sf

total_area

total_volume_ref

property totals: tuple[float | None, Sequence[tuple[TracerTotal, float, float]] | None]

Global totals of volume and tracers.

Returns:: A tuple with total volume and a list with (tracer_total, total, mean) tuples on the root subdomains. On non-root subdomains it returns None, None

tracer_totals: list[TracerTotal]: List of variables for which the domain-integrated total needs to be reported. These can be depth-integrated (2D) or depth-explicit (3D).

tracers: TracerCollection: Collection of tracers that are to be transported. Optionally they can have sources, open boundary conditions and riverine concentrations set.

update_depth(_3d: bool = False, timestep: float = 0.0)[source]

Use old and new surface elevation on T grid to calculate elevations on U, V, X grids. Subsequently update total water depth D on all grids. If _3d is True, also update layer thicknesses hn, layer center depths zc and interface depths zf on all grids.

Parameters:

_3d – update elevations of the macrotimestep (zin) rather than elevations of the microtimestep (z).This first synchronizes the elevations of the macrotimestep on the T grid (self.T.zin) with those of the microtimestep (self.T.z). It also updates layer thicknesses hn, layer center depths zc and interface depths zf on all grids.
timestep – time step (s) for layer thickness change if 0, any layer height relaxation is disabled

This routine will ensure values are up to date in the domain interior and in the halos, but that this requires that self.T.z (and old elevations self.T.zo or self.T.zio) are already up to date in halos.

update_surface_pressure_gradient(z: Array, sp: Array)[source]

ustar_s

vertical_coordinates

vertical_mixing

z0b

z0s

pygetm.simulation.log_exceptions(method)[source]

pygetm.simulation.to_cftime(time: datetime | datetime) → datetime[source]