thetis package

Submodules

thetis.assembledschur module

class thetis.assembledschur.AssembledSchurPC

Bases: PCBase

Preconditioner for the Schur complement

The preconditioner matrix is assembled by explicitly matrix multiplying \(A10*Minv*A10\).

Here:

• \(A01\), \(A10\) are the assembled sub-blocks of the saddle point

  system. The form of this system needs to be supplied in the appctx argument to the solver as appctx['a'].

• \(Minv\) is the inverse of the mass-matrix which is assembled as

  assemble(Tensor(v*u*dx).inv), i.e. the element-wise inverse, where \(v\) and \(u\) are the test and trial of the \(A00\) block. This gives the exact inverse of the mass matrix for a DG discretisation.

Create a PC context suitable for PETSc.

Matrix free preconditioners should inherit from this class and implement:

• initialize()

• update()

• apply()

• applyTranspose()

apply(pc, X, Y)

Apply the preconditioner to X, putting the result in Y.

Both X and Y are PETSc Vecs, Y is not guaranteed to be zero on entry.

applyTranspose(pc, X, Y)

Apply the transpose of the preconditioner to X, putting the result in Y.

Both X and Y are PETSc Vecs, Y is not guaranteed to be zero on entry.

initialize(pc)

Initialize any state in this preconditioner.

update(pc)

Update any state in this preconditioner.

view(pc, viewer=None)

thetis.callback module

Defines custom callback functions used to compute various metrics at runtime.

class thetis.callback.AccumulatorCallback(scalar_callback, solver_obj, **kwargs)

Bases: DiagnosticCallback

Callback that evaluates a (scalar) functional involving integrals in both time and space.

This callback can also be used to assemble time dependent objective functionals for adjoint simulations. Time integration is achieved using the trapezium rule.

Parameters:

• scalar_callback – Python function that returns a list of values of an objective functional.

• solver_obj – Thetis solver object

• kwargs – any additional keyword arguments, see DiagnosticCallback

get_val()

message_str(*args)

A string representation.

Parameters:

args – If provided, these will be the return value from __call__().

variable_names = ['spatial integral at current timestep']

class thetis.callback.CallbackManager

Bases: defaultdict

Stores callbacks in different categories and provides methods for evaluating them.

Create callbacks and register them under 'export' mode

cb1 = VolumeConservation3DCallback(...)
cb2 = TracerMassConservationCallback(...)
cm = CallbackManager()
cm.add(cb1, 'export')
cm.add(cb2, 'export')

Evaluate callbacks, calls evaluate() method of all callbacks registered in the given mode.

cm.evaluate('export')

add(callback, mode)

Add a callback under the given mode

Parameters:

• callback – a DiagnosticCallback object

• mode (str) – register callback under this mode

evaluate(mode, index=None)

Evaluate all callbacks registered under the given mode

Parameters:

• mode (str) – evaluate all callbacks under this mode

• index (int) – if provided, sets the export index. Default behavior is to append to the file or stream.

class thetis.callback.ConservativeTracerMassConservation2DCallback(tracer_name, solver_obj, **kwargs)

Bases: ScalarConservationCallback

Checks conservation of conservative tracer mass which is depth integrated.

Parameters:

• tracer_name – Name of the tracer. Use canonical field names as in FieldDict.

• solver_obj – Thetis solver object

• kwargs – any additional keyword arguments, see DiagnosticCallback.

name = 'tracer mass'

class thetis.callback.DetectorsCallback(solver_obj, detector_locations, field_names, name, detector_names=None, **kwargs)

Bases: DiagnosticCallback

Callback that evaluates the specified fields at the specified locations

Parameters:

• solver_obj – Thetis solver object

• detector_locations – List of x, y locations in which fields are to be interpolated.

• field_names – List of fields to be interpolated.

• name – Unique name for this callback and its associated set of detectors. This determines the name of the output h5 file (prefixed with diagnostic_).

• detector_names – List of names for each of the detectors. If not provided automatic names of the form detectorNNN are created where NNN is the (0-padded) detector number.

• kwargs – any additional keyword arguments, see DiagnosticCallback.

message_str(*args)

A string representation.

Parameters:

args – If provided, these will be the return value from __call__().

property name

The name of the diagnostic

property variable_names

Names of all scalar values

class thetis.callback.DiagnosticCallback(solver_obj, array_dim=1, attrs=None, outputdir=None, export_to_hdf5=True, append_to_log=True, include_time=True, hdf5_dtype='d', start_time=None, end_time=None)

Bases: ABC

A base class for all Callback classes

Parameters:

• solver_obj – Thetis solver object

• outputdir (str) – Custom directory where hdf5 files will be stored. By default solver’s output directory is used.

• array_dim – Dimension of the output array. Can be a tuple for multi-dimensional output. Use “1” for scalars.

• attrs (dict) – Global attributes to be saved in the hdf5 file.

• export_to_hdf5 (bool) – If True, diagnostics will be stored in hdf5 format

• append_to_log (bool) – If True, callback output messages will be printed in log

• include_time (bool) – whether to include time in the hdf5 file

• hdf5_dtype – Precision to use in hdf5 output: d for double precision (default), and f for single precision

• start_time – Optional start time for callback evaluation

• end_time – Optional end time for callback evaluation

evaluate(index=None)

Evaluates callback and pushes values to log and hdf file (if enabled)

abstract message_str(*args)

A string representation.

Parameters:

args – If provided, these will be the return value from __call__().

abstract property name

The name of the diagnostic

push_to_hdf5(time, args, index=None)

Append values to HDF5 file.

Parameters:

• time – time stamp of entry

• args – the return value from __call__().

push_to_log(time, args)

Push callback status message to log

Parameters:

• time – time stamp of entry

• args – the return value from __call__().

set_write_mode(mode)

Define whether to create a new hdf5 file or append to an existing one

Parameters:

mode (str) – Either ‘create’ (default) or ‘append’

abstract property variable_names

Names of all scalar values

class thetis.callback.DiagnosticHDF5(filename, varnames, array_dim=1, attrs=None, var_attrs=None, comm=<mpi4py.MPI.Intracomm object>, new_file=True, dtype='d', include_time=True)

Bases: object

A HDF5 file for storing diagnostic time series arrays.

Parameters:

• filename (str) – Full filename of the HDF5 file.

• varnames – List of variable names that the diagnostic callback provides

• array_dim – Dimension of the output array. Can be a tuple for multi-dimensional output. Use “1” for scalars.

• attrs (dict) – Global attributes to be saved in the hdf5 file.

• var_attrs (dict) – nested dict of variable specific attributes, e.g. {‘time’: {‘units’: ‘seconds since 1950-01-01’}}

• comm – MPI communicator

• new_file (bool) – Define whether to create a new hdf5 file or append to an existing one (if any)

• dtype – array datatype

• include_time – whether to include time array in the file

export(variables, time=None, index=None)

Appends a new entry of (time, variables) to the file.

The HDF5 is updated immediately.

Parameters:

• variables (tuple of float) – values of entry

• time (float) – time stamp of entry

• index (int) – If provided, defines the time index in the file

class thetis.callback.MinMaxConservationCallback(minmax_callback, solver_obj, **kwargs)

Bases: DiagnosticCallback

Base class for callbacks that check conservation of a minimum/maximum

Parameters:

• minmax_callback – Python function that takes the solver object as an argument and returns a (min, max) value tuple

• solver_obj – Thetis solver object

• kwargs – any additional keyword arguments, see DiagnosticCallback.

message_str(*args)

A string representation.

Parameters:

args – If provided, these will be the return value from __call__().

variable_names = ['min_value', 'max_value', 'undershoot', 'overshoot']

class thetis.callback.ScalarConservationCallback(scalar_callback, solver_obj, **kwargs)

Bases: DiagnosticCallback

Base class for callbacks that check conservation of a scalar quantity

Creates scalar conservation check callback object

Parameters:

• scalar_callback – Python function that takes the solver object as an argument and returns a scalar quantity of interest

• solver_obj – Thetis solver object

• kwargs – any additional keyword arguments, see DiagnosticCallback.

message_str(*args)

A string representation.

Parameters:

args – If provided, these will be the return value from __call__().

variable_names = ['integral', 'relative_difference']

class thetis.callback.TimeSeriesCallback2D(solver_obj, fieldnames, x, y, location_name, z=None, outputdir=None, export_to_hdf5=True, append_to_log=True, tolerance=0.001, eval_func=None, start_time=None, end_time=None)

Bases: DiagnosticCallback

Extract a time series of a 2D field at a given (x,y) location

Currently implemented only for the 3D model.

Parameters:

• solver_obj – Thetis FlowSolver object

• fieldnames – List of fields to extract

• y (x,) – location coordinates in model coordinate system.

• location_name – Unique name for this location. This determines the name of the output h5 file (prefixed with diagnostic_).

• outputdir (str) – Custom directory where hdf5 files will be stored. By default solver’s output directory is used.

• export_to_hdf5 (bool) – If True, diagnostics will be stored in hdf5 format

• append_to_log (bool) – If True, callback output messages will be printed in log

• start_time – Optional start time for timeseries extraction

• end_time – Optional end time for timeseries extraction

message_str(*args)

A string representation.

Parameters:

args – If provided, these will be the return value from __call__().

name = 'timeseries'

variable_names = ['value']

class thetis.callback.TimeSeriesCallback3D(solver_obj, fieldnames, x, y, z, location_name, outputdir=None, export_to_hdf5=True, append_to_log=True, start_time=None, end_time=None)

Bases: DiagnosticCallback

Extract a time series of a 3D field at a given (x,y,z) location

Currently implemented only for the 3D model.

Parameters:

• solver_obj – Thetis FlowSolver object

• fieldnames – List of fields to extract

• z (x, y,) – location coordinates in model coordinate system.

• location_name – Unique name for this location. This determines the name of the output h5 file (prefixed with diagnostic_).

• outputdir (str) – Custom directory where hdf5 files will be stored. By default solver’s output directory is used.

• export_to_hdf5 (bool) – If True, diagnostics will be stored in hdf5 format

• append_to_log (bool) – If True, callback output messages will be printed in log

• start_time – Optional start time for timeseries extraction

• end_time – Optional end time for timeseries extraction

message_str(*args)

A string representation.

Parameters:

args – If provided, these will be the return value from __call__().

name = 'timeseries'

variable_names = ['value']

class thetis.callback.TracerMassConservation2DCallback(tracer_name, solver_obj, **kwargs)

Bases: ScalarConservationCallback

Checks conservation of depth-averaged tracer mass

Depth-averaged tracer mass is defined as the integral of 2D tracer multiplied by total depth.

Parameters:

• tracer_name – Name of the tracer. Use canonical field names as in FieldDict.

• solver_obj – Thetis solver object

• kwargs – any additional keyword arguments, see DiagnosticCallback.

name = 'tracer mass'

class thetis.callback.TracerMassConservationCallback(tracer_name, solver_obj, **kwargs)

Bases: ScalarConservationCallback

Checks conservation of total tracer mass

Parameters:

• tracer_name – Name of the tracer. Use canonical field names as in FieldDict.

• solver_obj – Thetis solver object

• kwargs – any additional keyword arguments, see DiagnosticCallback.

name = 'tracer mass'

class thetis.callback.TracerOvershootCallBack(tracer_name, solver_obj, **kwargs)

Bases: MinMaxConservationCallback

Checks overshoots of the given tracer field.

Parameters:

• tracer_name – Name of the tracer. Use canonical field names as in FieldDict.

• solver_obj – Thetis solver object

• kwargs – any additional keyword arguments, see DiagnosticCallback.

name = 'tracer overshoot'

class thetis.callback.TransectCallback(solver_obj, fieldnames, x, y, location_name, n_points_z=48, z_min=None, z_max=None, outputdir=None, export_to_hdf5=True, append_to_log=True)

Bases: DiagnosticCallback

Extract a vertical transect of a 3D field at a given (x,y) locations.

Only for the 3D model.

Parameters:

• solver_obj – Thetis FlowSolver object

• fieldnames – List of fields to extract

• y (x,) – location coordinates in model coordinate system.

• location_name – Unique name for this location. This determines the name of the output h5 file (prefixed with diagnostic_).

• n_points_z (int) – Number of points along the vertical axis. The 3D field will be interpolated on these points, ranging from the bottom to the (time dependent) free surface.

• zmax (float z_min,) – Force min/max value of z coordinate extent. By default, transect will cover entire depth from bed to surface.

• outputdir (str) – Custom directory where hdf5 files will be stored. By default solver’s output directory is used.

• export_to_hdf5 (bool) – If True, diagnostics will be stored in hdf5 format

• append_to_log (bool) – If True, will print extracted min/max values of each field to log

message_str(*args)

A string representation.

Parameters:

args – If provided, these will be the return value from __call__().

name = 'transect'

variable_names = ['z_coord', 'value']

class thetis.callback.VerticalProfileCallback(solver_obj, fieldnames, x, y, location_name, npoints=48, outputdir=None, export_to_hdf5=True, append_to_log=True)

Bases: DiagnosticCallback

Extract a vertical profile of a 3D field at a given (x,y) location

Only for the 3D model.

Parameters:

• solver_obj – Thetis FlowSolver object

• fieldnames – List of fields to extract

• y (x,) – location coordinates in model coordinate system.

• location_name – Unique name for this location. This determines the name of the output h5 file (prefixed with diagnostic_).

• npoints (int) – Number of points along the vertical axis. The 3D field will be interpolated on these points, ranging from the bottom to the (time dependent) free surface.

• outputdir (str) – Custom directory where hdf5 files will be stored. By default solver’s output directory is used.

• export_to_hdf5 (bool) – If True, diagnostics will be stored in hdf5 format

• append_to_log (bool) – If True, callback output messages will be printed in log

message_str(*args)

A string representation.

Parameters:

args – If provided, these will be the return value from __call__().

name = 'vertprofile'

variable_names = ['z_coord', 'value']

class thetis.callback.VolumeConservation2DCallback(solver_obj, **kwargs)

Bases: ScalarConservationCallback

Checks conservation of 2D volume (integral of water elevation field)

Parameters:

• solver_obj – Thetis solver object

• kwargs – any additional keyword arguments, see DiagnosticCallback.

name = 'volume2d'

class thetis.callback.VolumeConservation3DCallback(solver_obj, **kwargs)

Bases: ScalarConservationCallback

Checks conservation of 3D volume (volume of 3D mesh)

Parameters:

• solver_obj – Thetis solver object

• kwargs – any additional keyword arguments, see DiagnosticCallback.

name = 'volume3d'

thetis.callback.timed_stage()

Log.Stage(cls, name) Source code at petsc4py/PETSc/Log.pyx:11

thetis.configuration module

Utility function and extensions to traitlets used for specifying Thetis options

class thetis.configuration.ABCMetaHasTraits(name, bases, namespace, /, **kwargs)

Bases: ABCMeta, MetaHasTraits

Combined metaclass of ABCMeta and MetaHasTraits

Finish initializing the HasDescriptors class.

class thetis.configuration.BoundedFloat(default_value=traitlets.Undefined, bounds=None, **kwargs)

Bases: Float

Declare a traitlet.

If allow_none is True, None is a valid value in addition to any values that are normally valid. The default is up to the subclass. For most trait types, the default value for allow_none is False.

If read_only is True, attempts to directly modify a trait attribute raises a TraitError.

If help is a string, it documents the attribute’s purpose.

Extra metadata can be associated with the traitlet using the .tag() convenience method or by using the traitlet instance’s .metadata dictionary.

info()

validate(obj, proposal)

class thetis.configuration.BoundedInteger(default_value=traitlets.Undefined, bounds=None, **kwargs)

Bases: Int

Declare a traitlet.

If allow_none is True, None is a valid value in addition to any values that are normally valid. The default is up to the subclass. For most trait types, the default value for allow_none is False.

If read_only is True, attempts to directly modify a trait attribute raises a TraitError.

If help is a string, it documents the attribute’s purpose.

Extra metadata can be associated with the traitlet using the .tag() convenience method or by using the traitlet instance’s .metadata dictionary.

info()

validate(obj, proposal)

class thetis.configuration.DatetimeTraitlet(default_value: Any = traitlets.Undefined, allow_none: bool = False, read_only: bool | None = None, help: str | None = None, config: Any = None, **kwargs: Any)

Bases: TraitType

Declare a traitlet.

If allow_none is True, None is a valid value in addition to any values that are normally valid. The default is up to the subclass. For most trait types, the default value for allow_none is False.

If read_only is True, attempts to directly modify a trait attribute raises a TraitError.

If help is a string, it documents the attribute’s purpose.

Extra metadata can be associated with the traitlet using the .tag() convenience method or by using the traitlet instance’s .metadata dictionary.

default_value: t.Any = None

info_text: str = 'a timezone-aware datetime object'

validate(obj, value)

class thetis.configuration.FiredrakeCoefficient(default_value: Any = traitlets.Undefined, allow_none: bool = False, read_only: bool | None = None, help: str | None = None, config: Any = None, **kwargs: Any)

Bases: TraitType

Declare a traitlet.

If allow_none is True, None is a valid value in addition to any values that are normally valid. The default is up to the subclass. For most trait types, the default value for allow_none is False.

If read_only is True, attempts to directly modify a trait attribute raises a TraitError.

If help is a string, it documents the attribute’s purpose.

Extra metadata can be associated with the traitlet using the .tag() convenience method or by using the traitlet instance’s .metadata dictionary.

default_value: t.Any = None

default_value_repr()

info_text: str = 'a Firedrake Constant or Function'

validate(obj, value)

class thetis.configuration.FiredrakeConstantTraitlet(default_value: Any = traitlets.Undefined, allow_none: bool = False, read_only: bool | None = None, help: str | None = None, config: Any = None, **kwargs: Any)

Bases: TraitType

Declare a traitlet.

If allow_none is True, None is a valid value in addition to any values that are normally valid. The default is up to the subclass. For most trait types, the default value for allow_none is False.

If read_only is True, attempts to directly modify a trait attribute raises a TraitError.

If help is a string, it documents the attribute’s purpose.

Extra metadata can be associated with the traitlet using the .tag() convenience method or by using the traitlet instance’s .metadata dictionary.

default_value: t.Any = None

default_value_repr()

info_text: str = 'a Firedrake Constant'

validate(obj, value)

class thetis.configuration.FiredrakeScalarExpression(default_value: Any = traitlets.Undefined, allow_none: bool = False, read_only: bool | None = None, help: str | None = None, config: Any = None, **kwargs: Any)

Bases: TraitType

Declare a traitlet.

If allow_none is True, None is a valid value in addition to any values that are normally valid. The default is up to the subclass. For most trait types, the default value for allow_none is False.

If read_only is True, attempts to directly modify a trait attribute raises a TraitError.

If help is a string, it documents the attribute’s purpose.

Extra metadata can be associated with the traitlet using the .tag() convenience method or by using the traitlet instance’s .metadata dictionary.

default_value: t.Any = None

default_value_repr()

info_text: str = 'a scalar UFL expression'

validate(obj, value)

class thetis.configuration.FiredrakeVectorExpression(default_value: Any = traitlets.Undefined, allow_none: bool = False, read_only: bool | None = None, help: str | None = None, config: Any = None, **kwargs: Any)

Bases: TraitType

Declare a traitlet.

If allow_none is True, None is a valid value in addition to any values that are normally valid. The default is up to the subclass. For most trait types, the default value for allow_none is False.

If read_only is True, attempts to directly modify a trait attribute raises a TraitError.

If help is a string, it documents the attribute’s purpose.

Extra metadata can be associated with the traitlet using the .tag() convenience method or by using the traitlet instance’s .metadata dictionary.

default_value: t.Any = None

default_value_repr()

info_text: str = 'a vector UFL expression'

validate(obj, value)

class thetis.configuration.FrozenConfigurable(**kwargs: Any)

Bases: OptionsBase, Configurable

A Configurable class that only allows adding new attributes in the class definition or when self._isfrozen is False.

class thetis.configuration.FrozenHasTraits(**kwargs: Any)

Bases: OptionsBase, HasTraits

class thetis.configuration.NonNegativeFloat(default_value: float | Sentinel = ..., allow_none: Literal[False] = ..., read_only: bool | None = ..., help: str | None = ..., config: Any | None = ..., **kwargs: Any)

class thetis.configuration.NonNegativeFloat(default_value: float | Sentinel | None = ..., allow_none: Literal[True] = ..., read_only: bool | None = ..., help: str | None = ..., config: Any | None = ..., **kwargs: Any)

Bases: Float

Declare a traitlet.

If allow_none is True, None is a valid value in addition to any values that are normally valid. The default is up to the subclass. For most trait types, the default value for allow_none is False.

If read_only is True, attempts to directly modify a trait attribute raises a TraitError.

If help is a string, it documents the attribute’s purpose.

Extra metadata can be associated with the traitlet using the .tag() convenience method or by using the traitlet instance’s .metadata dictionary.

info()

validate(obj, proposal)

class thetis.configuration.NonNegativeInteger(default_value: int | Sentinel = ..., allow_none: Literal[False] = ..., read_only: bool | None = ..., help: str | None = ..., config: Any | None = ..., **kwargs: Any)

class thetis.configuration.NonNegativeInteger(default_value: int | Sentinel | None = ..., allow_none: Literal[True] = ..., read_only: bool | None = ..., help: str | None = ..., config: Any | None = ..., **kwargs: Any)

Bases: Int

Declare a traitlet.

If allow_none is True, None is a valid value in addition to any values that are normally valid. The default is up to the subclass. For most trait types, the default value for allow_none is False.

If read_only is True, attempts to directly modify a trait attribute raises a TraitError.

If help is a string, it documents the attribute’s purpose.

Extra metadata can be associated with the traitlet using the .tag() convenience method or by using the traitlet instance’s .metadata dictionary.

info()

validate(obj, proposal)

class thetis.configuration.OptionsBase

Bases: object

Abstract base class for all options classes

abstract property name

Human readable name of the configurable object

update(options)

Assign options from another container

Parameters:

options – Either a dictionary of options or another HasTraits object

class thetis.configuration.PETScSolverParameters(value_trait: TraitType[t.Any, t.Any] | dict[K, V] | Sentinel | None = None, per_key_traits: t.Any = None, key_trait: TraitType[t.Any, t.Any] | None = None, default_value: dict[K, V] | Sentinel | None = traitlets.Undefined, **kwargs: t.Any)

Bases: Dict

PETSc solver options dictionary

Create a dict trait type from a Python dict.

The default value is created by doing dict(default_value), which creates a copy of the default_value.

Parameters

value_traitTraitType [ optional ]

The specified trait type to check and use to restrict the values of the dict. If unspecified, values are not checked.

per_key_traitsDictionary of {keys:trait types} [ optional, keyword-only ]

A Python dictionary containing the types that are valid for restricting the values of the dict on a per-key basis. Each value in this dict should be a Trait for validating

key_traitTraitType [ optional, keyword-only ]

The type for restricting the keys of the dict. If unspecified, the types of the keys are not checked.

default_valueSequenceType [ optional, keyword-only ]

The default value for the Dict. Must be dict, tuple, or None, and will be cast to a dict if not None. If any key or value traits are specified, the default_value must conform to the constraints.

Examples

a dict whose values must be text >>> d = Dict(Unicode())

d2[‘n’] must be an integer d2[‘s’] must be text >>> d2 = Dict(per_key_traits={“n”: Integer(), “s”: Unicode()})

d3’s keys must be text d3’s values must be integers >>> d3 = Dict(value_trait=Integer(), key_trait=Unicode())

info_text: str = 'a PETSc solver options dictionary'

validate(obj, value)

class thetis.configuration.PairedEnum(values, paired_name, default_value=traitlets.Undefined, **kwargs)

Bases: Enum

A enum whose value must be in a given sequence.

This enum controls a slaved option, with default values provided here.

Parameters:

• values – iterable of (value, HasTraits class) pairs. The HasTraits class will be called (with no arguments) to create default values if necessary.

• paired_name – trait name this enum is paired with.

• default_value – default value.

Declare a traitlet.

If allow_none is True, None is a valid value in addition to any values that are normally valid. The default is up to the subclass. For most trait types, the default value for allow_none is False.

If read_only is True, attempts to directly modify a trait attribute raises a TraitError.

If help is a string, it documents the attribute’s purpose.

Extra metadata can be associated with the traitlet using the .tag() convenience method or by using the traitlet instance’s .metadata dictionary.

info()

class thetis.configuration.PositiveFloat(default_value: float | Sentinel = ..., allow_none: Literal[False] = ..., read_only: bool | None = ..., help: str | None = ..., config: Any | None = ..., **kwargs: Any)

class thetis.configuration.PositiveFloat(default_value: float | Sentinel | None = ..., allow_none: Literal[True] = ..., read_only: bool | None = ..., help: str | None = ..., config: Any | None = ..., **kwargs: Any)

Bases: Float

Declare a traitlet.

If allow_none is True, None is a valid value in addition to any values that are normally valid. The default is up to the subclass. For most trait types, the default value for allow_none is False.

If read_only is True, attempts to directly modify a trait attribute raises a TraitError.

If help is a string, it documents the attribute’s purpose.

Extra metadata can be associated with the traitlet using the .tag() convenience method or by using the traitlet instance’s .metadata dictionary.

info()

validate(obj, proposal)

class thetis.configuration.PositiveInteger(default_value: int | Sentinel = ..., allow_none: Literal[False] = ..., read_only: bool | None = ..., help: str | None = ..., config: Any | None = ..., **kwargs: Any)

class thetis.configuration.PositiveInteger(default_value: int | Sentinel | None = ..., allow_none: Literal[True] = ..., read_only: bool | None = ..., help: str | None = ..., config: Any | None = ..., **kwargs: Any)

Bases: Int

Declare a traitlet.

If allow_none is True, None is a valid value in addition to any values that are normally valid. The default is up to the subclass. For most trait types, the default value for allow_none is False.

If read_only is True, attempts to directly modify a trait attribute raises a TraitError.

If help is a string, it documents the attribute’s purpose.

Extra metadata can be associated with the traitlet using the .tag() convenience method or by using the traitlet instance’s .metadata dictionary.

info()

validate(obj, proposal)

thetis.configuration.attach_paired_options(name, name_trait, value_trait)

Attach paired options to a Configurable object.

Parameters:

• name – the name of the enum trait

• name_trait – the enum trait (a PairedEnum)

• value_trait – the slaved value trait.

thetis.configuration.indent(s, nspaces)

thetis.configuration.rst_all_options(cls, nspace=0, prefix=None)

Recursively generate rST for a provided Configurable class.

Parameters:

• cls – The Configurable class.

• nspace – Indentation level.

• prefix – Prefix to use for new traits.

thetis.coordsys module

Generic methods for converting data between different spatial coordinate systems. Uses pyproj library.

class thetis.coordsys.CoordinateSystem

Bases: ABC

Base class for horizontal coordinate systems

Provides methods for coordinate transformations etc.

abstract get_vector_rotator(x, y)

Returns a vector rotator object.

The rotator converst vector-valued data to/from longitude, latitude coordinates.

abstract to_lonlat(x, y)

Convert coordinates to latitude and longitude

class thetis.coordsys.UTMCoordinateSystem(utm_zone)

Bases: CoordinateSystem

Represents Universal Transverse Mercator coordinate systems

get_mesh_lonlat_function(mesh2d)

Construct a Function holding the mesh coordinates in longitude-latitude coordinates.

Parameters:

mesh2d – the 2D mesh

get_vector_rotator(lon, lat)

Returns a vector rotator object.

The rotator converts vector-valued data from longitude, latitude coordinates to mesh coordinate system.

to_lonlat(x, y, positive_lon=False)

Convert (x, y) coordinates to (latitude, longitude)

Parameters:

• x (float or numpy.array_like) – x coordinate

• y (float or numpy.array_like) – y coordinate

• positive_lon – should positive longitude be enforced?

Returns:

longitude, latitude coordinates

to_xy(lon, lat)

Convert (latitude, longitude) coordinates to (x, y)

Parameters:

• lon – longitude coordinate

• lat – latitude coordinate

Returns:

x, y coordinates

class thetis.coordsys.VectorCoordSysRotation(trans, x, y)

Bases: object

Rotates vectors defined in source_sys coordinates to a different coordinate system.

Parameters:

• trans – pyproj.Transformer object, maps from source to destination system

• y (x,) – coordinates in the source coordinate system

thetis.coordsys.get_vector_rotation_matrix(trans, x, y, delta=None)

Estimate rotation matrix that converts vectors defined in source_sys to target_sys. Conversion is carried out by the given trans object.

Assume that we have a vector field defined in source_sys: vectors located at (x, y) define the x and y components. We can then rotate the vectors to represent x2 and y2 components of the target_sys by applying a local rotation:

trans = pyproj.Transformer.from_crs(source_sys, target_sys)
R, theta = get_vector_rotation_matrix(trans, x, y)
v_xy = numpy.array([[v_x], [v_y]])
v_new = numpy.matmul(R, v_xy)
v_x2, v_y2 = v_new

thetis.coordsys.proj_transform(x, y, trans)

Transform coordinates from source to target system.

Parameters:

• x,y – coordinates, float or numpy.array_like

• trans – pyproj Transformer object

thetis.coupled_timeintegrator module

Time integrators for solving coupled 2D-3D system of equations.

class thetis.coupled_timeintegrator.CoupledLeapFrogAM3(solver)

Bases: CoupledTimeIntegrator

Leap-Frog Adams-Moulton 3 time integrator for coupled 2D-3D problem

This is an ALE time integrator. Implementation follows the SLIM time integrator by Karna et al (2013)

Karna, et al. (2013). A baroclinic discontinuous Galerkin finite element model for coastal flows. Ocean Modelling, 61(0):1-20. http://dx.doi.org/10.1016/j.ocemod.2012.09.009

Parameters:

solver – FlowSolver object

advance(t, update_forcings=None, update_forcings3d=None)

Advances the equations for one time step

Parameters:

• t (float) – simulation time

• update_forcings – Optional user-defined function that takes simulation time and updates time-dependent boundary conditions of the 2D equations.

• update_forcings3d – Optional user defined function that updates boundary conditions of the 3D equations

integrator_2d

alias of DIRK22

integrator_3d

alias of LeapFrogAM3

integrator_vert_3d

alias of BackwardEuler

class thetis.coupled_timeintegrator.CoupledTimeIntegrator(solver)

Bases: CoupledTimeIntegratorBase, ABC

Base class of mode-split time integrators that use 2D, 3D and implicit 3D time integrators.

Parameters:

solver – FlowSolver object

initialize()

Assign initial conditions to all necessary fields

Initial conditions are read from fields dictionary.

abstract property integrator_2d

time integrator for 2D equations

abstract property integrator_3d

time integrator for explicit 3D equations (momentum, tracers)

abstract property integrator_vert_3d

time integrator for implicit 3D equations (vertical diffusion)

set_dt(dt, dt_2d)

Set time step for the coupled time integrator

Parameters:

• dt (float) – Time step. This is the master (macro) time step used to march the 3D equations.

• dt_2d (float) – Time step for 2D equations. For consistency dt_2d must be an integer fraction of dt. If 2D solver is implicit set dt_2d equal to dt.

class thetis.coupled_timeintegrator.CoupledTimeIntegratorBase(solver)

Bases: TimeIntegratorBase

Base class for coupled 2D-3D time integrators

Provides common functionality for updating diagnostic fields etc.

Parameters:

solver – FlowSolver object

class thetis.coupled_timeintegrator.CoupledTwoStageRK(solver)

Bases: CoupledTimeIntegrator

Coupled time integrator based on SSPRK(2,2) scheme

This ALE time integration method uses SSPRK(2,2) scheme to advance the 3D equations and a compatible implicit Trapezoid method to advance the 2D equations. Backward Euler scheme is used for vertical diffusion.

Parameters:

solver – FlowSolver object

advance(t, update_forcings=None, update_forcings3d=None)

Advances the equations for one time step

Parameters:

• t (float) – simulation time

• update_forcings – Optional user-defined function that takes simulation time and updates time-dependent boundary conditions of the 2D equations.

• update_forcings3d – Optional user defined function that updates boundary conditions of the 3D equations

compute_mesh_velocity(istage)

Computes mesh velocity for stage i

Must be called after updating the 2D mode.

Parameters:

istage (int) – stage of the Runge-Kutta iteration

integrator_2d

alias of ESDIRKTrapezoid

integrator_3d

alias of SSPRK22ALE

integrator_vert_3d

alias of BackwardEuler

store_elevation(istage)

Store current elevation field for computing mesh velocity

Must be called before updating the 2D mode.

Parameters:

istage (int) – stage of the Runge-Kutta iteration

thetis.coupled_timeintegrator.timed_stage()

Log.Stage(cls, name) Source code at petsc4py/PETSc/Log.pyx:11

thetis.coupled_timeintegrator_2d module

Time integrators for solving coupled shallow water equations with one tracer or sediment.

class thetis.coupled_timeintegrator_2d.CoupledTimeIntegrator2D(solver)

Bases: TimeIntegratorBase, ABC

Base class of time integrator for coupled shallow water and tracer/sediment equations and exner equation

Parameters:

solver – FlowSolver object

advance(t, update_forcings=None)

Advances equations for one time step

Parameters:

• t (float) – simulation time

• update_forcings – user-defined function that takes the simulation time and updates any time-dependent boundary conditions

advance_picard(t, update_forcings=None)

exner_integrator()

time integrator for the exner equation

initialize(solution2d)

Assign initial conditions to all necessary fields

Initial conditions are read from fields dictionary.

set_dt(dt)

Set time step for the coupled time integrator

Parameters:

dt (float) – Time step.

swe_integrator()

time integrator for the shallow water equations

tracer_integrator()

time integrator for the tracer equation

class thetis.coupled_timeintegrator_2d.GeneralCoupledTimeIntegrator2D(solver, integrators)

Bases: CoupledTimeIntegrator2D

A CoupledTimeIntegrator2D which supports a general set of time integrators for the different components.

Parameters:

• solver – the FlowSolver2d object

• integrators – dictionary of time integrators to be used for each equation

class thetis.coupled_timeintegrator_2d.NonHydrostaticTimeIntegrator2D(solver, swe_integrator, fs_integrator)

Bases: CoupledTimeIntegrator2D

2D non-hydrostatic time integrator based on Shallow Water time integrator

This time integration method uses SWE time integrator to advance the hydrostatic equations, depth-integrated Poisson solver to be solved for NH pressure, and a free surface integrator to advance the free surface correction. Advancing in serial or in a whole time stepping depends on the selection of time integrators.

Parameters:

solver – FlowSolver object

advance(t, update_forcings=None)

Advances equations for one time step.

initialize(solution2d)

Assign initial conditions to all necessary fields

Initial conditions are read from fields dictionary.

thetis.coupled_timeintegrator_2d.timed_stage()

Log.Stage(cls, name) Source code at petsc4py/PETSc/Log.pyx:11

thetis.diagnostics module

Classes for computing diagnostics.

class thetis.diagnostics.HessianRecoverer2D(**kwargs: Any)

Bases: DiagnosticCalculator

Linear solver for recovering Hessians.

Hessians are recoved using double \(L^2\) projection, which is implemented using a mixed finite element method.

It is recommended that gradients and Hessians are sought in \(\mathbb P1\) space of appropriate dimension.

Parameters:

• field_2d – scalar expression to recover the Hessian of.

• hessian_2d – Function to hold recovered Hessian.

• gradient_2d – Function to hold recovered gradient.

Kwargs:

to be passed to the LinearVariationalSolver.

field_2d

Field to be recovered

solve()

class thetis.diagnostics.KineticEnergyCalculator(**kwargs: Any)

Bases: DiagnosticCalculator

Class for calculating dynamic pressure (i.e. kinetic energy),

\[E_K = \frac12 \rho \|\mathbf{u}\|^2,\]

where \(\rho\) is the water density and \(\mathbf{u}\) is the velocity.

Parameters:

• uv – scalar expression for the fluid velocity.

• ke – Function to hold calculated kinetic energy.

• density – fluid density.

• horizontal – consider the horizontal components of velocity only?

• project – project, rather than interpolate?

density

Fluid density

solve()

class thetis.diagnostics.ShallowWaterDualWeightedResidual2D(**kwargs: Any)

Bases: DualWeightedResidual2D

Class for computing dual weighted residual contributions for the shallow water equations.

Parameters:

• solver_obj – FlowSolver2d instance

• dual – a Function that approximates the true adjoint solution, which will replace the test function

property form

property space

class thetis.diagnostics.TracerDualWeightedResidual2D(**kwargs: Any)

Bases: DualWeightedResidual2D

Class for computing dual weighted residual contributions for 2D tracer transport problems.

Parameters:

• solver_obj – FlowSolver2d instance

• dual – a Function that approximates the true adjoint solution, which will replace the test function

property form

property space

class thetis.diagnostics.VorticityCalculator2D(**kwargs: Any)

Bases: DiagnosticCalculator

Linear solver for recovering fluid vorticity, interpreted as a scalar field:

\[\omega = -v_x + u_y,\]

for a velocity field \(\mathbf{u} = (u, v)\).

It is recommended that the vorticity is sought in \(\mathbb P1\) space.

Parameters:

• uv_2d – vector expression for the horizontal velocity.

• vorticity_2d – Function to hold calculated vorticity.

Kwargs:

to be passed to the LinearVariationalSolver.

solve()

uv_2d

Horizontal velocity

thetis.equation module

Implements Equation and Term classes.

class thetis.equation.Equation(function_space)

Bases: object

Implements an equation, made out of terms.

Parameters:

function_space – the FunctionSpace the solution belongs to

SUPPORTED_LABELS = frozenset({'explicit', 'implicit', 'nonlinear', 'source'})

Valid labels for terms, indicating how they should be treated in the time integrator.

source

The term is a source term, i.e. does not depend on the solution.

explicit

The term should be treated explicitly

implicit

The term should be treated implicitly

nonlinear

The term is nonlinear and should be treated fully implicitly

add_term(term, label, suffix=None)

Adds a term in the equation

Parameters:

• term – Term object to add_term

• label (string) – Assign a label to the term. Valid labels are given by SUPPORTED_LABELS.

• suffix – optional custom key suffix

jacobian(label, solution, solution_old, fields, fields_old, bnd_conditions)

Returns an UFL form of the Jacobian by summing up all the Jacobians of the terms.

Sign convention: all terms are assumed to be on the right hand side of the equation: d(u)/dt = term.

Parameters:

• label – string defining the type of terms to sum up. Currently one of ‘source’|’explicit’|’implicit’|’nonlinear’. Can be a list of multiple labels, or ‘all’ in which case all defined terms are summed.

• solution – solution Function of the corresponding equation

• solution_old – a time lagged solution Function

• fields – a dictionary that provides all the remaining fields that the term depends on. The keys of the dictionary should standard field names in field_metadata

• fields_old – Time lagged dictionary of fields

• bnd_conditions – A dictionary describing boundary conditions. E.g. {3: {‘elev_2d’: Constant(1.0)}} replaces elev_2d function by a constant on boundary ID 3.

label_term(term, label)

Assings a label to the given term(s).

Parameters:

• term – Term object, or a tuple of terms

• label – string label to assign

mass_term(solution)

Returns default mass matrix term for the solution function space.

Returns:

UFL form of the mass term

residual(label, solution, solution_old, fields, fields_old, bnd_conditions)

Returns an UFL form of the residual by summing up all the terms with the desired label.

Sign convention: all terms are assumed to be on the right hand side of the equation: d(u)/dt = term.

Parameters:

• label – string defining the type of terms to sum up. Currently one of ‘source’|’explicit’|’implicit’|’nonlinear’. Can be a list of multiple labels, or ‘all’ in which case all defined terms are summed.

• solution – solution Function of the corresponding equation

• solution_old – a time lagged solution Function

• fields – a dictionary that provides all the remaining fields that the term depends on. The keys of the dictionary should standard field names in field_metadata

• fields_old – Time lagged dictionary of fields

• bnd_conditions – A dictionary describing boundary conditions. E.g. {3: {‘elev_2d’: Constant(1.0)}} replaces elev_2d function by a constant on boundary ID 3.

select_terms(label)

Generator function that selects terms by label(s).

label can be a single label (e.g. ‘explicit’), ‘all’ or a tuple of labels.

class thetis.equation.Term(function_space, test_function=None, trial_function=None)

Bases: object

Implements a single term of an equation.

Note

Sign convention: all terms are assumed to be on the right hand side of the equation: d(u)/dt = term.

Parameters:

• function_space – the FunctionSpace the solution belongs to

• test_function – custom TestFunction.

• trial_function – custom TrialFunction.

jacobian(solution, solution_old, fields, fields_old, bnd_conditions)

Returns an UFL form of the Jacobian of the term.

Parameters:

• solution – solution Function of the corresponding equation

• solution_old – a time lagged solution Function

• fields – a dictionary that provides all the remaining fields that the term depends on. The keys of the dictionary should standard field names in field_metadata

• fields_old – Time lagged dictionary of fields

• bnd_conditions – A dictionary describing boundary conditions. E.g. {3: {‘elev_2d’: Constant(1.0)}} replaces elev_2d function by a constant on boundary ID 3.

residual(solution, solution_old, fields, fields_old, bnd_conditions)

Returns an UFL form of the term.

Parameters:

• solution – solution Function of the corresponding equation

• solution_old – a time lagged solution Function

• fields – a dictionary that provides all the remaining fields that the term depends on. The keys of the dictionary should standard field names in field_metadata

• fields_old – Time lagged dictionary of fields

• bnd_conditions – A dictionary describing boundary conditions. E.g. {3: {‘elev_2d’: Constant(1.0)}} replaces elev_2d function by a constant on boundary ID 3.

thetis.equation.timed_stage()

Log.Stage(cls, name) Source code at petsc4py/PETSc/Log.pyx:11

thetis.exner_eq module

Exner equation

2D conservation of mass equation describing bed evolution due to sediment transport

The equation reads

(1)\[\frac{\partial z_b}{\partial t} + (m/(1-p)) \nabla_h \cdot \textbf{Q_b} = (m/(1-p)) H ((F_{sink} S) - F_{source})\]

where \(z_b\) is the bedlevel, \(S\) is \(HT\) for conservative (where H is depth and T is the sediment field) and \(T\) for non-conservative (where T is the sediment field), \(\nabla_h\) denotes horizontal gradient, \(m\) is the morphological scale factor, \(p\) is the porosity and \(\textbf{Q_b}\) is the bedload transport vector

class thetis.exner_eq.ExnerBedloadTerm(function_space, depth, sediment_model, depth_integrated_sediment=False)

Bases: ExnerTerm

Bedload transport term, nabla_h cdot textbf{Q_b}

The weak form is

\[\int_\Omega \nabla_h \cdot \textbf{Q_b} \psi dx = - \int_\Omega (\textbf{Q_b} \cdot \nabla) \psi dx + \int_\Gamma \psi \textbf{Q_b} \cdot \textbf{n} dS\]

where \(\textbf{n}\) is the unit normal of the element interfaces.

Parameters:

• function_space – FunctionSpace where the solution belongs

• depth – DepthExpression containing depth info

• sediment_model – SedimentModel containing sediment info

• depth_integrated_sediment (bool) – whether the sediment field is depth-integrated

residual(solution, solution_old, fields, fields_old, bnd_conditions)

Returns an UFL form of the term.

Parameters:

• solution – solution Function of the corresponding equation

• solution_old – a time lagged solution Function

• fields – a dictionary that provides all the remaining fields that the term depends on. The keys of the dictionary should standard field names in field_metadata

• fields_old – Time lagged dictionary of fields

• bnd_conditions – A dictionary describing boundary conditions. E.g. {3: {‘elev_2d’: Constant(1.0)}} replaces elev_2d function by a constant on boundary ID 3.

class thetis.exner_eq.ExnerEquation(function_space, depth, sediment_model, depth_integrated_sediment)

Bases: Equation

Exner equation

2D conservation of mass equation describing bed evolution due to sediment transport

Parameters:

• function_space – FunctionSpace where the solution belongs

• depth –

  class:

  DepthExpression containing depth info

• sediment_model –

  class:

  SedimentModel containing sediment info

• depth_integrated_sediment (bool) – whether to use conservative tracer

class thetis.exner_eq.ExnerSourceTerm(function_space, depth, sediment_model, depth_integrated_sediment=False)

Bases: ExnerTerm

Source term accounting for suspended sediment transport

The weak form reads

\[F_s = \int_\Omega (\sigma - sediment * \phi) * depth \psi dx\]

where \(\sigma\) is a user defined source scalar field Function and \(\phi\) is a user defined source scalar field Function.

Parameters:

• function_space – FunctionSpace where the solution belongs

• depth – DepthExpression containing depth info

• sediment_model – SedimentModel containing sediment info

• depth_integrated_sediment (bool) – whether the sediment field is depth-integrated

residual(solution, solution_old, fields, fields_old, bnd_conditions)

Returns an UFL form of the term.

Parameters:

• solution – solution Function of the corresponding equation

• solution_old – a time lagged solution Function

• fields – a dictionary that provides all the remaining fields that the term depends on. The keys of the dictionary should standard field names in field_metadata

• fields_old – Time lagged dictionary of fields

• bnd_conditions – A dictionary describing boundary conditions. E.g. {3: {‘elev_2d’: Constant(1.0)}} replaces elev_2d function by a constant on boundary ID 3.

class thetis.exner_eq.ExnerTerm(function_space, depth, sediment_model, depth_integrated_sediment=False)

Bases: Term

Generic term in the Exner equations that provides commonly used members There are no boundary conditions for the Exner equation.

Parameters:

• function_space – FunctionSpace where the solution belongs

• depth – DepthExpression containing depth info

• sediment_model – SedimentModel containing sediment info

• depth_integrated_sediment (bool) – whether the sediment field is depth-integrated

thetis.exporter module

Routines for handling file exports.

class thetis.exporter.ExportManager(outputdir, fields_to_export, functions, field_metadata, export_type='vtk', next_export_ix=0, verbose=False, legacy_mode=False, preproc_funcs={})

Bases: object

Helper object for exporting multiple fields simultaneously

from .field_defs import field_metadata
field_dict = {'elev_2d': Function(...), 'uv_3d': Function(...), ...}
e = exporter.ExportManager('mydirectory',
                           ['elev_2d', 'uv_3d', salt_3d'],
                           field_dict,
                           field_metadata,
                           export_type='vtk')
e.export()

Parameters:

• outputdir (string) – directory where files are stored

• fields_to_export (list of strings) – list of fields to export

• functions – dict that contains all existing Function s

• field_metadata – dict of all field metadata. See field_defs

• export_type (str) – export format, either ‘vtk’ or ‘hdf5’

• next_export_ix (int) – index for next export (default 0)

• verbose (bool) – print debug info to stdout

• legacy_mode (bool) – use legacy DumbCheckpoint hdf5 format

add_export(fieldname, function, export_type='vtk', next_export_ix=0, outputdir=None, shortname=None, filename=None, legacy_mode=False, preproc_func=None)

Adds a new field exporter in the manager.

This method allows exporting both default Thetis fields and user defined fields. In the latter case the user must provide sufficient metadata, i.e. fieldname, shortname and filename.

Parameters:

• fieldname (string) – canonical field name

• function – Firedrake function to export

• export_type (str) – export format, either ‘vtk’ or ‘hdf5’

• next_export_ix (int) – index for next export (default 0)

• outputdir (string) – optional directory where files are stored

• shortname (string) – override shortname defined in field_metadata

• filename (string) – override filename defined in field_metadata

• legacy_mode (bool) – use legacy DumbCheckpoint hdf5 format

• preproc_func – optional funtion that will be called prior to exporting. E.g. for computing diagnostic fields.

export()

Export all designated functions to disk

Increments export index by 1.

export_bathymetry(bathymetry_2d)

Special function to export 2D bathymetry data to disk

Parameters:

bathymetry_2d – 2D bathymetry Function

set_next_export_ix(next_export_ix)

Set export index to all child exporters

class thetis.exporter.ExporterBase(filename, outputdir, next_export_ix=0, verbose=False)

Bases: object

Base class for exporter objects.

Parameters:

• filename (string) – output file name (without directory)

• outputdir (string) – directory where file is stored

• next_export_ix (int) – set the index for next output

• verbose (bool) – print debug info to stdout

export(function)

Exports given function to disk

set_next_export_ix(next_export_ix)

Sets the index of next export

class thetis.exporter.HDF5Exporter(function_space, outputdir, filename_prefix, next_export_ix=0, legacy_mode=False, verbose=False)

Bases: ExporterBase

Stores fields in disk in native discretization using HDF5 containers

Create exporter object for given function.

Parameters:

• function_space (FunctionSpace) – space where the exported functions belong

• outputdir (string) – directory where outputs will be stored

• filename_prefix (string) – prefix of output filename. Filename is prefix_nnnnn.h5 where nnnnn is the export number.

• next_export_ix (int) – index for next export (default 0)

• legacy_mode (bool) – use legacy DumbCheckpoint format

• verbose (bool) – print debug info to stdout

export(function)

Export function to disk.

Increments export index by 1.

Parameters:

function – Function to export

export_as_index(iexport, function)

Export function to disk using the specified export index number

Parameters:

• iexport (int) – export index >= 0

• function – Function to export

gen_filename(iexport)

Generate file name ‘prefix_nnnnn.h5’ for i-th export

Parameters:

iexport (int) – export index >= 0

load(iexport, function)

Loads nodal values from disk and assigns to the given function

Parameters:

• iexport (int) – export index >= 0

• function – target Function

class thetis.exporter.VTKExporter(fs_visu, func_name, outputdir, filename, next_export_ix=0, project_output=False, verbose=False)

Bases: ExporterBase

Class that handles Paraview VTK file exports

Parameters:

• fs_visu – function space where input function will be cast before exporting

• func_name – name of the function

• outputdir – output directory

• filename – name of the pvd file

• next_export_ix (int) – index for next export (default 0)

• project_output (bool) – project function to output space instead of interpolating

• verbose (bool) – print debug info to stdout

export(function)

Exports given function to disk

set_next_export_ix(next_export_ix)

Sets the index of next export

thetis.exporter.get_visu_space(fs)

Returns an appropriate VTK visualization space for a function space

Parameters:

fs – function space

Returns:

function space for VTK visualization

thetis.exporter.is_2d(fs)

Tests wether a function space is 2D or 3D

thetis.exporter.timed_stage()

Log.Stage(cls, name) Source code at petsc4py/PETSc/Log.pyx:11

thetis.field_defs module

Definitions and meta data of fields

thetis.field_defs.field_metadata = {'baroc_head_3d': {'filename': 'BaroHead3d', 'name': 'Baroclinic head', 'shortname': 'Baroclinic head', 'unit': 'm'}, 'bathymetry_2d': {'filename': 'bathymetry2d', 'name': 'Bathymetry', 'shortname': 'Bathymetry', 'unit': 'm'}, 'buoy_freq_3d': {'filename': 'BuoyFreq3d', 'name': 'Buoyancy frequency squared', 'shortname': 'Buoyancy frequency squared', 'unit': 's-2'}, 'coriolis_2d': {'filename': 'coriolis_2d', 'name': 'Coriolis parameter', 'shortname': 'Coriolis parameter', 'unit': 's-1'}, 'coriolis_3d': {'filename': 'coriolis_3d', 'name': 'Coriolis parameter', 'shortname': 'Coriolis parameter', 'unit': 's-1'}, 'density_3d': {'filename': 'Density3d', 'name': 'Water density', 'shortname': 'Density', 'unit': 'kg m-3'}, 'eddy_diff_3d': {'filename': 'EddyDiff3d', 'name': 'Eddy diffusivity', 'shortname': 'Eddy diffusivity', 'unit': 'm2 s-1'}, 'eddy_visc_3d': {'filename': 'EddyVisc3d', 'name': 'Eddy Viscosity', 'shortname': 'Eddy Viscosity', 'unit': 'm2 s-1'}, 'elev_2d': {'filename': 'Elevation2d', 'name': 'Water elevation', 'shortname': 'Elevation', 'unit': 'm'}, 'elev_cg_2d': {'filename': 'ElevationCG2d', 'name': 'Water elevation CG', 'shortname': 'Elevation', 'unit': 'm'}, 'elev_domain_2d': {'filename': 'ElevationDomain2d', 'name': 'Surface elevation of domain', 'shortname': 'Elevation', 'unit': 'm'}, 'eps_3d': {'filename': 'TurbEps3d', 'name': 'TKE dissipation rate', 'shortname': 'TKE dissipation rate', 'unit': 'm2 s-3'}, 'h_elem_size_2d': {'filename': 'h_elem_size_2d', 'name': 'Element size in horizontal direction', 'shortname': 'Horizontal element size', 'unit': 'm'}, 'h_elem_size_3d': {'filename': 'h_elem_size_3d', 'name': 'Element size in horizontal direction', 'shortname': 'Horizontal element size', 'unit': 'm'}, 'hcc_metric_3d': {'filename': 'HCCMetric3d', 'name': 'HCC mesh quality', 'shortname': 'HCC metric', 'unit': '-'}, 'int_pg_3d': {'filename': 'IntPG3d', 'name': 'Internal pressure gradient', 'shortname': 'Int. Pressure gradient', 'unit': 'm s-2'}, 'len_3d': {'filename': 'TurbLen3d', 'name': 'Turbulent length scale', 'shortname': 'Turbulent length scale', 'unit': 'm'}, 'max_h_diff': {'filename': 'MaxHDiffusivity3d', 'name': 'Maximum stable horizontal diffusivity', 'shortname': 'Maximum horizontal diffusivity', 'unit': 'm2 s-1'}, 'psi_3d': {'filename': 'TurbPsi3d', 'name': 'Turbulence psi variable', 'shortname': 'Turbulence psi variable', 'unit': ''}, 'q_2d': {'filename': 'NHPressure2d', 'name': 'Non-hydrostatic pressure at bottom', 'shortname': 'NH pressure', 'unit': 'Pa'}, 'salt_3d': {'filename': 'Salinity3d', 'name': 'Water salinity', 'shortname': 'Salinity', 'unit': 'psu'}, 'sediment_2d': {'filename': 'Sediment2d', 'name': 'Sediment', 'shortname': 'Sediment', 'unit': ''}, 'shear_freq_3d': {'filename': 'ShearFreq3d', 'name': 'Vertical shear frequency squared', 'shortname': 'Vertical shear frequency squared', 'unit': 's-2'}, 'smag_visc_3d': {'filename': 'SmagViscosity3d', 'name': 'Smagorinsky viscosity', 'shortname': 'Smagorinsky viscosity', 'unit': 'm2 s-1'}, 'split_residual_2d': {'filename': 'SplitResidual2d', 'name': 'Momentum eq. residual for mode splitting', 'shortname': 'Momentum residual', 'unit': 'm s-2'}, 'temp_3d': {'filename': 'Temperature3d', 'name': 'Water temperature', 'shortname': 'Temperature', 'unit': 'C'}, 'tke_3d': {'filename': 'TurbKEnergy3d', 'name': 'Turbulent Kinetic Energy', 'shortname': 'Turbulent Kinetic Energy', 'unit': 'm2 s-2'}, 'turbine_density_2d': {'filename': 'turbine_density_2d', 'name': 'Turbine density', 'shortname': 'Turbine density', 'unit': 'm-2'}, 'uv_2d': {'filename': 'Velocity2d', 'name': 'Depth averaged velocity', 'shortname': 'Depth averaged velocity', 'unit': 'm s-1'}, 'uv_3d': {'filename': 'Velocity3d', 'name': 'Horizontal velocity', 'shortname': 'Horizontal velocity', 'unit': 'm s-1'}, 'uv_dav_2d': {'filename': 'DAVelocity2d', 'name': 'Depth averaged velocity', 'shortname': 'Depth averaged velocity', 'unit': 'm s-1'}, 'uv_dav_3d': {'filename': 'DAVelocity3d', 'name': 'Depth averaged velocity', 'shortname': 'Depth averaged velocity', 'unit': 'm s-1'}, 'v_elem_size_2d': {'filename': 'VElemSize2d', 'name': 'Element size in vertical direction', 'shortname': 'Vertical element size', 'unit': 'm'}, 'v_elem_size_3d': {'filename': 'VElemSize3d', 'name': 'Element size in vertical direction', 'shortname': 'Vertical element size', 'unit': 'm'}, 'w_2d': {'filename': 'VertVelo2d', 'name': 'Depth averaged vertical velocity', 'shortname': 'Depth averaged vertical velocity', 'unit': 'm s-1'}, 'w_3d': {'filename': 'VertVelo3d', 'name': 'Vertical velocity', 'shortname': 'Vertical velocity', 'unit': 'm s-1'}, 'w_mesh_3d': {'filename': 'MeshVelo3d', 'name': 'Mesh velocity', 'shortname': 'Mesh velocity', 'unit': 'm s-1'}, 'wind_stress_3d': {'filename': 'wind_stress_3d', 'name': 'Wind stress', 'shortname': 'Wind stress', 'unit': 'Pa'}, 'z_coord_3d': {'filename': 'ZCoord3d', 'name': 'Mesh z coordinates', 'shortname': 'Z coordinates', 'unit': 'm'}, 'z_coord_ref_3d': {'filename': 'ZCoordRef3d', 'name': 'Static mesh z coordinates', 'shortname': 'Z coordinates', 'unit': 'm'}}

Dictionary that contains the meta data of each field.

Required meta data entries are:

• name: human readable description

• shortname: description used in visualization etc

• unit: SI unit of the field

• filename: filename for output files

The naming convention for field keys is snake_case: field_name_3d

thetis.forcing module

Routines for interpolating forcing fields for the 3D solver.

class thetis.forcing.ATMInterpolator(function_space, wind_stress_field, atm_pressure_field, coord_system, ncfile_pattern, init_date, vect_rotator=None, east_wind_var_name='uwind', north_wind_var_name='vwind', pressure_var_name='prmsl', fill_mode=None, fill_value=nan, verbose=False)

Bases: object

Interpolates WRF/NAM atmospheric model data on 2D fields.

Parameters:

• function_space – Target (scalar) FunctionSpace object onto which data will be interpolated.

• wind_stress_field – A 2D vector Function where the output wind stress will be stored.

• atm_pressure_field – A 2D scalar Function where the output atmospheric pressure will be stored.

• coord_system – CoordinateSystem object

• ncfile_pattern – A file name pattern for reading the atmospheric model output files. E.g. ‘forcings/nam_air.local.2006_*.nc’

• init_date – A datetime object that indicates the start date/time of the Thetis simulation. Must contain time zone. E.g. ‘datetime(2006, 5, 1, tzinfo=pytz.utc)’

• vect_rotator – function that rotates vectors from ENU coordinates to target function space (optional).

• pressure_var_name (east_wind_var_name, north_wind_var_name,) – wind component and pressure field names in netCDF file.

• fill_mode – Determines how points outside the source grid will be treated. If ‘nearest’, value of the nearest source point will be used. Otherwise a constant fill value will be used (default).

• fill_value (float) – Set the fill value (default: NaN)

• verbose (bool) – Se True to print debug information.

set_fields(time)

Evaluates forcing fields at the given time.

Performs interpolation and updates the output wind stress and atmospheric pressure fields in place.

Parameters:

time (float) – Thetis simulation time in seconds.

class thetis.forcing.ATMNetCDFTime(filename, max_duration=None, verbose=False)

Bases: NetCDFTimeParser

A TimeParser class for reading atmosphere model output files.

Parameters:

• filename –

• max_duration – Time span to read from each file (in seconds). E.g. forecast files can consist of daily files with > 1 day of data. In this case max_duration should be set to 24 h. If None, all time steps are loaded. Default: None.

• verbose (bool) – Se True to print debug information.

class thetis.forcing.FES2004TidalBoundaryForcing(elev_field, init_date, coord_system, vect_rotator=None, uv_field=None, constituents=None, boundary_ids=None, data_dir=None)

Bases: TidalBoundaryForcing

Tidal boundary interpolator for FES2004 tidal model.

Parameters:

• elev_field – Function where tidal elevation will be interpolated.

• init_date – Datetime object defining the simulation init time.

• coord_system – CoordinateSystem object

• vect_rotator – User-defined vector rotator function

• uv_field – Function where tidal transport will be interpolated.

• constituents – list of tidal constituents, e.g. [‘M2’, ‘K1’]

• boundary_ids – list of boundary_ids where tidal data will be evaluated. If not defined, tides will be in evaluated in the entire domain.

• data_dir – path to directory where tidal model netCDF files are located.

compute_velocity = False

coord_layout = 'lat,lon'

elev_nc_file = 'tide.fes2004.nc'

grid_nc_file = None

uv_nc_file = None

class thetis.forcing.GenericInterpolator2D(function_space, fields, field_names, ncfile_pattern, init_date, coord_system, vector_field=None, vector_components=None, vector_rotator=None)

Bases: object

Interpolates 2D fields from netCDF files.

The grid latitude, longitude coordinates must be defined in 1D arrays with CF standard_name attributes “latitude” and “longitude”. Time must be defined with cftime compliant units and metadata.

set_fields(time)

Evaluates forcing fields at the given time

class thetis.forcing.GenericSpatialInterpolator2D(function_space, coord_system, fill_mode=None, fill_value=nan)

Bases: SpatialInterpolator2d

Spatial interpolator class for interpolating netCDF 2D fields.

Parameters:

• function_space – target Firedrake FunctionSpace

• coord_system – CoordinateSystem object

• fill_mode – Determines how points outside the source grid will be treated. If ‘nearest’, value of the nearest source point will be used. Otherwise a constant fill value will be used (default).

• fill_value (float) – Set the fill value (default: NaN)

interpolate(nc_filename, variable_list, itime)

Calls the interpolator object

class thetis.forcing.LiveOceanInterpolator(function_space, fields, field_names, ncfile_pattern, init_date, coord_system)

Bases: object

Interpolates LiveOcean (ROMS) model data on 3D fields

set_fields(time)

Evaluates forcing fields at the given time

class thetis.forcing.NCOMInterpolator(function_space_2d, function_space_3d, fields, field_names, field_fnstr, coord_system, basedir, file_pattern, init_date, verbose=False)

Bases: object

Interpolates NCOM model data on 3D fields.

Note

The following NCOM output files must be present: ./forcings/ncom/model_h.nc ./forcings/ncom/model_lat.nc ./forcings/ncom/model_ang.nc ./forcings/ncom/model_lon.nc ./forcings/ncom/model_zm.nc ./forcings/ncom/2006/s3d/s3d.glb8_2f_2006041900.nc ./forcings/ncom/2006/s3d/s3d.glb8_2f_2006042000.nc ./forcings/ncom/2006/t3d/t3d.glb8_2f_2006041900.nc ./forcings/ncom/2006/t3d/t3d.glb8_2f_2006042000.nc ./forcings/ncom/2006/u3d/u3d.glb8_2f_2006041900.nc ./forcings/ncom/2006/u3d/u3d.glb8_2f_2006042000.nc ./forcings/ncom/2006/v3d/v3d.glb8_2f_2006041900.nc ./forcings/ncom/2006/v3d/v3d.glb8_2f_2006042000.nc ./forcings/ncom/2006/ssh/ssh.glb8_2f_2006041900.nc ./forcings/ncom/2006/ssh/ssh.glb8_2f_2006042000.nc

Parameters:

• function_space_2d – Target (scalar) FunctionSpace object onto which 2D data will be interpolated.

• function_space_3d – Target (scalar) FunctionSpace object onto which 3D data will be interpolated.

• fields – list of Function objects where data will be stored.

• field_names – List of netCDF variable names for the fields. E.g. [‘Salinity’, ‘Temperature’].

• field_fnstr – List of variables in netCDF file names. E.g. [‘s3d’, ‘t3d’].

• coord_system – CoordinateSystem object

• basedir – Root dir where NCOM files are stored. E.g. ‘/forcings/ncom’.

• file_pattern – A file name pattern for reading the NCOM output files (excluding the basedir). E.g. {year:04d}/{fieldstr:}/{fieldstr:}.glb8_2f_{year:04d}{month:02d}{day:02d}00.nc’.

• init_date – A datetime object that indicates the start date/time of the Thetis simulation. Must contain time zone. E.g. ‘datetime(2006, 5, 1, tzinfo=pytz.utc)’

• verbose (bool) – Se True to print debug information.

set_fields(time)

Evaluates forcing fields at the given time

class thetis.forcing.SpatialInterpolatorNCOM2d(function_space, coord_system, grid_path)

Bases: SpatialInterpolatorNCOMBase

Spatial interpolator class for interpolating NCOM ocean model 2D fields.

Parameters:

• function_space – Target (scalar) FunctionSpace object onto which data will be interpolated.

• coord_system – CoordinateSystem object

• grid_path – File path where the NCOM model grid files (‘model_lat.nc’, ‘model_lon.nc’, ‘model_zm.nc’) are located.

interpolate(nc_filename, variable_list, itime)

Calls the interpolator object

class thetis.forcing.SpatialInterpolatorNCOM3d(function_space, coord_system, grid_path)

Bases: SpatialInterpolatorNCOMBase

Spatial interpolator class for interpolating NCOM ocean model 3D fields.

Parameters:

• function_space – Target (scalar) FunctionSpace object onto which data will be interpolated.

• coord_system – CoordinateSystem object

• grid_path – File path where the NCOM model grid files (‘model_lat.nc’, ‘model_lon.nc’, ‘model_zm.nc’) are located.

interpolate(nc_filename, variable_list, itime)

Calls the interpolator object

class thetis.forcing.SpatialInterpolatorNCOMBase(function_space, coord_system, grid_path)

Bases: SpatialInterpolator

Base class for 2D and 3D NCOM spatial interpolators.

Parameters:

• function_space – Target (scalar) FunctionSpace object onto which data will be interpolated.

• coord_system – CoordinateSystem object

• grid_path – File path where the NCOM model grid files (‘model_lat.nc’, ‘model_lon.nc’, ‘model_zm.nc’) are located.

class thetis.forcing.SpatialInterpolatorROMS3d(function_space, coord_system)

Bases: SpatialInterpolator

Abstract spatial interpolator class that can interpolate onto a Function

Parameters:

• function_space – target Firedrake FunctionSpace

• coord_system – CoordinateSystem object

interpolate(nc_filename, variable_list, itime)

Calls the interpolator object

class thetis.forcing.TPXOTidalBoundaryForcing(elev_field, init_date, coord_system, vect_rotator=None, uv_field=None, constituents=None, boundary_ids=None, data_dir=None, elev_file='h_tpxo9.v5a.nc', uv_file='u_tpxo9.v5a.nc', grid_file='gridtpxo9v5a.nc')

Bases: TidalBoundaryForcing

Interpolator for TPXO global tidal model data.

See the TPXO website for data access. By default, this routine assumes the tpxo9v5a data set in NetCDF format. Other versions can be used by setting correct elev_file, uv_file, and grid_file arguments.

Parameters:

• elev_field – Function where tidal elevation will be interpolated.

• init_date – Datetime object defining the simulation init time.

• coord_system – CoordinateSystem object

• vect_rotator – User-defined vector rotator function

• uv_field – Function where tidal transport will be interpolated.

• constituents – list of tidal constituents, e.g. [‘M2’, ‘K1’]

• boundary_ids – list of boundary_ids where tidal data will be evaluated. If not defined, tides will be in evaluated in the entire domain.

• data_dir – path to directory where tidal model netCDF files are located.

• elev_file – TPXO tidal elevation file

• uv_file – TPXO transport/velocity file

• grid_file – TPXO grid file

compute_velocity = True

coord_layout = 'lon,lat'

class thetis.forcing.TidalBoundaryForcing(elev_field, init_date, coord_system, vect_rotator=None, uv_field=None, constituents=None, boundary_ids=None, data_dir=None)

Bases: ABC

Base class for tidal boundary interpolators.

Parameters:

• elev_field – Function where tidal elevation will be interpolated.

• init_date – Datetime object defining the simulation init time.

• coord_system – CoordinateSystem object

• vect_rotator – User-defined vector rotator function

• uv_field – Function where tidal transport will be interpolated.

• constituents – list of tidal constituents, e.g. [‘M2’, ‘K1’]

• boundary_ids – list of boundary_ids where tidal data will be evaluated. If not defined, tides will be in evaluated in the entire domain.

• data_dir – path to directory where tidal model netCDF files are located.

abstract property compute_velocity

If True, compute tidal currents as well.

abstract property coord_layout

Data layout in the netcdf files.

Either ‘lon,lat’ or ‘lat,lon’.

set_tidal_field(t)

thetis.forcing.compute_wind_stress(wind_u, wind_v, method='LargeYeager2009')

Compute wind stress from atmospheric 10 m wind.

wind stress is defined as

where \(C_D\) is the drag coefficient, \(\rho_{air}\) is the density of air, and \(U_{10}\) is wind speed 10 m above the sea surface.

In practice C_D depends on the wind speed.

Two formulation are currently implemented:

• “LargePond1981”:

  Wind stress formulation by [1]

• “SmithBanke1975”:

  Wind stress formulation by [2]

• “LargeYeager2009”:

  Wind stress formulation by [3]

[1] Large and Pond (1981). Open Ocean Momentum Flux Measurements in

Moderate to Strong Winds. Journal of Physical Oceanography, 11(3):324-336. https://doi.org/10.1175/1520-0485(1981)011%3C0324:OOMFMI%3E2.0.CO;2

[2] Smith and Banke (1975). Variation of the sea surface drag coefficient

with wind speed. Q J R Meteorol Soc., 101(429):665-673. https://doi.org/10.1002/qj.49710142920

[3] Large and Yeager (2009). The global climatology of an interannually

varying air–sea flux data set. Climate Dynamics, 33:341–364. http://dx.doi.org/10.1007/s00382-008-0441-3

Parameters:

• wind_v (wind_u,) – Wind u and v components as numpy arrays

• method – Choose the stress formulation. Currently supports: ‘LargeYeager2009’ (default), ‘LargePond1981’, or ‘SmithBanke1975’.

Returns:

(tau_x, tau_y) wind stress x and y components as numpy arrays

thetis.implicitexplicit module

Implicit-explicit time integrators

class thetis.implicitexplicit.IMEXEuler(equation, solution, fields, dt, options, bnd_conditions)

Bases: IMEXGeneric

Forward-Backward Euler

Parameters:

• equation (Equation object) – equation to solve

• solution – Function where solution will be stored

• fields (dict of Function or Constant objects) – Dictionary of fields that are passed to the equation

• dt (float) – time step in seconds

• options – TimeStepperOptions instance containing parameter values.

• bnd_conditions (dict) – Dictionary of boundary conditions passed to the equation

dirk_class

alias of BackwardEuler

erk_class

alias of ERKEuler

class thetis.implicitexplicit.IMEXGeneric(equation, solution, fields, dt, options, bnd_conditions)

Bases: TimeIntegrator, ABC

Generic implementation of Runge-Kutta Implicit-Explicit schemes

Derived classes must define the implicit dirk_class and explicit erk_class Runge-Kutta time integrator classes.

This method solves the linearized equations: All implicit terms are fed to the implicit solver, while all the other terms are fed to the explicit solver. In case of non-linear terms proper linearization must defined in the equation using the two solution functions (solution, solution_old)

Parameters:

• equation (Equation object) – equation to solve

• solution – Function where solution will be stored

• fields (dict of Function or Constant objects) – Dictionary of fields that are passed to the equation

• dt (float) – time step in seconds

• options – TimeStepperOptions instance containing parameter values.

• bnd_conditions (dict) – Dictionary of boundary conditions passed to the equation

advance(t, update_forcings=None)

Advances equations for one time step.

abstract property dirk_class

Implicit DIRK class

abstract property erk_class

Explicit Runge-Kutta class

get_final_solution()

Evaluates the final solution.

initialize(solution)

Assigns initial conditions to all required fields.

set_dt(dt)

Update time step

Parameters:

dt (float) – time step

solve_stage(i_stage, t, update_forcings=None)

Solves i-th stage

update_solver()

Create solver objects

class thetis.implicitexplicit.IMEXLPUM2(equation, solution, fields, dt, options, bnd_conditions)

Bases: IMEXGeneric

SSP-IMEX RK scheme (20) in Higureras et al. (2014)

CFL coefficient is 2.0

Higueras et al (2014). Optimized strong stability preserving IMEX Runge-Kutta methods. Journal of Computational and Applied Mathematics 272(2014) 116-140. http://dx.doi.org/10.1016/j.cam.2014.05.011

Parameters:

• equation (Equation object) – equation to solve

• solution – Function where solution will be stored

• fields (dict of Function or Constant objects) – Dictionary of fields that are passed to the equation

• dt (float) – time step in seconds

• options – TimeStepperOptions instance containing parameter values.

• bnd_conditions (dict) – Dictionary of boundary conditions passed to the equation

dirk_class

alias of DIRKLPUM2

erk_class

alias of ERKLPUM2

class thetis.implicitexplicit.IMEXLSPUM2(equation, solution, fields, dt, options, bnd_conditions)

Bases: IMEXGeneric

SSP-IMEX RK scheme (17) in Higureras et al. (2014)

CFL coefficient is 2.0

Higueras et al (2014). Optimized strong stability preserving IMEX Runge-Kutta methods. Journal of Computational and Applied Mathematics 272(2014) 116-140. http://dx.doi.org/10.1016/j.cam.2014.05.011

Parameters:

• equation (Equation object) – equation to solve

• solution – Function where solution will be stored

• fields (dict of Function or Constant objects) – Dictionary of fields that are passed to the equation

• dt (float) – time step in seconds

• options – TimeStepperOptions instance containing parameter values.

• bnd_conditions (dict) – Dictionary of boundary conditions passed to the equation

dirk_class

alias of DIRKLSPUM2

erk_class

alias of ERKLSPUM2

class thetis.implicitexplicit.IMEXMidpoint(equation, solution, fields, dt, options, bnd_conditions)

Bases: IMEXGeneric

Implicit-explicit midpoint scheme (1, 2, 2) from Ascher et al. (1997)

Ascher et al. (1997). Implicit-explicit Runge-Kutta methods for time-dependent partial differential equations. Applied Numerical Mathematics, 25:151-167. http://dx.doi.org/10.1137/0732037

Parameters:

• equation (Equation object) – equation to solve

• solution – Function where solution will be stored

• fields (dict of Function or Constant objects) – Dictionary of fields that are passed to the equation

• dt (float) – time step in seconds

• options – TimeStepperOptions instance containing parameter values.

• bnd_conditions (dict) – Dictionary of boundary conditions passed to the equation

dirk_class

alias of ESDIRKMidpoint

erk_class

alias of ERKMidpoint

thetis.implicitexplicit.timed_region()

Log.Event(cls, name, klass=None) Source code at petsc4py/PETSc/Log.pyx:39

thetis.implicitexplicit.timed_stage()

Log.Stage(cls, name) Source code at petsc4py/PETSc/Log.pyx:11

thetis.interpolation module

Methods for interpolating data from structured data sets on Thetis fields.

Simple example of an atmospheric pressure interpolator:

class WRFInterpolator(object):
    # Interpolates WRF atmospheric model data on 2D fields
    def __init__(self, function_space, atm_pressure_field, ncfile_pattern, init_date):
        self.atm_pressure_field = atm_pressure_field

        # object that interpolates forcing data from structured grid on the local mesh
        self.grid_interpolator = NetCDFLatLonInterpolator2d(function_space, coord_system)
        # reader object that can read fields from netCDF files, applies spatial interpolation
        self.reader = NetCDFSpatialInterpolator(self.grid_interpolator, ['prmsl'])
        # object that can find previous/next time stamps in a collection of netCDF files
        self.timesearch_obj = NetCDFTimeSearch(ncfile_pattern, init_date, NetCDFTimeParser)
        # finally a linear intepolator class that performs linar interpolation in time
        self.interpolator = LinearTimeInterpolator(self.timesearch_obj, self.reader)

    def set_fields(self, time):
        # Evaluates forcing fields at the given time
        pressure = self.interpolator(time)
        self.atm_pressure_field.dat.data_with_halos[:] = pressure

Usage:

atm_pressure_2d = Function(solver_obj.function_spaces.P1_2d, name='atm pressure')
wrf_pattern = 'forcings/atm/wrf/wrf_air.2016_*_*.nc'
wrf_atm = WRFInterpolator(
    solver_obj.function_spaces.P1_2d,
    wind_stress_2d, atm_pressure_2d, wrf_pattern, init_date)
simulation_time = 3600.
wrf_atm.set_fields(simulation_time)

class thetis.interpolation.DailyFileTimeSearch(file_pattern, init_date, verbose=False, center_hour=12, center_timezone=<UTC>)

Bases: TimeSearch

Treats a list of daily files as a time series.

File name pattern must be given as a string where the 4-digit year is tagged with “{year:04d}”, and 2-digit zero-padded month and year are tagged with “{month:02d}” and “{day:02d}”, respectively. The tags can be used multiple times.

Example pattern:

‘ncom/{year:04d}/s3d.glb8_2f_{year:04d}{month:02d}{day:02d}00.nc’

In this time search method the time stamps are parsed solely from the filename, no other metadata is used. By default the data is assumed to be centered at 12:00 UTC every day.

find(simulation_time, previous=False)

Find file that contains the given simulation time

Parameters:

• simulation_time (float) – simulation time in seconds

• previous (bool) – if True finds previous existing time stamp instead of next (default False).

Returns:

(filename, time index, simulation time) of found data

simulation_time_to_datetime(t)

class thetis.interpolation.FileTreeReader

Bases: object

Abstract base class of file tree reader object

class thetis.interpolation.GridInterpolator(grid_xyz, target_xyz, fill_mode=None, fill_value=nan, normalize=False, dont_raise=False)

Bases: object

A reuseable griddata interpolator object.

Usage:

interpolator = GridInterpolator(source_xyz, target_xyz)
vals = interpolator(source_data)

Example:

x0 = numpy.linspace(0, 10, 10)
y0 = numpy.linspace(5, 10, 10)
X, Y = numpy.meshgrid(x, y)
x = X.ravel(); y = Y.ravel()
data = x + 25.*y
x_target = numpy.linspace(1, 10, 20)
y_target = numpy.linspace(5, 10, 20)
interpolator = GridInterpolator(numpy.vstack((x, y)).T, numpy.vstack((target_x, target_y)).T)
vals = interpolator(data)

Based on http://stackoverflow.com/questions/20915502/speedup-scipy-griddata-for-multiple-interpolations-between-two-irregular-grids

Parameters:

• grid_xyz – Array of source grid coordinates, shape (npoints, 2) or (npoints, 3)

• target_xyz – Array of target grid coordinates, shape (n, 2) or (n, 3)

• fill_mode – Determines how points outside the source grid will be treated. If ‘nearest’, value of the nearest source point will be used. Otherwise a constant fill value will be used (default).

• fill_value (float) – Set the fill value (default: NaN)

• normalize (bool) – If true the data is scaled to unit cube before interpolation. Default: False.

• dont_raise (bool) – Do not raise a Qhull error if triangulation fails. In this case the data will be set to fill value or nearest neighbor value.

class thetis.interpolation.LinearTimeInterpolator(timesearch_obj, reader)

Bases: object

Interpolates time series in time

User must provide timesearch_obj that finds time stamps from a file tree, and a reader that can read those time stamps into numpy arrays.

Previous/next data sets are cached in memory to avoid hitting disk every time.

Parameters:

• timesearch_obj – TimeSearch object

• reader – FileTreeReader object

class thetis.interpolation.NetCDFLatLonInterpolator2d(function_space, coord_system, fill_mode=None, fill_value=nan)

Bases: SpatialInterpolator2d

Interpolates netCDF data on a local 2D unstructured mesh

The intepolator is constructed for a single netCDF file that defines the source grid. Once the interpolator has been constructed, data can be read from any file that uses the same grid.

This routine returns the data in numpy arrays.

Usage:

fs = FunctionSpace(...)
myfunc = Function(fs, ...)
ncinterp2d = NetCDFLatLonInterpolator2d(fs, coord_system, nc_filename)
val1, val2 = ncinterp2d.interpolate(nc_filename, ['var1', 'var2'], 10)
myfunc.dat.data_with_halos[:] = val1 + val2

Parameters:

• function_space – target Firedrake FunctionSpace

• coord_system – CoordinateSystem object

• fill_mode – Determines how points outside the source grid will be treated. If ‘nearest’, value of the nearest source point will be used. Otherwise a constant fill value will be used (default).

• fill_value (float) – Set the fill value (default: NaN)

interpolate(nc_filename, variable_list, itime)

Interpolates data from a netCDF file onto Firedrake function space.

Parameters:

• nc_filename (str) – netCDF file to read

• variable_list – list of netCDF variable names to read

• itime (int) – time index to read

Returns:

list of numpy.arrays corresponding to variable_list

class thetis.interpolation.NetCDFSpatialInterpolator(grid_interpolator, variable_list)

Bases: FileTreeReader

Wrapper class that provides FileTreeReader API for grid interpolators

class thetis.interpolation.NetCDFTimeParser(filename, time_variable_name='time', allow_gaps=False, verbose=False)

Bases: TimeParser

Describes the time stamps stored in a netCDF file.

Construct a new object by scraping data from the given netcdf file.

Parameters:

• filename (str) – name of the netCDF file to read

• time_variable_name (str) – name of the time variable in the netCDF file (default: ‘time’)

• allow_gaps (bool) – if False, an error is raised if time step is not constant.

find_time_stamp(t, previous=False)

Given time t, returns index of the next (previous) time stamp

raises IndexError if t is out of range, i.e. t > self.get_end_time() or t < self.get_start_time()

get_end_time()

Returns the last time stamp in the file/data set

get_start_time()

Returns the first time stamp in the file/data set

class thetis.interpolation.NetCDFTimeSearch(file_pattern, init_date, netcdf_class, *args, **kwargs)

Bases: TimeSearch

Finds a nearest time stamp in a collection of netCDF files.

find(simulation_time, previous=False)

Find file that contains the given simulation time

Parameters:

• simulation_time (float) – simulation time in seconds

• previous (bool) – if True finds previous existing time stamp instead of next (default False).

Returns:

(filename, time index, simulation time) of found data

simulation_time_to_datetime(t)

class thetis.interpolation.NetCDFTimeSeriesInterpolator(ncfile_pattern, variable_list, init_date, time_variable_name='time', scalars=None, allow_gaps=False)

Bases: object

Reads and interpolates scalar time series from a sequence of netCDF files.

Parameters:

• ncfile_pattern (str) – file search pattern, e.g. “mydir/foo_*.nc”

• variable_list – list if netCDF variable names to read

• init_date (datetime.datetime) – simulation start time

• scalars – (optional) list of scalars; scale output variables by a factor.

Note

All the variables must have the same dimensions in the netCDF files. If the shapes differ, create separate interpolator instances.

class thetis.interpolation.NetCDFTimeSeriesReader(variable_list, time_variable_name='time')

Bases: FileTreeReader

A simple netCDF reader that returns a time slice of the given variable.

This class does not interpolate the data in any way. Useful for interpolating time series.

class thetis.interpolation.SpatialInterpolator(function_space, coord_system)

Bases: ABC

Abstract base class for spatial interpolators that read data from disk

Parameters:

• function_space – target Firedrake FunctionSpace

• coord_system – CoordinateSystem object

abstract interpolate(filename, variable_list, itime)

Interpolates data from the given file at given time step

class thetis.interpolation.SpatialInterpolator2d(function_space, coord_system, fill_mode=None, fill_value=nan)

Bases: SpatialInterpolator, ABC

Abstract spatial interpolator class that can interpolate onto a 2D Function

Parameters:

• function_space – target Firedrake FunctionSpace

• coord_system – CoordinateSystem object

• fill_mode – Determines how points outside the source grid will be treated. If ‘nearest’, value of the nearest source point will be used. Otherwise a constant fill value will be used (default).

• fill_value (float) – Set the fill value (default: NaN)

abstract interpolate(filename, variable_list, time)

Calls the interpolator object

class thetis.interpolation.TimeParser

Bases: object

Abstract base class for time definition objects.

Defines the time span that a file (or data set) covers and provides a time index search routine.

abstract find_time_stamp(t, previous=False)

Given time t, returns index of the next (previous) time stamp

raises IndexError if t is out of range, i.e. t > self.get_end_time() or t < self.get_start_time()

abstract get_end_time()

Returns the last time stamp in the file/data set

abstract get_start_time()

Returns the first time stamp in the file/data set

class thetis.interpolation.TimeSearch

Bases: object

Base class for searching nearest time steps in a file tree or database

abstract find(time, previous=False)

Find a next (previous) time stamp from a given time

Parameters:

• time (float) – input time stamp

• previous (bool) – if True, look for last time stamp before requested time. Otherwise returns next time stamp.

Returns:

a (filename, time_index, time) tuple

thetis.interpolation.get_ncvar_name(ncfile, standard_name=None, long_name=None, var_name=None)

Look for variables that match either CF standard_name or long_name attributes.

If both are defined, standard_name takes precedence.

Note that the attributes in the netCDF file converted to lower case prior to checking.

Parameters:

• ncfile – netCDF4 Dataset object

• standard_name – a target standard_name, or a list of them

• long_name – a target long_name, or a list of them

• var_name – a target netCDF variable name, or a list of them

thetis.inversion_tools module

class thetis.inversion_tools.ControlRegularizationManager(function_list, gamma_list, penalty_term_scaling=None, calculator=<class 'thetis.inversion_tools.HessianRegularizationCalculator'>)

Bases: object

Handles regularization of multiple control fields

Parameters:

• function_list – list of control functions

• gamma_list – list of penalty parameters

• penalty_term_scaling – Penalty term scaling factor

• calculator – class used for obtaining regularization

eval_cost_function()

class thetis.inversion_tools.HessianRegularizationCalculator(function, gamma, scaling=1.0)

Bases: RegularizationCalculator

Computes the following regularization term for a cost function involving a control Function \(f\):

\[J = \gamma \| (\Delta x)^2 H(f) \|^2,\]

where \(H\) is the Hessian of field \(f\).

Parameters:

• function – Control Function

• gamma – Hessian penalty coefficient

eval_cost_function()

class thetis.inversion_tools.InversionManager(**kwargs: Any)

Bases: FrozenHasTraits

Class for handling inversion problems and stashing the progress of the associated optimization routines.

Parameters:

• sta_manager – the StationManager instance

• output_dir – model output directory

• no_exports – if True, nothing will be written to disk

• real – is the inversion in the Real space?

• penalty_parameters – a list of penalty parameters to pass to the ControlRegularizationManager

• cost_function_scaling – global scaling for the cost function. As rule of thumb, it’s good to scale the functional to J < 1.

• test_consistency – toggle testing the correctness with which the ReducedFunctional can recompute values

• test_gradient – toggle testing the correctness with which the ReducedFunctional can recompute gradients

add_control(f)

Add a control field.

Can be called multiple times in case of multiparameter optimization.

Parameters:

f – Function or Constant to be used as a control variable.

consistency_test()

Test that reduced_functional can correctly recompute the objective value, assuming that none of the controls have changed since it was created.

get_cost_function(solver_obj, weight_by_variance=False)

Get a sum of square errors cost function for the problem:

..math::

J(u) = sum_{i=1}^{n_{ts}} sum_{j=1}^{n_{sta}} (u_j^{(i)} - u_{j,o}^{(i)})^2,

where \(u_{j,o}^{(i)}\) and \(u_j^{(i)}\) denote the observed and computed values at timestep \(i\), and \(n_{ts}\) and \(n_{sta}\) are the numbers of timesteps and stations, respectively.

Regularization terms are included if a RegularizationManager instance is provided.

arg solver_obj:

the FlowSolver2d instance

kwarg weight_by_variance:

should the observation data be weighted by the variance at each station?

get_optimization_callback()

Get a callback for stashing optimization progress after successful line search.

initialize()

minimize(opt_method='BFGS', bounds=None, **opt_options)

Minimize the reduced functional using a given optimization routine.

Parameters:

• opt_method – the optimization routine

• bounds – a list of bounds to pass to the optimization routine

• opt_options – other optimization parameters to pass

property reduced_functional

Create a Pyadjoint ReducedFunctional for the optimization.

reset_counters()

property rf_kwargs

Default keyword arguments to pass to the ReducedFunctional class.

set_control_state(j, djdm_list, m_list)

Stores optimization state.

To call whenever variables are updated.

Parameters:

• j – error functional value

• djdm_list – list of gradient functions

• m_list – list of control coefficents

set_initial_state(*state)

start_clock()

stop_annotating()

Stop recording operations for the adjoint solver.

This method should be called after the iterate() method of FlowSolver2d.

stop_clock()

taylor_test()

Run a Taylor test to check that the reduced_functional can correctly compute consistent gradients.

Note that the Taylor test is applied on the current control values.

update_progress()

Updates optimization progress and stores variables to disk.

To call after successful line searches.

class thetis.inversion_tools.RSpaceRegularizationCalculator(function, gamma, eps=0.001, scaling=1.0)

Bases: RegularizationCalculator

Computes the following regularization term for a cost function involving a control Function \(f\) from an R-space:

\[J = \gamma (f - f_0)^2,\]

where \(f_0\) is a prior, taken to be the initial value of \(f\).

Parameters:

• function – Control Function

• gamma – penalty coefficient

• eps – tolerance for normalising by near-zero priors

class thetis.inversion_tools.RegularizationCalculator(function, scaling=1.0)

Bases: ABC

Base class for computing regularization terms.

A derived class should set regularization_expr in __init__(). Whenever the cost function is evaluated, the ratio of this expression and the total mesh area will be added.

Parameters:

function – Control Function

eval_cost_function()

class thetis.inversion_tools.StationObservationManager(mesh, output_directory='outputs')

Bases: object

Implements error functional based on observation time series.

The functional is the squared sum of error between the model and observations.

This object evaluates the model fields at the station locations, interpolates the observations time series to the model time, computes the error functional, and also stores the model’s time series data to disk.

Parameters:

• mesh – the 2D mesh object.

• output_directory – directory where model time series are stored.

construct_evaluator()

Builds evaluators needed to compute the error functional.

dump_time_series()

Stores model time series to disk.

Obtains station time series from the last optimization iteration, and stores the data to disk.

The output files are have the format {odir}/diagnostic_timeseries_progress_{station_name}_{variable}.hdf5

The file contains the simulation time in the time array, and the station name and coordinates as attributes. The time series data is stored as a 2D (n_iterations, n_time_steps) array.

eval_cost_function(t)

Evaluate the cost function.

Should be called at every export of the forward model.

eval_observation_at_time(t)

Evaluate observation time series at the given time.

Parameters:

t – model simulation time

Returns:

list of observation time series values at time t

load_observation_data(observation_data_dir, station_names, variable, start_times=None, end_times=None)

Load observation data from disk.

Assumes that observation data were stored with TimeSeriesCallback2D during the forward run. For generic case, use register_observation_data instead.

Parameters:

• observation_data_dir (str) – directory where observation data is stored

• station_names (list) – list of station names

• variable (str) – canonical variable name, e.g. ‘elev’

• start_times (list) – optional start times for the observation periods

• end_times (list) – optional end times for the observation periods

register_observation_data(station_names, variable, time, values, x, y, start_times=None, end_times=None)

Add station time series data to the object.

The x, and y coordinates must be such that they allow extraction of model data at the same coordinates.

Parameters:

• station_names (list) – list of station names

• variable (str) – canonical variable name, e.g. ‘elev’

• time (list) – array of time stamps, one for each station

• values (list) – array of observations, one for each station

• x (list) – list of station x coordinates

• y (list) – list of station y coordinates

• start_times (list) – optional start times for the observation periods

• end_times (list) – optional end times for the observation periods

set_model_field(function)

Set the model field that will be evaluated.

update_stations_in_use(t)

Indicate which stations are in use at the current time.

An entry of unity indicates use, whereas zero indicates disuse.

thetis.limiter module

Slope limiters for discontinuous fields

class thetis.limiter.VertexBasedP1DGLimiter(p1dg_space, time_dependent_mesh=True)

Bases: VertexBasedLimiter

Vertex based limiter for P1DG tracer fields, see Kuzmin (2010)

Note

Currently only scalar fields are supported

Kuzmin (2010). A vertex-based hierarchical slope limiter for p-adaptive discontinuous Galerkin methods. Journal of Computational and Applied Mathematics, 233(12):3077-3085. http://dx.doi.org/10.1016/j.cam.2009.05.028

Parameters:

p1dg_space – P1DG function space

apply(field)

Applies the limiter on the given field (in place)

Parameters:

field – Function to limit

compute_bounds(field)

Re-compute min/max values of all neighbouring centroids

Parameters:

field – Function to limit

thetis.limiter.assert_function_space(fs, family, degree)

Checks the family and degree of function space.

Raises AssertionError if function space differs. If the function space lies on an extruded mesh, checks both spaces of the outer product.

Parameters:

• fs – function space

• family (string) – name of element family

• degree (int) – polynomial degree of the function space

thetis.limiter.timed_stage()

Log.Stage(cls, name) Source code at petsc4py/PETSc/Log.pyx:11

thetis.log module

Loggers for Thetis

Creates two logger instances, one for general model output and one for debug, warning, error etc. messages.

To print to the model output stream, use print_output().

Debug, warning etc. messages are issued with debug(), info(), warning(), error(), critical() methods.

thetis.log.critical(msg, *args, **kwargs)

Log ‘msg % args’ with severity ‘CRITICAL’.

To pass exception information, use the keyword argument exc_info with a true value, e.g.

logger.critical(“Houston, we have a %s”, “major disaster”, exc_info=1)

thetis.log.debug(msg, *args, **kwargs)

Log ‘msg % args’ with severity ‘DEBUG’.

To pass exception information, use the keyword argument exc_info with a true value, e.g.

logger.debug(“Houston, we have a %s”, “thorny problem”, exc_info=1)

thetis.log.error(msg, *args, **kwargs)

Log ‘msg % args’ with severity ‘ERROR’.

To pass exception information, use the keyword argument exc_info with a true value, e.g.

logger.error(“Houston, we have a %s”, “major problem”, exc_info=1)

thetis.log.info(msg, *args, **kwargs)

Log ‘msg % args’ with severity ‘INFO’.

To pass exception information, use the keyword argument exc_info with a true value, e.g.

logger.info(“Houston, we have a %s”, “interesting problem”, exc_info=1)

thetis.log.log(level, msg, *args, **kwargs)

Log ‘msg % args’ with the integer severity ‘level’.

To pass exception information, use the keyword argument exc_info with a true value, e.g.

logger.log(level, “We have a %s”, “mysterious problem”, exc_info=1)

thetis.log.print_output(msg, *args, **kwargs)

Log ‘msg % args’ with severity ‘INFO’.

To pass exception information, use the keyword argument exc_info with a true value, e.g.

logger.info(“Houston, we have a %s”, “interesting problem”, exc_info=1)

thetis.log.set_log_directory(output_directory, comm=<mpi4py.MPI.Intracomm object>, mode='w')

Forward all log output to output_directory/log file.

When called, a new empty log file is created.

If called twice with a different output_directory, a warning is raised, and the new log file location is assigned. The old log file or the output_directory are not removed.

Parameters:

• output_directory – the directory where log file is stored

• comm – The communicator the handler should be collective over. Only rank-0 on that communicator will write to the log, other ranks will use a logging.NullHandler.

• mode – write mode, ‘w’ removes previous log file (if any), otherwise appends to it. Default: ‘w’.

thetis.log.set_thetis_loggers(comm=<mpi4py.MPI.Intracomm object>)

Set stream handlers for log messages.

Parameters:

comm – The communicator the handler should be collective over. Only rank-0 on that communicator will write to the log, other ranks will use a logging.NullHandler.

thetis.log.thetis_log_level(level)

Set the log level for Thetis logger.

This controls what level of logging messages are printed to stderr. The higher the level, the fewer the number of messages.

Parameters:

level – The level to use, one of ‘DEBUG’, ‘INFO’, ‘WARNING’, ‘ERROR’, ‘CRITICAL’.

thetis.log.warning(msg, *args, **kwargs)

Log ‘msg % args’ with severity ‘WARNING’.

To pass exception information, use the keyword argument exc_info with a true value, e.g.

logger.warning(“Houston, we have a %s”, “bit of a problem”, exc_info=1)

thetis.momentum_eq module

3D momentum equation for hydrostatic Boussinesq flow.

The three dimensional momentum equation reads

(2)\[\frac{\partial \textbf{u}}{\partial t} + \nabla_h \cdot (\textbf{u} \textbf{u}) + \frac{\partial \left(w\textbf{u} \right)}{\partial z} + f\textbf{e}_z\wedge\textbf{u} + g\nabla_h \eta + g\nabla_h r = \nabla_h \cdot \left( \nu_h \nabla_h \textbf{u} \right) + \frac{\partial }{\partial z}\left( \nu \frac{\partial \textbf{u}}{\partial z}\right)\]

where \(\textbf{u}\) and \(w\) denote horizontal and vertical velocity, \(\nabla_h\) is the horizontal gradient, \(\wedge\) denotes the cross product, \(g\) is the gravitational acceleration, \(f\) is the Coriolis frequency, \(\textbf{e}_z\) is a vertical unit vector, and \(\nu_h, \nu\) stand for horizontal and vertical viscosity. Water density is given by \(\rho = \rho'(T, S, p) + \rho_0\), where \(\rho_0\) is a constant reference density. Above \(r\) denotes the baroclinic head

(3)\[r = \frac{1}{\rho_0} \int_{z}^\eta \rho' d\zeta.\]

The internal pressure gradient is computed as a separate diagnostic field:

(4)\[\mathbf{F}_{pg} = g\nabla_h r.\]

In the case of purely barotropic problems the \(r\) and \(\mathbf{F}_{pg}\) fields are omitted.

When using mode splitting we split the velocity field into a depth average and a deviation, \(\textbf{u} = \bar{\textbf{u}} + \textbf{u}'\). Following Higdon and de Szoeke (1997) we write an equation for the deviation \(\textbf{u}'\):

(5)\[\frac{\partial \textbf{u}'}{\partial t} = + \nabla_h \cdot (\textbf{u} \textbf{u}) + \frac{\partial \left(w\textbf{u} \right)}{\partial z} + f\textbf{e}_z\wedge\textbf{u}' + g\nabla_h r = \nabla_h \cdot \left( \nu_h \nabla_h \textbf{u} \right) + \frac{\partial }{\partial z}\left( \nu \frac{\partial \textbf{u}}{\partial z}\right)\]

In (5) the external pressure gradient \(g\nabla_h \eta\) vanishes and the Coriolis term only contains the deviation \(\textbf{u}'\). Advection and diffusion terms are not changed.

Higdon and de Szoeke (1997). Barotropic-Baroclinic Time Splitting for Ocean Circulation Modeling. Journal of Computational Physics, 135(1):30-53. http://dx.doi.org/10.1006/jcph.1997.5733

class thetis.momentum_eq.BottomFrictionTerm(function_space, bathymetry=None, v_elem_size=None, h_elem_size=None, use_nonlinear_equations=True, use_lax_friedrichs=True, use_bottom_friction=False, sipg_factor=Constant([1.], 6), sipg_factor_vertical=Constant([1.], 7))

Bases: MomentumTerm

Quadratic bottom friction term, \(\tau_b = C_D \| \textbf{u}_b \| \textbf{u}_b\)

The weak formulation reads

\[\int_{\Gamma_{bot}} \tau_b \cdot \boldsymbol{\psi} dx = \int_{\Gamma_{bot}} C_D \| \textbf{u}_b \| \textbf{u}_b \cdot \boldsymbol{\psi} dx\]

where \(\textbf{u}_b\) is reconstructed velocity in the middle of the bottom element:

\[\textbf{u}_b = \textbf{u}\Big|_{\Gamma_{bot}} + \frac{\partial \textbf{u}}{\partial z}\Big|_{\Gamma_{bot}} h_b,\]

\(h_b\) being half of the element height. For implicit solvers we linearize the stress as \(\tau_b = C_D \| \textbf{u}_b^{n} \| \textbf{u}_b^{n+1}\)

The drag is computed from the law-of-the wall

\[C_D = \left( \frac{\kappa}{\ln (h_b + z_0)/z_0} \right)^2\]

where \(z_0\) is the bottom roughness length field. The user can override the \(C_D\) value by providing quadratic_drag_coefficient field.

Parameters:

• function_space – FunctionSpace where the solution belongs

• bathymetry (3D Function or Constant) – bathymetry of the domain

• v_elem_size – scalar Function that defines the vertical element size

• h_elem_size – scalar Function that defines the horizontal element size

• use_nonlinear_equations (bool) – If False defines the linear shallow water equations

• use_bottom_friction (bool) – If True includes bottom friction term

• sipg_factor –

  class:

  Constant or :class: Function horizontal SIPG penalty scaling factor

• sipg_factor_vertical –

  class:

  Constant or :class: Function vertical SIPG penalty scaling factor

residual(solution, solution_old, fields, fields_old, bnd_conditions)

Returns an UFL form of the term.

Parameters:

• solution – solution Function of the corresponding equation

• solution_old – a time lagged solution Function

• fields – a dictionary that provides all the remaining fields that the term depends on. The keys of the dictionary should standard field names in field_metadata

• fields_old – Time lagged dictionary of fields

• bnd_conditions – A dictionary describing boundary conditions. E.g. {3: {‘elev_2d’: Constant(1.0)}} replaces elev_2d function by a constant on boundary ID 3.

class thetis.momentum_eq.CoriolisTerm(function_space, bathymetry=None, v_elem_size=None, h_elem_size=None, use_nonlinear_equations=True, use_lax_friedrichs=True, use_bottom_friction=False, sipg_factor=Constant([1.], 6), sipg_factor_vertical=Constant([1.], 7))

Bases: MomentumTerm

Coriolis term, \(f\textbf{e}_z\wedge \bar{\textbf{u}}\)

Parameters:

• function_space – FunctionSpace where the solution belongs

• bathymetry (3D Function or Constant) – bathymetry of the domain

• v_elem_size – scalar Function that defines the vertical element size

• h_elem_size – scalar Function that defines the horizontal element size

• use_nonlinear_equations (bool) – If False defines the linear shallow water equations

• use_bottom_friction (bool) – If True includes bottom friction term

• sipg_factor –

  class:

  Constant or :class: Function horizontal SIPG penalty scaling factor

• sipg_factor_vertical –

  class:

  Constant or :class: Function vertical SIPG penalty scaling factor

residual(solution, solution_old, fields, fields_old, bnd_conditions)

Returns an UFL form of the term.

Parameters:

• solution – solution Function of the corresponding equation

• solution_old – a time lagged solution Function

• fields – a dictionary that provides all the remaining fields that the term depends on. The keys of the dictionary should standard field names in field_metadata

• fields_old – Time lagged dictionary of fields

• bnd_conditions – A dictionary describing boundary conditions. E.g. {3: {‘elev_2d’: Constant(1.0)}} replaces elev_2d function by a constant on boundary ID 3.

class thetis.momentum_eq.HorizontalAdvectionTerm(function_space, bathymetry=None, v_elem_size=None, h_elem_size=None, use_nonlinear_equations=True, use_lax_friedrichs=True, use_bottom_friction=False, sipg_factor=Constant([1.], 6), sipg_factor_vertical=Constant([1.], 7))

Bases: MomentumTerm

Horizontal advection term, \(\nabla_h \cdot (\textbf{u} \textbf{u})\)

The weak form reads

\[\int_\Omega \nabla_h \cdot (\textbf{u} \textbf{u}) \cdot \boldsymbol{\psi} dx = - \int_\Omega \nabla_h \boldsymbol{\psi} : (\textbf{u} \textbf{u}) dx + \int_{\mathcal{I}_h \cup \mathcal{I}_v} \textbf{u}^{\text{up}} \cdot \text{jump}(\boldsymbol{\psi} \textbf{n}_h) \cdot \text{avg}(\textbf{u}) dS\]

where the right hand side has been integrated by parts; \(:\) stand for the Frobenius inner product, \(\textbf{n}_h\) is the horizontal projection of the normal vector, \(\textbf{u}^{\text{up}}\) is the upwind value, and \(\text{jump}\) and \(\text{avg}\) denote the jump and average operators across the interface.

Parameters:

• function_space – FunctionSpace where the solution belongs

• bathymetry (3D Function or Constant) – bathymetry of the domain

• v_elem_size – scalar Function that defines the vertical element size

• h_elem_size – scalar Function that defines the horizontal element size

• use_nonlinear_equations (bool) – If False defines the linear shallow water equations

• use_bottom_friction (bool) – If True includes bottom friction term

• sipg_factor –

  class:

  Constant or :class: Function horizontal SIPG penalty scaling factor

• sipg_factor_vertical –

  class:

  Constant or :class: Function vertical SIPG penalty scaling factor

residual(solution, solution_old, fields, fields_old, bnd_conditions)

Returns an UFL form of the term.

Parameters:

• solution – solution Function of the corresponding equation

• solution_old – a time lagged solution Function

• fields – a dictionary that provides all the remaining fields that the term depends on. The keys of the dictionary should standard field names in field_metadata

• fields_old – Time lagged dictionary of fields

• bnd_conditions – A dictionary describing boundary conditions. E.g. {3: {‘elev_2d’: Constant(1.0)}} replaces elev_2d function by a constant on boundary ID 3.

class thetis.momentum_eq.HorizontalViscosityTerm(function_space, bathymetry=None, v_elem_size=None, h_elem_size=None, use_nonlinear_equations=True, use_lax_friedrichs=True, use_bottom_friction=False, sipg_factor=Constant([1.], 6), sipg_factor_vertical=Constant([1.], 7))

Bases: MomentumTerm

Horizontal viscosity term, \(- \nabla_h \cdot \left( \nu_h \nabla_h \textbf{u} \right)\)

Using the symmetric interior penalty method the weak form becomes

\[\begin{split}\int_\Omega \nabla_h \cdot \left( \nu_h \nabla_h \textbf{u} \right) \cdot \boldsymbol{\psi} dx =& -\int_\Omega \nu_h (\nabla_h \boldsymbol{\psi}) : (\nabla_h \textbf{u})^T dx \\ &+ \int_{\mathcal{I}_h \cup \mathcal{I}_v} \text{jump}(\boldsymbol{\psi} \textbf{n}_h) \cdot \text{avg}( \nu_h \nabla_h \textbf{u}) dS + \int_{\mathcal{I}_h \cup \mathcal{I}_v} \text{jump}(\textbf{u} \textbf{n}_h) \cdot \text{avg}( \nu_h \nabla_h \boldsymbol{\psi}) dS \\ &- \int_{\mathcal{I}_h \cup \mathcal{I}_v} \sigma \text{avg}(\nu_h) \text{jump}(\textbf{u} \textbf{n}_h) \cdot \text{jump}(\boldsymbol{\psi} \textbf{n}_h) dS\end{split}\]

where \(\sigma\) is a penalty parameter, see Hillewaert (2013).

Hillewaert, Koen (2013). Development of the discontinuous Galerkin method for high-resolution, large scale CFD and acoustics in industrial geometries. PhD Thesis. Université catholique de Louvain. https://dial.uclouvain.be/pr/boreal/object/boreal:128254/

Parameters:

• function_space – FunctionSpace where the solution belongs

• bathymetry (3D Function or Constant) – bathymetry of the domain

• v_elem_size – scalar Function that defines the vertical element size

• h_elem_size – scalar Function that defines the horizontal element size

• use_nonlinear_equations (bool) – If False defines the linear shallow water equations

• use_bottom_friction (bool) – If True includes bottom friction term

• sipg_factor –

  class:

  Constant or :class: Function horizontal SIPG penalty scaling factor

• sipg_factor_vertical –

  class:

  Constant or :class: Function vertical SIPG penalty scaling factor

residual(solution, solution_old, fields, fields_old, bnd_conditions)

Returns an UFL form of the term.

Parameters:

• solution – solution Function of the corresponding equation

• solution_old – a time lagged solution Function

• fields – a dictionary that provides all the remaining fields that the term depends on. The keys of the dictionary should standard field names in field_metadata

• fields_old – Time lagged dictionary of fields

• bnd_conditions – A dictionary describing boundary conditions. E.g. {3: {‘elev_2d’: Constant(1.0)}} replaces elev_2d function by a constant on boundary ID 3.

class thetis.momentum_eq.InternalPressureGradientCalculator(fields, bathymetry, bnd_functions, internal_pg_scalar=None, solver_parameters=None)

Bases: MomentumTerm

Computes the internal pressure gradient term, \(g\nabla_h r\)

where \(r\) is the baroclinic head (3).

If \(r\) belongs to a discontinuous function space, the term is integrated by parts:

\[\int_\Omega g \nabla_h r \cdot \boldsymbol{\psi} dx = - \int_\Omega g r \nabla_h \cdot \boldsymbol{\psi} dx + \int_{\mathcal{I}_h \cup \mathcal{I}_v} g \text{avg}(r) \text{jump}(\boldsymbol{\psi} \cdot \textbf{n}_h) dx\]

Note

Due to the Term sign convention this term is assembled on the right-hand-side.

Parameters:

• solver – class`FlowSolver object

• solver_parameters (dict) – PETSc solver options

residual(solution, solution_old, fields, fields_old, bnd_conditions)

Returns an UFL form of the term.

Parameters:

• solution – solution Function of the corresponding equation

• solution_old – a time lagged solution Function

• fields – a dictionary that provides all the remaining fields that the term depends on. The keys of the dictionary should standard field names in field_metadata

• fields_old – Time lagged dictionary of fields

• bnd_conditions – A dictionary describing boundary conditions. E.g. {3: {‘elev_2d’: Constant(1.0)}} replaces elev_2d function by a constant on boundary ID 3.

solve()

Computes internal pressure gradient and stores it in int_pg_3d field

class thetis.momentum_eq.LinearDragTerm(function_space, bathymetry=None, v_elem_size=None, h_elem_size=None, use_nonlinear_equations=True, use_lax_friedrichs=True, use_bottom_friction=False, sipg_factor=Constant([1.], 6), sipg_factor_vertical=Constant([1.], 7))

Bases: MomentumTerm

Linear drag term, \(\tau_b = D \textbf{u}_b\)

where \(D\) is the drag coefficient, read from linear_drag_coefficient field.

Parameters:

• function_space – FunctionSpace where the solution belongs

• bathymetry (3D Function or Constant) – bathymetry of the domain

• v_elem_size – scalar Function that defines the vertical element size

• h_elem_size – scalar Function that defines the horizontal element size

• use_nonlinear_equations (bool) – If False defines the linear shallow water equations

• use_bottom_friction (bool) – If True includes bottom friction term

• sipg_factor –

  class:

  Constant or :class: Function horizontal SIPG penalty scaling factor

• sipg_factor_vertical –

  class:

  Constant or :class: Function vertical SIPG penalty scaling factor

residual(solution, solution_old, fields, fields_old, bnd_conditions)

Returns an UFL form of the term.

Parameters:

• solution – solution Function of the corresponding equation

• solution_old – a time lagged solution Function

• fields – a dictionary that provides all the remaining fields that the term depends on. The keys of the dictionary should standard field names in field_metadata

• fields_old – Time lagged dictionary of fields

• bnd_conditions – A dictionary describing boundary conditions. E.g. {3: {‘elev_2d’: Constant(1.0)}} replaces elev_2d function by a constant on boundary ID 3.

class thetis.momentum_eq.MomentumEquation(function_space, bathymetry=None, v_elem_size=None, h_elem_size=None, use_nonlinear_equations=True, use_lax_friedrichs=True, use_bottom_friction=False, sipg_factor=Constant([1.], 8), sipg_factor_vertical=Constant([1.], 9))

Bases: Equation

Hydrostatic 3D momentum equation (5) for mode split models

Parameters:

• function_space – FunctionSpace where the solution belongs

• bathymetry (3D Function or Constant) – bathymetry of the domain

• v_elem_size – scalar Function that defines the vertical element size

• h_elem_size – scalar Function that defines the horizontal element size

• use_nonlinear_equations (bool) – If False defines the linear shallow water equations

• use_bottom_friction (bool) – If True includes bottom friction term

• sipg_factor –

  class:

  Constant or :class: Function horizontal SIPG penalty scaling factor

• sipg_factor_vertical –

  class:

  Constant or :class: Function vertical SIPG penalty scaling factor

class thetis.momentum_eq.MomentumTerm(function_space, bathymetry=None, v_elem_size=None, h_elem_size=None, use_nonlinear_equations=True, use_lax_friedrichs=True, use_bottom_friction=False, sipg_factor=Constant([1.], 6), sipg_factor_vertical=Constant([1.], 7))

Bases: Term

Generic term for momentum equation that provides commonly used members and mapping for boundary functions.

Parameters:

• function_space – FunctionSpace where the solution belongs

• bathymetry (3D Function or Constant) – bathymetry of the domain

• v_elem_size – scalar Function that defines the vertical element size

• h_elem_size – scalar Function that defines the horizontal element size

• use_nonlinear_equations (bool) – If False defines the linear shallow water equations

• use_bottom_friction (bool) – If True includes bottom friction term

• sipg_factor –

  class:

  Constant or :class: Function horizontal SIPG penalty scaling factor

• sipg_factor_vertical –

  class:

  Constant or :class: Function vertical SIPG penalty scaling factor

class thetis.momentum_eq.PressureGradientTerm(function_space, bathymetry=None, v_elem_size=None, h_elem_size=None, use_nonlinear_equations=True, use_lax_friedrichs=True, use_bottom_friction=False, sipg_factor=Constant([1.], 6), sipg_factor_vertical=Constant([1.], 7))

Bases: MomentumTerm

Internal pressure gradient term, \(g\nabla_h r\)

where \(r\) is the baroclinic head (3). Let \(s\) denote \(r/H\). We can then write

\[F_{IPG} = g\nabla_h((s -\bar{s}) H) + g\nabla_h\left(\frac{1}{H}\right) H^2\bar{s} + g s_{bot}\nabla_h h\]

where \(\bar{s},s_{bot}\) are the depth average and bottom value of \(s\).

If \(s\) belongs to a discontinuous function space, the first term is integrated by parts. Its weak form reads

\[\int_\Omega g\nabla_h((s -\bar{s}) H) \cdot \boldsymbol{\psi} dx = - \int_\Omega g (s -\bar{s}) H \nabla_h \cdot \boldsymbol{\psi} dx + \int_{\mathcal{I}_h \cup \mathcal{I}_v} g (s -\bar{s}) H \boldsymbol{\psi} \cdot \textbf{n}_h dx\]

Parameters:

• function_space – FunctionSpace where the solution belongs

• bathymetry (3D Function or Constant) – bathymetry of the domain

• v_elem_size – scalar Function that defines the vertical element size

• h_elem_size – scalar Function that defines the horizontal element size

• use_nonlinear_equations (bool) – If False defines the linear shallow water equations

• use_bottom_friction (bool) – If True includes bottom friction term

• sipg_factor –

  class:

  Constant or :class: Function horizontal SIPG penalty scaling factor

• sipg_factor_vertical –

  class:

  Constant or :class: Function vertical SIPG penalty scaling factor

residual(solution, solution_old, fields, fields_old, bnd_conditions)

Returns an UFL form of the term.

Parameters:

• solution – solution Function of the corresponding equation

• solution_old – a time lagged solution Function

• fields – a dictionary that provides all the remaining fields that the term depends on. The keys of the dictionary should standard field names in field_metadata

• fields_old – Time lagged dictionary of fields

• bnd_conditions – A dictionary describing boundary conditions. E.g. {3: {‘elev_2d’: Constant(1.0)}} replaces elev_2d function by a constant on boundary ID 3.

class thetis.momentum_eq.SourceTerm(function_space, bathymetry=None, v_elem_size=None, h_elem_size=None, use_nonlinear_equations=True, use_lax_friedrichs=True, use_bottom_friction=False, sipg_factor=Constant([1.], 6), sipg_factor_vertical=Constant([1.], 7))

Bases: MomentumTerm

Generic momentum source term

The weak form reads

\[F_s = \int_\Omega \sigma \cdot \boldsymbol{\psi} dx\]

where \(\sigma\) is a user defined vector valued Function.

This term also implements the wind stress, \(-\tau_w/(H \rho_0)\). \(\tau_w\) is a user-defined wind stress Function wind_stress. The weak form is

\[F_w = \int_{\Gamma_s} \frac{1}{\rho_0} \tau_w \cdot \boldsymbol{\psi} dx\]

Wind stress is only included if vertical viscosity is provided.

Parameters:

• function_space – FunctionSpace where the solution belongs

• bathymetry (3D Function or Constant) – bathymetry of the domain

• v_elem_size – scalar Function that defines the vertical element size

• h_elem_size – scalar Function that defines the horizontal element size

• use_nonlinear_equations (bool) – If False defines the linear shallow water equations

• use_bottom_friction (bool) – If True includes bottom friction term

• sipg_factor –

  class:

  Constant or :class: Function horizontal SIPG penalty scaling factor

• sipg_factor_vertical –

  class:

  Constant or :class: Function vertical SIPG penalty scaling factor

residual(solution, solution_old, fields, fields_old, bnd_conditions)

Returns an UFL form of the term.

Parameters:

• solution – solution Function of the corresponding equation

• solution_old – a time lagged solution Function

• fields – a dictionary that provides all the remaining fields that the term depends on. The keys of the dictionary should standard field names in field_metadata

• fields_old – Time lagged dictionary of fields

• bnd_conditions – A dictionary describing boundary conditions. E.g. {3: {‘elev_2d’: Constant(1.0)}} replaces elev_2d function by a constant on boundary ID 3.

class thetis.momentum_eq.VerticalAdvectionTerm(function_space, bathymetry=None, v_elem_size=None, h_elem_size=None, use_nonlinear_equations=True, use_lax_friedrichs=True, use_bottom_friction=False, sipg_factor=Constant([1.], 6), sipg_factor_vertical=Constant([1.], 7))

Bases: MomentumTerm

Vertical advection term, \(\partial \left(w\textbf{u} \right)/(\partial z)\)

The weak form reads

\[\int_\Omega \frac{\partial \left(w\textbf{u} \right)}{\partial z} \cdot \boldsymbol{\psi} dx = - \int_\Omega \left( w \textbf{u} \right) \cdot \frac{\partial \boldsymbol{\psi}}{\partial z} dx + \int_{\mathcal{I}_{h}} \textbf{u}^{\text{up}} \cdot \text{jump}(\boldsymbol{\psi} n_z) \text{avg}(w) dS\]

Parameters:

• function_space – FunctionSpace where the solution belongs

• bathymetry (3D Function or Constant) – bathymetry of the domain

• v_elem_size – scalar Function that defines the vertical element size

• h_elem_size – scalar Function that defines the horizontal element size

• use_nonlinear_equations (bool) – If False defines the linear shallow water equations

• use_bottom_friction (bool) – If True includes bottom friction term

• sipg_factor –

  class:

  Constant or :class: Function horizontal SIPG penalty scaling factor

• sipg_factor_vertical –

  class:

  Constant or :class: Function vertical SIPG penalty scaling factor

residual(solution, solution_old, fields, fields_old, bnd_conditions)

Returns an UFL form of the term.

Parameters:

• solution – solution Function of the corresponding equation

• solution_old – a time lagged solution Function

• fields – a dictionary that provides all the remaining fields that the term depends on. The keys of the dictionary should standard field names in field_metadata

• fields_old – Time lagged dictionary of fields

• bnd_conditions – A dictionary describing boundary conditions. E.g. {3: {‘elev_2d’: Constant(1.0)}} replaces elev_2d function by a constant on boundary ID 3.

class thetis.momentum_eq.VerticalViscosityTerm(function_space, bathymetry=None, v_elem_size=None, h_elem_size=None, use_nonlinear_equations=True, use_lax_friedrichs=True, use_bottom_friction=False, sipg_factor=Constant([1.], 6), sipg_factor_vertical=Constant([1.], 7))

Bases: MomentumTerm

Vertical viscosity term, \(- \frac{\partial }{\partial z}\left( \nu \frac{\partial \textbf{u}}{\partial z}\right)\)

Using the symmetric interior penalty method the weak form becomes

\[\begin{split}\int_\Omega \frac{\partial }{\partial z}\left( \nu \frac{\partial \textbf{u}}{\partial z}\right) \cdot \boldsymbol{\psi} dx =& -\int_\Omega \nu \frac{\partial \boldsymbol{\psi}}{\partial z} \cdot \frac{\partial \textbf{u}}{\partial z} dx \\ &+ \int_{\mathcal{I}_h} \text{jump}(\boldsymbol{\psi} n_z) \cdot \text{avg}\left(\nu \frac{\partial \textbf{u}}{\partial z}\right) dS + \int_{\mathcal{I}_h} \text{jump}(\textbf{u} n_z) \cdot \text{avg}\left(\nu \frac{\partial \boldsymbol{\psi}}{\partial z}\right) dS \\ &- \int_{\mathcal{I}_h} \sigma \text{avg}(\nu) \text{jump}(\textbf{u} n_z) \cdot \text{jump}(\boldsymbol{\psi} n_z) dS\end{split}\]

where \(\sigma\) is a penalty parameter, see Hillewaert (2013).

Hillewaert, Koen (2013). Development of the discontinuous Galerkin method for high-resolution, large scale CFD and acoustics in industrial geometries. PhD Thesis. Université catholique de Louvain. https://dial.uclouvain.be/pr/boreal/object/boreal:128254/

Parameters:

• function_space – FunctionSpace where the solution belongs

• bathymetry (3D Function or Constant) – bathymetry of the domain

• v_elem_size – scalar Function that defines the vertical element size

• h_elem_size – scalar Function that defines the horizontal element size

• use_nonlinear_equations (bool) – If False defines the linear shallow water equations

• use_bottom_friction (bool) – If True includes bottom friction term

• sipg_factor –

  class:

  Constant or :class: Function horizontal SIPG penalty scaling factor

• sipg_factor_vertical –

  class:

  Constant or :class: Function vertical SIPG penalty scaling factor

residual(solution, solution_old, fields, fields_old, bnd_conditions)

Returns an UFL form of the term.

Parameters:

• solution – solution Function of the corresponding equation

• solution_old – a time lagged solution Function

• fields – a dictionary that provides all the remaining fields that the term depends on. The keys of the dictionary should standard field names in field_metadata

• fields_old – Time lagged dictionary of fields

• bnd_conditions – A dictionary describing boundary conditions. E.g. {3: {‘elev_2d’: Constant(1.0)}} replaces elev_2d function by a constant on boundary ID 3.

thetis.optimisation module

Some classes to help optimisation problems formulated with thetis_adjoint.

In particular this module contains some OptimisationCallbacks that can be used as callbacks of a ReducedFunctional called at various stages during the optimisation process: - eval_cb_pre(controls) and eval_cb_post(functional, controls) called before and after (re)evaluation of the forward model - derivative_cb_pre(controls) and eval_cb_post(functional, derivative, controls) called before and after the gradient computation using the adjoint of the model - hessian_cb_pre(controls) and eval_cb_post(functional, derivative, controls) called before and after the hessian computation OptimisationCallbacks that (can) use controls, functional and derivative information, work out what is provided by the number of arguments: current control values are always in the last argument; if more than 2 arguments are provided, the first is the latest evaluated functional value.

class thetis.optimisation.ConstantControlOptimisationCallback(solver_obj, **kwargs)

Bases: DiagnosticOptimisationCallback

OptimisationCallback that records the control values (which are assumed to be a list of Constants) in the log and/or hdf5 file.

Parameters:

• solver_obj – Thetis solver object

• kwargs – keyword arguments passed to DiagnosticCallback

compute_values(*args)

Compute diagnostic values.

This method is to be implemented in concrete subclasses of a DiagnosticOptimisationCallback. The number of arguments varies depending on which of the 6 [eval|derivative|hessian]_cb_[pre|post] callbacks this is used as. The last argument always contains the current controls. In the “pre” callbacks this is the only argument. In all “post” callbacks the 0th argument is the current functional value. eval_cb_post is given two arguments: functional and controls. derivative_cb_post and hessian_cb_post are given three arguments with args[1] being the derivative/hessian just calculated.

message_str(*controls)

A string representation.

Parameters:

args – If provided, these will be the return value from __call__().

name = 'controls'

variable_names = ['controls']

class thetis.optimisation.ControlsExportOptimisationCallback(solver_obj_or_outputdir, **kwargs)

Bases: DeferredExportManager, OptimisationCallback

A callback that exports the current control values (assumed to all be Function s)

The control values are assumed to be the last argument in the callback (as for all ReducedFunctional callbacks).

Parameters:

• solver_obj_or_outputdir – a FlowSolver2d object, used to determine the output directory. Alternatively, the outputdir can be specified with a string as the first argument.

• kwargs – any further keyword arguments are passed on to UserExportManager

callback(*args)

class thetis.optimisation.DeferredExportManager(solver_obj_or_outputdir, **kwargs)

Bases: object

A wrapper around a UserExportManager that is only created on the first export() call.

In addition the functions provided in the export call are copied into a fixed set of functions, where the functions provided in subsequent calls may be different (they need to be in the same function space). This is used in the ControlsExportOptimisationCallback and DerivativesExportOptimisationCallback.

Parameters:

• solver_obj_or_outputdir – a FlowSolver2d object, used to determine the output directory. Alternatively, the outputdir can be specified with a string as the first argument.

• kwargs – any further keyword arguments are passed on to UserExportManager

export(functions, suggested_names=None)

Create the UserExportManager (first call only), and call its export() method.

Parameters:

functions – a list of Function s that the UserExportManager will be based on. Their values are first copied. The list may contain different functions in subsequent calls, but their function space should remain the same.

class thetis.optimisation.DerivativeConstantControlOptimisationCallback(solver_obj, **kwargs)

Bases: DiagnosticOptimisationCallback

OptimisationCallback that records the derivatives with respect to the controls, assumed to be a list of Constants, in the log and/or hdf5 file.

Parameters:

• solver_obj – Thetis solver object

• kwargs – keyword arguments passed to DiagnosticCallback

compute_values(*args)

Compute diagnostic values.

This method is to be implemented in concrete subclasses of a DiagnosticOptimisationCallback. The number of arguments varies depending on which of the 6 [eval|derivative|hessian]_cb_[pre|post] callbacks this is used as. The last argument always contains the current controls. In the “pre” callbacks this is the only argument. In all “post” callbacks the 0th argument is the current functional value. eval_cb_post is given two arguments: functional and controls. derivative_cb_post and hessian_cb_post are given three arguments with args[1] being the derivative/hessian just calculated.

message_str(*derivatives)

A string representation.

Parameters:

args – If provided, these will be the return value from __call__().

name = 'derivatives'

variable_names = ['derivatives']

class thetis.optimisation.DerivativesExportOptimisationCallback(solver_obj_or_outputdir, **kwargs)

Bases: DeferredExportManager, OptimisationCallback

A callback that exports the derivatives calculated by the adjoint.

The derivatives are assumed to be the second argument in the callback. This can therefore be used as a derivative_cb_post callback in a ReducedFunctional

Parameters:

• solver_obj_or_outputdir – a FlowSolver2d object, used to determine the output directory. Alternatively, the outputdir can be specified with a string as the first argument.

• kwargs – any further keyword arguments are passed on to UserExportManager

callback(*args)

class thetis.optimisation.DiagnosticOptimisationCallback(solver_obj, **kwargs)

Bases: OptimisationCallback, DiagnosticCallback

An OptimisationCallback similar to DiagnosticCallback that can be used as callback in a ReducedFunctional.

Note that in this case the computing of the values needs to be defined in the compute_values method, not in the __call__ method (as this one is directly called from the ReducedFunctional). In addition, like any DiagnosticCallback, the name and variable_names properties and a message_str method need to be defined.

Parameters:

• solver_obj – Thetis solver object

• kwargs – keyword arguments passed to DiagnosticCallback

callback(*args)

abstract compute_values(*args)

Compute diagnostic values.

This method is to be implemented in concrete subclasses of a DiagnosticOptimisationCallback. The number of arguments varies depending on which of the 6 [eval|derivative|hessian]_cb_[pre|post] callbacks this is used as. The last argument always contains the current controls. In the “pre” callbacks this is the only argument. In all “post” callbacks the 0th argument is the current functional value. eval_cb_post is given two arguments: functional and controls. derivative_cb_post and hessian_cb_post are given three arguments with args[1] being the derivative/hessian just calculated.

evaluate(*args, index=None)

Evaluates callback and pushes values to log and hdf file (if enabled)

class thetis.optimisation.FunctionalOptimisationCallback(solver_obj, **kwargs)

Bases: DiagnosticOptimisationCallback

A simple OptimisationCallback that records the functional value in the log and/or hdf5 file.

Parameters:

• solver_obj – Thetis solver object

• kwargs – keyword arguments passed to DiagnosticCallback

compute_values(*args)

Compute diagnostic values.

This method is to be implemented in concrete subclasses of a DiagnosticOptimisationCallback. The number of arguments varies depending on which of the 6 [eval|derivative|hessian]_cb_[pre|post] callbacks this is used as. The last argument always contains the current controls. In the “pre” callbacks this is the only argument. In all “post” callbacks the 0th argument is the current functional value. eval_cb_post is given two arguments: functional and controls. derivative_cb_post and hessian_cb_post are given three arguments with args[1] being the derivative/hessian just calculated.

message_str(functional)

A string representation.

Parameters:

args – If provided, these will be the return value from __call__().

name = 'functional'

variable_names = ['functional']

class thetis.optimisation.OptimisationCallback

Bases: ABC

Base class for callback that can be used as callbacks of a ReducedFunctional

Called at various stages during the optimisation process: - eval_cb_pre(controls) and eval_cb_post(functional, controls) called before and after (re)evaluation of the forward model - derivative_cb_pre(controls) and eval_cb_post(functional, derivative, controls) called before and after the gradient computation using the adjoint of the model - hessian_cb_pre(controls) and eval_cb_post(functional, derivative, controls) called before and after the hessian computation OptimisationCallbacks that (can) use controls, functional and derivative information, work out what is provided by the number of arguments: current control values are always in the last argument; if more than 2 arguments are provided, the first is the latest evaluated functional value.

abstract callback(*args)

class thetis.optimisation.OptimisationCallbackList(iterable=(), /)

Bases: list, OptimisationCallback

A list of callbacks that can be used as a single callback itself.

Calls all callbacks in order.

callback(*args)

class thetis.optimisation.UserExportManager(solver_obj_or_outputdir, functions_to_export, filenames=None, filename_prefix='', shortnames=None, **kwargs)

Bases: ExportManager

ExportManager for user provided functions (not necessarily known to Thetis)

In the standard ExportManager all provided functions need to have standard names present in field_metadata. Here, any functions can be provided. If function.name() is in field_metadata, the standard filename and shortname are used. If the function.name() is unknown, both are based on function.name() directly (with an optional additional filename_prefix). Filenames and shortnames can be overruled by the shortnames and filenames arguments.

Parameters:

• solver_obj_or_outputdir – a FlowSolver2d object, used to determine the output directory. Alternatively, the outputdir can be specified with a string as the first argument.

• functions_to_export – a list of Function s

• filenames – a list of strings that specify the filename for each provided function. If not provided, filenames are based on function.name().

• filename_prefix – a string prefixed to each filename

• shortnames – a list of strings with the shortnames used for each provided function. If not provided, shortnames are based on function.name().

• kwargs – any further keyword arguments are passed on to ExportManager

class thetis.optimisation.UserExportOptimisationCallback(solver_obj_or_outputdir, functions_to_export, **kwargs)

Bases: UserExportManager, OptimisationCallback

A UserExportManager that can be used as a ReducedFunctional callback

Any callback arguments (functional value, derivatives, controls) are ignored

Parameters:

• solver_obj_or_outputdir – a FlowSolver2d object, used to determine the output directory. Alternatively, the outputdir can be specified with a string as the first argument.

• functions_to_export – a list of Function s

• kwargs – any further keyword arguments are passed on to UserExportManager

callback(*args)

Ensure the UserExportManager uses the checkpointed values and call its export().

Args:

these are ignored

thetis.options module

Thetis options for the 2D and 3D model

All options are type-checked and they are stored in traitlets Configurable objects.

class thetis.options.CommonModelOptions(**kwargs: Any)

Bases: FrozenConfigurable

Options that are common for both 2d and 3d models

atmospheric_pressure

Atmospheric pressure at free surface, in pascals

cfl_2d

Factor to scale the 2d time step OBSOLETE

cfl_3d

Factor to scale the 2d time step OBSOLETE

check_volume_conservation_2d

Compute volume of the 2D mode at every export

2D volume is defined as the integral of the water elevation field. Prints deviation from the initial volume to stdout.

coriolis_frequency

2D Coriolis parameter

element_family

Finite element family

2D solver supports ‘dg-dg’, ‘rt-dg’, ‘bdm-dg’, or ‘dg-cg’ velocity-pressure pairs. 3D solver supports ‘dg-dg’, ‘rt-dg’, or ‘bdm-dg’ velocity-pressure pairs.

export_diagnostics

Store diagnostic variables to disk in HDF5 format

fields_to_export

Fields to export in VTK format

fields_to_export_hdf5

Fields to export in HDF5 format

horizontal_diffusivity_scale

Maximum horizontal diffusivity

Used to compute the mesh Peclet number in the 2D tracer SUPG stabilization scheme.

horizontal_velocity_scale

Maximum horizontal velocity magnitude

Used to compute max stable advection time step.

horizontal_viscosity

Horizontal viscosity

horizontal_viscosity_scale

Maximum horizontal viscosity

Used to compute max stable diffusion time step.

lax_friedrichs_tracer_scaling_factor

Scaling factor for tracer Lax Friedrichs stability term.

lax_friedrichs_velocity_scaling_factor

Scaling factor for Lax Friedrichs stabilisation term in horizontal momentum advection.

linear_drag_coefficient

2D linear drag parameter \(L\)

Bottom stress is \(\tau_b/\rho_0 = -L \mathbf{u} H\)

log_output

Redirect all output to log file in output directory

manning_drag_coefficient

Manning-Strickler 2D quadratic drag parameter \(\mu\)

Bottom stress is \(\tau_b/\rho_0 = -g \mu^2 |\mathbf{u}|\mathbf{u}/H^{1/3}\)

momentum_source_2d

Source term for 2D momentum equation

name = 'Model options'

nh_model_options

A trait whose value must be an instance of a specified class.

The value can also be an instance of a subclass of the specified class.

Subclasses can declare default classes by overriding the klass attribute

nikuradse_bed_roughness

Nikuradse bed roughness length used to construct the 2D quadratic drag parameter \(C_D\).

In sediment transport this term is usually three times the average sediment diameter size.

no_exports

Do not store any outputs to disk

Disables VTK and HDF5 field outputs. and HDF5 diagnostic outputs. Used in CI test suite.

norm_smoother

Coefficient used to avoid non-differentiable functions in the continuous formulation of the velocity norm in the quadratic bottom drag term in the momentum equation. This replaces the velocity norm in the quadratic bottom drag term with \(\|u\| \approx \sqrt{\|u\|^2 + \alpha^2}\)

output_directory

Directory where model output files are stored

polynomial_degree

Polynomial degree of elements

quadratic_drag_coefficient

Dimensionless 2D quadratic drag parameter \(C_D\)

Bottom stress is \(\tau_b/\rho_0 = -C_D |\mathbf{u}|\mathbf{u}\)

simulation_end_date

Simulation end date

simulation_end_time

Simulation duration in seconds

simulation_export_time

Export interval in seconds

All fields in fields_to_export list will be stored to disk and diagnostics will be computed

simulation_initial_date

Model initialization date. Corresponds to zero in simulation time.

sipg_factor

Penalty parameter scaling factor for horizontal viscosity terms.

sipg_factor_tracer

Penalty parameter scaling factor for horizontal diffusivity terms.

timestep

Time step

use_grad_depth_viscosity_term

Include \(\nabla H\) term in the depth-averaged viscosity

See shallowwater_eq.HorizontalViscosityTerm for details.

use_grad_div_viscosity_term

Include \(\nabla (\nu_h \nabla \cdot \bar{\textbf{u}})\) term in the depth-averaged viscosity

See shallowwater_eq.HorizontalViscosityTerm for details.

use_lax_friedrichs_tracer

Use Lax Friedrichs stabilisation in tracer advection.

use_lax_friedrichs_velocity

use Lax Friedrichs stabilisation in horizontal momentum advection.

use_limiter_for_tracers

Apply P1DG limiter for tracer fields

use_nonlinear_equations

Use nonlinear shallow water equations

verbose

Verbosity level

volume_source_2d

Source term for 2D continuity equation

wind_stress

Stress at free surface (2D vector function)

class thetis.options.ConstantTidalTurbineOptions(**kwargs: Any)

Bases: TidalTurbineOptions

Options for tidal turbine with constant thrust

name = 'Constant tidal turbine options'

thrust_coefficient

Thrust coefficient C_T

class thetis.options.CrankNicolsonSWETimeStepperOptions2d(**kwargs: Any)

Bases: SemiImplicitSWETimeStepperOptions2d

Options for 2d Crank-Nicolson time integrator applied to shallow water equations

implicitness_theta

implicitness parameter theta. Value 0.5 implies Crank-Nicolson scheme, 1.0 implies fully implicit formulation.

class thetis.options.CrankNicolsonTracerTimeStepperOptions2d(**kwargs: Any)

Bases: SemiImplicitTracerTimeStepperOptions2d

Options for 2d Crank-Nicolson time integrator applied to tracer equations

implicitness_theta

implicitness parameter theta. Value 0.5 implies Crank-Nicolson scheme, 1.0 implies fully implicit formulation.

class thetis.options.DiscreteTidalTurbineFarmOptions(**kwargs: Any)

Bases: TidalTurbineFarmOptions

Discrete Tidal turbine farm options - defaults to 0 turbines in the field

name: str | None = 'Discrete Farm options'

quadrature_degree

Quadrature degree for thrust force and power output integral

turbine_coordinates

Coordinates for turbines

upwind_correction

bool: Apply flow correction to correct for upwind velocity

class thetis.options.EquationOfStateOptions(**kwargs: Any)

Bases: FrozenHasTraits

Base class of equation of state options

name = 'Equation of State'

class thetis.options.ExplicitMomentumTimeStepperOptions3d(**kwargs: Any)

Bases: TimeStepperOptions3d

Options for 3d explicit time integrator momentum component

solver_parameters

PETSc solver options dictionary

class thetis.options.ExplicitSWETimeStepperOptions2d(**kwargs: Any)

Bases: ExplicitTimeStepperOptions2d

Options for 2d explicit time integrator applied to shallow water equations

solver_parameters

PETSc solver options dictionary

class thetis.options.ExplicitTimeStepperOptions(**kwargs: Any)

Bases: TimeStepperOptions

Options for explicit time integrator

use_automatic_timestep

Set time step automatically based on local CFL conditions.

class thetis.options.ExplicitTimeStepperOptions2d(**kwargs: Any)

Bases: ExplicitTimeStepperOptions

Options for 2d explicit time integrator

class thetis.options.ExplicitTracerTimeStepperOptions2d(**kwargs: Any)

Bases: ExplicitTimeStepperOptions2d

Options for 2d explicit time integrator applied to tracer equations

solver_parameters

PETSc solver options dictionary

class thetis.options.ExplicitTracerTimeStepperOptions3d(**kwargs: Any)

Bases: TimeStepperOptions3d

Options for 3d explicit time integrator applied to tracer equations

solver_parameters

PETSc solver options dictionary

class thetis.options.GLSModelOptions(**kwargs: Any)

Bases: TurbulenceModelOptions

Options for Generic Length Scale turbulence model

apply_defaults(closure_name)

Applies default parameters for given closure name

Parameters:

closure_name (string) – name of the turbulence closure model

Sets default values for parameters p, m, n, schmidt_nb_tke, schmidt_nb_psi, c1, c2, c3_plus, c3_minus, f_wall, k_min, psi_min

c1

float: c1 parameter for Psi equations

c2

float: c2 parameter for Psi equations

c3_minus

float: c3 parameter for Psi equations, stable stratification

If compute_c3_minus is True this value will be overriden

c3_plus

float: c3 parameter for Psi equations, unstable stratification

closure_name

Name of two-equation closure

cmu0

float: cmu0 parameter

compute_c3_minus

bool: compute c3_minus from ri_st

compute_cmu0

bool: compute cmu0 from stability function parameters

If compute_cmu0 is True, this value will be overriden

compute_galperin_clim

bool: compute c_lim length scale limiting factor

compute_kappa

bool: compute von Karman constant from schmidt_nb_psi

compute_len_min

bool: compute min_len from k_min and psi_min

compute_psi_min

bool: compute psi_len from k_min and eps_min

compute_schmidt_nb_psi

bool: compute psi Schmidt number

diff_min

float: minimum value for eddy diffusivity

eps_min

float: minimum value for epsilon

f_wall

float: wall function parameter

galperin_clim

float: Galperin length scale limitation parameter

k_min

float: minimum value for turbulent kinetic energy

kappa

float: von Karman constant

If compute_kappa is True this value will be overriden

len_min

float: minimum value for turbulent length scale

limit_eps

bool: apply Galperin length scale limit on epsilon

limit_len

bool: apply Galperin length scale limit

limit_len_min

bool: limit minimum turbulent length scale to len_min

limit_psi

bool: apply Galperin length scale limit on psi

m

float: parameter m for the definition of psi

n

float: parameter n for the definition of psi

name = 'Generic Length Scale turbulence closure model'

p

float: parameter p for the definition of psi

psi_min

float: minimum value for psi

ri_st

steady state gradient Richardson number

schmidt_nb_psi

float: psi Schmidt number

schmidt_nb_tke

float: turbulent kinetic energy Schmidt number

stability_function_name

Name of stability function family

visc_min

float: minimum value for eddy viscosity

class thetis.options.IMEXSWETimeStepperOptions2d(**kwargs: Any)

Bases: SemiImplicitTimeStepperOptions2d

Options for 2d implicit-explicit time integrators applied to shallow water equations

solver_parameters

PETSc solver options dictionary

class thetis.options.ImplicitMomentumTimeStepperOptions3d(**kwargs: Any)

Bases: TimeStepperOptions3d

Options for 3d implicit time integrator momentum component

solver_parameters

PETSc solver options dictionary

class thetis.options.ImplicitSWETimeStepperOptions3d(**kwargs: Any)

Bases: SWETimeStepperOptions3d

Options for 3d implicit time integrator shallow water component

implicitness_theta

implicitness parameter theta. Value 0.5 implies Crank-Nicolson scheme, 1.0 implies fully implicit formulation.

class thetis.options.ImplicitTracerTimeStepperOptions3d(**kwargs: Any)

Bases: TimeStepperOptions3d

Options for 3d implicit time integrator applied to tracer equations

solver_parameters

PETSc solver options dictionary

class thetis.options.LeapFrogTimeStepperOptions3d(**kwargs: Any)

Bases: SSPRKTimeStepperOptions3d

Options for 3d LeapFrog coupled time integrator

swe_options = <thetis.options.ImplicitSWETimeStepperOptions3d object>

class thetis.options.LinearEquationOfStateOptions(**kwargs: Any)

Bases: EquationOfStateOptions

Linear equation of state options

alpha

Thermal expansion coefficient of ocean water

beta

Saline contraction coefficient of ocean water

name = 'Linear Equation of State'

rho_ref

Reference water density

s_ref

Reference water salinity

th_ref

Reference water temperature

class thetis.options.ModelOptions2d(**kwargs: Any)

Bases: CommonModelOptions

Options for 2D depth-averaged shallow water model

add_tracer_2d(label, name, filename, shortname=None, unit='-', **kwargs)

Add a 2D tracer field to tracer.

Note that the tracer equations will be solved in the order in which they are added.

Parameters:

• label – field label used internally by Thetis, e.g. ‘tracer_2d’

• name – human readable name for the tracer field, e.g. ‘Depth averaged tracer’

• filename – file name for outputs, e.g. ‘Tracer2d’

• shortname – short version of name, e.g. ‘Tracer’

• unit – units for field, e.g. ‘-’

• function – Function to use for the tracer

• source – associated source term

• diffusivity – associated diffusivity coefficient

• use_conservative_form – should the tracer equation be solved in conservative form?

add_tracer_system_2d(labels, names, filenames, shortnames=None, units=None, function=None, **kwargs)

Add multiple 2D tracer fields to tracer at once.

The equations associated with these fields will be solved as a mixed system.

Parameters:

• labels – a list of field labels used internally by Thetis

• names – a list of human readable names for the tracer fields

• filenames – a list of file names for outputs

• shortnames – a list of short versions of the names

• units – a list of units for fields

• function – Function to use for the mixed tracer

Kwargs:

other parameters passed to add_tracer_2d()

check_tracer_conservation

Compute total tracer mass at every export

Prints deviation from the initial mass to stdout.

check_tracer_overshoot

Compute tracer overshoots at every export

Prints overshoot values that exceed the initial range to stdout.

discrete_tidal_turbine_farms

Dictionary mapping subdomain ids to the options of the corresponding farm

name = 'Depth-averaged 2D model'

sediment_model_options

A trait whose value must be an instance of a specified class.

The value can also be an instance of a subclass of the specified class.

Subclasses can declare default classes by overriding the klass attribute

set_timestepper_type(timestepper_type, **kwargs)

Set the same timestepper type for all components.

Any keyword arguments are passed through to the associated TimeStepperOptions object.

swe_timestepper_options

A trait whose value must be an instance of a specified class.

The value can also be an instance of a subclass of the specified class.

Subclasses can declare default classes by overriding the klass attribute

swe_timestepper_type

Name of the time integrator

tidal_turbine_farms

Dictionary mapping subdomain ids to the options of the corresponding farm

tracer_advective_velocity_factor

Custom factor multiplied to the velocity variable in tracer advection equation.

Used to account for mismatch between depth-averaged product of velocity with tracer and product of depth-averaged velocity with depth-averaged tracer

tracer_element_family

Finite element family for tracer transport

2D solver supports ‘dg’ or ‘cg’.

tracer_only

Hold shallow water variables in initial state

Advects tracer in the associated (constant) velocity field.

tracer_picard_iterations

Number of Picard iterations taken for tracer equations.

tracer_timestepper_options

A trait whose value must be an instance of a specified class.

The value can also be an instance of a subclass of the specified class.

Subclasses can declare default classes by overriding the klass attribute

tracer_timestepper_type

Name of the tracer time integrator

use_automatic_wetting_and_drying_alpha

Toggle automatic computation of the alpha parameter used in wetting and drying schemes.

By default, this parameter is set to 0.5.

For problems whose bathymetry varies wildly in coastal regions, it is advisable to use the automatic wetting and drying parameter, rather than the default.

use_supg_tracer

Use SUPG stabilisation in tracer advection

use_tracer_conservative_form

Solve 2D tracer transport in the conservative form

use_wetting_and_drying

bool: Turn on wetting and drying

Uses the wetting and drying scheme from Karna et al (2011). If True, one should also set wetting_and_drying_alpha to control the bathymetry displacement.

wetting_and_drying_alpha

Coefficient: Wetting and drying parameter \(\alpha\).

Used in bathymetry displacement function that ensures positive water depths. Unit is meters.

wetting_and_drying_alpha_max

Maximum value to be taken by wetting and drying parameter \(\alpha\).

Note this is only relevant if use_automatic_wetting_and_drying_alpha is set to True.

wetting_and_drying_alpha_min

Minimum value to be taken by wetting and drying parameter \(\alpha\).

Note this is only relevant if use_automatic_wetting_and_drying_alpha is set to True.

class thetis.options.ModelOptions3d(**kwargs: Any)

Bases: CommonModelOptions

Options for 3D hydrostatic model

bottom_roughness

Bottom roughness length in meters.

check_salinity_conservation

Compute total salinity mass at every export

Prints deviation from the initial mass to stdout.

check_salinity_overshoot

Compute salinity overshoots at every export

Prints overshoot values that exceed the initial range to stdout.

check_temperature_conservation

Compute total temperature mass at every export

Prints deviation from the initial mass to stdout.

check_temperature_overshoot

Compute temperature overshoots at every export

Prints overshoot values that exceed the initial range to stdout.

check_volume_conservation_3d

Compute volume of the 3D domain at every export

Prints deviation from the initial volume to stdout.

constant_salinity

Constant salinity if salinity is not solved

constant_temperature

Constant temperature if temperature is not solved

equation_of_state_options

A trait whose value must be an instance of a specified class.

The value can also be an instance of a subclass of the specified class.

Subclasses can declare default classes by overriding the klass attribute

equation_of_state_type

Type of equation of state

horizontal_diffusivity

Horizontal diffusivity for tracers

internal_pg_scalar

A constant to scale the internal pressure gradient. Used to ramp up the model.

momentum_source_3d

Source term for 3D momentum equation

name = '3D hydrostatic model'

salinity_source_3d

Source term for salinity equation

sipg_factor_turb

Penalty parameter scaling factor for horizontal diffusivity terms of the turbulence model.

sipg_factor_vertical

Penalty parameter scaling factor for vertical viscosity terms.

sipg_factor_vertical_tracer

Penalty parameter scaling factor for vertical diffusivity terms.

sipg_factor_vertical_turb

Penalty parameter scaling factor for vertical diffusivity terms of the turbulence model.

smagorinsky_coefficient

Smagorinsky viscosity coefficient \(C_S\)

See SmagorinskyViscosity.

solve_salinity

Solve salinity transport

solve_temperature

Solve temperature transport

temperature_source_3d

Source term for temperature equation

timestep_2d

Time step of the 2d mode

This option is only used in the 3d solver, if 2d mode is solved explicitly.

timestepper_options

A trait whose value must be an instance of a specified class.

The value can also be an instance of a subclass of the specified class.

Subclasses can declare default classes by overriding the klass attribute

timestepper_type

Name of the 3D time integrator

turbulence_model_options

A trait whose value must be an instance of a specified class.

The value can also be an instance of a subclass of the specified class.

Subclasses can declare default classes by overriding the klass attribute

turbulence_model_type

Type of vertical turbulence model

use_ale_moving_mesh

Use ALE formulation where 3D mesh tracks free surface

use_baroclinic_formulation

Compute internal pressure gradient in momentum equation

use_bottom_friction

Apply log layer bottom stress in the 3D model

use_implicit_vertical_diffusion

Solve vertical diffusion and viscosity implicitly

use_limiter_for_velocity

Apply P1DG limiter for 3D horizontal velocity field

use_quadratic_density

Water density is projected to P2DGxP2 space.

This reduces pressure gradient errors associated with nonlinear equation of state. If False, density is computed point-wise in the tracer space.

use_quadratic_pressure

Use P2DGxP2 space for baroclinic head.

If element_family=’dg-dg’, P2DGxP1DG space is also used for the internal pressure gradient.

This is useful to alleviate bathymetry-induced pressure gradient errors. If False, the baroclinic head is in the tracer space, and internal pressure gradient is in the velocity space.

use_smagorinsky_viscosity

Use Smagorinsky horisontal viscosity parametrization

use_turbulence

Activate turbulence model in the 3D model

use_turbulence_advection

Advect TKE and Psi in the GLS turbulence model

vertical_diffusivity

Vertical diffusivity for tracers

vertical_velocity_scale

Maximum vertical velocity magnitude

Used to compute max stable advection time step.

vertical_viscosity

Vertical viscosity

class thetis.options.NonhydrostaticModelOptions(**kwargs: Any)

Bases: FrozenHasTraits

Options for non-hydrostatic models

free_surface_timestepper_options

A trait whose value must be an instance of a specified class.

The value can also be an instance of a subclass of the specified class.

Subclasses can declare default classes by overriding the klass attribute

free_surface_timestepper_type

Name of the free surface time integrator

name = 'Non-hydrostatic 2D/3D models'

q_degree

Polynomial degree of the non-hydrostatic pressure space

solve_nonhydrostatic_pressure

Solve equations with the non-hydrostatic pressure

solver_parameters

PETSc solver options dictionary

update_free_surface

Update free surface elevation after pressure projection/correction step

class thetis.options.PacanowskiPhilanderModelOptions(**kwargs: Any)

Bases: TurbulenceModelOptions

Options for Pacanowski-Philander turbulence model

alpha

float: Richardson number multiplier

exponent

float: Exponent of viscosity numerator \(n\)

max_viscosity

float: Constant maximum viscosity \(\nu_{max}\)

name = 'Pacanowski-Philander turbulence closure model'

class thetis.options.PressureProjectionSWETimeStepperOptions2d(**kwargs: Any)

Bases: TimeStepperOptions

Options for 2d pressure-projection time integrator applied to shallow water equations

implicitness_theta

implicitness parameter theta. Value 0.5 implies Crank-Nicolson scheme, 1.0 implies fully implicit formulation.

picard_iterations

number of Picard iterations to converge the nonlinearity in the equations.

solver_parameters_momentum

PETSc solver options dictionary

solver_parameters_pressure

PETSc solver options dictionary

use_semi_implicit_linearization

Use linearized semi-implicit time integration

class thetis.options.SSPRKTimeStepperOptions3d(**kwargs: Any)

Bases: TimeStepperOptions3d

Options for 3d SSPRK coupled time integrator

explicit_momentum_options = <thetis.options.ExplicitMomentumTimeStepperOptions3d object>

explicit_tracer_options = <thetis.options.ExplicitTracerTimeStepperOptions3d object>

implicit_momentum_options = <thetis.options.ImplicitMomentumTimeStepperOptions3d object>

implicit_tracer_options = <thetis.options.ImplicitTracerTimeStepperOptions3d object>

swe_options = <thetis.options.SWETimeStepperOptions3d object>

use_automatic_timestep

Set time step automatically based on local CFL conditions.

class thetis.options.SWETimeStepperOptions3d(**kwargs: Any)

Bases: TimeStepperOptions3d

Options for 3d time integrator shallow water component

solver_parameters

PETSc solver options dictionary

class thetis.options.SedimentModelOptions(**kwargs: Any)

Bases: FrozenHasTraits

average_sediment_size

Average sediment size

bed_reference_height

Bottom bed reference height

check_sediment_conservation

Compute total sediment mass at every export

Prints deviation from the initial mass to stdout.

check_sediment_overshoot

Compute sediment overshoots at every export

Prints overshoot values that exceed the initial range to stdout.

exner_timestepper_options

A trait whose value must be an instance of a specified class.

The value can also be an instance of a subclass of the specified class.

Subclasses can declare default classes by overriding the klass attribute

exner_timestepper_type

Name of the exner time integrator

horizontal_diffusivity

Horizontal diffusivity for sediment

max_angle

Angle of repose for sediment slide mechanism in degrees

morphological_acceleration_factor

Rate at which timestep in exner equation is accelerated compared to timestep for model

timestep in exner = morphological_acceleration_factor * timestep

morphological_viscosity

Viscosity used to derive morphology terms.

Usually equal to horizontal viscosity but can be set to have a different value

porosity

Bed porosity for exner equation

secondary_current_parameter

Parameter controlling secondary current

sed_slide_length_scale

Length scale for sediment slide mechanism.

This should normally be the average meshgrid size.

sediment_density

Density of sediment

sediment_model_class

Class used to define the sediment model

This option can be used to provide a user-defined sediment model class that should be a subclass of SedimentModel. For example:

class UserSedimentModel(SedimentModel):
   def __init__(options, mesh2d, uv, elev, depth, extra_term):
      super().__init__(options, mesh2d, uv, elev, depth)
      self.extra_term = extra_term

   def get_bedloadterm(self, bathymetry):
      return super().get_bedloadterm(bathymetry) + self.term

sediment_timestepper_options

A trait whose value must be an instance of a specified class.

The value can also be an instance of a subclass of the specified class.

Subclasses can declare default classes by overriding the klass attribute

sediment_timestepper_type

Name of the sediment time integrator

slide_region

Region where sediment slide occurs.

If None then sediment slide is applied over whole domain.

slope_effect_angle_parameter

Parameter controlling angle of slope effect

slope_effect_parameter

Parameter controlling magnitude of slope effect

solve_exner

Solve exner equation for bed morphology

solve_suspended_sediment

Solve suspended sediment transport equation

use_advective_velocity_correction

Switch to apply correction to advective velocity used in sediment equation

Accounts for mismatch between depth-averaged product of velocity with sediment and product of depth-averaged velocity with depth-averaged sediment

use_angle_correction

Switch to use slope effect angle correction

use_bedload

Use bedload transport in sediment model

use_secondary_current

Switch to use secondary current for helical flow effect

use_sediment_conservative_form

Solve 2D sediment transport in the conservative form

use_sediment_slide

Use sediment slide mechanism in sediment model

use_slope_mag_correction

Switch to use slope effect magnitude correction

class thetis.options.SemiImplicitSWETimeStepperOptions2d(**kwargs: Any)

Bases: SemiImplicitTimeStepperOptions2d

Options for 2d semi-implicit time integrator applied to shallow water equations

solver_parameters

PETSc solver options dictionary

class thetis.options.SemiImplicitTimeStepperOptions2d(**kwargs: Any)

Bases: TimeStepperOptions

Options for 2d semi-implicit time integrator

use_semi_implicit_linearization

Use linearized semi-implicit time integration

class thetis.options.SemiImplicitTracerTimeStepperOptions2d(**kwargs: Any)

Bases: SemiImplicitTimeStepperOptions2d

Options for 2d semi-implicit time integrator applied to tracer equations

solver_parameters

PETSc solver options dictionary

class thetis.options.SteadyStateTimeStepperOptions2d(**kwargs: Any)

Bases: TimeStepperOptions

Options for 2d steady state solver

solver_parameters

PETSc solver options dictionary

class thetis.options.TabulatedTidalTurbineOptions(**kwargs: Any)

Bases: TidalTurbineOptions

Options for tidal turbine with tabulated thrust coefficient

name = 'Tabulated tidal turbine options'

thrust_coefficients

Table of thrust coefficients

thrust_speeds

List of speeds at which thrust_coefficients are applied. First and last entry function as cut-in and cut-out speeds respectively

class thetis.options.TidalTurbineFarmOptions(**kwargs: Any)

Bases: FrozenHasTraits, TraitType

Tidal turbine farm options

break_even_wattage

Average power production per turbine required to break even

name: str | None = 'Farm options'

turbine_density

Density of turbines within the farm

turbine_options

A trait whose value must be an instance of a specified class.

The value can also be an instance of a subclass of the specified class.

Subclasses can declare default classes by overriding the klass attribute

turbine_type

Type of turbine thrust specification

class thetis.options.TidalTurbineOptions(**kwargs: Any)

Bases: FrozenHasTraits

Tidal turbine parameters

A_support

Cross section of support structure

C_support

Thrust coefficient for support structure

diameter

Turbine diameter

name = 'Tidal turbine options'

class thetis.options.TimeStepperOptions(**kwargs: Any)

Bases: FrozenHasTraits

Base class for all time stepper options

ad_block_tag

Custom tag for the Pyadjoint blocks generated by this timestepper.

name = 'Time stepper'

solver_parameters

PETSc solver options dictionary

class thetis.options.TimeStepperOptions3d(**kwargs: Any)

Bases: FrozenHasTraits

Options for 3d explicit time integrator

ad_block_tag

Custom tag for the Pyadjoint blocks generated by this timestepper.

class thetis.options.TracerFieldOptions(**kwargs: Any)

Bases: FrozenHasTraits

Tracer field options

diffusivity

Diffusion coefficient for the tracer equation

function

Firedrake Function representing the tracer

metadata

Dictionary of metadata for the tracer field

name = 'Tracer options'

source

Source term for the tracer equation

use_conservative_form

Should the tracer equation be solved in conservative form?

class thetis.options.TurbulenceModelOptions(**kwargs: Any)

Bases: FrozenHasTraits

Abstract base class for all turbulence model options

name = 'Turbulence closure model'

thetis.physical_constants module

Default values for physical constants and parameters

thetis.rungekutta module

Implements Runge-Kutta time integration methods.

The abstract class AbstractRKScheme defines the Runge-Kutta coefficients, and can be used to implement generic time integrators.

class thetis.rungekutta.AbstractRKScheme

Bases: ABC

Abstract class for defining Runge-Kutta schemes.

Derived classes must define the Butcher tableau (arrays a, b, c) and the CFL number (cfl_coeff).

Currently only explicit or diagonally implicit schemes are supported.

abstract property a

Runge-Kutta matrix \(a_{i,j}\) of the Butcher tableau

abstract property b

weights \(b_{i}\) of the Butcher tableau

abstract property c

nodes \(c_{i}\) of the Butcher tableau

abstract property cfl_coeff

CFL number of the scheme

Value 1.0 corresponds to Forward Euler time step.

class thetis.rungekutta.BackwardEuler(equation, solution, fields, dt, options, bnd_conditions, terms_to_add='all')

Bases: DIRKGeneric, BackwardEulerAbstract

Parameters:

• equation (Equation object) – the equation to solve

• solution – Function where solution will be stored

• fields (dict of Function or Constant objects) – Dictionary of fields that are passed to the equation

• dt (float) – time step in seconds

• options – TimeStepperOptions instance containing parameter values.

• bnd_conditions (dict) – Dictionary of boundary conditions passed to the equation

• terms_to_add ('all' or list of 'implicit', 'explicit', 'source'.) – Defines which terms of the equation are to be added to this solver. Default ‘all’ implies [‘implicit’, ‘explicit’, ‘source’].

class thetis.rungekutta.BackwardEulerAbstract

Bases: AbstractRKScheme

Backward Euler method

a = [[1.0]]

b = [1.0]

c = [1.0]

cfl_coeff = inf

class thetis.rungekutta.BackwardEulerUForm(equation, solution, fields, dt, options, bnd_conditions, terms_to_add='all')

Bases: DIRKGenericUForm, BackwardEulerAbstract

Parameters:

• equation (Equation object) – the equation to solve

• solution – Function where solution will be stored

• fields (dict of Function or Constant objects) – Dictionary of fields that are passed to the equation

• dt (float) – time step in seconds

• options – TimeStepperOptions instance containing parameter values.

• bnd_conditions (dict) – Dictionary of boundary conditions passed to the equation

• terms_to_add ('all' or list of 'implicit', 'explicit', 'source'.) – Defines which terms of the equation are to be added to this solver. Default ‘all’ implies [‘implicit’, ‘explicit’, ‘source’].

class thetis.rungekutta.CrankNicolsonAbstract

Bases: AbstractRKScheme

Crack-Nicolson scheme

a = [[0.0, 0.0], [0.5, 0.5]]

b = [0.5, 0.5]

c = [0.0, 1.0]

cfl_coeff = inf

class thetis.rungekutta.CrankNicolsonRK(equation, solution, fields, dt, options, bnd_conditions, terms_to_add='all')

Bases: DIRKGeneric, CrankNicolsonAbstract

Parameters:

• equation (Equation object) – the equation to solve

• solution – Function where solution will be stored

• fields (dict of Function or Constant objects) – Dictionary of fields that are passed to the equation

• dt (float) – time step in seconds

• options – TimeStepperOptions instance containing parameter values.

• bnd_conditions (dict) – Dictionary of boundary conditions passed to the equation

• terms_to_add ('all' or list of 'implicit', 'explicit', 'source'.) – Defines which terms of the equation are to be added to this solver. Default ‘all’ implies [‘implicit’, ‘explicit’, ‘source’].

class thetis.rungekutta.DIRK22(equation, solution, fields, dt, options, bnd_conditions, terms_to_add='all')

Bases: DIRKGeneric, DIRK22Abstract

Parameters:

• equation (Equation object) – the equation to solve

• solution – Function where solution will be stored

• fields (dict of Function or Constant objects) – Dictionary of fields that are passed to the equation

• dt (float) – time step in seconds

• options – TimeStepperOptions instance containing parameter values.

• bnd_conditions (dict) – Dictionary of boundary conditions passed to the equation

• terms_to_add ('all' or list of 'implicit', 'explicit', 'source'.) – Defines which terms of the equation are to be added to this solver. Default ‘all’ implies [‘implicit’, ‘explicit’, ‘source’].

class thetis.rungekutta.DIRK22Abstract

Bases: AbstractRKScheme

2-stage, 2nd order, L-stable Diagonally Implicit Runge Kutta method

This method has the Butcher tableau

\[\begin{split}\begin{array}{c|cc} \gamma & \gamma & 0 \\ 1 & 1-\gamma & \gamma \\ \hline & 1/2 & 1/2 \end{array}\end{split}\]

with \(\gamma = (2 - \sqrt{2})/2\).

From DIRK(2,3,2) IMEX scheme in Ascher et al. (1997)

Ascher et al. (1997). Implicit-explicit Runge-Kutta methods for time-dependent partial differential equations. Applied Numerical Mathematics, 25:151-167. http://dx.doi.org/10.1137/0732037

a = [[0.2928932188134524, 0], [0.7071067811865476, 0.2928932188134524]]

b = [0.7071067811865476, 0.2928932188134524]

c = [0.2928932188134524, 1]

cfl_coeff = inf

gamma = 0.2928932188134524

class thetis.rungekutta.DIRK22UForm(equation, solution, fields, dt, options, bnd_conditions, terms_to_add='all')

Bases: DIRKGenericUForm, DIRK22Abstract

Parameters:

• equation (Equation object) – the equation to solve

• solution – Function where solution will be stored

• fields (dict of Function or Constant objects) – Dictionary of fields that are passed to the equation

• dt (float) – time step in seconds

• options – TimeStepperOptions instance containing parameter values.

• bnd_conditions (dict) – Dictionary of boundary conditions passed to the equation

• terms_to_add ('all' or list of 'implicit', 'explicit', 'source'.) – Defines which terms of the equation are to be added to this solver. Default ‘all’ implies [‘implicit’, ‘explicit’, ‘source’].

class thetis.rungekutta.DIRK23(equation, solution, fields, dt, options, bnd_conditions, terms_to_add='all')

Bases: DIRKGeneric, DIRK23Abstract

Parameters:

• equation (Equation object) – the equation to solve

• solution – Function where solution will be stored

• fields (dict of Function or Constant objects) – Dictionary of fields that are passed to the equation

• dt (float) – time step in seconds

• options – TimeStepperOptions instance containing parameter values.

• bnd_conditions (dict) – Dictionary of boundary conditions passed to the equation

• terms_to_add ('all' or list of 'implicit', 'explicit', 'source'.) – Defines which terms of the equation are to be added to this solver. Default ‘all’ implies [‘implicit’, ‘explicit’, ‘source’].

class thetis.rungekutta.DIRK23Abstract

Bases: AbstractRKScheme

2-stage, 3rd order Diagonally Implicit Runge Kutta method

This method has the Butcher tableau

\[\begin{split}\begin{array}{c|cc} \gamma & \gamma & 0 \\ 1-\gamma & 1-2\gamma & \gamma \\ \hline & 1/2 & 1/2 \end{array}\end{split}\]

with \(\gamma = (3 + \sqrt{3})/6\).

From DIRK(2,3,3) IMEX scheme in Ascher et al. (1997)

Ascher et al. (1997). Implicit-explicit Runge-Kutta methods for time-dependent partial differential equations. Applied Numerical Mathematics, 25:151-167. http://dx.doi.org/10.1137/0732037

a = [[0.7886751345948128, 0], [-0.5773502691896255, 0.7886751345948128]]

b = [0.5, 0.5]

c = [0.7886751345948128, 0.21132486540518725]

cfl_coeff = inf

gamma = 0.7886751345948128

class thetis.rungekutta.DIRK33(equation, solution, fields, dt, options, bnd_conditions, terms_to_add='all')

Bases: DIRKGeneric, DIRK33Abstract

Parameters:

• equation (Equation object) – the equation to solve

• solution – Function where solution will be stored

• fields (dict of Function or Constant objects) – Dictionary of fields that are passed to the equation

• dt (float) – time step in seconds

• options – TimeStepperOptions instance containing parameter values.

• bnd_conditions (dict) – Dictionary of boundary conditions passed to the equation

• terms_to_add ('all' or list of 'implicit', 'explicit', 'source'.) – Defines which terms of the equation are to be added to this solver. Default ‘all’ implies [‘implicit’, ‘explicit’, ‘source’].

class thetis.rungekutta.DIRK33Abstract

Bases: AbstractRKScheme

3-stage, 3rd order, L-stable Diagonally Implicit Runge Kutta method

From DIRK(3,4,3) IMEX scheme in Ascher et al. (1997)

Ascher et al. (1997). Implicit-explicit Runge-Kutta methods for time-dependent partial differential equations. Applied Numerical Mathematics, 25:151-167. http://dx.doi.org/10.1137/0732037

a = [[0.4358665215, 0, 0], [0.28206673925000003, 0.4358665215, 0], [1.208496649153235, -0.6443631706532353, 0.4358665215]]

b = [1.208496649153235, -0.6443631706532353, 0.4358665215]

b1 = 1.208496649153235

b2 = -0.6443631706532353

c = [0.4358665215, 0.71793326075, 1]

cfl_coeff = inf

gamma = 0.4358665215

class thetis.rungekutta.DIRK33UForm(equation, solution, fields, dt, options, bnd_conditions, terms_to_add='all')

Bases: DIRKGenericUForm, DIRK33Abstract

Parameters:

• equation (Equation object) – the equation to solve

• solution – Function where solution will be stored

• fields (dict of Function or Constant objects) – Dictionary of fields that are passed to the equation

• dt (float) – time step in seconds

• options – TimeStepperOptions instance containing parameter values.

• bnd_conditions (dict) – Dictionary of boundary conditions passed to the equation

• terms_to_add ('all' or list of 'implicit', 'explicit', 'source'.) – Defines which terms of the equation are to be added to this solver. Default ‘all’ implies [‘implicit’, ‘explicit’, ‘source’].

class thetis.rungekutta.DIRK43(equation, solution, fields, dt, options, bnd_conditions, terms_to_add='all')

Bases: DIRKGeneric, DIRK43Abstract

Parameters:

• equation (Equation object) – the equation to solve

• solution – Function where solution will be stored

• fields (dict of Function or Constant objects) – Dictionary of fields that are passed to the equation

• dt (float) – time step in seconds

• options – TimeStepperOptions instance containing parameter values.

• bnd_conditions (dict) – Dictionary of boundary conditions passed to the equation

• terms_to_add ('all' or list of 'implicit', 'explicit', 'source'.) – Defines which terms of the equation are to be added to this solver. Default ‘all’ implies [‘implicit’, ‘explicit’, ‘source’].

class thetis.rungekutta.DIRK43Abstract

Bases: AbstractRKScheme

4-stage, 3rd order, L-stable Diagonally Implicit Runge Kutta method

From DIRK(4,4,3) IMEX scheme in Ascher et al. (1997)

Ascher et al. (1997). Implicit-explicit Runge-Kutta methods for time-dependent partial differential equations. Applied Numerical Mathematics, 25:151-167. http://dx.doi.org/10.1137/0732037

a = [[0.5, 0, 0, 0], [0.16666666666666666, 0.5, 0, 0], [-0.5, 0.5, 0.5, 0], [1.5, -1.5, 0.5, 0.5]]

b = [1.5, -1.5, 0.5, 0.5]

c = [0.5, 0.6666666666666666, 0.5, 1.0]

cfl_coeff = inf

class thetis.rungekutta.DIRKGeneric(equation, solution, fields, dt, options, bnd_conditions, terms_to_add='all')

Bases: RungeKuttaTimeIntegrator

Generic implementation of Diagonally Implicit Runge Kutta schemes.

All derived classes must define the Butcher tableau coefficients a, b, c.

Parameters:

• equation (Equation object) – the equation to solve

• solution – Function where solution will be stored

• fields (dict of Function or Constant objects) – Dictionary of fields that are passed to the equation

• dt (float) – time step in seconds

• options – TimeStepperOptions instance containing parameter values.

• bnd_conditions (dict) – Dictionary of boundary conditions passed to the equation

• terms_to_add ('all' or list of 'implicit', 'explicit', 'source'.) – Defines which terms of the equation are to be added to this solver. Default ‘all’ implies [‘implicit’, ‘explicit’, ‘source’].

get_final_solution()

Assign final solution to self.solution

initialize(init_cond)

Assigns initial conditions to all required fields.

solve_stage(i_stage, t, update_forcings=None)

Solve i-th stage and assign solution to self.solution.

solve_tendency(i_stage, t, update_forcings=None)

Evaluates the tendency of i-th stage.

update_solution(i_stage)

Updates solution to i_stage sub-stage.

Tendencies must have been evaluated first.

update_solver()

Create solver objects

class thetis.rungekutta.DIRKGenericUForm(equation, solution, fields, dt, options, bnd_conditions, terms_to_add='all')

Bases: RungeKuttaTimeIntegrator

Parameters:

• equation (Equation object) – the equation to solve

• solution – Function where solution will be stored

• fields (dict of Function or Constant objects) – Dictionary of fields that are passed to the equation

• dt (float) – time step in seconds

• options – TimeStepperOptions instance containing parameter values.

• bnd_conditions (dict) – Dictionary of boundary conditions passed to the equation

• terms_to_add ('all' or list of 'implicit', 'explicit', 'source'.) – Defines which terms of the equation are to be added to this solver. Default ‘all’ implies [‘implicit’, ‘explicit’, ‘source’].

cfl_coeff = inf

get_final_solution(additive=False)

Evaluates the final solution

initialize(init_cond)

Assigns initial conditions to all required fields.

solve_stage(i_stage, t, update_forcings=None)

Solves a single stage of step from t to t+dt. All functions that the equation depends on must be at right state corresponding to each sub-step.

update_solver()

Create solver objects

class thetis.rungekutta.DIRKLPUM2(equation, solution, fields, dt, options, bnd_conditions, terms_to_add='all')

Bases: DIRKGeneric, DIRKLPUM2Abstract

Parameters:

• equation (Equation object) – the equation to solve

• solution – Function where solution will be stored

• fields (dict of Function or Constant objects) – Dictionary of fields that are passed to the equation

• dt (float) – time step in seconds

• options – TimeStepperOptions instance containing parameter values.

• bnd_conditions (dict) – Dictionary of boundary conditions passed to the equation

• terms_to_add ('all' or list of 'implicit', 'explicit', 'source'.) – Defines which terms of the equation are to be added to this solver. Default ‘all’ implies [‘implicit’, ‘explicit’, ‘source’].

class thetis.rungekutta.DIRKLPUM2Abstract

Bases: AbstractRKScheme

DIRKLPUM2, 3-stage, 2nd order, L-stable Diagonally Implicit Runge Kutta method

From IMEX RK scheme (20) in Higureras et al. (2014).

Higueras et al (2014). Optimized strong stability preserving IMEX Runge-Kutta methods. Journal of Computational and Applied Mathematics 272(2014) 116-140. http://dx.doi.org/10.1016/j.cam.2014.05.011

a = [[0.18181818181818182, 0, 0], [0.2662337662337662, 0.18181818181818182, 0], [0.3412042502951594, 0.34710743801652894, 0.18181818181818182]]

b = [0.3333333333333333, 0.3333333333333333, 0.3333333333333333]

c = [0.18181818181818182, 0.44805194805194803, 0.8701298701298701]

cfl_coeff = 4.34

class thetis.rungekutta.DIRKLSPUM2(equation, solution, fields, dt, options, bnd_conditions, terms_to_add='all')

Bases: DIRKGeneric, DIRKLSPUM2Abstract

Parameters:

• equation (Equation object) – the equation to solve

• solution – Function where solution will be stored

• fields (dict of Function or Constant objects) – Dictionary of fields that are passed to the equation

• dt (float) – time step in seconds

• options – TimeStepperOptions instance containing parameter values.

• bnd_conditions (dict) – Dictionary of boundary conditions passed to the equation

• terms_to_add ('all' or list of 'implicit', 'explicit', 'source'.) – Defines which terms of the equation are to be added to this solver. Default ‘all’ implies [‘implicit’, ‘explicit’, ‘source’].

class thetis.rungekutta.DIRKLSPUM2Abstract

Bases: AbstractRKScheme

DIRKLSPUM2, 3-stage, 2nd order, L-stable Diagonally Implicit Runge Kutta method

From IMEX RK scheme (17) in Higureras et al. (2014).

Higueras et al (2014). Optimized strong stability preserving IMEX Runge-Kutta methods. Journal of Computational and Applied Mathematics 272(2014) 116-140. http://dx.doi.org/10.1016/j.cam.2014.05.011

a = [[0.18181818181818182, 0, 0], [0.44372294372294374, 0.18181818181818182, 0], [0.44004329004329007, 0.19090909090909092, 0.18181818181818182]]

b = [0.43636363636363634, 0.2, 0.36363636363636365]

c = [0.18181818181818182, 0.6255411255411255, 0.8127705627705628]

cfl_coeff = 4.34

class thetis.rungekutta.ERKEuler(equation, solution, fields, dt, options, bnd_conditions, terms_to_add='all')

Bases: ERKGeneric, ForwardEulerAbstract

Parameters:

• equation (Equation object) – the equation to solve

• solution – Function where solution will be stored

• fields (dict of Function or Constant objects) – Dictionary of fields that are passed to the equation

• dt (float) – time step in seconds

• options – TimeStepperOptions instance containing parameter values.

• bnd_conditions (dict) – Dictionary of boundary conditions passed to the equation

• terms_to_add ('all' or list of 'implicit', 'explicit', 'source'.) – Defines which terms of the equation are to be added to this solver. Default ‘all’ implies [‘implicit’, ‘explicit’, ‘source’].

class thetis.rungekutta.ERKGeneric(equation, solution, fields, dt, options, bnd_conditions, terms_to_add='all')

Bases: RungeKuttaTimeIntegrator

Generic explicit Runge-Kutta time integrator.

Implements the Butcher form. All terms in the equation are treated explicitly.

Parameters:

• equation (Equation object) – the equation to solve

• solution – Function where solution will be stored

• fields (dict of Function or Constant objects) – Dictionary of fields that are passed to the equation

• dt (float) – time step in seconds

• options – TimeStepperOptions instance containing parameter values.

• bnd_conditions (dict) – Dictionary of boundary conditions passed to the equation

• terms_to_add ('all' or list of 'implicit', 'explicit', 'source'.) – Defines which terms of the equation are to be added to this solver. Default ‘all’ implies [‘implicit’, ‘explicit’, ‘source’].

get_final_solution(additive=False)

Assign final solution to self.solution

If additive=False, will overwrite solution function, otherwise will add to it.

initialize(solution)

Assigns initial conditions to all required fields.

solve_stage(i_stage, t, update_forcings=None)

Solve i-th stage and assign solution to self.solution.

solve_tendency(i_stage, t, update_forcings=None)

Evaluates the tendency of i-th stage

update_solution(i_stage, additive=False)

Computes the solution of the i-th stage

Tendencies must have been evaluated first.

If additive=False, will overwrite solution function, otherwise will add to it.

update_solver()

class thetis.rungekutta.ERKGenericShuOsher(equation, solution, fields, dt, options, bnd_conditions, terms_to_add='all')

Bases: TimeIntegrator

Generic explicit Runge-Kutta time integrator.

Implements the Shu-Osher form.

Parameters:

• equation (Equation object) – the equation to solve

• solution – Function where solution will be stored

• fields (dict of Function or Constant objects) – Dictionary of fields that are passed to the equation

• dt (float) – time step in seconds

• options – TimeStepperOptions instance containing parameter values.

• bnd_conditions (dict) – Dictionary of boundary conditions passed to the equation

• terms_to_add ('all' or list of 'implicit', 'explicit', 'source'.) – Defines which terms of the equation are to be added to this solver. Default ‘all’ implies [‘implicit’, ‘explicit’, ‘source’].

advance(t, update_forcings=None)

Advances equations for one time step.

initialize(solution)

Initialize the time integrator

Parameters:

init_solution – initial solution

solve_stage(i_stage, t, update_forcings=None)

Solve i-th stage and assign solution to self.solution.

update_solver()

class thetis.rungekutta.ERKLPUM2(equation, solution, fields, dt, options, bnd_conditions, terms_to_add='all')

Bases: ERKGeneric, ERKLPUM2Abstract

Parameters:

• equation (Equation object) – the equation to solve

• solution – Function where solution will be stored

• fields (dict of Function or Constant objects) – Dictionary of fields that are passed to the equation

• dt (float) – time step in seconds

• options – TimeStepperOptions instance containing parameter values.

• bnd_conditions (dict) – Dictionary of boundary conditions passed to the equation

• terms_to_add ('all' or list of 'implicit', 'explicit', 'source'.) – Defines which terms of the equation are to be added to this solver. Default ‘all’ implies [‘implicit’, ‘explicit’, ‘source’].

class thetis.rungekutta.ERKLPUM2Abstract

Bases: AbstractRKScheme

ERKLPUM2, 3-stage, 2nd order Explicit Runge Kutta method

From IMEX RK scheme (20) in Higureras et al. (2014).

Higueras et al (2014). Optimized strong stability preserving IMEX Runge-Kutta methods. Journal of Computational and Applied Mathematics 272(2014) 116-140. http://dx.doi.org/10.1016/j.cam.2014.05.011

a = [[0, 0, 0], [0.5, 0, 0], [0.5, 0.5, 0]]

b = [0.3333333333333333, 0.3333333333333333, 0.3333333333333333]

c = [0, 0.5, 1.0]

cfl_coeff = 2.0

class thetis.rungekutta.ERKLSPUM2(equation, solution, fields, dt, options, bnd_conditions, terms_to_add='all')

Bases: ERKGeneric, ERKLSPUM2Abstract

Parameters:

• equation (Equation object) – the equation to solve

• solution – Function where solution will be stored

• fields (dict of Function or Constant objects) – Dictionary of fields that are passed to the equation

• dt (float) – time step in seconds

• options – TimeStepperOptions instance containing parameter values.

• bnd_conditions (dict) – Dictionary of boundary conditions passed to the equation

• terms_to_add ('all' or list of 'implicit', 'explicit', 'source'.) – Defines which terms of the equation are to be added to this solver. Default ‘all’ implies [‘implicit’, ‘explicit’, ‘source’].

class thetis.rungekutta.ERKLSPUM2Abstract

Bases: AbstractRKScheme

ERKLSPUM2, 3-stage, 2nd order Explicit Runge Kutta method

From IMEX RK scheme (17) in Higureras et al. (2014).

Higueras et al (2014). Optimized strong stability preserving IMEX Runge-Kutta methods. Journal of Computational and Applied Mathematics 272(2014) 116-140. http://dx.doi.org/10.1016/j.cam.2014.05.011

a = [[0, 0, 0], [0.8333333333333334, 0, 0], [0.4583333333333333, 0.4583333333333333, 0]]

b = [0.43636363636363634, 0.2, 0.36363636363636365]

c = [0, 0.8333333333333334, 0.9166666666666666]

cfl_coeff = 1.2

class thetis.rungekutta.ERKMidpoint(equation, solution, fields, dt, options, bnd_conditions, terms_to_add='all')

Bases: ERKGeneric, ERKMidpointAbstract

Parameters:

• equation (Equation object) – the equation to solve

• solution – Function where solution will be stored

• fields (dict of Function or Constant objects) – Dictionary of fields that are passed to the equation

• dt (float) – time step in seconds

• options – TimeStepperOptions instance containing parameter values.

• bnd_conditions (dict) – Dictionary of boundary conditions passed to the equation

• terms_to_add ('all' or list of 'implicit', 'explicit', 'source'.) – Defines which terms of the equation are to be added to this solver. Default ‘all’ implies [‘implicit’, ‘explicit’, ‘source’].

class thetis.rungekutta.ERKMidpointAbstract

Bases: AbstractRKScheme

a = [[0.0, 0.0], [0.5, 0.0]]

b = [0.0, 1.0]

c = [0.0, 0.5]

cfl_coeff = 1.0

class thetis.rungekutta.ESDIRKMidpoint(equation, solution, fields, dt, options, bnd_conditions, terms_to_add='all')

Bases: DIRKGeneric, ESDIRKMidpointAbstract

Parameters:

• equation (Equation object) – the equation to solve

• solution – Function where solution will be stored

• fields (dict of Function or Constant objects) – Dictionary of fields that are passed to the equation

• dt (float) – time step in seconds

• options – TimeStepperOptions instance containing parameter values.

• bnd_conditions (dict) – Dictionary of boundary conditions passed to the equation

• terms_to_add ('all' or list of 'implicit', 'explicit', 'source'.) – Defines which terms of the equation are to be added to this solver. Default ‘all’ implies [‘implicit’, ‘explicit’, ‘source’].

class thetis.rungekutta.ESDIRKMidpointAbstract

Bases: AbstractRKScheme

a = [[0.0, 0.0], [0.0, 0.5]]

b = [0.0, 1.0]

c = [0.0, 0.5]

cfl_coeff = 1.0

class thetis.rungekutta.ESDIRKTrapezoid(equation, solution, fields, dt, options, bnd_conditions, terms_to_add='all')

Bases: DIRKGeneric, ESDIRKTrapezoidAbstract

Parameters:

• equation (Equation object) – the equation to solve

• solution – Function where solution will be stored

• fields (dict of Function or Constant objects) – Dictionary of fields that are passed to the equation

• dt (float) – time step in seconds

• options – TimeStepperOptions instance containing parameter values.

• bnd_conditions (dict) – Dictionary of boundary conditions passed to the equation

• terms_to_add ('all' or list of 'implicit', 'explicit', 'source'.) – Defines which terms of the equation are to be added to this solver. Default ‘all’ implies [‘implicit’, ‘explicit’, ‘source’].

class thetis.rungekutta.ESDIRKTrapezoidAbstract

Bases: AbstractRKScheme

a = [[0.0, 0.0], [0.5, 0.5]]

b = [0.5, 0.5]

c = [0.0, 1.0]

cfl_coeff = inf

class thetis.rungekutta.ForwardEulerAbstract

Bases: AbstractRKScheme

Forward Euler method

a = [[0]]

b = [1.0]

c = [0]

cfl_coeff = 1.0

class thetis.rungekutta.ImplicitMidpoint(equation, solution, fields, dt, options, bnd_conditions, terms_to_add='all')

Bases: DIRKGeneric, ImplicitMidpointAbstract

Parameters:

• equation (Equation object) – the equation to solve

• solution – Function where solution will be stored

• fields (dict of Function or Constant objects) – Dictionary of fields that are passed to the equation

• dt (float) – time step in seconds

• options – TimeStepperOptions instance containing parameter values.

• bnd_conditions (dict) – Dictionary of boundary conditions passed to the equation

• terms_to_add ('all' or list of 'implicit', 'explicit', 'source'.) – Defines which terms of the equation are to be added to this solver. Default ‘all’ implies [‘implicit’, ‘explicit’, ‘source’].

class thetis.rungekutta.ImplicitMidpointAbstract

Bases: AbstractRKScheme

Implicit midpoint method, second order.

This method has the Butcher tableau

\[\begin{split}\begin{array}{c|c} 0.5 & 0.5 \\ \hline & 1.0 \end{array}\end{split}\]

a = [[0.5]]

b = [1.0]

c = [0.5]

cfl_coeff = inf

class thetis.rungekutta.RungeKuttaTimeIntegrator(equation, solution, fields, dt, options)

Bases: TimeIntegrator, ABC

Abstract base class for all Runge-Kutta time integrators

Parameters:

• equation (Equation object) – the equation to solve

• solution – Function where solution will be stored

• fields (dict of Function or Constant objects) – Dictionary of fields that are passed to the equation

• dt (float) – time step in seconds

• options – TimeStepperOptions instance containing parameter values

advance(t, update_forcings=None)

Advances equations for one time step.

abstract get_final_solution(additive=False)

Evaluates the final solution

abstract solve_stage(i_stage, t, update_forcings=None)

Solves a single stage of step from t to t+dt. All functions that the equation depends on must be at right state corresponding to each sub-step.

class thetis.rungekutta.SSPRK33(equation, solution, fields, dt, options, bnd_conditions, terms_to_add='all')

Bases: ERKGenericShuOsher, SSPRK33Abstract

Parameters:

• equation (Equation object) – the equation to solve

• solution – Function where solution will be stored

• fields (dict of Function or Constant objects) – Dictionary of fields that are passed to the equation

• dt (float) – time step in seconds

• options – TimeStepperOptions instance containing parameter values.

• bnd_conditions (dict) – Dictionary of boundary conditions passed to the equation

• terms_to_add ('all' or list of 'implicit', 'explicit', 'source'.) – Defines which terms of the equation are to be added to this solver. Default ‘all’ implies [‘implicit’, ‘explicit’, ‘source’].

class thetis.rungekutta.SSPRK33Abstract

Bases: AbstractRKScheme

3rd order Strong Stability Preserving Runge-Kutta scheme, SSP(3,3).

This scheme has Butcher tableau

\[\begin{split}\begin{array}{c|ccc} 0 & \\ 1 & 1 \\ 1/2 & 1/4 & 1/4 & \\ \hline & 1/6 & 1/6 & 2/3 \end{array}\end{split}\]

CFL coefficient is 1.0

a = [[0, 0, 0], [1.0, 0, 0], [0.25, 0.25, 0]]

b = [0.16666666666666666, 0.16666666666666666, 0.6666666666666666]

c = [0, 1.0, 0.5]

cfl_coeff = 1.0

thetis.rungekutta.butcher_to_shuosher_form(a, b)

Converts Butcher tableau to Shu-Osher form.

The Shu-Osher form of a s-stage scheme is defined by two s+1 by s+1 arrays \(\alpha\) and \(\beta\):

\[\begin{split}u^{0} &= u^n \\ u^{(i)} &= \sum_{j=0}^s \alpha_{i,j} u^{(j)} + \sum_{j=0}^s \beta_{i,j} F(u^{(j)}) \\ u^{n+1} &= u^{(s)}\end{split}\]

The Shu-Osher form is not unique. Here we construct the form where beta values are the diagonal entries (for DIRK schemes) or sub-diagonal entries (for explicit schemes) of the concatenated Butcher tableau [\(a\); \(b\)].

For more information see Ketchelson et al. (2009) http://dx.doi.org/10.1016/j.apnum.2008.03.034

thetis.rungekutta.timed_region()

Log.Event(cls, name, klass=None) Source code at petsc4py/PETSc/Log.pyx:39

thetis.rungekutta.timed_stage()

Log.Stage(cls, name) Source code at petsc4py/PETSc/Log.pyx:11

thetis.sediment_eq_2d module

2D advection diffusion equation for sediment transport.

This can be either conservative \(q=HT\) or non-conservative \(T\) sediment and allows for a separate source and sink term. The equation reads

(6)\[\frac{\partial S}{\partial t} + \nabla_h \cdot (\textbf{u} S) = \nabla_h \cdot (\mu_h \nabla_h S) + F_{source} - (F_{sink} S)\]

where \(S\) is \(q\) for conservative and \(T\) for non-conservative, \(\nabla_h\) denotes horizontal gradient, \(\textbf{u}\) are the horizontal velocities, and \(\mu_h\) denotes horizontal diffusivity.

class thetis.sediment_eq_2d.ConservativeSedimentAdvectionTerm(function_space, depth, options, sediment_model, conservative=False)

Bases: SedimentTerm, ConservativeHorizontalAdvectionTerm

Advection term for sediment equation

Same as ConservativeHorizontalAdvectionTerm but allows for equilibrium boundary condition through get_bnd_conditions() inherited from SedimentTerm.

Parameters:

• function_space – FunctionSpace where the solution belongs

• depth – DepthExpression containing depth info

• options – :class`ModelOptions2d` containing parameters

• conservative (bool) – whether to use conservative tracer

class thetis.sediment_eq_2d.SedimentAdvectionTerm(function_space, depth, options, sediment_model, conservative=False)

Bases: SedimentTerm, HorizontalAdvectionTerm

Advection term for sediment equation

Same as HorizontalAdvectionTerm but allows for equilibrium boundary condition through get_bnd_conditions() inherited from SedimentTerm.

Parameters:

• function_space – FunctionSpace where the solution belongs

• depth – DepthExpression containing depth info

• options – :class`ModelOptions2d` containing parameters

• conservative (bool) – whether to use conservative tracer

class thetis.sediment_eq_2d.SedimentDepositionTerm(function_space, depth, options, sediment_model, conservative=False)

Bases: SedimentTerm

Deposition term for sediment equation

Parameters:

• function_space – FunctionSpace where the solution belongs

• depth – DepthExpression containing depth info

• options – :class`ModelOptions2d` containing parameters

• conservative (bool) – whether to use conservative tracer

residual(solution, solution_old, fields, fields_old, bnd_conditions)

Returns an UFL form of the term.

Parameters:

• solution – solution Function of the corresponding equation

• solution_old – a time lagged solution Function

• fields – a dictionary that provides all the remaining fields that the term depends on. The keys of the dictionary should standard field names in field_metadata

• fields_old – Time lagged dictionary of fields

• bnd_conditions – A dictionary describing boundary conditions. E.g. {3: {‘elev_2d’: Constant(1.0)}} replaces elev_2d function by a constant on boundary ID 3.

class thetis.sediment_eq_2d.SedimentEquation2D(function_space, depth, options, sediment_model, conservative=False)

Bases: Equation

2D sediment advection-diffusion equation: (16) or (17) with sediment source and sink term

Parameters:

• function_space – FunctionSpace where the solution belongs

• depth – DepthExpression containing depth info

• options – :class`ModelOptions2d` containing parameters

• conservative (bool) – whether to use conservative tracer

class thetis.sediment_eq_2d.SedimentErosionTerm(function_space, depth, options, sediment_model, conservative=False)

Bases: SedimentTerm

Erosion term for sediment equation

Parameters:

• function_space – FunctionSpace where the solution belongs

• depth – DepthExpression containing depth info

• options – :class`ModelOptions2d` containing parameters

• conservative (bool) – whether to use conservative tracer

residual(solution, solution_old, fields, fields_old, bnd_conditions)

Returns an UFL form of the term.

Parameters:

• solution – solution Function of the corresponding equation

• solution_old – a time lagged solution Function

• fields – a dictionary that provides all the remaining fields that the term depends on. The keys of the dictionary should standard field names in field_metadata

• fields_old – Time lagged dictionary of fields

• bnd_conditions – A dictionary describing boundary conditions. E.g. {3: {‘elev_2d’: Constant(1.0)}} replaces elev_2d function by a constant on boundary ID 3.

class thetis.sediment_eq_2d.SedimentTerm(function_space, depth, options, sediment_model, conservative=False)

Bases: TracerTerm

Generic sediment term that provides commonly used members.

Parameters:

• function_space – FunctionSpace where the solution belongs

• depth – DepthExpression containing depth info

• options – :class`ModelOptions2d` containing parameters

• conservative (bool) – whether to use conservative tracer

get_bnd_functions(c_in, uv_in, elev_in, bnd_id, bnd_conditions)

Returns external values of tracer and uv for all supported boundary conditions.

Volume flux (flux) and normal velocity (un) are defined positive out of the domain.

Parameters:

• c_in – Internal value of tracer

• uv_in – Internal value of horizontal velocity

• elev_in – Internal value of elevation

• bnd_id (int) – boundary id

• bnd_conditions – dict of boundary conditions: {bnd_id: {field: value, ...}, ...}

thetis.sediment_model module

class thetis.sediment_model.CorrectiveVelocityFactor(depth, ksp, settling_velocity, ustar, a)

Bases: object

Set up advective velocity factor self.velocity_correction_factor which accounts for mismatch between depth-averaged product of velocity with sediment and product of depth-averaged velocity with depth-averaged sediment.

Parameters:

• depth (Function) – Depth of fluid

• ksp (Constant) – Grain roughness coefficient

• settling_velocity (Constant) – Settling velocity of the sediment particles

• ustar (Expression of functions) – Shear velocity

• a (Constant) – Factor of bottom bed reference height

update()

Update self.velocity_correction_factor using the updated values for velocity

class thetis.sediment_model.SedimentModel(options, mesh2d, uv, elev, depth)

Bases: object

Set up a full morphological model simulation based on provided velocity and elevation functions.

Parameters:

• options (ModelOptions2d instance) – Model options.

• mesh2d – Mesh object of the 2D mesh

• uv (Function) – the velocity solution during the simulation

• elev (Function) – the elevation solution during the simulation

• depth – a DepthExpression instance to evaluate the current depth

The SedimentModel provides various expressions to be used in a suspended sediment and/or the Exner equation. NOTE that the functions used in these expressions need to be updated with the current values of the uv and elev fields by calling SedimentModel.update(). This is not done in the initialisation of the sediment model, so that the SedimentModel can be created before initial conditions have been assigned to uv and elev. After the initial conditions have been assigned a call to update is required to ensure that the initial values are reflected in the SedimentModel terms.

get_advective_velocity_correction_factor()

Returns correction factor for the advective velocity in the sediment equations

With SedimentModelOptions.use_advective_velocity_correction, this applies a correction to the supplied velocity solution uv to take into account the mismatch between depth-averaged product of velocity with sediment and product of depth-averaged velocity with depth-averaged sediment.

get_bedload_term(bathymetry)

Returns expression for bedload transport \((qbx, qby)\) to be used in the Exner equation. Note bathymetry is the function which is solved for in the exner equation.

Parameters:

bathymetry – Bathymetry of the domain. Bathymetry stands for the bedlevel (positive downwards).

get_deposition_coefficient()

Returns coefficient \(C\) such that \(C/H*sediment\) is deposition term in sediment equation

If sediment field is depth-averaged, \(C*sediment\) is (total) deposition (over the column) as it appears in the Exner equation, but deposition term in sediment equation needs averaging: \(C*sediment/H\) If sediment field is depth-integrated, \(C*sediment/H\) is (total) deposition (over the column) as it appears in the Exner equation, and is the same in the sediment equation.

get_equilibrium_tracer()

Returns expression for (depth-averaged) equilibrium tracer.

get_erosion_term()

Returns expression for (depth-integrated) erosion.

get_sediment_slide_term(bathymetry)

update()

Update all functions used by SedimentModel

This repeats all projection and interpolations steps based on the current values of the uv and elev functions, provided in __init__.

thetis.sediment_model.timed_stage()

Log.Stage(cls, name) Source code at petsc4py/PETSc/Log.pyx:11

thetis.shallowwater_eq module

Depth averaged shallow water equations

Equations

The state variables are water elevation, \(\eta\), and depth averaged velocity \(\bar{\textbf{u}}\).

Denoting the total water depth by \(H=\eta + h\), the non-conservative form of the free surface equation is

(7)\[\frac{\partial \eta}{\partial t} + \nabla \cdot (H \bar{\textbf{u}}) = 0\]

The non-conservative momentum equation reads

(8)\[\frac{\partial \bar{\textbf{u}}}{\partial t} + \bar{\textbf{u}} \cdot \nabla\bar{\textbf{u}} + f\textbf{e}_z\wedge \bar{\textbf{u}} + g \nabla \eta + \nabla \left(\frac{p_a}{\rho_0} \right) + g \frac{1}{H}\int_{-h}^\eta \nabla r dz = \nabla \cdot \big( \nu_h ( \nabla \bar{\textbf{u}} + (\nabla \bar{\textbf{u}})^T )\big) + \frac{\nu_h \nabla(H)}{H} \cdot ( \nabla \bar{\textbf{u}} + (\nabla \bar{\textbf{u}})^T ),\]

where \(g\) is the gravitational acceleration, \(f\) is the Coriolis frequency, \(\wedge\) is the cross product, \(\textbf{e}_z\) is a vertical unit vector, \(p_a\) is the atmospheric pressure at the free surface, and \(\nu_h\) is viscosity. Water density is given by \(\rho = \rho'(T, S, p) + \rho_0\), where \(\rho_0\) is a constant reference density.

Above \(r\) denotes the baroclinic head

\[r = \frac{1}{\rho_0} \int_{z}^\eta \rho' d\zeta.\]

In the case of purely barotropic problems the \(r\) and the internal pressure gradient are omitted.

If the option ModelOptions.use_nonlinear_equations is False, we solve the linear shallow water equations (i.e. wave equation):

(9)\[\frac{\partial \eta}{\partial t} + \nabla \cdot (h \bar{\textbf{u}}) = 0\]

(10)\[\frac{\partial \bar{\textbf{u}}}{\partial t} + f\textbf{e}_z\wedge \bar{\textbf{u}} + g \nabla \eta = \nabla \cdot \big( \nu_h ( \nabla \bar{\textbf{u}} + (\nabla \bar{\textbf{u}})^T )\big) + \frac{\nu_h \nabla(H)}{H} \cdot ( \nabla \bar{\textbf{u}} + (\nabla \bar{\textbf{u}})^T ).\]

In case of a 3D problem with mode splitting, we use a simplified 2D system that contains nothing but the rotational external gravity waves:

(11)\[\frac{\partial \eta}{\partial t} + \nabla \cdot (H \bar{\textbf{u}}) = 0\]

(12)\[\frac{\partial \bar{\textbf{u}}}{\partial t} + f\textbf{e}_z\wedge \bar{\textbf{u}} + g \nabla \eta = \textbf{G},\]

where \(\textbf{G}\) is a source term used to couple the 2D and 3D momentum equations.

Boundary Conditions

All boundary conditions are imposed weakly by providing external values for \(\eta\) and \(\bar{\textbf{u}}\).

Boundary conditions are set with a dictionary that defines all prescribed variables at each open boundary. For example, to assign elevation and volume flux on boundary 1 we set

swe_bnd_funcs = {}
swe_bnd_funcs[1] = {'elev':myfunc1, 'flux':myfunc2}

where myfunc1 and myfunc2 are Constant or Function objects.

The user can provide \(\eta\) and/or \(\bar{\textbf{u}}\) values. Supported combinations are:

• unspecified : impermeable (land) boundary, implies symmetric \(\eta\) condition and zero normal velocity

• 'elev': elevation only, symmetric velocity (usually unstable)

• 'uv': 2d velocity vector \(\bar{\textbf{u}}=(u, v)\) (in mesh coordinates), symmetric elevation

• 'un': normal velocity (scalar, positive out of domain), symmetric elevation

• 'flux': normal volume flux (scalar, positive out of domain), symmetric elevation

• 'elev' and 'uv': water elevation and 2d velocity vector

• 'elev' and 'un': water elevation and normal velocity

• 'elev' and 'flux': water elevation and normal flux

The boundary conditions are assigned to the FlowSolver2d or FlowSolver objects:

solver_obj = solver2d.FlowSolver2d(...)
...
solver_obj.bnd_functions['shallow_water'] = swe_bnd_funcs

Internally the boundary conditions passed to the Term.residual() method of each term:

adv_term = shallowwater_eq.HorizontalAdvectionTerm(...)
adv_form = adv_term.residual(..., bnd_conditions=swe_bnd_funcs)

Wetting and drying

If the option ModelOptions.use_wetting_and_drying is True, then wetting and drying is included through the formulation of Karna et al. (2011).

The method introduces a modified bathymetry \(\tilde{h} = h + f(H)\), which ensures positive total water depth, with \(f(H)\) defined by

\[f(H) = \frac{1}{2}(\sqrt{H^2 + \alpha^2} - H),\]

introducing a wetting-drying parameter \(\alpha\), with dimensions of length. This results in a modified total water depth \(\tilde{H}=H+f(H)\).

The value for \(\alpha\) is specified by the user through the option ModelOptions.wetting_and_drying_alpha, in units of meters. The default value for ModelOptions.wetting_and_drying_alpha is 0.5, but the appropriate value is problem specific and should be set by the user.

An approximate method for selecting a suitable value for \(\alpha\) is suggested by Karna et al. (2011). Defining \(L_x\) as the horizontal length scale of the mesh elements at the wet-dry front, it can be reasoned that \(\alpha \approx |L_x \nabla h|\) yields a suitable choice. Smaller \(\alpha\) leads to a more accurate solution to the shallow water equations in wet regions, but if \(\alpha\) is too small the simulation will become unstable.

When wetting and drying is turned on, two things occur:

1. All instances of the height, \(H\), are replaced by \(\tilde{H}\) (as defined above);

2. An additional displacement term \(\frac{\partial \tilde{h}}{\partial t}\) is added to the bathymetry in the free surface equation.

The free surface and momentum equations then become:

(13)\[\frac{\partial \eta}{\partial t} + \frac{\partial \tilde{h}}{\partial t} + \nabla \cdot (\tilde{H} \bar{\textbf{u}}) = 0,\]

(14)\[\frac{\partial \bar{\textbf{u}}}{\partial t} + \bar{\textbf{u}} \cdot \nabla\bar{\textbf{u}} + f\textbf{e}_z\wedge \bar{\textbf{u}} + g \nabla \eta + g \frac{1}{\tilde{H}}\int_{-h}^\eta \nabla r dz = \nabla \cdot \big( \nu_h ( \nabla \bar{\textbf{u}} + (\nabla \bar{\textbf{u}})^T )\big) + \frac{\nu_h \nabla(\tilde{H})}{\tilde{H}} \cdot ( \nabla \bar{\textbf{u}} + (\nabla \bar{\textbf{u}})^T ).\]

class thetis.shallowwater_eq.AtmosphericPressureTerm(u_test, u_space, eta_space, depth, options=None)

Bases: ShallowWaterMomentumTerm

Atmospheric pressure term, \(\nabla (p_a / \rho_0)\)

Here \(p_a\) is a user-defined atmospheric pressure Function.

Parameters:

• function_space – the FunctionSpace the solution belongs to

• test_function – custom TestFunction.

• trial_function – custom TrialFunction.

residual(uv, eta, uv_old, eta_old, fields, fields_old, bnd_conditions)

Returns an UFL form of the term.

Parameters:

• solution – solution Function of the corresponding equation

• solution_old – a time lagged solution Function

• fields – a dictionary that provides all the remaining fields that the term depends on. The keys of the dictionary should standard field names in field_metadata

• fields_old – Time lagged dictionary of fields

• bnd_conditions – A dictionary describing boundary conditions. E.g. {3: {‘elev_2d’: Constant(1.0)}} replaces elev_2d function by a constant on boundary ID 3.

class thetis.shallowwater_eq.BaseShallowWaterEquation(function_space, depth, options)

Bases: Equation

Abstract base class for ShallowWaterEquations, ShallowWaterMomentumEquation and FreeSurfaceEquation.

Provides common functionality to compute time steps and add either momentum or continuity terms.

Parameters:

function_space – the FunctionSpace the solution belongs to

add_continuity_terms(*args)

add_momentum_terms(*args, tidal_farms=None)

residual_uv_eta(label, uv, eta, uv_old, eta_old, fields, fields_old, bnd_conditions)

class thetis.shallowwater_eq.BottomDrag3DTerm(u_test, u_space, eta_space, depth, options=None)

Bases: ShallowWaterMomentumTerm

Bottom drag term consistent with the 3D mode, \(C_D \| \textbf{u}_b \| \textbf{u}_b\)

Here \(\textbf{u}_b\) is the bottom velocity used in the 3D mode, and \(C_D\) the corresponding bottom drag. These fields are computed in the 3D model.

Parameters:

• function_space – the FunctionSpace the solution belongs to

• test_function – custom TestFunction.

• trial_function – custom TrialFunction.

residual(uv, eta, uv_old, eta_old, fields, fields_old, bnd_conditions)

Returns an UFL form of the term.

Parameters:

• solution – solution Function of the corresponding equation

• solution_old – a time lagged solution Function

• fields – a dictionary that provides all the remaining fields that the term depends on. The keys of the dictionary should standard field names in field_metadata

• fields_old – Time lagged dictionary of fields

• bnd_conditions – A dictionary describing boundary conditions. E.g. {3: {‘elev_2d’: Constant(1.0)}} replaces elev_2d function by a constant on boundary ID 3.

class thetis.shallowwater_eq.ContinuitySourceTerm(eta_test, eta_space, u_space, depth, options=None)

Bases: ShallowWaterContinuityTerm

Generic source term in the depth-averaged continuity equation

The weak form reads

\[F_s = \int_\Omega S \phi dx\]

where \(S\) is a user defined scalar Function.

Parameters:

• function_space – the FunctionSpace the solution belongs to

• test_function – custom TestFunction.

• trial_function – custom TrialFunction.

residual(uv, eta, uv_old, eta_old, fields, fields_old, bnd_conditions)

Returns an UFL form of the term.

Parameters:

• solution – solution Function of the corresponding equation

• solution_old – a time lagged solution Function

• fields – a dictionary that provides all the remaining fields that the term depends on. The keys of the dictionary should standard field names in field_metadata

• fields_old – Time lagged dictionary of fields

• bnd_conditions – A dictionary describing boundary conditions. E.g. {3: {‘elev_2d’: Constant(1.0)}} replaces elev_2d function by a constant on boundary ID 3.

class thetis.shallowwater_eq.CoriolisTerm(u_test, u_space, eta_space, depth, options=None)

Bases: ShallowWaterMomentumTerm

Coriolis term, \(f\textbf{e}_z\wedge \bar{\textbf{u}}\)

Parameters:

• function_space – the FunctionSpace the solution belongs to

• test_function – custom TestFunction.

• trial_function – custom TrialFunction.

residual(uv, eta, uv_old, eta_old, fields, fields_old, bnd_conditions)

Returns an UFL form of the term.

Parameters:

• solution – solution Function of the corresponding equation

• solution_old – a time lagged solution Function

• fields – a dictionary that provides all the remaining fields that the term depends on. The keys of the dictionary should standard field names in field_metadata

• fields_old – Time lagged dictionary of fields

• bnd_conditions – A dictionary describing boundary conditions. E.g. {3: {‘elev_2d’: Constant(1.0)}} replaces elev_2d function by a constant on boundary ID 3.

class thetis.shallowwater_eq.ExternalPressureGradientTerm(u_test, u_space, eta_space, depth, options=None)

Bases: ShallowWaterMomentumTerm

External pressure gradient term, \(g \nabla \eta\)

The weak form reads

\[\int_\Omega g \nabla \eta \cdot \boldsymbol{\psi} dx = \int_\Gamma g \eta^* \text{jump}(\boldsymbol{\psi} \cdot \textbf{n}) dS - \int_\Omega g \eta \nabla \cdot \boldsymbol{\psi} dx\]

where the right hand side has been integrated by parts; \(\textbf{n}\) denotes the unit normal of the element interfaces, \(n^*\) is value at the interface obtained from an approximate Riemann solver.

If \(\eta\) belongs to a discontinuous function space, the form on the right hand side is used.

Parameters:

• function_space – the FunctionSpace the solution belongs to

• test_function – custom TestFunction.

• trial_function – custom TrialFunction.

residual(uv, eta, uv_old, eta_old, fields, fields_old, bnd_conditions)

Returns an UFL form of the term.

Parameters:

• solution – solution Function of the corresponding equation

• solution_old – a time lagged solution Function

• fields – a dictionary that provides all the remaining fields that the term depends on. The keys of the dictionary should standard field names in field_metadata

• fields_old – Time lagged dictionary of fields

• bnd_conditions – A dictionary describing boundary conditions. E.g. {3: {‘elev_2d’: Constant(1.0)}} replaces elev_2d function by a constant on boundary ID 3.

class thetis.shallowwater_eq.FreeSurfaceEquation(eta_test, eta_space, u_space, depth, options)

Bases: BaseShallowWaterEquation

2D free surface equation (7) in non-conservative form.

Parameters:

• eta_test – test function of the elevation function space

• eta_space – elevation function space

• u_space – velocity function space

• function_space – Mixed function space where the solution belongs

• depth –

  class:

  DepthExpression containing depth info

• options – AttrDict object containing all circulation model options

mass_term(solution)

Returns default mass matrix term for the solution function space.

Returns:

UFL form of the mass term

residual(label, solution, solution_old, fields, fields_old, bnd_conditions)

Returns an UFL form of the residual by summing up all the terms with the desired label.

Sign convention: all terms are assumed to be on the right hand side of the equation: d(u)/dt = term.

Parameters:

• label – string defining the type of terms to sum up. Currently one of ‘source’|’explicit’|’implicit’|’nonlinear’. Can be a list of multiple labels, or ‘all’ in which case all defined terms are summed.

• solution – solution Function of the corresponding equation

• solution_old – a time lagged solution Function

• fields – a dictionary that provides all the remaining fields that the term depends on. The keys of the dictionary should standard field names in field_metadata

• fields_old – Time lagged dictionary of fields

• bnd_conditions – A dictionary describing boundary conditions. E.g. {3: {‘elev_2d’: Constant(1.0)}} replaces elev_2d function by a constant on boundary ID 3.

class thetis.shallowwater_eq.HUDivTerm(eta_test, eta_space, u_space, depth, options=None)

Bases: ShallowWaterContinuityTerm

Divergence term, \(\nabla \cdot (H \bar{\textbf{u}})\)

The weak form reads

\[\int_\Omega \nabla \cdot (H \bar{\textbf{u}}) \phi dx = \int_\Gamma (H^* \bar{\textbf{u}}^*) \cdot \text{jump}(\phi \textbf{n}) dS - \int_\Omega H (\bar{\textbf{u}}\cdot\nabla \phi) dx\]

where the right hand side has been integrated by parts; \(\textbf{n}\) denotes the unit normal of the element interfaces, and \(\text{jump}\) and \(\text{avg}\) denote the jump and average operators across the interface. \(H^*, \bar{\textbf{u}}^*\) are values at the interface obtained from an approximate Riemann solver.

If \(\bar{\textbf{u}}\) belongs to a discontinuous function space, the form on the right hand side is used.

Parameters:

• function_space – the FunctionSpace the solution belongs to

• test_function – custom TestFunction.

• trial_function – custom TrialFunction.

residual(uv, eta, uv_old, eta_old, fields, fields_old, bnd_conditions)

Returns an UFL form of the term.

Parameters:

• solution – solution Function of the corresponding equation

• solution_old – a time lagged solution Function

• fields – a dictionary that provides all the remaining fields that the term depends on. The keys of the dictionary should standard field names in field_metadata

• fields_old – Time lagged dictionary of fields

• bnd_conditions – A dictionary describing boundary conditions. E.g. {3: {‘elev_2d’: Constant(1.0)}} replaces elev_2d function by a constant on boundary ID 3.

class thetis.shallowwater_eq.HorizontalAdvectionTerm(u_test, u_space, eta_space, depth, options=None)

Bases: ShallowWaterMomentumTerm

Advection of momentum term, \(\bar{\textbf{u}} \cdot \nabla\bar{\textbf{u}}\)

The weak form is

\[\int_\Omega \bar{\textbf{u}} \cdot \nabla\bar{\textbf{u}} \cdot \boldsymbol{\psi} dx = - \int_\Omega \nabla_h \cdot (\bar{\textbf{u}} \boldsymbol{\psi}) \cdot \bar{\textbf{u}} dx + \int_\Gamma \text{avg}(\bar{\textbf{u}}) \cdot \text{jump}(\boldsymbol{\psi} (\bar{\textbf{u}}\cdot\textbf{n})) dS\]

where the right hand side has been integrated by parts; \(\textbf{n}\) is the unit normal of the element interfaces, and \(\text{jump}\) and \(\text{avg}\) denote the jump and average operators across the interface.

Parameters:

• function_space – the FunctionSpace the solution belongs to

• test_function – custom TestFunction.

• trial_function – custom TrialFunction.

residual(uv, eta, uv_old, eta_old, fields, fields_old, bnd_conditions)

Returns an UFL form of the term.

Parameters:

• solution – solution Function of the corresponding equation

• solution_old – a time lagged solution Function

• fields – a dictionary that provides all the remaining fields that the term depends on. The keys of the dictionary should standard field names in field_metadata

• fields_old – Time lagged dictionary of fields

• bnd_conditions – A dictionary describing boundary conditions. E.g. {3: {‘elev_2d’: Constant(1.0)}} replaces elev_2d function by a constant on boundary ID 3.

class thetis.shallowwater_eq.HorizontalViscosityTerm(u_test, u_space, eta_space, depth, options=None)

Bases: ShallowWaterMomentumTerm

Viscosity of momentum term

If option ModelOptions.use_grad_div_viscosity_term is True, we use the symmetric viscous stress \(\boldsymbol{\tau}_\nu = \nu_h ( \nabla \bar{\textbf{u}} + (\nabla \bar{\textbf{u}})^T )\). Using the symmetric interior penalty method the weak form then reads

\[\begin{split}\int_\Omega -\nabla \cdot \boldsymbol{\tau}_\nu \cdot \boldsymbol{\psi} dx =& \int_\Omega (\nabla \boldsymbol{\psi}) : \boldsymbol{\tau}_\nu dx \\ &- \int_\Gamma \text{jump}(\boldsymbol{\psi} \textbf{n}) \cdot \text{avg}(\boldsymbol{\tau}_\nu) dS - \int_\Gamma \text{avg}(\nu_h)\big(\text{jump}(\bar{\textbf{u}} \textbf{n}) + \text{jump}(\bar{\textbf{u}} \textbf{n})^T\big) \cdot \text{avg}(\nabla \boldsymbol{\psi}) dS \\ &+ \int_\Gamma \sigma \text{avg}(\nu_h) \big(\text{jump}(\bar{\textbf{u}} \textbf{n}) + \text{jump}(\bar{\textbf{u}} \textbf{n})^T\big) \cdot \text{jump}(\boldsymbol{\psi} \textbf{n}) dS\end{split}\]

where \(\sigma\) is a penalty parameter, see Hillewaert (2013).

If option ModelOptions.use_grad_div_viscosity_term is False, we use viscous stress \(\boldsymbol{\tau}_\nu = \nu_h \nabla \bar{\textbf{u}}\). In this case the weak form is

\[\begin{split}\int_\Omega -\nabla \cdot \boldsymbol{\tau}_\nu \cdot \boldsymbol{\psi} dx =& \int_\Omega (\nabla \boldsymbol{\psi}) : \boldsymbol{\tau}_\nu dx \\ &- \int_\Gamma \text{jump}(\boldsymbol{\psi} \textbf{n}) \cdot \text{avg}(\boldsymbol{\tau}_\nu) dS - \int_\Gamma \text{avg}(\nu_h)\text{jump}(\bar{\textbf{u}} \textbf{n}) \cdot \text{avg}(\nabla \boldsymbol{\psi}) dS \\ &+ \int_\Gamma \sigma \text{avg}(\nu_h) \text{jump}(\bar{\textbf{u}} \textbf{n}) \cdot \text{jump}(\boldsymbol{\psi} \textbf{n}) dS\end{split}\]

If option ModelOptions.use_grad_depth_viscosity_term is True, we also include the term

\[\boldsymbol{\tau}_{\nabla H} = - \frac{\nu_h \nabla(H)}{H} \cdot ( \nabla \bar{\textbf{u}} + (\nabla \bar{\textbf{u}})^T )\]

as a source term.

Hillewaert, Koen (2013). Development of the discontinuous Galerkin method for high-resolution, large scale CFD and acoustics in industrial geometries. PhD Thesis. Université catholique de Louvain. https://dial.uclouvain.be/pr/boreal/object/boreal:128254/

Parameters:

• function_space – the FunctionSpace the solution belongs to

• test_function – custom TestFunction.

• trial_function – custom TrialFunction.

residual(uv, eta, uv_old, eta_old, fields, fields_old, bnd_conditions)

Returns an UFL form of the term.

Parameters:

• solution – solution Function of the corresponding equation

• solution_old – a time lagged solution Function

• fields – a dictionary that provides all the remaining fields that the term depends on. The keys of the dictionary should standard field names in field_metadata

• fields_old – Time lagged dictionary of fields

• bnd_conditions – A dictionary describing boundary conditions. E.g. {3: {‘elev_2d’: Constant(1.0)}} replaces elev_2d function by a constant on boundary ID 3.

class thetis.shallowwater_eq.LinearDragTerm(u_test, u_space, eta_space, depth, options=None)

Bases: ShallowWaterMomentumTerm

Linear friction term, \(C \bar{\textbf{u}}\)

Here \(C\) is a user-defined drag coefficient.

Parameters:

• function_space – the FunctionSpace the solution belongs to

• test_function – custom TestFunction.

• trial_function – custom TrialFunction.

residual(uv, eta, uv_old, eta_old, fields, fields_old, bnd_conditions)

Returns an UFL form of the term.

Parameters:

• solution – solution Function of the corresponding equation

• solution_old – a time lagged solution Function

• fields – a dictionary that provides all the remaining fields that the term depends on. The keys of the dictionary should standard field names in field_metadata

• fields_old – Time lagged dictionary of fields

• bnd_conditions – A dictionary describing boundary conditions. E.g. {3: {‘elev_2d’: Constant(1.0)}} replaces elev_2d function by a constant on boundary ID 3.

class thetis.shallowwater_eq.ModeSplit2DEquations(function_space, depth, options)

Bases: BaseShallowWaterEquation

2D depth-averaged shallow water equations for mode splitting schemes.

Defines the equations (11) - (12).

Parameters:

• function_space – Mixed function space where the solution belongs

• depth –

  class:

  DepthExpression containing depth info

• options – AttrDict object containing all circulation model options

add_momentum_terms(*args)

residual(label, solution, solution_old, fields, fields_old, bnd_conditions)

Returns an UFL form of the residual by summing up all the terms with the desired label.

Sign convention: all terms are assumed to be on the right hand side of the equation: d(u)/dt = term.

Parameters:

• label – string defining the type of terms to sum up. Currently one of ‘source’|’explicit’|’implicit’|’nonlinear’. Can be a list of multiple labels, or ‘all’ in which case all defined terms are summed.

• solution – solution Function of the corresponding equation

• solution_old – a time lagged solution Function

• fields – a dictionary that provides all the remaining fields that the term depends on. The keys of the dictionary should standard field names in field_metadata

• fields_old – Time lagged dictionary of fields

• bnd_conditions – A dictionary describing boundary conditions. E.g. {3: {‘elev_2d’: Constant(1.0)}} replaces elev_2d function by a constant on boundary ID 3.

class thetis.shallowwater_eq.MomentumSourceTerm(u_test, u_space, eta_space, depth, options=None)

Bases: ShallowWaterMomentumTerm

Generic source term in the shallow water momentum equation

The weak form reads

\[F_s = \int_\Omega \boldsymbol{\tau} \cdot \boldsymbol{\psi} dx\]

where \(\boldsymbol{\tau}\) is a user defined vector valued Function.

Parameters:

• function_space – the FunctionSpace the solution belongs to

• test_function – custom TestFunction.

• trial_function – custom TrialFunction.

residual(uv, eta, uv_old, eta_old, fields, fields_old, bnd_conditions)

Returns an UFL form of the term.

Parameters:

• solution – solution Function of the corresponding equation

• solution_old – a time lagged solution Function

• fields – a dictionary that provides all the remaining fields that the term depends on. The keys of the dictionary should standard field names in field_metadata

• fields_old – Time lagged dictionary of fields

• bnd_conditions – A dictionary describing boundary conditions. E.g. {3: {‘elev_2d’: Constant(1.0)}} replaces elev_2d function by a constant on boundary ID 3.

class thetis.shallowwater_eq.QuadraticDragTerm(u_test, u_space, eta_space, depth, options=None)

Bases: ShallowWaterMomentumTerm

Quadratic Manning bottom friction term \(C_D \| \bar{\textbf{u}} \| \bar{\textbf{u}}\)

where the drag coefficient is computed with the Manning formula

\[C_D = g \frac{\mu^2}{H^{1/3}}\]

if the Manning coefficient \(\mu\) is defined (see field manning_drag_coefficient). Otherwise \(C_D\) is taken as a constant (see field quadratic_drag_coefficient).

Parameters:

• function_space – the FunctionSpace the solution belongs to

• test_function – custom TestFunction.

• trial_function – custom TrialFunction.

residual(uv, eta, uv_old, eta_old, fields, fields_old, bnd_conditions)

Returns an UFL form of the term.

Parameters:

• solution – solution Function of the corresponding equation

• solution_old – a time lagged solution Function

• fields – a dictionary that provides all the remaining fields that the term depends on. The keys of the dictionary should standard field names in field_metadata

• fields_old – Time lagged dictionary of fields

• bnd_conditions – A dictionary describing boundary conditions. E.g. {3: {‘elev_2d’: Constant(1.0)}} replaces elev_2d function by a constant on boundary ID 3.

class thetis.shallowwater_eq.ShallowWaterContinuityTerm(eta_test, eta_space, u_space, depth, options=None)

Bases: ShallowWaterTerm

Generic term in the depth-integrated continuity equation that provides commonly used members and mapping for boundary functions.

Parameters:

• function_space – the FunctionSpace the solution belongs to

• test_function – custom TestFunction.

• trial_function – custom TrialFunction.

class thetis.shallowwater_eq.ShallowWaterEquations(function_space, depth, options, tidal_farms=None)

Bases: BaseShallowWaterEquation

2D depth-averaged shallow water equations in non-conservative form.

This defines the full 2D SWE equations (7) - (8).

Parameters:

• function_space – Mixed function space where the solution belongs

• depth –

  class:

  DepthExpression containing depth info

• options – AttrDict object containing all circulation model options

mass_term(solution)

Returns default mass matrix term for the solution function space.

Returns:

UFL form of the mass term

residual(label, solution, solution_old, fields, fields_old, bnd_conditions)

Returns an UFL form of the residual by summing up all the terms with the desired label.

Sign convention: all terms are assumed to be on the right hand side of the equation: d(u)/dt = term.

Parameters:

• label – string defining the type of terms to sum up. Currently one of ‘source’|’explicit’|’implicit’|’nonlinear’. Can be a list of multiple labels, or ‘all’ in which case all defined terms are summed.

• solution – solution Function of the corresponding equation

• solution_old – a time lagged solution Function

• fields – a dictionary that provides all the remaining fields that the term depends on. The keys of the dictionary should standard field names in field_metadata

• fields_old – Time lagged dictionary of fields

• bnd_conditions – A dictionary describing boundary conditions. E.g. {3: {‘elev_2d’: Constant(1.0)}} replaces elev_2d function by a constant on boundary ID 3.

class thetis.shallowwater_eq.ShallowWaterMomentumEquation(u_test, u_space, eta_space, depth, options, tidal_farms=None)

Bases: BaseShallowWaterEquation

2D depth averaged momentum equation (8) in non-conservative form.

Parameters:

• u_test – test function of the velocity function space

• u_space – velocity function space

• eta_space – elevation function space

• depth –

  class:

  DepthExpression containing depth info

• options – AttrDict object containing all circulation model options

residual(label, solution, solution_old, fields, fields_old, bnd_conditions)

Returns an UFL form of the residual by summing up all the terms with the desired label.

Sign convention: all terms are assumed to be on the right hand side of the equation: d(u)/dt = term.

Parameters:

• label – string defining the type of terms to sum up. Currently one of ‘source’|’explicit’|’implicit’|’nonlinear’. Can be a list of multiple labels, or ‘all’ in which case all defined terms are summed.

• solution – solution Function of the corresponding equation

• solution_old – a time lagged solution Function

• fields – a dictionary that provides all the remaining fields that the term depends on. The keys of the dictionary should standard field names in field_metadata

• fields_old – Time lagged dictionary of fields

• bnd_conditions – A dictionary describing boundary conditions. E.g. {3: {‘elev_2d’: Constant(1.0)}} replaces elev_2d function by a constant on boundary ID 3.

class thetis.shallowwater_eq.ShallowWaterMomentumTerm(u_test, u_space, eta_space, depth, options=None)

Bases: ShallowWaterTerm

Generic term in the shallow water momentum equation that provides commonly used members and mapping for boundary functions.

Parameters:

• function_space – the FunctionSpace the solution belongs to

• test_function – custom TestFunction.

• trial_function – custom TrialFunction.

class thetis.shallowwater_eq.ShallowWaterTerm(space, depth, options=None)

Bases: Term

Generic term in the shallow water equations that provides commonly used members and mapping for boundary functions.

Parameters:

• function_space – the FunctionSpace the solution belongs to

• test_function – custom TestFunction.

• trial_function – custom TrialFunction.

get_bnd_functions(eta_in, uv_in, bnd_id, bnd_conditions)

Returns external values of elev and uv for all supported boundary conditions.

Volume flux (flux) and normal velocity (un) are defined positive out of the domain.

impose_dynamic_bnd(bnd_funcs, bnd_id)

Check if the prognostic variables have been specified on the boundary.

If any prognostic value has been specified, dynamic boundary terms will be evaluated. If not, a closed boundary is assumed (which implies e.g. that volume flux boundary terms are omitted).

Parameters:

• bnd_funcs – None or dictionary of boundary coefficients.

• bnd_id – Boundary marker id

Returns:

True if elev or uv is defined, otherwise False.

class thetis.shallowwater_eq.WindStressTerm(u_test, u_space, eta_space, depth, options=None)

Bases: ShallowWaterMomentumTerm

Wind stress term, \(-\tau_w/(H \rho_0)\)

Here \(\tau_w\) is a user-defined wind stress Function.

Parameters:

• function_space – the FunctionSpace the solution belongs to

• test_function – custom TestFunction.

• trial_function – custom TrialFunction.

residual(uv, eta, uv_old, eta_old, fields, fields_old, bnd_conditions)

Returns an UFL form of the term.

Parameters:

• solution – solution Function of the corresponding equation

• solution_old – a time lagged solution Function

• fields – a dictionary that provides all the remaining fields that the term depends on. The keys of the dictionary should standard field names in field_metadata

• fields_old – Time lagged dictionary of fields

• bnd_conditions – A dictionary describing boundary conditions. E.g. {3: {‘elev_2d’: Constant(1.0)}} replaces elev_2d function by a constant on boundary ID 3.

thetis.solver module

Module for three dimensional baroclinic solver

class thetis.solver.FlowSolver(mesh2d, bathymetry_2d, n_layers, options=None, extrude_options=None, keep_log=False)

Bases: FrozenClass

Main object for 3D solver

Example

Create 2D mesh

from thetis import *
mesh2d = RectangleMesh(20, 20, 10e3, 10e3)

Create bathymetry function, set a constant value

fs_p1 = FunctionSpace(mesh2d, 'CG', 1)
bathymetry_2d = Function(fs_p1, name='Bathymetry').assign(10.0)

Create a 3D model with 6 uniform levels, and set some options (see ModelOptions3d)

solver_obj = solver.FlowSolver(mesh2d, bathymetry_2d, n_layers=6)
options = solver_obj.options
options.element_family = 'dg-dg'
options.polynomial_degree = 1
options.timestepper_type = 'SSPRK22'
options.timestepper_options.use_automatic_timestep = False
options.solve_salinity = False
options.solve_temperature = False
options.simulation_export_time = 50.0
options.simulation_end_time = 3600.
options.timestep = 25.0

Assign initial condition for water elevation

solver_obj.create_function_spaces()
init_elev = Function(solver_obj.function_spaces.H_2d)
coords = SpatialCoordinate(mesh2d)
init_elev.project(2.0*exp(-((coords[0] - 4e3)**2 + (coords[1] - 4.5e3)**2)/2.2e3**2))
solver_obj.assign_initial_conditions(elev=init_elev)

Run simulation

solver_obj.iterate()

See the manual for more complex examples.

Parameters:

• mesh2d – Mesh object of the 2D mesh

• bathymetry_2d (2D Function) – Bathymetry of the domain. Bathymetry stands for the mean water depth (positive downwards).

• n_layers (int) – Number of layers in the vertical direction. Elements are distributed uniformly over the vertical.

• options (ModelOptions3d instance) – Model options (optional). Model options can also be changed directly via the options class property.

• keep_log (bool) – append to an existing log file, or overwrite it?

M_modesplit

Mode split ratio (int)

add_callback(callback, eval_interval='export')

Adds callback to solver object

Parameters:

• callback – DiagnosticCallback instance

• eval_interval (str) – Determines when callback will be evaluated, either ‘export’ or ‘timestep’ for evaluating after each export or time step.

add_new_field(function, label, name, filename, shortname=None, unit='-', preproc_func=None)

Add a field to fields.

Parameters:

• function – representation of the field as a Function

• label – field label used internally by Thetis, e.g. ‘tracer_3d’

• name – human readable name for the tracer field, e.g. ‘Tracer concentration’

• filename – file name for outputs, e.g. ‘Tracer3d’

• shortname – short version of name, e.g. ‘Tracer’

• unit – units for field, e.g. ‘-’

• preproc_func – optional pre-processor function which will be called before exporting

assign_initial_conditions(elev=None, salt=None, temp=None, uv_2d=None, uv_3d=None, tke=None, psi=None)

Assigns initial conditions

Parameters:

• elev (scalar 2D Function, Constant, or an expression) – Initial condition for water elevation

• salt (scalar 3D Function, Constant, or an expression) – Initial condition for salinity field

• temp (scalar 3D Function, Constant, or an expression) – Initial condition for temperature field

• uv_2d (vector valued 2D Function, Constant, or an expression) – Initial condition for depth averaged velocity

• uv_3d (vector valued 3D Function, Constant, or an expression) – Initial condition for horizontal velocity

• tke (scalar 3D Function, Constant, or an expression) – Initial condition for turbulent kinetic energy field

• psi (scalar 3D Function, Constant, or an expression) – Initial condition for turbulence generic length scale field

callbacks

CallbackManager object that stores all callbacks

compute_dt_2d(u_scale)

Computes maximum explicit time step from CFL condition.

\[\Delta t = \frac{\Delta x}{U}\]

Assumes velocity scale \(U = \sqrt{g H} + U_{scale}\) where \(U_{scale}\) is estimated advective velocity.

Parameters:

u_scale (float or Constant) – User provided maximum advective velocity scale

compute_dt_diffusion(nu_scale)

Computes maximum explicit time step for horizontal diffusion.

\[\Delta t = \alpha \frac{(\Delta x)^2}{\nu_{scale}}\]

where \(\nu_{scale}\) is estimated diffusivity scale.

compute_dt_h_advection(u_scale)

Computes maximum explicit time step for horizontal advection

\[\Delta t = \frac{\Delta x}{U_{scale}}\]

where \(U_{scale}\) is estimated horizontal advective velocity.

Parameters:

u_scale (float or Constant) – User provided maximum horizontal velocity scale

compute_dt_v_advection(w_scale)

Computes maximum explicit time step for vertical advection

\[\Delta t = \frac{\Delta z}{W_{scale}}\]

where \(W_{scale}\) is estimated vertical advective velocity.

Parameters:

w_scale (float or Constant) – User provided maximum vertical velocity scale

compute_dx_factor()

Computes normalized distance between nodes in the horizontal direction

The factor depends on the finite element space and its polynomial degree. It is used to compute maximal stable time steps.

compute_dz_factor()

Computes a normalized distance between nodes in the vertical direction

The factor depends on the finite element space and its polynomial degree. It is used to compute maximal stable time steps.

compute_mesh_stats()

Computes number of elements, nodes etc and prints to sdtout

create_equations()

Creates equation instances

create_exporters()

Creates file exporters

create_fields()

Creates all fields

create_function_spaces()

Creates function spaces

Function spaces are accessible via function_spaces object.

create_timestepper()

Creates time stepper instance

dt

Time step

dt_2d

Time of the 2D solver

export()

Export all fields to disk

Also evaluates all callbacks set to ‘export’ interval.

export_initial_state

Do export initial state. False if continuing a simulation

fields

FieldDict that holds all functions needed by the solver object

function_spaces

AttrDict that holds all function spaces needed by the solver object

initialize()

Creates function spaces, equations, time stepper and exporters

iterate(update_forcings=None, update_forcings3d=None, export_func=None)

Runs the simulation

Iterates over the time loop until time options.simulation_end_time is reached. Exports fields to disk on options.simulation_export_time intervals.

Parameters:

• update_forcings – User-defined function that takes simulation time as an argument and updates time-dependent boundary conditions of the 2D system (if any).

• update_forcings_3d – User-defined function that takes simulation time as an argument and updates time-dependent boundary conditions of the 3D equations (if any).

• export_func – User-defined function (with no arguments) that will be called on every export.

load_state(i_stored, outputdir=None, t=None, iteration=None, i_export=None, legacy_mode=False)

Loads simulation state from hdf5 outputs.

Replaces assign_initial_conditions() in model initialization.

For example, continue simulation from export 40,

solver_obj.load_state(40)

Continue simulation from another output directory,

solver_obj.load_state(40, outputdir='outputs_spinup')

Continue simulation from another output directory and reset the counters,

solver_obj.load_state(40, outputdir='outputs_spinup',
    iteration=0, t=0, i_export=0)

Model state can be loaded if all prognostic state variables have been stored in hdf5 format. Required state variables are: elev_2d, uv_2d, uv_3d, salt_3d, temp_3d, tke_3d, and psi_3d.

Simulation time and iteration can be recovered automatically provided that the model setup is the same (e.g. time step and export_time).

Parameters:

• i_stored (int) – export index to load

• outputdir (string) – (optional) directory where files are read from. By default options.output_directory.

• t (float) – simulation time. Overrides the time stamp inferred from model options.

• iteration (int) – Overrides the iteration count inferred from model options.

• i_export (int) – Set initial export index for the present run. By default, i_stored is used.

• legacy_mode (bool) – Load legacy DumbCheckpoint files.

mesh

3D :class`Mesh`

mesh2d

2D :class`Mesh`

options

Dictionary of all options. A ModelOptions3d object.

print_state(cputime, print_header=False)

Print a summary of the model state on stdout

Parameters:

• cputime (float) – Measured CPU time in seconds

• print_header – Whether to print column header first

print_state_debug()

Print min/max values of prognostic/diagnostic fields for debugging.

set_time_step()

Sets the model the model time step

If the time integrator supports automatic time step, and ModelOptions3d.timestepper_options.use_automatic_timestep is True, we compute the maximum time step allowed by the CFL condition. Otherwise uses ModelOptions3d.timestep.

Once the time step is determined, will adjust it to be an integer fraction of export interval options.simulation_export_time.

thetis.solver.timed_stage()

Log.Stage(cls, name) Source code at petsc4py/PETSc/Log.pyx:11

thetis.solver2d module

Module for 2D depth averaged solver

class thetis.solver2d.FlowSolver2d(mesh2d, bathymetry_2d, options=None, keep_log=False)

Bases: FrozenClass

Main object for 2D depth averaged solver

Example

Create mesh

from thetis import *
mesh2d = RectangleMesh(20, 20, 10e3, 10e3)

Create bathymetry function, set a constant value

fs_p1 = FunctionSpace(mesh2d, 'CG', 1)
bathymetry_2d = Function(fs_p1, name='Bathymetry').assign(10.0)

Create solver object and set some options

solver_obj = solver2d.FlowSolver2d(mesh2d, bathymetry_2d)
options = solver_obj.options
options.element_family = 'dg-dg'
options.polynomial_degree = 1
options.swe_timestepper_type = 'CrankNicolson'
options.simulation_export_time = 50.0
options.simulation_end_time = 3600.
options.timestep = 25.0

Assign initial condition for water elevation

solver_obj.create_function_spaces()
init_elev = Function(solver_obj.function_spaces.H_2d)
coords = SpatialCoordinate(mesh2d)
init_elev.project(exp(-((coords[0] - 4e3)**2 + (coords[1] - 4.5e3)**2)/2.2e3**2))
solver_obj.assign_initial_conditions(elev=init_elev)

Run simulation

solver_obj.iterate()

See the manual for more complex examples.

Parameters:

• mesh2d – Mesh object of the 2D mesh

• bathymetry_2d (Function) – Bathymetry of the domain. Bathymetry stands for the mean water depth (positive downwards).

• options (ModelOptions2d instance) – Model options (optional). Model options can also be changed directly via the options class property.

• keep_log (bool) – append to an existing log file, or overwrite it?

add_callback(callback, eval_interval='export')

Adds callback to solver object

Parameters:

• callback – DiagnosticCallback instance

• eval_interval (string) – Determines when callback will be evaluated, either ‘export’ or ‘timestep’ for evaluating after each export or time step.

add_new_field(function, label, name, filename, shortname=None, unit='-', preproc_func=None)

Add a field to fields.

Parameters:

• function – representation of the field as a Function

• label – field label used internally by Thetis, e.g. ‘tracer_2d’

• name – human readable name for the tracer field, e.g. ‘Tracer concentration’

• filename – file name for outputs, e.g. ‘Tracer2d’

• shortname – short version of name, e.g. ‘Tracer’

• unit – units for field, e.g. ‘-’

• preproc_func – optional pre-processor function which will be called before exporting

assign_initial_conditions(elev=None, uv=None, sediment=None, **tracers)

Assigns initial conditions

Parameters:

• elev (scalar Function, Constant, or an expression) – Initial condition for water elevation

• uv (vector valued Function, Constant, or an expression) – Initial condition for depth averaged velocity

• sediment (scalar valued Function, Constant, or an expression) – Initial condition for sediment concantration

• tracers (scalar valued Functions, Constants, or an expressions) – Initial conditions for tracer fields

callbacks

CallbackManager object that stores all callbacks

compute_mesh_stats()

Computes number of elements, nodes etc and prints to sdtout

compute_time_step(u_scale=Constant([0.], 43))

Computes maximum explicit time step from CFL condition.

\[\Delta t = \frac{\Delta x}{U}\]

Assumes velocity scale \(U = \sqrt{g H} + U_{scale}\) where \(U_{scale}\) is estimated advective velocity.

Parameters:

u_scale (float or Constant) – User provided maximum advective velocity scale

create_equations()

Creates equation instances

create_exporters()

Creates file exporters

create_fields()

Creates field Functions

create_function_spaces()

Creates function spaces

Function spaces are accessible via function_spaces object.

create_timestepper()

Creates time stepper instance

dt

Time step

export()

Export all fields to disk

Also evaluates all callbacks set to ‘export’ interval.

export_initial_state

Do export initial state. False if continuing a simulation

fields

FieldDict that holds all functions needed by the solver object

function_spaces

AttrDict that holds all function spaces needed by the solver object

get_exner_timestepper(integrator)

Gets exner timestepper object with appropriate parameters

get_fs_timestepper(integrator)

Gets free-surface correction timestepper object with appropriate parameters

get_sediment_timestepper(integrator)

Gets sediment timestepper object with appropriate parameters

get_swe_timestepper(integrator)

Gets shallow water timestepper object with appropriate parameters

get_tracer_timestepper(integrator, system)

Gets tracer timestepper object with appropriate parameters

initialize()

Creates function spaces, equations, time stepper and exporters

iterate(update_forcings=None, export_func=None)

Runs the simulation

Iterates over the time loop until time options.simulation_end_time is reached. Exports fields to disk on options.simulation_export_time intervals.

Parameters:

• update_forcings – User-defined function that takes simulation time as an argument and updates time-dependent boundary conditions (if any).

• export_func – User-defined function (with no arguments) that will be called on every export.

load_state(i_stored, outputdir=None, t=None, iteration=None, i_export=None, legacy_mode=False)

Loads simulation state from hdf5 outputs.

Replaces assign_initial_conditions() in model initialization.

For example, continue simulation from export 40,

solver_obj.load_state(40)

Continue simulation from another output directory,

solver_obj.load_state(40, outputdir='outputs_spinup')

Continue simulation from another output directory and reset the counters,

solver_obj.load_state(40, outputdir='outputs_spinup',
    iteration=0, t=0, i_export=0)

Model state can be loaded if all prognostic state variables have been stored in hdf5 format. For the hydrodynamics the required state variables are: elev_2d, and uv_2d.

Simulation time and iteration can be recovered automatically provided that the model setup is the same (e.g. time step and export_time).

Parameters:

• i_stored (int) – export index to load

• outputdir (string) – (optional) directory where files are read from. By default options.output_directory.

• t (float) – simulation time. Overrides the time stamp inferred from model options.

• iteration (int) – Overrides the iteration count inferred from model options.

• i_export (int) – Set initial export index for the present run. By default, i_stored is used.

• legacy_mode (bool) – Load legacy DumbCheckpoint files.

options

Dictionary of all options. A ModelOptions2d object.

print_state(cputime, print_header=False)

Print a summary of the model state on stdout

Parameters:

• cputime (float) – Measured CPU time in seconds

• print_header – Whether to print column header first

sediment_model

set up option for sediment model

set_time_step(alpha=0.05)

Sets the model the model time step

If the time integrator supports automatic time step, and ModelOptions2d.timestepper_options.use_automatic_timestep is True, we compute the maximum time step allowed by the CFL condition. Otherwise uses ModelOptions2d.timestep.

Parameters:

alpha (float) – CFL number scaling factor

set_wetting_and_drying_alpha()

Compute a wetting and drying parameter \(\alpha\) which ensures positive water depth using the approximate method suggested by Karna et al. (2011).

This method takes

..math::

alpha approx mid L_x nabla h mid,

where \(L_x\) is the horizontal length scale of the mesh elements at the wet-dry front and \(h\) is the bathymetry profile.

This expression is interpolated into \(\mathbb P1\) space in order to remove noise. Note that we use the interpolate method, rather than the project method, in order to avoid introducing new extrema.

NOTE: The minimum and maximum values at which to cap the alpha parameter may be specified via ModelOptions2d.wetting_and_drying_alpha_min and ModelOptions2d.wetting_and_drying_alpha_max.

thetis.solver2d.timed_stage()

Log.Stage(cls, name) Source code at petsc4py/PETSc/Log.pyx:11

thetis.stability_functions module

Implements turbulence closure model stability functions.

\[\begin{split}S_m &= S_m(\alpha_M, \alpha_N) \\ S_\rho &= S_\rho(\alpha_M, \alpha_N)\end{split}\]

where \(\alpha_M, \alpha_N\) are the normalized shear and buoyancy frequency

\[\begin{split}\alpha_M &= \frac{k^2}{\varepsilon^2} M^2 \\ \alpha_N &= \frac{k^2}{\varepsilon^2} N^2\end{split}\]

The following stability functions have been implemented

• Canuto A

• Canuto B

• Kantha-Clayson

• Cheng

References:

Umlauf, L. and Burchard, H. (2005). Second-order turbulence closure models for geophysical boundary layers. A review of recent work. Continental Shelf Research, 25(7-8):795–827. http://dx.doi.org/10.1016/j.csr.2004.08.004

Burchard, H. and Bolding, K. (2001). Comparative Analysis of Four Second-Moment Turbulence Closure Models for the Oceanic Mixed Layer. Journal of Physical Oceanography, 31(8):1943–1968. http://dx.doi.org/10.1175/1520-0485(2001)031

Umlauf, L. and Burchard, H. (2003). A generic length-scale equation for geophysical turbulence models. Journal of Marine Research, 61:235–265(31). http://dx.doi.org/10.1357/002224003322005087

class thetis.stability_functions.GOTMStabilityFunctionCanutoA(lim_alpha_shear=True, lim_alpha_buoy=True, smooth_alpha_buoy_lim=True, alpha_buoy_crit=-1.2)

Bases: GOTMStabilityFunctionBase

Canuto et al. (2001) version A stability functions

Parameters are from Umlauf and Buchard (2005), Table 1

Parameters:

• lim_alpha_shear (bool) – limit maximum \(\alpha_M\) values (see Umlauf and Burchard (2005) eq. 44)

• lim_alpha_buoy (bool) – limit minimum (negative) \(\alpha_N\) values (see Umlauf and Burchard (2005))

• smooth_alpha_buoy_lim (bool) – if \(\alpha_N\) is limited, apply a smooth limiter (see Burchard and Bolding (2001) eq. 19). Otherwise \(\alpha_N\) is clipped at minimum value.

• alpha_buoy_crit (float) – parameter for \(\alpha_N\) smooth limiter

cb1 = 5.95

cb2 = 0.6

cb3 = 1.0

cb4 = 0.0

cb5 = 0.3333

cbb = 0.72

cc1 = 5.0

cc2 = 0.8

cc3 = 1.968

cc4 = 1.136

cc5 = 0.0

cc6 = 0.4

name = 'Canuto A'

class thetis.stability_functions.GOTMStabilityFunctionCanutoB(lim_alpha_shear=True, lim_alpha_buoy=True, smooth_alpha_buoy_lim=True, alpha_buoy_crit=-1.2)

Bases: GOTMStabilityFunctionBase

Canuto et al. (2001) version B stability functions

Parameters are from Umlauf and Buchard (2005), Table 1

Parameters:

• lim_alpha_shear (bool) – limit maximum \(\alpha_M\) values (see Umlauf and Burchard (2005) eq. 44)

• lim_alpha_buoy (bool) – limit minimum (negative) \(\alpha_N\) values (see Umlauf and Burchard (2005))

• smooth_alpha_buoy_lim (bool) – if \(\alpha_N\) is limited, apply a smooth limiter (see Burchard and Bolding (2001) eq. 19). Otherwise \(\alpha_N\) is clipped at minimum value.

• alpha_buoy_crit (float) – parameter for \(\alpha_N\) smooth limiter

cb1 = 5.6

cb2 = 0.6

cb3 = 1.0

cb4 = 0.0

cb5 = 0.3333

cbb = 0.477

cc1 = 5.0

cc2 = 0.6983

cc3 = 1.9664

cc4 = 1.094

cc5 = 0.0

cc6 = 0.495

name = 'Canuto B'

class thetis.stability_functions.GOTMStabilityFunctionCheng(lim_alpha_shear=True, lim_alpha_buoy=True, smooth_alpha_buoy_lim=True, alpha_buoy_crit=-1.2)

Bases: GOTMStabilityFunctionBase

Cheng et al. (2002) quasi-equilibrium stability functions

Parameters are from Umlauf and Buchard (2005), Table 1

Parameters:

• lim_alpha_shear (bool) – limit maximum \(\alpha_M\) values (see Umlauf and Burchard (2005) eq. 44)

• lim_alpha_buoy (bool) – limit minimum (negative) \(\alpha_N\) values (see Umlauf and Burchard (2005))

• smooth_alpha_buoy_lim (bool) – if \(\alpha_N\) is limited, apply a smooth limiter (see Burchard and Bolding (2001) eq. 19). Otherwise \(\alpha_N\) is clipped at minimum value.

• alpha_buoy_crit (float) – parameter for \(\alpha_N\) smooth limiter

cb1 = 5.52

cb2 = 0.2134

cb3 = 0.357

cb4 = 0.0

cb5 = 0.3333

cbb = 0.82

cc1 = 5.0

cc2 = 0.7983

cc3 = 1.968

cc4 = 1.136

cc5 = 0.0

cc6 = 0.5

name = 'Cheng'

class thetis.stability_functions.GOTMStabilityFunctionKanthaClayson(lim_alpha_shear=True, lim_alpha_buoy=True, smooth_alpha_buoy_lim=True, alpha_buoy_crit=-1.2)

Bases: GOTMStabilityFunctionBase

Kantha and Clayson (1994) quasi-equilibrium stability functions

Parameters are from Umlauf and Buchard (2005), Table 1

Parameters:

• lim_alpha_shear (bool) – limit maximum \(\alpha_M\) values (see Umlauf and Burchard (2005) eq. 44)

• lim_alpha_buoy (bool) – limit minimum (negative) \(\alpha_N\) values (see Umlauf and Burchard (2005))

• smooth_alpha_buoy_lim (bool) – if \(\alpha_N\) is limited, apply a smooth limiter (see Burchard and Bolding (2001) eq. 19). Otherwise \(\alpha_N\) is clipped at minimum value.

• alpha_buoy_crit (float) – parameter for \(\alpha_N\) smooth limiter

cb1 = 3.728

cb2 = 0.7

cb3 = 0.7

cb4 = 0.0

cb5 = 0.2

cbb = 0.6102

cc1 = 6.0

cc2 = 0.32

cc3 = 0.0

cc4 = 0.0

cc5 = 0.0

cc6 = 0.0

name = 'Kantha Clayson'

class thetis.stability_functions.StabilityFunctionBase(lim_alpha_shear=True, lim_alpha_buoy=True, smooth_alpha_buoy_lim=True, alpha_buoy_crit=-1.2)

Bases: ABC

Base class for all stability functions

Parameters:

• lim_alpha_shear (bool) – limit maximum \(\alpha_M\) values (see Umlauf and Burchard (2005) eq. 44)

• lim_alpha_buoy (bool) – limit minimum (negative) \(\alpha_N\) values (see Umlauf and Burchard (2005))

• smooth_alpha_buoy_lim (bool) – if \(\alpha_N\) is limited, apply a smooth limiter (see Burchard and Bolding (2001) eq. 19). Otherwise \(\alpha_N\) is clipped at minimum value.

• alpha_buoy_crit (float) – parameter for \(\alpha_N\) smooth limiter

compute_alpha_shear_steady(ri_st, analytical=True)

Compute the steady-state \(\alpha_M\).

Under steady-state conditions, the stability functions satisfy:

\[S_m \alpha_M - S_\rho \alpha_M Ri_{st} = 1.0\]

(Umlauf and Buchard, 2005, eq A.15) from which \(\alpha_M\) can be solved for given gradient Richardson number \(Ri_{st}\).

Parameters:

• ri_st (float) – Gradient Richardson number

• analytical (bool) – If True (default), solve analytically using the coefficients of the stability function. Otherwise, solve \(\alpha_M\) numerically from the equilibrium condition.

compute_c3_minus(c1, c2, ri_st)

Compute c3_minus parameter from c1 and c2 parameters.

c3_minus is solved from equation

\[Ri_{st} = \frac{s_m}{s_h} \frac{c2 - c1}{c2 - c3_{-}}\]

where \(Ri_{st}\) is the steady state gradient Richardson number. (see Burchard and Bolding, 2001, eq 32)

compute_cmu0(analytical=True)

Compute parameter \(c_\mu^0\)

See: Umlauf and Buchard (2005) eq A.22

Parameters:

analytical (bool) – If True (default), solve analytically using the coefficients of the stability function. Otherwise, solve \(\alpha_M\) numerically from the equilibrium condition.

compute_kappa(sigma_psi, cmu0, n, c1, c2)

Computes von Karman constant from the Psi Schmidt number.

See: Umlauf and Burchard (2003) eq (14)

Parameters:

• sigma_psi – Psi Schmidt number

• c2 (cmu0, n, c1,) – GLS model parameters

compute_length_clim(cmu0, ri_st)

Computes the Galpering length scale limit.

Parameters:

• cmu0 – parameter \(c_\mu^0\)

• ri_st – gradient Richardson number

compute_sigma_psi(kappa, cmu0, n, c1, c2)

Computes the Psi Schmidt number from von Karman constant.

See: Umlauf and Burchard (2003) eq (14)

Parameters:

• kappa – von Karman constant

• c2 (cmu0, n, c1,) – GLS model parameters

eval_funcs(alpha_buoy, alpha_shear)

Evaluate (unlimited) stability functions

See: Burchard and Petersen (1999) eqns (30) and (31)

Parameters:

• alpha_buoy – normalized buoyancy frequency \(\alpha_N\)

• alpha_shear – normalized shear frequency \(\alpha_M\)

Returns:

\(S_m\), \(S_\rho\)

evaluate(shear2, buoy2, k, eps)

Evaluate stability functions from dimensional variables.

Applies limiters on \(\alpha_N\) and \(\alpha_M\).

Parameters:

• shear2 – shear frequency squared, \(M^2\)

• buoy2 – buoyancy frequency squared,:math:N^2

• k – turbulent kinetic energy, \(k\)

• eps – TKE dissipation rate, \(\varepsilon\)

get_alpha_buoy_min()

Compute minimum normalized buoyancy frequency \(\alpha_N\)

See: Umlauf and Buchard (2005), Table 3

get_alpha_buoy_smooth_min(alpha_buoy)

Compute smoothed minimum for normalized buoyancy frequency

See: Burchard and Petersen (1999), eq (19)

Parameters:

alpha_buoy – normalized buoyancy frequency \(\alpha_N\)

get_alpha_shear_max(alpha_buoy, alpha_shear)

Compute maximum normalized shear frequency \(\alpha_M\)

from Umlauf and Buchard (2005) eq (44)

Parameters:

• alpha_buoy – normalized buoyancy frequency \(\alpha_N\)

• alpha_shear – normalized shear frequency \(\alpha_M\)

abstract property name

class thetis.stability_functions.StabilityFunctionCanutoA(lim_alpha_shear=True, lim_alpha_buoy=True, smooth_alpha_buoy_lim=True, alpha_buoy_crit=-1.2)

Bases: CanutoStabilityFunctionBase

Canuto A stability function as defined in the Canuto (2001) paper.

Parameters:

• lim_alpha_shear (bool) – limit maximum \(\alpha_M\) values (see Umlauf and Burchard (2005) eq. 44)

• lim_alpha_buoy (bool) – limit minimum (negative) \(\alpha_N\) values (see Umlauf and Burchard (2005))

• smooth_alpha_buoy_lim (bool) – if \(\alpha_N\) is limited, apply a smooth limiter (see Burchard and Bolding (2001) eq. 19). Otherwise \(\alpha_N\) is clipped at minimum value.

• alpha_buoy_crit (float) – parameter for \(\alpha_N\) smooth limiter

l1 = 0.107

l2 = 0.0032

l3 = 0.0864

l4 = 0.12

l5 = 11.9

l6 = 0.4

l7 = 0

l8 = 0.48

name = 'Canuto A'

class thetis.stability_functions.StabilityFunctionCanutoB(lim_alpha_shear=True, lim_alpha_buoy=True, smooth_alpha_buoy_lim=True, alpha_buoy_crit=-1.2)

Bases: CanutoStabilityFunctionBase

Canuto B stability function as defined in the Canuto (2001) paper.

Parameters:

• lim_alpha_shear (bool) – limit maximum \(\alpha_M\) values (see Umlauf and Burchard (2005) eq. 44)

• lim_alpha_buoy (bool) – limit minimum (negative) \(\alpha_N\) values (see Umlauf and Burchard (2005))

• smooth_alpha_buoy_lim (bool) – if \(\alpha_N\) is limited, apply a smooth limiter (see Burchard and Bolding (2001) eq. 19). Otherwise \(\alpha_N\) is clipped at minimum value.

• alpha_buoy_crit (float) – parameter for \(\alpha_N\) smooth limiter

l1 = 0.127

l2 = 0.00336

l3 = 0.0906

l4 = 0.101

l5 = 11.2

l6 = 0.4

l7 = 0

l8 = 0.318

name = 'Canuto B'

class thetis.stability_functions.StabilityFunctionCheng(lim_alpha_shear=True, lim_alpha_buoy=True, smooth_alpha_buoy_lim=True, alpha_buoy_crit=-1.2)

Bases: ChengStabilityFunctionBase

Cheng stability function as defined in the Cheng et al (2002) paper.

Parameters:

• lim_alpha_shear (bool) – limit maximum \(\alpha_M\) values (see Umlauf and Burchard (2005) eq. 44)

• lim_alpha_buoy (bool) – limit minimum (negative) \(\alpha_N\) values (see Umlauf and Burchard (2005))

• smooth_alpha_buoy_lim (bool) – if \(\alpha_N\) is limited, apply a smooth limiter (see Burchard and Bolding (2001) eq. 19). Otherwise \(\alpha_N\) is clipped at minimum value.

• alpha_buoy_crit (float) – parameter for \(\alpha_N\) smooth limiter

l1 = 0.107

l2 = 0.0032

l3 = 0.0864

l4 = 0.1

l5 = 11.04

l6 = 0.786

l7 = 0.643

l8 = 0.547

name = 'Cheng'

thetis.stability_functions.compute_normalized_frequencies(shear2, buoy2, k, eps, verbose=False)

Computes normalized buoyancy and shear frequency squared.

\[\begin{split}\alpha_M &= \frac{k^2}{\varepsilon^2} M^2 \\ \alpha_N &= \frac{k^2}{\varepsilon^2} N^2\end{split}\]

From Burchard and Bolding (2001).

Parameters:

• shear2 – \(M^2\)

• buoy2 – \(N^2\)

• k – turbulent kinetic energy

• eps – TKE dissipation rate

thetis.timeintegrator module

Generic time integration schemes to advance equations in time.

class thetis.timeintegrator.CrankNicolson(equation, solution, fields, dt, options, bnd_conditions)

Bases: TimeIntegrator

Standard Crank-Nicolson time integration scheme.

Parameters:

• equation (Equation object) – the equation to solve

• solution – Function where solution will be stored

• fields (dict of Function or Constant objects) – Dictionary of fields that are passed to the equation

• dt (float) – time step in seconds

• options – TimeStepperOptions instance containing parameter values.

• bnd_conditions (dict) – Dictionary of boundary conditions passed to the equation

advance(t, update_forcings=None)

Advances equations for one time step.

advance_picard(t, update_forcings=None, update_lagged=True, update_fields=True)

Advances equations for one time step in a Picard iteration.

cfl_coeff = inf

initialize(solution)

Assigns initial conditions to all required fields.

update_solver()

Create solver objects

class thetis.timeintegrator.ForwardEuler(equation, solution, fields, dt, options, bnd_conditions)

Bases: TimeIntegrator

Standard forward Euler time integration scheme.

Parameters:

• equation (Equation object) – the equation to solve

• solution – Function where solution will be stored

• fields (dict of Function or Constant objects) – Dictionary of fields that are passed to the equation

• dt (float) – time step in seconds

• options – TimeStepperOptions instance containing parameter values.

• bnd_conditions (dict) – Dictionary of boundary conditions passed to the equation

advance(t, update_forcings=None)

Advances equations for one time step.

cfl_coeff = 1.0

initialize(solution)

Assigns initial conditions to all required fields.

update_solver()

class thetis.timeintegrator.LeapFrogAM3(equation, solution, fields, dt, options, bnd_conditions, terms_to_add='all')

Bases: TimeIntegrator

Leap-Frog Adams-Moulton 3 ALE time integrator

Defined in (2.27)-(2.30) in [1]; (2.21)-(2.22) in [2]

[1] Shchepetkin and McWilliams (2005). The regional oceanic modeling system (ROMS): a split-explicit, free-surface, topography-following-coordinate oceanic model. Ocean Modelling, 9(4):347-404. http://dx.doi.org/10.1016/j.ocemod.2013.04.010

[2] Shchepetkin and McWilliams (2009). Computational Kernel Algorithms for Fine-Scale, Multiprocess, Longtime Oceanic Simulations, 14:121-183. http://dx.doi.org/10.1016/S1570-8659(08)01202-0

Parameters:

• equation (Equation object) – equation to solve

• solution – Function where solution will be stored

• fields (dict of Function or Constant objects) – Dictionary of fields that are passed to the equation

• dt (float) – time step in seconds

• options – TimeStepperOptions instance containing parameter values.

• bnd_conditions (dict) – Dictionary of boundary conditions passed to the equation

• terms_to_add ('all' or list of 'implicit', 'explicit', 'source'.) – Defines which terms of the equation are to be added to this solver. Default ‘all’ implies [‘implicit’, ‘explicit’, ‘source’].

advance(t, update_forcings=None)

Advances equations for one time step.

cfl_coeff = 1.5874

correct()

Correction step from \(t_{n}\) to \(t_{n+1}\)

Let \(M_n\) denote the mass matrix at time \(t_{n}\). The correction step is

\[M_{n+1} T_{n+1} = M_{n} T_{n} + \Delta t L_{n+1/2}\]

This is Euler ALE step: LHS is evaluated in \(\Omega_{n+1}\), RHS in \(\Omega_n\).

eval_rhs()

initialize(solution)

Assigns initial conditions to all required fields.

predict()

Prediction step from \(t_{n-1/2}\) to \(t_{n+1/2}\)

Let \(M_n\) denote the mass matrix at time \(t_{n}\). The prediction step is

\[\begin{split}T_{n-1/2} &= (1/2 - 2\gamma) T_{n-1} + (1/2 + 2 \gamma) T_{n} \\ M_n T_{n+1/2} &= M_n T_{n-1/2} + \Delta t (1 - 2\gamma) M_n L_{n}\end{split}\]

This is computed in a fixed mesh: all terms are evaluated in \(\Omega_n\).

class thetis.timeintegrator.PressureProjectionPicard(equation, equation_mom, solution, fields, dt, options, bnd_conditions)

Bases: TimeIntegrator

Pressure projection scheme with Picard iteration for shallow water equations

Parameters:

• equation (Equation object) – free surface equation

• equation_mom (Equation object) – momentum equation

• solution – Function where solution will be stored

• fields (dict of Function or Constant objects) – Dictionary of fields that are passed to the equation

• dt (float) – time step in seconds

• options – TimeStepperOptions instance containing parameter values.

• bnd_conditions (dict) – Dictionary of boundary conditions passed to the equation

advance(t, update_forcings=None)

Advances equations for one time step.

cfl_coeff = 1.0

initialize(solution)

Assigns initial conditions to all required fields.

update_solver()

Create solver objects

class thetis.timeintegrator.SSPRK22ALE(equation, solution, fields, dt, options, bnd_conditions, terms_to_add='all')

Bases: TimeIntegrator

SSPRK(2,2) ALE time integrator for 3D fields

The scheme is

\[\begin{split}u^{(1)} &= u^{n} + \Delta t F(u^{n}) \\ u^{n+1} &= u^{n} + \frac{\Delta t}{2}(F(u^{n}) + F(u^{(1)}))\end{split}\]

Both stages are implemented as ALE updates from geometry \(\Omega_n\) to \(\Omega_{(1)}\), and \(\Omega_{n+1}\).

Parameters:

• equation (Equation object) – equation to solve

• solution – Function where solution will be stored

• fields (dict of Function or Constant objects) – Dictionary of fields that are passed to the equation

• dt (float) – time step in seconds

• options – TimeStepperOptions instance containing parameter values.

• bnd_conditions (dict) – Dictionary of boundary conditions passed to the equation

• terms_to_add ('all' or list of 'implicit', 'explicit', 'source'.) – Defines which terms of the equation are to be added to this solver. Default ‘all’ implies [‘implicit’, ‘explicit’, ‘source’].

advance(t, update_forcings=None)

Advances equations for one time step.

cfl_coeff = 1.0

initialize(solution)

Assigns initial conditions to all required fields.

prepare_stage(i_stage, t, update_forcings=None)

Preprocess stage i_stage.

This must be called prior to updating mesh geometry.

solve_stage(i_stage)

Solves i-th stage

stage_one_prep()

Preprocess first stage: compute all forms on the old geometry

stage_one_solve()

First stage: solve \(u^{(1)}\) given previous solution \(u^n\).

This is a forward Euler ALE step between domains \(\Omega^n\) and \(\Omega^{(1)}\):

\[\int_{\Omega^{(1)}} u^{(1)} \psi dx = \int_{\Omega^n} u^n \psi dx + \Delta t \int_{\Omega^n} F(u^n) \psi dx\]

stage_two_prep()

Preprocess 2nd stage: compute all forms on the old geometry

stage_two_solve()

2nd stage: solve \(u^{n+1}\) given previous solutions \(u^n, u^{(1)}\).

This is an ALE step:

\[\begin{split}\int_{\Omega^{n+1}} u^{n+1} \psi dx &= \int_{\Omega^n} u^n \psi dx \\ &+ \frac{\Delta t}{2} \int_{\Omega^n} F(u^n) \psi dx \\ &+ \frac{\Delta t}{2} \int_{\Omega^{(1)}} F(u^{(1)}) \psi dx\end{split}\]

class thetis.timeintegrator.SteadyState(equation, solution, fields, dt, options, bnd_conditions)

Bases: TimeIntegrator

Time integrator that solves the steady state equations, leaving out the mass terms

Parameters:

• equation (Equation object) – the equation to solve

• solution – Function where solution will be stored

• fields (dict of Function or Constant objects) – Dictionary of fields that are passed to the equation

• dt (float) – time step in seconds

• options – TimeStepperOptions instance containing parameter values.

• bnd_conditions (dict) – Dictionary of boundary conditions passed to the equation

advance(t, update_forcings=None)

Advances equations for one time step.

cfl_coeff = inf

initialize(solution)

Assigns initial conditions to all required fields.

update_solver()

Create solver objects

class thetis.timeintegrator.TimeIntegrator(equation, solution, fields, dt, options)

Bases: TimeIntegratorBase

Base class for all time integrator objects that march a single equation

Parameters:

• equation (Equation object) – the equation to solve

• solution – Function where solution will be stored

• fields (dict of Function or Constant objects) – Dictionary of fields that are passed to the equation

• dt (float) – time step in seconds

• options – TimeStepperOptions instance containing parameter values

advance_picard(t, update_forcings=None, update_lagged=True, update_fields=True)

Advances equations for one time step within a Picard iteration

Parameters:

• t (float) – simulation time

• update_forcings – user-defined function that takes the simulation time and updates any time-dependent boundary conditions

• update_lagged – should the old solution be updated?

• update_fields – should the fields be updated?

create_fields_old()

Create a copy of fields dictionary to store beginning of timestep values

set_dt(dt)

Update time step

update_fields_old()

Update the values of fields_old with those of fields

class thetis.timeintegrator.TimeIntegratorBase

Bases: ABC

Abstract class that defines the API for all time integrators

Both TimeIntegrator and CoupledTimeIntegrator inherit from this class.

abstract advance(t, update_forcings=None)

Advances equations for one time step

Parameters:

• t (float) – simulation time

• update_forcings – user-defined function that takes the simulation time and updates any time-dependent boundary conditions

abstract initialize(init_solution)

Initialize the time integrator

Parameters:

init_solution – initial solution

thetis.timeintegrator.timed_region()

Log.Event(cls, name, klass=None) Source code at petsc4py/PETSc/Log.pyx:39

thetis.timeintegrator.timed_stage()

Log.Stage(cls, name) Source code at petsc4py/PETSc/Log.pyx:11

thetis.timezone module

Timezone definitions and conversion methods

class thetis.timezone.FixedTimeZone(offset, name)

Bases: _FixedOffset

Class that represents a fixed time zone defined by UTC offset in hours.

arg int offset: timezone UTC offset in hours arg str name: timezone name

tzname(dt)

datetime -> string name of time zone.

thetis.timezone.datetime_to_epoch(t)

Convert python datetime object to epoch time stamp.

thetis.timezone.epoch_to_datetime(t)

Convert python datetime object to epoch time stamp.

thetis.tracer_eq module

3D advection diffusion equation for tracers.

The advection-diffusion equation of tracer \(T\) in conservative form reads

(15)\[\frac{\partial T}{\partial t} + \nabla_h \cdot (\textbf{u} T) + \frac{\partial (w T)}{\partial z} = \nabla_h \cdot (\mu_h \nabla_h T) + \frac{\partial}{\partial z} \Big(\mu \frac{\partial T}{\partial z}\Big)\]

where \(\nabla_h\) denotes horizontal gradient, \(\textbf{u}\) and \(w\) are the horizontal and vertical velocities, respectively, and \(\mu_h\) and \(\mu\) denote horizontal and vertical diffusivity.

class thetis.tracer_eq.HorizontalAdvectionTerm(function_space, bathymetry=None, v_elem_size=None, h_elem_size=None, use_symmetric_surf_bnd=True, use_lax_friedrichs=True, sipg_factor=Constant([1.], 10), sipg_factor_vertical=Constant([1.], 11))

Bases: TracerTerm

Horizontal advection term \(\nabla_h \cdot (\textbf{u} T)\)

The weak formulation reads

\[\int_\Omega \nabla_h \cdot (\textbf{u} T) \phi dx = -\int_\Omega T\textbf{u} \cdot \nabla_h \phi dx + \int_{\mathcal{I}_h\cup\mathcal{I}_v} T^{\text{up}} \text{avg}(\textbf{u}) \cdot \text{jump}(\phi \textbf{n}_h) dS\]

where the right hand side has been integrated by parts; \(\mathcal{I}_h,\mathcal{I}_v\) denote the set of horizontal and vertical facets, \(\textbf{n}_h\) is the horizontal projection of the unit normal vector, \(T^{\text{up}}\) is the upwind value, and \(\text{jump}\) and \(\text{avg}\) denote the jump and average operators across the interface.

Parameters:

• function_space – FunctionSpace where the solution belongs

• bathymetry (3D Function or Constant) – bathymetry of the domain

• v_elem_size – scalar Function that defines the vertical element size

• h_elem_size – scalar Function that defines the horizontal element size

• use_symmetric_surf_bnd (bool) – If True, use symmetric surface boundary condition in the horizontal advection term

• sipg_factor –

  class:

  Constant or :class: Function horizontal SIPG penalty scaling factor

• sipg_factor_vertical –

  class:

  Constant or :class: Function vertical SIPG penalty scaling factor

residual(solution, solution_old, fields, fields_old, bnd_conditions)

Returns an UFL form of the term.

Parameters:

• solution – solution Function of the corresponding equation

• solution_old – a time lagged solution Function

• fields – a dictionary that provides all the remaining fields that the term depends on. The keys of the dictionary should standard field names in field_metadata

• fields_old – Time lagged dictionary of fields

• bnd_conditions – A dictionary describing boundary conditions. E.g. {3: {‘elev_2d’: Constant(1.0)}} replaces elev_2d function by a constant on boundary ID 3.

class thetis.tracer_eq.HorizontalDiffusionTerm(function_space, bathymetry=None, v_elem_size=None, h_elem_size=None, use_symmetric_surf_bnd=True, use_lax_friedrichs=True, sipg_factor=Constant([1.], 10), sipg_factor_vertical=Constant([1.], 11))

Bases: TracerTerm

Horizontal diffusion term \(-\nabla_h \cdot (\mu_h \nabla_h T)\)

Using the symmetric interior penalty method the weak form becomes

\[\begin{split}\int_\Omega \nabla_h \cdot (\mu_h \nabla_h T) \phi dx =& -\int_\Omega \mu_h (\nabla_h \phi) \cdot (\nabla_h T) dx \\ &+ \int_{\mathcal{I}_h\cup\mathcal{I}_v} \text{jump}(\phi \textbf{n}_h) \cdot \text{avg}(\mu_h \nabla_h T) dS + \int_{\mathcal{I}_h\cup\mathcal{I}_v} \text{jump}(T \textbf{n}_h) \cdot \text{avg}(\mu_h \nabla \phi) dS \\ &- \int_{\mathcal{I}_h\cup\mathcal{I}_v} \sigma \text{avg}(\mu_h) \text{jump}(T \textbf{n}_h) \cdot \text{jump}(\phi \textbf{n}_h) dS\end{split}\]

where \(\sigma\) is a penalty parameter, see Hillewaert (2013).

Hillewaert, Koen (2013). Development of the discontinuous Galerkin method for high-resolution, large scale CFD and acoustics in industrial geometries. PhD Thesis. Université catholique de Louvain. https://dial.uclouvain.be/pr/boreal/object/boreal:128254/

Parameters:

• function_space – FunctionSpace where the solution belongs

• bathymetry (3D Function or Constant) – bathymetry of the domain

• v_elem_size – scalar Function that defines the vertical element size

• h_elem_size – scalar Function that defines the horizontal element size

• use_symmetric_surf_bnd (bool) – If True, use symmetric surface boundary condition in the horizontal advection term

• sipg_factor –

  class:

  Constant or :class: Function horizontal SIPG penalty scaling factor

• sipg_factor_vertical –

  class:

  Constant or :class: Function vertical SIPG penalty scaling factor

residual(solution, solution_old, fields, fields_old, bnd_conditions)

Returns an UFL form of the term.

Parameters:

• solution – solution Function of the corresponding equation

• solution_old – a time lagged solution Function

• fields – a dictionary that provides all the remaining fields that the term depends on. The keys of the dictionary should standard field names in field_metadata

• fields_old – Time lagged dictionary of fields

• bnd_conditions – A dictionary describing boundary conditions. E.g. {3: {‘elev_2d’: Constant(1.0)}} replaces elev_2d function by a constant on boundary ID 3.

class thetis.tracer_eq.SourceTerm(function_space, bathymetry=None, v_elem_size=None, h_elem_size=None, use_symmetric_surf_bnd=True, use_lax_friedrichs=True, sipg_factor=Constant([1.], 10), sipg_factor_vertical=Constant([1.], 11))

Bases: TracerTerm

Generic source term

The weak form reads

\[F_s = \int_\Omega \sigma \phi dx\]

where \(\sigma\) is a user defined scalar Function.

Parameters:

• function_space – FunctionSpace where the solution belongs

• bathymetry (3D Function or Constant) – bathymetry of the domain

• v_elem_size – scalar Function that defines the vertical element size

• h_elem_size – scalar Function that defines the horizontal element size

• use_symmetric_surf_bnd (bool) – If True, use symmetric surface boundary condition in the horizontal advection term

• sipg_factor –

  class:

  Constant or :class: Function horizontal SIPG penalty scaling factor

• sipg_factor_vertical –

  class:

  Constant or :class: Function vertical SIPG penalty scaling factor

residual(solution, solution_old, fields, fields_old, bnd_conditions)

Returns an UFL form of the term.

Parameters:

• solution – solution Function of the corresponding equation

• solution_old – a time lagged solution Function

• fields – a dictionary that provides all the remaining fields that the term depends on. The keys of the dictionary should standard field names in field_metadata

• fields_old – Time lagged dictionary of fields

• bnd_conditions – A dictionary describing boundary conditions. E.g. {3: {‘elev_2d’: Constant(1.0)}} replaces elev_2d function by a constant on boundary ID 3.

class thetis.tracer_eq.TracerEquation(function_space, bathymetry=None, v_elem_size=None, h_elem_size=None, use_symmetric_surf_bnd=True, use_lax_friedrichs=True, sipg_factor=Constant([10.], 12), sipg_factor_vertical=Constant([10.], 13))

Bases: Equation

3D tracer advection-diffusion equation (15) in conservative form

Parameters:

• function_space – FunctionSpace where the solution belongs

• bathymetry (3D Function or Constant) – bathymetry of the domain

• v_elem_size – scalar Function that defines the vertical element size

• h_elem_size – scalar Function that defines the horizontal element size

• use_symmetric_surf_bnd (bool) – If True, use symmetric surface boundary condition in the horizontal advection term

• sipg_factor –

  class:

  Constant or :class: Function horizontal SIPG penalty scaling factor

• sipg_factor_vertical –

  class:

  Constant or :class: Function vertical SIPG penalty scaling factor

class thetis.tracer_eq.TracerTerm(function_space, bathymetry=None, v_elem_size=None, h_elem_size=None, use_symmetric_surf_bnd=True, use_lax_friedrichs=True, sipg_factor=Constant([1.], 10), sipg_factor_vertical=Constant([1.], 11))

Bases: Term

Generic tracer term that provides commonly used members and mapping for boundary functions.

Parameters:

• function_space – FunctionSpace where the solution belongs

• bathymetry (3D Function or Constant) – bathymetry of the domain

• v_elem_size – scalar Function that defines the vertical element size

• h_elem_size – scalar Function that defines the horizontal element size

• use_symmetric_surf_bnd (bool) – If True, use symmetric surface boundary condition in the horizontal advection term

• sipg_factor –

  class:

  Constant or :class: Function horizontal SIPG penalty scaling factor

• sipg_factor_vertical –

  class:

  Constant or :class: Function vertical SIPG penalty scaling factor

get_bnd_functions(c_in, uv_in, elev_in, bnd_id, bnd_conditions)

Returns external values of tracer and uv for all supported boundary conditions.

Volume flux (flux) and normal velocity (un) are defined positive out of the domain.

Parameters:

• c_in – Internal value of tracer

• uv_in – Internal value of horizontal velocity

• elev_in – Internal value of elevation

• bnd_id (int) – boundary id

• bnd_conditions – dict of boundary conditions: {bnd_id: {field: value, ...}, ...}

class thetis.tracer_eq.VerticalAdvectionTerm(function_space, bathymetry=None, v_elem_size=None, h_elem_size=None, use_symmetric_surf_bnd=True, use_lax_friedrichs=True, sipg_factor=Constant([1.], 10), sipg_factor_vertical=Constant([1.], 11))

Bases: TracerTerm

Vertical advection term \(\partial (w T)/(\partial z)\)

The weak form reads

\[\int_\Omega \frac{\partial (w T)}{\partial z} \phi dx = - \int_\Omega T w \frac{\partial \phi}{\partial z} dx + \int_{\mathcal{I}_v} T^{\text{up}} \text{avg}(w) \text{jump}(\phi n_z) dS\]

where the right hand side has been integrated by parts; \(\mathcal{I}_v\) denotes the set of vertical facets, \(n_z\) is the vertical projection of the unit normal vector, \(T^{\text{up}}\) is the upwind value, and \(\text{jump}\) and \(\text{avg}\) denote the jump and average operators across the interface.

In the case of ALE moving mesh we substitute \(w\) with \(w - w_m\), \(w_m\) being the mesh velocity.

Parameters:

• function_space – FunctionSpace where the solution belongs

• bathymetry (3D Function or Constant) – bathymetry of the domain

• v_elem_size – scalar Function that defines the vertical element size

• h_elem_size – scalar Function that defines the horizontal element size

• use_symmetric_surf_bnd (bool) – If True, use symmetric surface boundary condition in the horizontal advection term

• sipg_factor –

  class:

  Constant or :class: Function horizontal SIPG penalty scaling factor

• sipg_factor_vertical –

  class:

  Constant or :class: Function vertical SIPG penalty scaling factor

residual(solution, solution_old, fields, fields_old, bnd_conditions)

Returns an UFL form of the term.

Parameters:

• solution – solution Function of the corresponding equation

• solution_old – a time lagged solution Function

• fields – a dictionary that provides all the remaining fields that the term depends on. The keys of the dictionary should standard field names in field_metadata

• fields_old – Time lagged dictionary of fields

• bnd_conditions – A dictionary describing boundary conditions. E.g. {3: {‘elev_2d’: Constant(1.0)}} replaces elev_2d function by a constant on boundary ID 3.

class thetis.tracer_eq.VerticalDiffusionTerm(function_space, bathymetry=None, v_elem_size=None, h_elem_size=None, use_symmetric_surf_bnd=True, use_lax_friedrichs=True, sipg_factor=Constant([1.], 10), sipg_factor_vertical=Constant([1.], 11))

Bases: TracerTerm

Vertical diffusion term \(-\frac{\partial}{\partial z} \Big(\mu \frac{T}{\partial z}\Big)\)

Using the symmetric interior penalty method the weak form becomes

\[\begin{split}\int_\Omega \frac{\partial}{\partial z} \Big(\mu \frac{T}{\partial z}\Big) \phi dx =& -\int_\Omega \mu \frac{\partial T}{\partial z} \frac{\partial \phi}{\partial z} dz \\ &+ \int_{\mathcal{I}_{h}} \text{jump}(\phi n_z) \text{avg}\Big(\mu \frac{\partial T}{\partial z}\Big) dS + \int_{\mathcal{I}_{h}} \text{jump}(T n_z) \text{avg}\Big(\mu \frac{\partial \phi}{\partial z}\Big) dS \\ &- \int_{\mathcal{I}_{h}} \sigma \text{avg}(\mu) \text{jump}(T n_z) \cdot \text{jump}(\phi n_z) dS\end{split}\]

where \(\sigma\) is a penalty parameter, see Hillewaert (2013).

Hillewaert, Koen (2013). Development of the discontinuous Galerkin method for high-resolution, large scale CFD and acoustics in industrial geometries. PhD Thesis. Université catholique de Louvain. https://dial.uclouvain.be/pr/boreal/object/boreal:128254/

Parameters:

• function_space – FunctionSpace where the solution belongs

• bathymetry (3D Function or Constant) – bathymetry of the domain

• v_elem_size – scalar Function that defines the vertical element size

• h_elem_size – scalar Function that defines the horizontal element size

• use_symmetric_surf_bnd (bool) – If True, use symmetric surface boundary condition in the horizontal advection term

• sipg_factor –

  class:

  Constant or :class: Function horizontal SIPG penalty scaling factor

• sipg_factor_vertical –

  class:

  Constant or :class: Function vertical SIPG penalty scaling factor

residual(solution, solution_old, fields, fields_old, bnd_conditions)

Returns an UFL form of the term.

Parameters:

• solution – solution Function of the corresponding equation

• solution_old – a time lagged solution Function

• fields – a dictionary that provides all the remaining fields that the term depends on. The keys of the dictionary should standard field names in field_metadata

• fields_old – Time lagged dictionary of fields

• bnd_conditions – A dictionary describing boundary conditions. E.g. {3: {‘elev_2d’: Constant(1.0)}} replaces elev_2d function by a constant on boundary ID 3.

thetis.tracer_eq_2d module

2D advection diffusion equation for tracers.

The advection-diffusion equation of tracer \(T\) in non-conservative form reads

(16)\[\frac{\partial T}{\partial t} + \nabla_h \cdot (\textbf{u} T) = \nabla_h \cdot (\mu_h \nabla_h T)\]

where \(\nabla_h\) denotes horizontal gradient, \(\textbf{u}\) are the horizontal velocities, and \(\mu_h\) denotes horizontal diffusivity.

The advection-diffusion equation of depth-integrated tracer \(q=HT\) in conservative form reads

(17)\[\frac{\partial q}{\partial t} + \nabla_h \cdot (\textbf{u} q) = \nabla_h \cdot (\mu_h \nabla_h q)\]

where \(\nabla_h\) denotes horizontal gradient, \(\textbf{u}\) are the horizontal velocities, and \(\mu_h\) denotes horizontal diffusivity.

class thetis.tracer_eq_2d.ConservativeHorizontalAdvectionTerm(index, label, function_space, depth, options, test_function=None, trial_function=None)

Bases: ConservativeTracerTerm

Advection of tracer term, \(\nabla \cdot \bar{\textbf{u}} \nabla q\)

The weak form is

\[\int_\Omega \boldsymbol{\psi} \nabla\cdot \bar{\textbf{u}} \nabla q dx = - \int_\Omega \left(\nabla_h \boldsymbol{\psi})\right) \cdot \bar{\textbf{u}} \cdot q dx + \int_\Gamma \text{avg}(q\bar{\textbf{u}}\cdot\textbf{n}) \cdot \text{jump}(\boldsymbol{\psi}) dS\]

where the right hand side has been integrated by parts; \(\textbf{n}\) is the unit normal of the element interfaces, and \(\text{jump}\) and \(\text{avg}\) denote the jump and average operators across the interface.

Parameters:

• index – index for this tracer component within the vector

• label – label for this tracer component

• function_space – FunctionSpace where the solution belongs

• depth –

  class:

  DepthExpression containing depth info

• options – :class`ModelOptions2d` containing parameters

• test_function – custom TestFunction.

• trial_function – custom TrialFunction.

residual(solution, solution_old, fields, fields_old, bnd_conditions=None)

Returns an UFL form of the term.

Parameters:

• solution – solution Function of the corresponding equation

• solution_old – a time lagged solution Function

• fields – a dictionary that provides all the remaining fields that the term depends on. The keys of the dictionary should standard field names in field_metadata

• fields_old – Time lagged dictionary of fields

• bnd_conditions – A dictionary describing boundary conditions. E.g. {3: {‘elev_2d’: Constant(1.0)}} replaces elev_2d function by a constant on boundary ID 3.

class thetis.tracer_eq_2d.ConservativeHorizontalDiffusionTerm(index, label, function_space, depth, options, test_function=None, trial_function=None)

Bases: ConservativeTracerTerm, HorizontalDiffusionTerm

Horizontal diffusion term \(-\nabla_h \cdot (\mu_h \nabla_h q)\)

Using the symmetric interior penalty method the weak form becomes

\[\begin{split}-\int_\Omega \nabla_h \cdot (\mu_h \nabla_h q) \phi dx =& \int_\Omega \mu_h (\nabla_h \phi) \cdot (\nabla_h q) dx \\ &- \int_{\mathcal{I}_h\cup\mathcal{I}_v} \text{jump}(\phi \textbf{n}_h) \cdot \text{avg}(\mu_h \nabla_h q) dS - \int_{\mathcal{I}_h\cup\mathcal{I}_v} \text{jump}(q \textbf{n}_h) \cdot \text{avg}(\mu_h \nabla \phi) dS \\ &+ \int_{\mathcal{I}_h\cup\mathcal{I}_v} \sigma \text{avg}(\mu_h) \text{jump}(q \textbf{n}_h) \cdot \text{jump}(\phi \textbf{n}_h) dS \\ &- \int_\Gamma \mu_h (\nabla_h \phi) \cdot \textbf{n}_h ds\end{split}\]

where \(\sigma\) is a penalty parameter, see Hillewaert (2013).

Hillewaert, Koen (2013). Development of the discontinuous Galerkin method for high-resolution, large scale CFD and acoustics in industrial geometries. PhD Thesis. Université catholique de Louvain. https://dial.uclouvain.be/pr/boreal/object/boreal:128254/

Parameters:

• index – index for this tracer component within the vector

• label – label for this tracer component

• function_space – FunctionSpace where the solution belongs

• depth –

  class:

  DepthExpression containing depth info

• options – :class`ModelOptions2d` containing parameters

• test_function – custom TestFunction.

• trial_function – custom TrialFunction.

class thetis.tracer_eq_2d.ConservativeSourceTerm(index, label, function_space, depth, options, test_function=None, trial_function=None)

Bases: ConservativeTracerTerm

Generic source term

The weak form reads

\[F_s = \int_\Omega \sigma \phi dx\]

where \(\sigma\) is a user defined scalar Function.

Parameters:

• index – index for this tracer component within the vector

• label – label for this tracer component

• function_space – FunctionSpace where the solution belongs

• depth –

  class:

  DepthExpression containing depth info

• options – :class`ModelOptions2d` containing parameters

• test_function – custom TestFunction.

• trial_function – custom TrialFunction.

residual(solution, solution_old, fields, fields_old, bnd_conditions=None)

Returns an UFL form of the term.

Parameters:

• solution – solution Function of the corresponding equation

• solution_old – a time lagged solution Function

• fields – a dictionary that provides all the remaining fields that the term depends on. The keys of the dictionary should standard field names in field_metadata

• fields_old – Time lagged dictionary of fields

• bnd_conditions – A dictionary describing boundary conditions. E.g. {3: {‘elev_2d’: Constant(1.0)}} replaces elev_2d function by a constant on boundary ID 3.

class thetis.tracer_eq_2d.ConservativeTracerTerm(index, label, function_space, depth, options, test_function=None, trial_function=None)

Bases: TracerTerm

Generic depth-integrated tracer term that provides commonly used members and mapping for boundary functions.

Parameters:

• index – index for this tracer component within the vector

• label – label for this tracer component

• function_space – FunctionSpace where the solution belongs

• depth –

  class:

  DepthExpression containing depth info

• options – :class`ModelOptions2d` containing parameters

• test_function – custom TestFunction.

• trial_function – custom TrialFunction.

class thetis.tracer_eq_2d.HorizontalAdvectionTerm(index, label, function_space, depth, options, test_function=None, trial_function=None)

Bases: TracerTerm

Advection of tracer term, \(\bar{\textbf{u}} \cdot \nabla T\)

The weak form is

\[\int_\Omega \bar{\textbf{u}} \cdot \boldsymbol{\psi} \cdot \nabla T dx = - \int_\Omega \nabla_h \cdot (\bar{\textbf{u}} \boldsymbol{\psi}) \cdot T dx + \int_\Gamma \text{avg}(T) \cdot \text{jump}(\boldsymbol{\psi} (\bar{\textbf{u}}\cdot\textbf{n})) dS\]

where the right hand side has been integrated by parts; \(\textbf{n}\) is the unit normal of the element interfaces, and \(\text{jump}\) and \(\text{avg}\) denote the jump and average operators across the interface.

For the continuous Galerkin method we use

\[\int_\Omega \bar{\textbf{u}} \cdot \boldsymbol{\psi} \cdot \nabla T dx = - \int_\Omega \nabla_h \cdot (\bar{\textbf{u}} \boldsymbol{\psi}) \cdot T dx.\]

Parameters:

• index – index for this tracer component within the vector

• label – label for this tracer component

• function_space – FunctionSpace where the solution belongs

• depth – DepthExpression containing depth info

• options – :class`ModelOptions2d` containing parameters

• test_function – custom TestFunction

• trial_function – custom TrialFunction

residual(solution, solution_old, fields, fields_old, bnd_conditions)

Returns an UFL form of the term.

Parameters:

• solution – solution Function of the corresponding equation

• solution_old – a time lagged solution Function

• fields – a dictionary that provides all the remaining fields that the term depends on. The keys of the dictionary should standard field names in field_metadata

• fields_old – Time lagged dictionary of fields

• bnd_conditions – A dictionary describing boundary conditions. E.g. {3: {‘elev_2d’: Constant(1.0)}} replaces elev_2d function by a constant on boundary ID 3.

class thetis.tracer_eq_2d.HorizontalDiffusionTerm(index, label, function_space, depth, options, test_function=None, trial_function=None)

Bases: TracerTerm

Horizontal diffusion term \(-\nabla_h \cdot (\mu_h \nabla_h T)\)

Using the symmetric interior penalty method the weak form becomes

\[\begin{split}-\int_\Omega \nabla_h \cdot (\mu_h \nabla_h T) \phi dx =& \int_\Omega \mu_h (\nabla_h \phi) \cdot (\nabla_h T) dx \\ &- \int_{\mathcal{I}_h\cup\mathcal{I}_v} \text{jump}(\phi \textbf{n}_h) \cdot \text{avg}(\mu_h \nabla_h T) dS - \int_{\mathcal{I}_h\cup\mathcal{I}_v} \text{jump}(T \textbf{n}_h) \cdot \text{avg}(\mu_h \nabla \phi) dS \\ &+ \int_{\mathcal{I}_h\cup\mathcal{I}_v} \sigma \text{avg}(\mu_h) \text{jump}(T \textbf{n}_h) \cdot \text{jump}(\phi \textbf{n}_h) dS \\ &- \int_\Gamma \mu_h (\nabla_h \phi) \cdot \textbf{n}_h ds\end{split}\]

where \(\sigma\) is a penalty parameter, see Hillewaert (2013).

For the continuous Galerkin method we use

\[-\int_\Omega \nabla_h \cdot (\mu_h \nabla_h T) \phi dx = \int_\Omega \mu_h (\nabla_h \phi) \cdot (\nabla_h T) dx.\]

Hillewaert, Koen (2013). Development of the discontinuous Galerkin method for high-resolution, large scale CFD and acoustics in industrial geometries. PhD Thesis. Université catholique de Louvain. https://dial.uclouvain.be/pr/boreal/object/boreal:128254/

Parameters:

• index – index for this tracer component within the vector

• label – label for this tracer component

• function_space – FunctionSpace where the solution belongs

• depth – DepthExpression containing depth info

• options – :class`ModelOptions2d` containing parameters

• test_function – custom TestFunction

• trial_function – custom TrialFunction

residual(solution, solution_old, fields, fields_old, bnd_conditions)

Returns an UFL form of the term.

Parameters:

• solution – solution Function of the corresponding equation

• solution_old – a time lagged solution Function

• fields – a dictionary that provides all the remaining fields that the term depends on. The keys of the dictionary should standard field names in field_metadata

• fields_old – Time lagged dictionary of fields

• bnd_conditions – A dictionary describing boundary conditions. E.g. {3: {‘elev_2d’: Constant(1.0)}} replaces elev_2d function by a constant on boundary ID 3.

class thetis.tracer_eq_2d.SourceTerm(index, label, function_space, depth, options, test_function=None, trial_function=None)

Bases: TracerTerm

Generic source term

The weak form reads

\[F_s = \int_\Omega \sigma \phi dx\]

where \(\sigma\) is a user defined scalar Function.

Parameters:

• index – index for this tracer component within the vector

• label – label for this tracer component

• function_space – FunctionSpace where the solution belongs

• depth – DepthExpression containing depth info

• options – :class`ModelOptions2d` containing parameters

• test_function – custom TestFunction

• trial_function – custom TrialFunction

residual(solution, solution_old, fields, fields_old, bnd_conditions)

Returns an UFL form of the term.

Parameters:

• solution – solution Function of the corresponding equation

• solution_old – a time lagged solution Function

• fields – a dictionary that provides all the remaining fields that the term depends on. The keys of the dictionary should standard field names in field_metadata

• fields_old – Time lagged dictionary of fields

• bnd_conditions – A dictionary describing boundary conditions. E.g. {3: {‘elev_2d’: Constant(1.0)}} replaces elev_2d function by a constant on boundary ID 3.

class thetis.tracer_eq_2d.TracerEquation2D(system, function_space, depth, options, velocity)

Bases: Equation

Several 2D tracer advection-diffusion equations (15) in conservative or non-conservative form, solved as a mixed system.

Parameters:

• system – comma separated tracer fields under consideration

• function_space – FunctionSpace where the solution belongs

• depth –

  class:

  DepthExpression containing depth info

• options – :class`ModelOptions2d` containing parameters

• velocity – velocity field associated with the shallow water model

add_conservative_terms(*args, **kwargs)

add_nonconservative_terms(*args, **kwargs)

apply_supg(test_function)

Apply SUPG stabilization in the sense of modifying the test function.

class thetis.tracer_eq_2d.TracerTerm(index, label, function_space, depth, options, test_function=None, trial_function=None)

Bases: Term

Generic tracer term that provides commonly used members and mapping for boundary functions.

Parameters:

• index – index for this tracer component within the vector

• label – label for this tracer component

• function_space – FunctionSpace where the solution belongs

• depth – DepthExpression containing depth info

• options – :class`ModelOptions2d` containing parameters

• test_function – custom TestFunction

• trial_function – custom TrialFunction

component(f)

Return the component of a function corresponding to this tracer.

get_bnd_functions(c_in, uv_in, elev_in, bnd_id, bnd_conditions)

Returns external values of tracer and uv for all supported boundary conditions.

Volume flux (flux) and normal velocity (un) are defined positive out of the domain.

Parameters:

• c_in – Internal value of tracer

• uv_in – Internal value of horizontal velocity

• elev_in – Internal value of elevation

• bnd_id (int) – boundary id

• bnd_conditions – dict of boundary conditions: {bnd_id: {field: value, ...}, ...}

thetis.turbines module

Classes related to tidal turbine farms in Thetis.

class thetis.turbines.ConstantThrustTurbine(options, upwind_correction=False)

Bases: TidalTurbine

thrust_coefficient(uv)

class thetis.turbines.DiscreteTidalTurbineFarm(mesh, dx, options)

Bases: TidalTurbineFarm

Class that can be used for the addition of turbines in the turbine density field

Parameters:

• mesh – mesh domain

• dx – measure to integrate power output, n/o turbines

• options – a TidalTurbineFarmOptions options dictionary

add_turbines(coordinates)

Parameters:

• coords – Array with turbine coordinates to be positioned

• function – turbine density function to be adapted

• mesh – computational mesh domain

• radius – radius where the bump will be applied

Returns:

updated turbine density field

class thetis.turbines.MinimumDistanceConstraints(turbine_positions, minimum_distance)

Bases: InequalityConstraint

This class implements minimum distance constraints between turbines.

Note

This class subclasses pyadjoint.InequalityConstraint. The following methods must be implemented:

• length(self)

• function(self, m)

• jacobian(self, m)

Create MinimumDistanceConstraints

Parameters:

• turbine_positions – list of [x,y] where x and y are either float or Constant

• minimum_distance – The minimum distance allowed between turbines.

function(m)

Return an object which must be positive for the point to be feasible.

Parameters:

m (numpy.ndarray.) – The serialized paramaterisation of the turbines.

Returns:

numpy.ndarray – each entry must be positive for the positions to be feasible.

jacobian(m)

Returns the gradient of the constraint function.

Return a list of vector-like objects representing the gradient of the constraint function with respect to the parameter m.

Parameters:

m (numpy.ndarray.) – The serialized paramaterisation of the turbines.

Returns:

numpy.ndarray – the gradient of the constraint function with respect to each input parameter m.

length()

Returns the number of constraints len(function(m)).

class thetis.turbines.TabulatedThrustTurbine(options, upwind_correction=False)

Bases: TidalTurbine

thrust_coefficient(uv)

class thetis.turbines.TidalTurbine(options, upwind_correction=False)

Bases: object

friction_coefficient(uv, depth)

power(uv, depth)

velocity_correction(uv, depth)

class thetis.turbines.TidalTurbineFarm(turbine_density, dx, options)

Bases: object

Parameters:

• turbine_density – turbine distribution density field or expression

• dx – measure to integrate power output, n/o turbines

• options – a TidalTurbineFarmOptions options dictionary

friction_coefficient(uv, depth)

number_of_turbines()

power_output(uv, depth)

class thetis.turbines.TurbineFunctionalCallback(solver_obj, **kwargs)

Bases: DiagnosticCallback

DiagnosticCallback that evaluates the performance of each tidal turbine farm.

Parameters:

• solver_obj – a FlowSolver2d object containing the tidal_turbine_farms

• kwargs – see DiagnosticCallback

message_str(current_power, average_power, average_profit)

A string representation.

Parameters:

args – If provided, these will be the return value from __call__().

name = 'turbine'

variable_names = ['current_power', 'average_power', 'average_profit']

class thetis.turbines.TurbineOptimisationCallback(solver_obj, turbine_functional_callback, **kwargs)

Bases: DiagnosticOptimisationCallback

DiagnosticOptimisationCallback that evaluates the performance of each tidal turbine farm during an optimisation.

See the optimisation module for more info about the use of OptimisationCallbacks.

Parameters:

• solver_obj – a FlowSolver2d object

• turbine_functional_callback – a TurbineFunctionalCallback used in the forward model

Args kwargs:

see DiagnosticOptimisationCallback

compute_values(*args)

Compute diagnostic values.

This method is to be implemented in concrete subclasses of a DiagnosticOptimisationCallback. The number of arguments varies depending on which of the 6 [eval|derivative|hessian]_cb_[pre|post] callbacks this is used as. The last argument always contains the current controls. In the “pre” callbacks this is the only argument. In all “post” callbacks the 0th argument is the current functional value. eval_cb_post is given two arguments: functional and controls. derivative_cb_post and hessian_cb_post are given three arguments with args[1] being the derivative/hessian just calculated.

message_str(cost, average_power, average_profit)

A string representation.

Parameters:

args – If provided, these will be the return value from __call__().

name = 'farm_optimisation'

variable_names = ['cost', 'average_power', 'average_profit']

thetis.turbines.linearly_interpolate_table(x_list, y_list, y_final, x)

Return UFL expression that linearly interpolates between y-values in x-points

Parameters:

• x_list – (1D) x-points

• y_list – y-values in those points

• y_final – value for x>x_list[-1]

• x – point to interpolate (assumed x>x_list[0])

thetis.turbulence module

Generic Length Scale Turbulence Closure model

This model solves two dynamic equations, for turbulent kinetic energy (TKE, \(k\)) and one for an additional variable, the generic length scale \(\psi\) [1]:

(18)\[\frac{\partial k}{\partial t} + \nabla_h \cdot (\textbf{u} k) + \frac{\partial (w k)}{\partial z} = \frac{\partial}{\partial z}\left(\frac{\nu}{\sigma_k} \frac{\partial k}{\partial z}\right) + P + B - \varepsilon\]

(19)\[\frac{\partial \psi}{\partial t} + \nabla_h \cdot (\textbf{u} \psi) + \frac{\partial (w \psi)}{\partial z} = \frac{\partial}{\partial z}\left(\frac{\nu}{\sigma_\psi} \frac{\partial \psi}{\partial z}\right) + \frac{\psi}{k} (c_1 P + c_3 B - c_2 \varepsilon f_{wall})\]

with the production \(P\) and buoyancy production \(B\) are

\[\begin{split}P &= \nu M^2 \\ B &= -\mu N^2\end{split}\]

where \(M\) and \(N\) are the shear and buoyancy frequencies

\[\begin{split}M^2 &= \left(\frac{\partial u}{\partial z}\right)^2 + \left(\frac{\partial v}{\partial z}\right)^2 \\ N^2 &= -\frac{g}{\rho_0}\frac{\partial \rho}{\partial z}\end{split}\]

The generic length scale variable is defined as

\[\psi = (c_\mu^0)^p k^m l^n\]

where \(p, m, n\) are parameters and \(c_\mu^0\) is an empirical constant.

The parameters \(c_1,c_2,c_3,f_{wall}\) depend on the chosen closure. The parameter \(c_3\) takes two values: \(c_3^-\) in stably stratified regime, and \(c_3^+\) in unstably stratified cases.

Turbulent length scale \(l\), and the TKE dissipation rate \(\varepsilon\) are obtained diagnostically as

\[\begin{split}l &= (c_\mu^0)^3 k^{3/2} \varepsilon^{-1} \\ \varepsilon &= (c_\mu^0)^{3+p/n} k^{3/2 + m/n} \psi^{-1/n}\end{split}\]

Finally the vertical eddy viscosity and diffusivity are also computed diagnostically

\[\begin{split}\nu &= \sqrt{2k} l S_m \\ \mu &= \sqrt{2k} l S_\rho\end{split}\]

Stability functions \(S_m\) and \(S_\rho\) are defined in [2] or [3]. Implementation follows [4].

Supported closures

The GLS model parameters are controlled via the GLSModelOptions class.

The parameters can be accessed from the solver object:

solver = FlowSolver(...)
solver.options.turbulence_model_type = 'gls'  # activate GLS model (default)
turbulence_model_options = solver.options.turbulence_model_options
turbulence_model_options.closure_name = 'k-omega'
turbulence_model_options.stability_function_name = 'CB'
turbulence_model_options.compute_c3_minus = True

Currently the following closures have been implemented:

• \(k-\varepsilon\) model

  This closure is obtained with \(p=3, m=3/2, n=-1\), resulting in \(\psi=\varepsilon\). To use this option set closure_name = k-epsilon

• \(k-\omega\) model

  This closure is obtained with \(p=-1, m=1/2, n=-1\), resulting in \(\psi=\omega\). To use this option set closure_name = k-omega

• GLS model A

  This closure is obtained with \(p=2, m=1, n=-2/3\), resulting in \(\psi=\omega\). To use this option set closure_name = gen

The following stability functions have been implemented

• Canuto A [3]

  To use this option set closure_name = CA

• Canuto B [3]

  To use this option set closure_name = CB

• Kantha-Clayson [2]

  To use this option set closure_name = KC

• Cheng [6]

  To use this option set closure_name = CH

See stability_functions for more information.

[1] Umlauf, L. and Burchard, H. (2003). A generic length-scale equation for

geophysical turbulence models. Journal of Marine Research, 61:235–265(31). http://dx.doi.org/10.1357/002224003322005087

[2] Kantha, L. H. and Clayson, C. A. (1994). An improved mixed layer model for

geophysical applications. Journal of Geophysical Research: Oceans, 99(C12):25235–25266. http://dx.doi.org/10.1029/94JC02257

[3] Canuto et al. (2001). Ocean Turbulence. Part I: One-Point Closure Model -

Momentum and Heat Vertical Diffusivities. Journal of Physical Oceanography, 31(6):1413-1426. http://dx.doi.org/10.1175/1520-0485(2001)031

[4] Warner et al. (2005). Performance of four turbulence closure models

implemented using a generic length scale method. Ocean Modelling, 8(1-2):81–113. http://dx.doi.org/10.1016/j.ocemod.2003.12.003

[5] Umlauf, L. and Burchard, H. (2005). Second-order turbulence closure models

for geophysical boundary layers. A review of recent work. Continental Shelf Research, 25(7-8):795–827. http://dx.doi.org/10.1016/j.csr.2004.08.004

[6] Cheng et al. (2002). An improved model for the turbulent PBL.

J. Atmos. Sci., 59:1550-1565. http://dx.doi.org/10.1175/1520-0469(2002)059%3C1550:AIMFTT%3E2.0.CO;2

[7] Burchard and Petersen (1999). Models of turbulence in the marine

environment - a comparative study of two-equation turbulence models. Journal of Marine Systems, 21(1-4):29-53. http://dx.doi.org/10.1016/S0924-7963(99)00004-4

class thetis.turbulence.BuoyFrequencySolver(rho, n2, n2_tmp, relaxation=1.0, minval=1e-12)

Bases: object

Computes buoyancy frequency squared form the given horizontal velocity field.

\[N^2 = -\frac{g}{\rho_0}\frac{\partial \rho}{\partial z}\]

Parameters:

• rho (Function) – water density field

• n2 (Function) – \(N^2\) field

• n2_tmp (Function) – temporary field

• relaxation (float) – relaxation coefficient for mixing old and new values N2 = relaxation*N2_new + (1-relaxation)*N2_old

• minval (float) – minimum value for \(N^2\)

solve(init_solve=False)

Computes buoyancy frequency

Parameters:

init_solve (bool) – Set to True if solving for the first time, skips relaxation

class thetis.turbulence.GLSVerticalDiffusionTerm(function_space, schmidt_nb, bathymetry=None, v_elem_size=None, h_elem_size=None, sipg_factor=Constant([1.], 42))

Bases: VerticalDiffusionTerm

Vertical diffusion term where the diffusivity is replaced by viscosity/Schmidt number.

Parameters:

• function_space – FunctionSpace where the solution belongs

• schmidt_nb – the Schmidt number of TKE or Psi

• bathymetry (3D Function or Constant) – bathymetry of the domain

• v_elem_size – scalar Function that defines the vertical element size

• h_elem_size – scalar Function that defines the horizontal element size

• sipg_factor –

  class:

  Constant or :class: Function vertical SIPG penalty scaling factor

residual(solution, solution_old, fields, fields_old, bnd_conditions)

Returns an UFL form of the term.

Parameters:

• solution – solution Function of the corresponding equation

• solution_old – a time lagged solution Function

• fields – a dictionary that provides all the remaining fields that the term depends on. The keys of the dictionary should standard field names in field_metadata

• fields_old – Time lagged dictionary of fields

• bnd_conditions – A dictionary describing boundary conditions. E.g. {3: {‘elev_2d’: Constant(1.0)}} replaces elev_2d function by a constant on boundary ID 3.

class thetis.turbulence.GenericLengthScaleModel(solver, k_field, psi_field, uv_field, rho_field, l_field, epsilon_field, eddy_diffusivity, eddy_viscosity, n2, m2, options=None)

Bases: TurbulenceModel

Generic Length Scale turbulence closure model implementation

Parameters:

• solver – FlowSolver object

• k_field (Function) – turbulent kinetic energy (TKE) field

• psi_field (Function) – generic length scale field

• uv_field (Function) – horizontal velocity field

• rho_field (Function) – water density field

• l_field (Function) – turbulence length scale field

• epsilon_field (Function) – TKE dissipation rate field

• eddy_diffusivity (Function) – eddy diffusivity field

• eddy_viscosity (Function) – eddy viscosity field

• n2 (Function) – field for buoyancy frequency squared

• m2 (Function) – field for vertical shear frequency squared

• options – GLS model options

initialize(l_init=0.01)

Initialize turbulent fields.

k is set to k_min value. epsilon and psi are set to a value that corresponds to l_init length scale.

Parameters:

l_init – initial value for turbulent length scale.

postprocess()

Updates all diagnostic variables that depend on the turbulence state variables \(k,\psi\).

To be called after updating the turbulence PDEs.

preprocess(init_solve=False)

Computes all diagnostic variables that depend on the mean flow model variables.

To be called before updating the turbulence PDEs.

print_debug()

Print diagnostic field values for debugging.

class thetis.turbulence.PacanowskiPhilanderModel(solver, uv_field, rho_field, eddy_diffusivity, eddy_viscosity, n2, m2, options=None)

Bases: TurbulenceModel

Gradient Richardson number based model by Pacanowski and Philander (1981).

Given the gradient Richardson number \(Ri\) the eddy viscosity and diffusivity are computed diagnostically as

\[\begin{split}\nu &= \frac{\nu_{max}}{(1 + \alpha Ri)^n} \\ \mu &= \frac{\nu}{1 + \alpha Ri}\end{split}\]

where \(\nu_{max},\alpha,n\) are constant parameters. In unstably stratified cases where \(Ri<0\), value \(Ri=0\) is used.

Pacanowski and Philander (1981). Parameterization of vertical mixing in numerical models of tropical oceans. Journal of Physical Oceanography, 11(11):1443-1451. http://dx.doi.org/10.1175/1520-0485(1981)011%3C1443:POVMIN%3E2.0.CO;2

Parameters:

• solver – FlowSolver object

• uv_field (Function) – horizontal velocity field

• rho_field (Function) – water density field

• eddy_diffusivity (Function) – eddy diffusivity field

• eddy_viscosity (Function) – eddy viscosity field

• n2 (Function) – field for buoyancy frequency squared

• m2 (Function) – field for vertical shear frequency squared

• options – model options

initialize()

Initializes fields

postprocess()

Updates all diagnostic variables that depend on the turbulence state variables.

To be called after evaluating the equations.

preprocess(init_solve=False)

Computes all diagnostic variables that depend on the mean flow model variables.

To be called before updating the turbulence PDEs.

class thetis.turbulence.PsiEquation(function_space, gls_model, bathymetry=None, v_elem_size=None, h_elem_size=None)

Bases: Equation

Generic length scale equation (19) without advection terms.

Advection of \(\psi\) is implemented using the standard tracer equation.

Parameters:

• function_space – FunctionSpace where the solution belongs

• gls_model – GenericLengthScaleModel object

• bathymetry (3D Function or Constant) – bathymetry of the domain

• v_elem_size – scalar Function that defines the vertical element size

• h_elem_size – scalar Function that defines the horizontal element size

class thetis.turbulence.PsiSourceTerm(function_space, gls_model, bathymetry=None, v_elem_size=None, h_elem_size=None)

Bases: TracerTerm

Production and destruction terms of the Psi equation (19)

\[F_\psi = \frac{\psi}{k} (c_1 P + c_3 B - c_2 \varepsilon f_{wall})\]

To ensure positivity we use Patankar-type time discretization: all source terms are treated explicitly and sink terms are treated implicitly. To this end the buoyancy production term \(c_3 B\) is split in two:

\[F_\psi = \frac{\psi^n}{k^n} (c_1 P + B_{source}) + \frac{\psi^{n+1}}{k^n} (B_{sink} - c_2 \varepsilon f_{wall})\]

with \(B_{source} \ge 0\) and \(B_{sink} < 0\).

Also implements Neumann boundary condition at top and bottom [7]

\[\left( \frac{\nu}{\sigma_\psi} \frac{\psi}{z} \right)\Big|_{\Gamma_b} = n_z \frac{\nu}{\sigma_\psi} (c_\mu^0)^p k^m \kappa^n (z_b + z_0)^{n-1}\]

where \(z_b\) is the distance from boundary, and \(z_0\) is the roughness length.

Parameters:

• function_space – FunctionSpace where the solution belongs

• gls_model – GenericLengthScaleModel object

• bathymetry (3D Function or Constant) – bathymetry of the domain

• v_elem_size – scalar Function that defines the vertical element size

• h_elem_size – scalar Function that defines the horizontal element size

residual(solution, solution_old, fields, fields_old, bnd_conditions)

Returns an UFL form of the term.

Parameters:

• solution – solution Function of the corresponding equation

• solution_old – a time lagged solution Function

• fields – a dictionary that provides all the remaining fields that the term depends on. The keys of the dictionary should standard field names in field_metadata

• fields_old – Time lagged dictionary of fields

• bnd_conditions – A dictionary describing boundary conditions. E.g. {3: {‘elev_2d’: Constant(1.0)}} replaces elev_2d function by a constant on boundary ID 3.

class thetis.turbulence.ShearFrequencySolver(uv, m2, mu, mv, mu_tmp, relaxation=1.0, minval=1e-12)

Bases: object

Computes vertical shear frequency squared form the given horizontal velocity field.

\[M^2 = \left(\frac{\partial u}{\partial z}\right)^2 + \left(\frac{\partial v}{\partial z}\right)^2\]

Parameters:

• uv (Function) – horizontal velocity field

• m2 (Function) – \(M^2\) field

• mu (Function) – field for x component of \(M^2\)

• mv (Function) – field for y component of \(M^2\)

• mu_tmp (Function) – temporary field

• relaxation (float) – relaxation coefficient for mixing old and new values M2 = relaxation*M2_new + (1-relaxation)*M2_old

• minval (float) – minimum value for \(M^2\)

solve(init_solve=False)

Computes buoyancy frequency

Parameters:

init_solve (bool) – Set to True if solving for the first time, skips relaxation

class thetis.turbulence.TKEEquation(function_space, gls_model, bathymetry=None, v_elem_size=None, h_elem_size=None)

Bases: Equation

Turbulent kinetic energy equation (18) without advection terms.

Advection of TKE is implemented using the standard tracer equation.

Parameters:

• function_space – FunctionSpace where the solution belongs

• gls_model – GenericLengthScaleModel object

• bathymetry (3D Function or Constant) – bathymetry of the domain

• v_elem_size – scalar Function that defines the vertical element size

• h_elem_size – scalar Function that defines the horizontal element size

class thetis.turbulence.TKESourceTerm(function_space, gls_model, bathymetry=None, v_elem_size=None, h_elem_size=None)

Bases: TracerTerm

Production and destruction terms of the TKE equation (18)

\[F_k = P + B - \varepsilon\]

To ensure positivity we use Patankar-type time discretization: all source terms are treated explicitly and sink terms are treated implicitly. To this end the buoyancy production term \(B\) is split in two:

\[F_k = P + B_{source} + \frac{k^{n+1}}{k^n}(B_{sink} - \varepsilon)\]

with \(B_{source} \ge 0\) and \(B_{sink} < 0\).

Parameters:

• function_space – FunctionSpace where the solution belongs

• gls_model – GenericLengthScaleModel object

• bathymetry (3D Function or Constant) – bathymetry of the domain

• v_elem_size – scalar Function that defines the vertical element size

• h_elem_size – scalar Function that defines the horizontal element size

residual(solution, solution_old, fields, fields_old, bnd_conditions)

Returns an UFL form of the term.

Parameters:

• solution – solution Function of the corresponding equation

• solution_old – a time lagged solution Function

• fields – a dictionary that provides all the remaining fields that the term depends on. The keys of the dictionary should standard field names in field_metadata

• fields_old – Time lagged dictionary of fields

• bnd_conditions – A dictionary describing boundary conditions. E.g. {3: {‘elev_2d’: Constant(1.0)}} replaces elev_2d function by a constant on boundary ID 3.

class thetis.turbulence.TurbulenceModel

Bases: ABC

Base class for all vertical turbulence models

abstract initialize()

Initialize all turbulence fields

abstract postprocess()

Updates all diagnostic variables that depend on the turbulence state variables.

To be called after updating the turbulence PDEs.

abstract preprocess(init_solve=False)

Computes all diagnostic variables that depend on the mean flow model variables.

To be called before updating the turbulence PDEs.

class thetis.turbulence.VerticalGradSolver(source, solution, solver_parameters=None)

Bases: object

Computes vertical gradient in the weak sense.

Parameters:

• source – A Function or expression to differentiate.

• solution – A Function where the solution will be stored. Must be in P0 space.

• solver_parameters (dict) – PETSc solver options

solve()

Computes the gradient

thetis.turbulence.set_func_max_val(f, maxval)

Sets a minimum value to a Function

thetis.turbulence.set_func_min_val(f, minval)

Sets a minimum value to a Function

thetis.turbulence.timed_stage()

Log.Stage(cls, name) Source code at petsc4py/PETSc/Log.pyx:11

thetis.utility module

Utility functions and classes for 2D and 3D ocean models

class thetis.utility.AttrDict(*args, **kwargs)

Bases: dict

Dictionary that provides both self[‘key’] and self.key access to members.

http://stackoverflow.com/questions/4984647/accessing-dict-keys-like-an-attribute-in-python

class thetis.utility.DepthExpression(bathymetry_2d, use_nonlinear_equations=True, use_wetting_and_drying=False, wetting_and_drying_alpha=0.5)

Bases: object

Construct expression for depth depending on options

If not use_nonlinear_equations, then the depth is simply the bathymetry:

..math::

H = h

Otherwise we include the free surface elevation:

..math::

H = h + eta

and if use_wetting_and_drying, includes a bathymetry displacement term to ensure a positive depth (see Karna et al. 2011):

..math::

H = h + f(h+eta) + eta

where

..math::

f(h+eta) = (sqrt{(h+eta)^2 +alpha^2} - (h+eta))/2

This introduces a wetting-drying parameter \(\alpha\), with dimensions of length. The value for \(\alpha\) is specified by ModelOptions.wetting_and_drying_alpha, in units of meters. The default value is 0.5, but the appropriate value is problem specific and should be set by the user.

get_total_depth(eta)

Returns total water column depth based on options :arg eta: current elevation as UFL expression

wd_bathymetry_displacement(eta)

Returns wetting and drying bathymetry displacement as described in: Karna et al., 2011. :arg eta: current elevation as UFL expression

class thetis.utility.DepthIntegratedPoissonSolver(q_2d, uv_2d, w_2d, elev_2d, depth, dt, bnd_functions=None, solver_parameters=None)

Bases: object

Construct solvers for Poisson equation and updating velocities

Poisson equation is related to 2d NH SWE system

Non-hydrostatic pressure \(q\) is obtained from the generic form of equation

\[\nabla \cdot \nabla q^{n+1/2} + A \cdot \nabla q^{n+1/2} + B q^{n+1/2} + C = 0\]

The parameter terms A, B and C are defined as

\[A = \frac{\nabla (\eta^* - d)}{H^*} B = \nabla A - \frac{4}{(H^*)^2} C = -2 \frac{\rho_0}{\Delta t} ( \nabla \cdot \bar{\textbf{u}}^* + 2 \frac{\bar{w} - w_b}{H^*} )\]

where the \(H = \eta + d\) denotes the water depth and the superscript star symbol represents the intermediate level of terms.

solve(solve_w=True)

class thetis.utility.ElementContinuity(horizontal, vertical)

Bases: tuple

A named tuple describing the continuity of an element in the horizontal/vertical direction.

The field value is one of “cg”, “hdiv”, or “dg”.

horizontal

Alias for field number 0

vertical

Alias for field number 1

class thetis.utility.ExtrudedFunction(*args, **kwargs)

Bases: Function

A 2D Function that provides a 3D view on the extruded domain.

The 3D function can be accessed as ExtrudedFunction.view_3d. The 3D function resides in V x R function space, where V is the function space of the source function. The 3D function shares the data of the 2D function.

Create a 2D Function with a 3D view on extruded mesh.

Parameters:

mesh_3d – Extruded 3D mesh where the function will be extended to.

class thetis.utility.FieldDict(*args, **kwargs)

Bases: AttrDict

AttrDict that checks that all added fields have proper meta data.

Values can be either Function or Constant objects.

class thetis.utility.FrozenClass

Bases: object

A class where creating a new attribute will raise an exception if _isfrozen is True.

_unfreezedepth allows for multiple applications of the unfrozen decorator.

class thetis.utility.SubdomainProjector(v, v_out, subdomain_id, solver_parameters=None, constant_jacobian=True)

Bases: object

Projector that projects the restriction of an expression to the specified subdomain.

project()

Apply the projection.

class thetis.utility.SumFunction

Bases: object

Helper class to keep track of sum of Coefficients.

Initialize empty sum.

get operation returns Constant(0)

add(coeff)

Adds a coefficient to self

get_sum()

Returns a sum of all added Coefficients

thetis.utility.anisotropic_cell_size(mesh)

Measure of cell size for anisotropic meshes, as described in Micheletti et al. (2003).

This is used in the SUPG formulation for the 2D tracer model.

Micheletti, Perotto and Picasso (2003). Stabilized finite elements on anisotropic meshes: a priori error estimates for the advection-diffusion and the Stokes problems. SIAM Journal on Numerical Analysis 41.3: 1131-1162.

thetis.utility.beta_plane_coriolis_function(latitude, out_function, y_offset=0.0)

Interpolates beta plane Coriolis function to a field

Parameters:

• latitude (float) – latitude in degrees

• out_function – Function where to interpolate

• y_offset (float) – offset (y - y_0) used in Beta-plane approximation. A constant in mesh coordinates.

thetis.utility.beta_plane_coriolis_params(latitude)

Computes beta plane parameters \(f_0,\beta\) based on latitude

Parameters:

latitude (float) – latitude in degrees

Returns:

f_0, beta

Return type:

float

thetis.utility.comp_tracer_mass_2d(scalar_func, total_depth)

Computes total tracer mass in the 2D domain :arg scalar_func: depth-averaged scalar Function to integrate :arg total_depth: scalar UFL expression (e.g. from get_total_depth())

thetis.utility.comp_tracer_mass_3d(scalar_func)

Computes total tracer mass in the 3D domain

Parameters:

scalar_func – scalar Function to integrate

thetis.utility.comp_volume_2d(eta, bath)

Computes volume of the 2D domain as an integral of the elevation field

thetis.utility.comp_volume_3d(mesh)

Computes volume of the 3D domain as an integral

thetis.utility.compute_baroclinic_head(solver)

Computes the baroclinic head \(r\) from the density field

\[r = \frac{1}{\rho_0} \int_{z}^\eta \rho' d\zeta.\]

thetis.utility.compute_boundary_length(mesh2d)

Computes the length of the boundary segments in given 2d mesh

thetis.utility.compute_elem_height(zcoord, output)

Computes the element height on an extruded mesh.

Parameters:

• zcoord (Function) – field that contains the z coordinates of the mesh

• output (Function) – field where element height is stored

thetis.utility.create_directory(path, comm=<mpi4py.MPI.Intracomm object>)

Create a directory on disk

Raises IOError if a file with the same name already exists.

thetis.utility.element_continuity(ufl_element)

Return an ElementContinuity instance with the continuity of a given element.

Parameters:

ufl_element – The UFL element to determine the continuity of.

Returns:

A new ElementContinuity instance.

thetis.utility.extend_function_to_3d(func, mesh_extruded)

Returns a 3D view of a 2D Function on the extruded domain.

The 3D function resides in V x R function space, where V is the function space of the source function. The 3D function shares the data of the 2D function.

thetis.utility.extrude_mesh_sigma(mesh2d, n_layers, bathymetry_2d, z_stretch_fact=1.0, min_depth=None)

Extrudes a 2d surface mesh with bathymetry data defined in a 2d field.

Generates a uniform terrain following mesh.

Parameters:

• mesh2d – 2D mesh

• n_layers – number of vertical layers

• bathymetry – 2D Function of the bathymetry (the depth of the domain; positive downwards)

thetis.utility.form2indicator(F)

Deduce the cell-wise contributions to a functional.

Given a 0-form, multiply the integrand of each of its integrals by a \(\mathbb P0\) test function and reassemble to give an element-wise error indicator.

Note that a 0-form does not contain any firedrake.ufl_expr.TestFunctions or firedrake.ufl_expr.TrialFunctions.

Parameters:

F – the 0-form

Returns:

the corresponding error indicator field

Modified code based on https://github.com/pyroteus/goalie/blob/main/goalie/error_estimation.py

thetis.utility.get_cell_widths_2d(mesh2d)

Compute widths of mesh elements in each coordinate direction as the maximum distance between components of vertex coordinates.

thetis.utility.get_extruded_base_element(ufl_element)

Return UFL TensorProductElement of an extruded UFL element.

In case of a non-extruded mesh, returns the element itself.

thetis.utility.get_facet_areas(mesh)

Compute area of each facet of mesh. The facet areas are stored as a HDiv trace field.

NOTES:

• In the 2D case, this gives edge lengths.

• The plus sign is arbitrary and could equally well be chosen as minus.

thetis.utility.get_facet_mask(function_space, facet='bottom')

Returns the top/bottom nodes of extruded 3D elements.

Parameters:

• function_space – Firedrake FunctionSpace object

• facet (str) – ‘top’ or ‘bottom’

Note

The definition of top/bottom depends on the direction of the extrusion. Here we assume that the mesh has been extruded upwards (along positive z axis).

thetis.utility.get_functionspace(mesh, h_family, h_degree, v_family=None, v_degree=None, vector=False, tensor=False, hdiv=False, variant=None, v_variant=None, **kwargs)

thetis.utility.get_horizontal_elem_size_2d(sol2d)

Computes horizontal element size from the 2D mesh

Parameters:

sol2d – 2D Function where result is stored

thetis.utility.get_minimum_angles_2d(mesh2d)

Compute the minimum angle in each element of a triangular mesh, mesh2d, using the cosine rule. The minimum angles are outputted as a P0 field.

thetis.utility.get_zcoord_from_mesh(zcoord, solver_parameters=None)

Evaluates z coordinates from the 3D mesh

Parameters:

zcoord – scalar Function where coordinates will be stored

thetis.utility.print_function_value_range(f, comm=<mpi4py.MPI.Intracomm object>, name=None, prefix=None, format='2.3g')

Prints the min/max DOF values of a function.

print_function_value_range(f, name='myfunc', prefix='Initial')

Prints Initial myfunc 0.00 .. 0.00.

Parameters:

• comm – MPI communicator to use for the reduction

• name – Optional function name. By default uses f.name()

• prefix – Optional prefix for the output string

• format – Value formatting string

thetis.utility.read_mesh_from_checkpoint(filename_or_outputdir, mesh_name=None)

Read mesh from a hdf5 checkpoint file. :arg filename_or_outputdir: file name of the hdf5 checkpoint file,

or the output directory used in the previous run that create the checkpoint. In the latter case the mesh will be read from the first file that’s found in outputdir/hdf5/*.h5

When loading fields from a checkpoint file in a run, the mesh used in that run needs to be read from that same checkpoint file.

When multiple checkpoint files are used as model inputs which have been created in separate runs/scripts, make sure that only one of those scripts created the original mesh (by reading a .msh file or using a mesh creation utility like RectangleMesh) and all other script read their mesh from the checkpoint created by that first script. For example, a preprocessing script might read in a .msh file and interpolate and smoothen the bathymetry on that mesh and write out the result in a checkpoint. A first Thetis run should read its mesh from that checkpoint, and may then save a series of hdf5 files. A second Thetis run can then read in the mesh and bathymetry from the checkpoint of the preprocessing script, and call load_state() to pick up from the previous run.

thetis.utility.select_and_move_detectors(mesh, detector_locations, detector_names=None, maximum_distance=0.0)

Select those detectors that are within the domain and/or move them to the nearest cell centre within the domain

Parameters:

• mesh – Defines the domain in which detectors are to be located

• detector_locations – List of x, y locations

• detector_names – List of detector names (optional). If provided, a list of selected locations and a list of selected detector names are returned, otherwise only a list of selected locations is returned

• maximum_distance – Detectors whose initial locations is outside the domain, but for which the nearest cell centre is within the specified distance, are moved to this location. By default a maximum distance of 0.0 is used, i.e no detectors are moved.

thetis.utility.tensor_jump(v, n)

Jump term for vector functions based on the tensor product

\[\text{jump}(\mathbf{u}, \mathbf{n}) = (\mathbf{u}^+ \mathbf{n}^+) + (\mathbf{u}^- \mathbf{n}^-)\]

This is the discrete equivalent of grad(u) as opposed to the vectorial UFL jump operator \(ufl.jump\) which represents div(u).

thetis.utility.timed_stage()

Log.Stage(cls, name) Source code at petsc4py/PETSc/Log.pyx:11

thetis.utility.unfrozen(method)

Decorator to temporarily unfreeze an object whilst one of its methods is being called.

thetis.utility3d module

Utility solvers and calculators for 3D hydrostatic ocean model

class thetis.utility3d.ALEMeshUpdater(solver)

Bases: object

Class that handles vertically moving ALE mesh

Mesh geometry is updated to match the elevation field (solver.fields.elev_2d). First the discontinuous elevation field is projected to continuous space, and this field is used to update the mesh coordinates.

This class stores the reference coordinate field and keeps track of the updated mesh coordinates. It also provides a method for computing the mesh velocity from two adjacent elevation fields.

Parameters:

solver – FlowSolver object

compute_mesh_velocity_begin()

Stores the current 2D elevation state as the “old” field

compute_mesh_velocity_finalize(c=1.0, w_mesh_surf_expr=None)

Computes mesh velocity from the elevation difference

Stores the current 2D elevation state as the “new” field, and computes w_mesh using the given time step factor c.

initialize()

Set values for initial mesh (elevation at rest)

update_elem_height()

Updates vertical element size fields

update_mesh_coordinates()

Updates 3D mesh coordinates to match current elev_2d field

elev_2d is first projected to continous space

class thetis.utility3d.DensitySolver(salinity, temperature, density, eos_class)

Bases: object

Computes density from salinity and temperature using the equation of state.

Water density is defined as

\[\rho = \rho'(T, S, p) + \rho_0\]

This method computes the density anomaly \(\rho'\).

Density is computed point-wise assuming that temperature, salinity and density are in the same function space.

Parameters:

• salinity (Function) – water salinity field

• temperature (Function) – water temperature field

• density (Function) – water density field

• eos_class (EquationOfState) – equation of state that defines water density

solve()

Compute density

class thetis.utility3d.DensitySolverWeak(salinity, temperature, density, eos_class)

Bases: object

Computes density from salinity and temperature using the equation of state.

Water density is defined as

\[\rho = \rho'(T, S, p) + \rho_0\]

This method computes the density anomaly \(\rho'\).

Density is computed in a weak sense by projecting the analytical expression on the density field.

Parameters:

• salinity (Function) – water salinity field

• temperature (Function) – water temperature field

• density (Function) – water density field

• eos_class (EquationOfState) – equation of state that defines water density

ensure_positive_salinity()

make sure salinity is not negative

some EOS depend on sqrt(salt).

solve()

Compute density

class thetis.utility3d.EquationOfState

Bases: ABC

Base class of all equation of state objects

abstract compute_rho(s, th, p, rho0=0.0)

Compute sea water density.

Parameters:

• s (float or numpy.array) – Salinity expressed on the Practical Salinity Scale 1978

• th (float or numpy.array) – Potential temperature in Celsius, referenced to pressure p_r = 0 dbar.

• p (float or numpy.array) – Pressure in decibars (1 dbar = 1e4 Pa)

• rho0 (float) – Optional reference density. If provided computes \(\rho' = \rho(S, Th, p) - \rho_0\)

Returns:

water density

Return type:

float or numpy.array

All pressures are gauge pressures: they are the absolute pressures minus standard atmosperic pressure 10.1325 dbar.

abstract eval(s, th, p, rho0=0.0)

Compute sea water density.

class thetis.utility3d.ExpandFunctionTo3d(input_2d, output_3d, elem_height=None)

Bases: object

Copy a 2D field to 3D

Copies a field from 2D mesh to 3D mesh, assigning the same value over the vertical dimension. Horizontal function spaces must be the same.

U = FunctionSpace(mesh, 'DG', 1)
U_2d = FunctionSpace(mesh2d, 'DG', 1)
func2d = Function(U_2d)
func3d = Function(U)
ex = ExpandFunctionTo3d(func2d, func3d)
ex.solve()

Parameters:

• input_2d (Function) – 2D source field

• output_3d (Function) – 3D target field

• elem_height – scalar Function in 3D mesh that defines the vertical element size. Needed only in the case of HDiv function spaces.

solve()

class thetis.utility3d.JackettEquationOfState

Bases: EquationOfState

Equation of State according of Jackett et al. (2006) for computing sea water density.

(20)\[\rho = \rho'(T, S, p) + \rho_0\]

\(\rho'(T, S, p)\) is a nonlinear rational function.

Jackett et al. (2006). Algorithms for Density, Potential Temperature, Conservative Temperature, and the Freezing Temperature of Seawater. Journal of Atmospheric and Oceanic Technology, 23(12):1709-1728. http://dx.doi.org/10.1175/JTECH1946.1

a = array([ 9.99840854e+02,  7.34716259e+00, -5.32112318e-02,  3.64924391e-04,         2.58805710e+00, -6.71682828e-03,  1.92032021e-03,  1.17982637e-02,         9.89202193e-08,  4.69966428e-06, -2.58621871e-08, -3.29214140e-12])

b = array([ 1.00000000e+00,  7.28152101e-03, -4.47872655e-05,  3.38510030e-07,         1.36512024e-10,  1.76321267e-03, -8.80665833e-06, -1.88326894e-10,         5.74637767e-06,  1.47162755e-09,  6.71032463e-06, -2.44616980e-17,        -9.15344176e-18])

compute_rho(s, th, p, rho0=0.0)

Compute sea water density.

Parameters:

• s (float or numpy.array) – Salinity expressed on the Practical Salinity Scale 1978

• th (float or numpy.array) – Potential temperature in Celsius, referenced to pressure p_r = 0 dbar.

• p (float or numpy.array) – Pressure in decibars (1 dbar = 1e4 Pa)

• rho0 (float) – Optional reference density. If provided computes \(\rho' = \rho(S, Th, p) - \rho_0\)

Returns:

water density

Return type:

float or numpy.array

All pressures are gauge pressures: they are the absolute pressures minus standard atmosperic pressure 10.1325 dbar.

eval(s, th, p, rho0=0.0)

Compute sea water density.

class thetis.utility3d.LinearEquationOfState(rho_ref, alpha, beta, th_ref, s_ref)

Bases: EquationOfState

Linear Equation of State for computing sea water density

\[\rho = \rho_{ref} - \alpha (T - T_{ref}) + \beta (S - S_{ref})\]

Parameters:

• rho_ref (float) – reference density

• alpha (float) – thermal expansion coefficient

• beta (float) – haline contraction coefficient

• th_ref (float) – reference temperature

• s_ref (float) – reference salinity

compute_rho(s, th, p, rho0=0.0)

Compute sea water density.

Parameters:

• s (float or numpy.array) – Salinity expressed on the Practical Salinity Scale 1978

• th (float or numpy.array) – Potential temperature in Celsius

• p (float or numpy.array) – Pressure in decibars (1 dbar = 1e4 Pa)

• rho0 (float) – Optional reference density. If provided computes \(\rho' = \rho(S, Th, p) - \rho_0\)

Returns:

water density

Return type:

float or numpy.array

Pressure is ingored in this equation of state.

eval(s, th, p, rho0=0.0)

Compute sea water density.

class thetis.utility3d.Mesh3DConsistencyCalculator(solver_obj)

Bases: object

Computes a hydrostatic consistency criterion metric on the 3D mesh.

Let \(\Delta x\) and \(\Delta z\) denote the horizontal and vertical element sizes. The hydrostatic consistency criterion (HCC) can then be expressed as

\[R = \frac{|\nabla h| \Delta x}{\Delta z} < 1\]

where \(\nabla h\) is the bathymetry gradient (or gradient of the internal horizontal facet).

Violating the hydrostatic consistency criterion leads to internal pressure gradient errors. In practice one can violate the \(R < 1\) condition without jeopardizing numerical stability; typically \(R < 5\). Mesh consistency can be improved by coarsening the vertical mesh, refining the horizontal mesh, or smoothing the bathymetry.

For a 3D prism, let \(\delta z_t,\delta z_b\) denote the maximal \(z\) coordinate difference in the surface and bottom facets, respectively, and \(\Delta z\) the height of the prism. We can then compute \(R\) for the two facets as

\[\begin{split}R_t &= \frac{\delta z_t}{\Delta z} \\ R_b &= \frac{\delta z_b}{\Delta z}\end{split}\]

For a straight prism we have \(R = 0\), and \(R = 1\) in the case where the highest bottom node is at the same level as the lowest surface node.

Parameters:

solver_obj – FlowSolver object

solve()

Compute the HCC metric

class thetis.utility3d.SmagorinskyViscosity(uv, output, c_s, h_elem_size, max_val, min_val=1e-10, weak_form=True, solver_parameters=None)

Bases: object

Computes Smagorinsky subgrid scale horizontal viscosity

This formulation is according to Ilicak et al. (2012) and Griffies and Hallberg (2000).

\[\nu = (C_s \Delta x)^2 |S|\]

with the deformation rate

\[\begin{split}|S| &= \sqrt{D_T^2 + D_S^2} \\ D_T &= \frac{\partial u}{\partial x} - \frac{\partial v}{\partial y} \\ D_S &= \frac{\partial u}{\partial y} + \frac{\partial v}{\partial x}\end{split}\]

\(\Delta x\) is the horizontal element size and \(C_s\) is the Smagorinsky coefficient.

To match a certain mesh Reynolds number \(Re_h\) set \(C_s = 1/\sqrt{Re_h}\).

Ilicak et al. (2012). Spurious dianeutral mixing and the role of momentum closure. Ocean Modelling, 45-46(0):37-58. http://dx.doi.org/10.1016/j.ocemod.2011.10.003

Griffies and Hallberg (2000). Biharmonic friction with a Smagorinsky-like viscosity for use in large-scale eddy-permitting ocean models. Monthly Weather Review, 128(8):2935-2946. http://dx.doi.org/10.1175/1520-0493(2000)128%3C2935:BFWASL%3E2.0.CO;2

Parameters:

• uv_3d (3D vector Function) – horizontal velocity

• output (3D scalar Function) – Smagorinsky viscosity field

• c_s (float or Constant) – Smagorinsky coefficient

• h_elem_size (3D scalar Function or Constant) – field that defines the horizontal element size

• max_val (float) – Maximum allowed viscosity. Viscosity will be clipped at this value.

• min_val (float) – Minimum allowed viscosity. Viscosity will be clipped at this value.

• weak_form (bool) – Compute velocity shear by integrating by parts. Necessary for some function spaces (e.g. P0).

• solver_parameters (dict) – PETSc solver options

solve()

Compute viscosity

class thetis.utility3d.SubFunctionExtractor(input_3d, output_2d, boundary='top', elem_facet=None, elem_height=None)

Bases: object

Extract a 2D sub-function from a 3D function in an extruded mesh

Given 2D and 3D functions,

U = FunctionSpace(mesh, 'DG', 1)
U_2d = FunctionSpace(mesh2d, 'DG', 1)
func2d = Function(U_2d)
func3d = Function(U)

Get surface value:

ex = SubFunctionExtractor(func3d, func2d,
    boundary='top', elem_facet='top')
ex.solve()

Get bottom value:

ex = SubFunctionExtractor(func3d, func2d,
    boundary='bottom', elem_facet='bottom')
ex.solve()

Get value at the top of bottom element:

ex = SubFunctionExtractor(func3d, func2d,
    boundary='bottom', elem_facet='top')
ex.solve()

Parameters:

• input_3d (Function) – 3D source field

• output_2d (Function) – 2D target field

• boundary (str) – ‘top’|’bottom’ Defines whether to extract from the surface or bottom 3D elements

• elem_facet (str) – ‘top’|’bottom’|’average’ Defines which facet of the 3D element is extracted. The ‘average’ computes mean of the top and bottom facets of the 3D element.

• elem_height – scalar Function in 2D mesh that defines the vertical element size. Needed only in the case of HDiv function spaces.

solve()

class thetis.utility3d.VelocityMagnitudeSolver(solution, u=None, w=None, min_val=1e-06, solver_parameters=None)

Bases: object

Computes magnitude of (u[0],u[1],w) and stores it in solution

Parameters:

• solution (Function) – scalar field for velocity magnitude scalar Function

• u (Function) – horizontal velocity

• w (Function) – vertical velocity

• min_val (float) – minimum value of magnitude. Minimum value of solution will be clipped to this value

• solver_parameters (dict) – PETSc solver options

If u is None computes magnitude of (0,0,w).

If w is None computes magnitude of (u[0],u[1],0).

solve()

Compute the magnitude

class thetis.utility3d.VerticalIntegrator(input, output, bottom_to_top=True, bnd_value=Constant([0.], 5), average=False, bathymetry=None, elevation=None, solver_parameters=None)

Bases: object

Computes vertical integral (or average) of a field.

Parameters:

• input – 3D field to integrate

• output – 3D field where the integral is stored

• bottom_to_top – Defines the integration direction: If True integration is performed along the z axis, from bottom surface to top surface.

• bnd_value – Value of the integral at the bottom (top) boundary if bottom_to_top is True (False)

• average – If True computes the vertical average instead. Requires bathymetry and elevation fields

• bathymetry – 3D field defining the bathymetry

• elevation – 3D field defining the free surface elevation

• solver_parameters (dict) – PETSc solver options

solve()

Computes the integral and stores it in the output field.

class thetis.utility3d.VerticalVelocitySolver(solution, uv, bathymetry, boundary_funcs={}, solver_parameters=None)

Bases: object

Computes vertical velocity diagnostically from the continuity equation

Vertical velocity is obtained from the continuity equation

(21)\[\frac{\partial w}{\partial z} = -\nabla_h \cdot \textbf{u}\]

and the bottom impermeability condition (\(h\) denotes the bathymetry)

\[\begin{split}\textbf{n}_h \cdot \textbf{u} + w n_z &= 0 \quad \forall \mathbf{x} \in \Gamma_{b} \\ \Leftrightarrow w &= -\nabla_h h \cdot \mathbf{u} \quad \forall \mathbf{x} \in \Gamma_{b}\end{split}\]

\(w\) can be solved with the weak form

\[\begin{split}\int_{\Gamma_s} w n_z \varphi dS + \int_{\mathcal{I}_h} \text{avg}(w) \text{jump}(\varphi n_z) dS - \int_{\Omega} w \frac{\partial \varphi}{\partial z} dx = \\ \int_{\Omega} \mathbf{u} \cdot \nabla_h \varphi dx - \int_{\mathcal{I}_h \cup \mathcal{I}_v} \text{avg}(\mathbf{u}) \cdot \text{jump}(\varphi \mathbf{n}_h) dS - \int_{\Gamma_s} \mathbf{u} \cdot \varphi \mathbf{n}_h dS\end{split}\]

where the \(\Gamma_b\) terms vanish due to the bottom impermeability condition.

Parameters:

• solution – w Function

• uv – horizontal velocity Function

• bathymetry – bathymetry Function

• boundary_funcs (dict) – boundary conditions used in the 3D momentum equation. Provides external values of uv (if any).

• solver_parameters (dict) – PETSc solver options

solve()

Compute w

thetis.utility3d.get_horizontal_elem_size_3d(sol2d, sol3d)

Computes horizontal element size from the 2D mesh, then copies it on a 3D field

Parameters:

• sol2d – 2D Function for the element size field

• sol3d – 3D Function for the element size field

Module contents

thetis.timed_stage()

Log.Stage(cls, name) Source code at petsc4py/PETSc/Log.pyx:11