parsac.job.gotm module

class parsac.job.gotm.Output(name, file, expression, times, zs)

Bases: NamedTuple

Create new instance of Output(name, file, expression, times, zs)

expression: str

Alias for field number 2

file: Path

Alias for field number 1

name: str

Alias for field number 0

times: list[datetime] | None

Alias for field number 3

zs: ndarray | None

Alias for field number 4

class parsac.job.gotm.OutputExtractor(output: Output, wrappednc: NcDict, logger: Logger)

Bases: object

This class encapsulates all information necessary to extract a variable from the model output and (optionally) to interpolate the extracted values to the time and location of observations.

depth_dimension: str | None
ileft: ndarray | None
ileft_weights: ndarray | None
iright: ndarray | None
iright_weights: ndarray | None
numtimes: ndarray | None
class parsac.job.gotm.OutputPlotter(times: list[datetime], zs: ndarray | None, values: ndarray, obs_times: list[datetime], obs_zs: ndarray | None, previous: dict[str, OutputPlotter])

Bases: ComparisonPlotter

This class encapsulates the model output and observations necessary to produce a comparison plot for single variable. It also provides one method plot to plot the data in a matplotlib axes object.

Instances of this class will be created in workers and then pickled to be sent to the main process for plotting. Therefore, all its attributes must be picklable.

plot(ax: matplotlib.axes.Axes, logger: Logger) → None

Plot model output versus observations.

class parsac.job.gotm.Simulation(setup_dir: PathLike[str] | str, *, executable: PathLike[str] | str = 'gotm', exclude_files: Iterable[str] = ('*.nc', '*.cache'), exclude_dirs: Iterable[str] = ('*',), args: Iterable[str] = (), **kwargs: Any)

Bases: Runner

A simulation with GOTM (General Ocean Turbulence Model).

Call get_parameter() to select a configurable parameter from a YAML file. This parameter can subsequently be targeted in optimization or sensitivity analysis.

Call request_comparison() to link a model output to observations. This can subsequently contribute to the objective function (likelihood) when performing optimization.

Call record_output() to record specific model outputs. These serve as target metrics to assess the sensitivity of when performing sensitivity analysis. When performing optimization, these outputs will be recorded as diagnostics accompanying each evaluated parameter set.

Parameters:

  • setup_dir – path to the GOTM setup directory

  • executable – path to the GOTM executable It can be an absolute path, a path relative to the current working directory, or the name of the executable available via the PATH environment variable.

  • exclude_files – patterns to exclude files from being copied to the working directory

  • exclude_dirs – patterns to exclude directories from being copied to the working directory

  • args – additional arguments to pass to the GOTM executable

  • kwargs – additional keyword arguments to pass to the parent class parsac.core.Runner.

get_parameter(file: PathLike[str] | str, variable_path: str, default: Any = None) → InitializedParameter

Get a parameter from a YAML file.

The parameter is identified by the path to the YAML file and the location of the variable in the file. This location is a path-like string that uses slashes to separate nested dictionaries, e.g. “a/b/c” for variable c in this file:

a:
  b:
    c: 42.0
Parameters:

  • file – path to the YAML file (relative to the setup directory)

  • variable_path – location of the variable in the YAML file

  • default – default value if the variable is not found. This must be specified for parameters that are not present yet in the YAML file.

Returns:

A parameter object that can be used in optimization or sensitivity analysis. The value that the parameter has in the YAML file (or default, if the parameter is not present) is available as the initial_value attribute of the parameter.

on_start() → None
output2extractor: dict[str, OutputExtractor]
outputs: list[Output]
parameters: list[tuple[str, Path, str]]
parsed_yaml: dict[Path, YAMLFile]
prepare_work_dir(work_dir: Path | None) → Tuple[Path, bool]

Prepare a work directory. It will reuse an existing work directory (without emptying it), unless you provide an explicit directory path that is different from the previous call.

record_output(output_file: PathLike[str] | str, output_expression: str)

Request an expression of output variables to be recorded.

In sensitivity analysis, this output will serve as one of the targets to assess the sensitivity of. In optimization, it will serve as additional metric recorded along with each model result.

Parameters:

  • output_file – path to the NetCDF output file (relative to the setup directory)

  • output_expression – expression to evaluate in the output file. It should return a scalar value.

request_comparison(output_file: PathLike[str] | str, output_expression: str, obs_file: PathLike[str] | str, *, obs_file_format: TextFormat = TextFormat.DEPTH_EXPLICIT, obs_variable: str | None = None, obs_depth_variable: str | None = None, spinupyears: int = 0, mindepth: float = -inf, maxdepth: float = inf) → Comparison | None

Request comparison of model results and observations for a particular variable.

Parameters:

  • output_file – path to the NetCDF output file (relative to the setup directory)

  • output_expression – expression to evaluate in the output file. It should produce the model equivalent of the provided observations. It can reference variables from the output file as well as numpy functions.

  • obs_file – path to the file with observations (relative to the current working directory)

  • obs_file_format – format of the observations file Used only if obs_file is a whitespace-separated text file.

  • obs_variable – variable name in the NetCDF file with observations Used only if obs_file is a NetCDF file.

  • obs_depth_variable – name of depth variable in the NetCDF file with observations Used only if obs_file is a NetCDF file.

  • spinupyears – number of years to skip from the beginning of the simulation when comparing model results to the observations

  • mindepth – minimum depth of observations; shallower observations are ignored

  • maxdepth – maximum depth of observations; deeper observations are ignored

start_time: datetime
stop_time: datetime
parsac.job.gotm.read_profiles(path: PathLike[str] | str, column: int = 0) → tuple[Sequence[datetime], ndarray, ndarray]

Read GOTM observations in profile format

Parameters:

  • path – path to the GOTM profile file

  • column – column number to read. This index is zero-based, so 0 means the first column.