FieldBase

class fridom.framework.field_base.FieldBase(mset: fr.ModelSettingsBase)

Bases: object

Base class for all types of fields.

Description

A field is a mathematical mapping from the grid space \(\Omega\) to an abstract space \(\mathcal{F}\). This abstract space can for example be the real or complex numbers for scalar fields, or the space of vectors or tensors for vector or tensor fields.

This base class defines the interface for all types of fields.

Parameters

msetfr.ModelSettingsBase

The model settings.

__init__(mset: fr.ModelSettingsBase) → None

Methods

__init__(mset)
abs()	Map the field by taking the absolute value (\(|f|\)).
apply_water_mask()	Apply a water mask to the field.
conj()	Compute the complex conjugate.
cumulative_integral(axis[, direction])	Compute the cumulative integral along an axis.
diff(axis[, order])	Compute the partial derivative along an axis.
div()	Compute the divergence.
dot(other)	Compute the dot product with another field.
extend(topo)	Extend the field in the specified directions.
fft([padding])	Perform a Fast Fourier Transform (FFT) on the field.
from_netcdf(mset, path)	Create a field from a NetCDF file.
from_xarray(mset, ds)	Create a field from an xarray object.
grad([axes])	Compute the gradient.
has_nan()	Check if the field contains NaN values.
ifft([padding])	Perform an Inverse Fast Fourier Transform (IFFT) on the field.
integrate([axes])	Global integral of the Field in specified axes.
laplacian([axes])	Compute the Laplacian.
max([axes])	Maximum value of the Field over the whole domain.
mean([axes])	Global mean of the Field in specified axes.
min([axes])	Minimum value of the Field over the whole domain.
norm_l2()	Calculate the L2 norm of the field.
set_random([seed])	Set the field to random values.
sum([axes])	Sum of the Field over the whole domain in the specified axes.
sync()	Synchronize the field across all MPI ranks and apply boundary conditions.
to_netcdf(path)	Save the field to a NetCDF file.

Attributes

grid	The grid object.
info	Dictionary with information about the field.
is_constant	Flag indicating whether the field is constant.
is_spectral	Flag indicating whether the field is in spectral space.
mset	The model settings.
xr	The xarray representation of the field.
xrs	Convert a slice of the field to an xarray object.

Examples using fridom.framework.FieldBase

Barotropic Jet

Barotropic Jet

Convection and Closures

Convection and Closures

Dancing Eddies

Dancing Eddies

Rayleigh-Bénard Convection

Rayleigh-Bénard Convection

Rayleigh-Taylor Instability

Rayleigh-Taylor Instability

Single Internal Wave

Single Internal Wave

Symmetric Instability

Symmetric Instability

Tracers and Eddies

Tracers and Eddies

Reflecting Wave Package

Reflecting Wave Package

Barotropic Instability.

Barotropic Instability.

Equatorial Waves.

Equatorial Waves.

abstract fft(padding: FFTPadding = FFTPadding.NOPADDING) → T

Perform a Fast Fourier Transform (FFT) on the field.

Description

Computes the Fast Fourier Transform (FFT) of the field. The padding parameter can be used to specify the zero-padding strategy.

Parameters

paddingfr.grid.FFTPadding

The padding strategy.

Returns

FieldBase

The FFT of the field.

abstract ifft(padding: FFTPadding = FFTPadding.NOPADDING) → T

Perform an Inverse Fast Fourier Transform (IFFT) on the field.

Description

Computes the Inverse Fast Fourier Transform (IFFT) of the field. The padding parameter can be used to specify the zero-padding strategy.

Parameters

paddingfr.grid.FFTPadding

The padding strategy.

Returns

FieldBase

The IFFT of the field.

abstract sync() → T

Synchronize the field across all MPI ranks and apply boundary conditions.

Description

This method synchronizes the field across all MPI ranks and applies the boundary conditions. This is necessary to ensure that the ghost cells are up-to-date. This method changes the field in-place, but also returns the synchronized field.

Returns

FieldBase

The synchronized field.

abstract apply_water_mask() → T

Apply a water mask to the field.

Description

A water mask is a binary field that indicates which cells are water (active) and which are land (inactive). This method applies the water mask to the field. The field is changed in-place.

Returns

FieldBase

The field with the water mask applied.

abstract has_nan() → bool

Check if the field contains NaN values.

Returns

bool

Flag indicating whether the field contains NaN values.

abstract set_random(seed: int = 1234) → T

Set the field to random values.

Description

This method sets the field to random values. If the field is in spectral space, the random values are complex.

Parameters

seedint

The seed for the random number generator.

Returns

FieldBase

The field with random values.

abstract diff(axis: int, order: int = 1) → T

Compute the partial derivative along an axis.

\[\partial_i^n f\]

with axis \(i\) and order \(n\).

Parameters

axisint

The axis along which to differentiate.

orderint

The order of the derivative. Default is 1.

Returns

fr.ScalarField | fr.VectorField | fr.TensorField

The derivative of the field along the specified axis.

abstract grad(axes: list[int] | None = None) → fr.VectorField | fr.TensorField

Compute the gradient.

\[\begin{split}\nabla f = \begin{pmatrix} \partial_1 f \\ \dots \\ \partial_n f \end{pmatrix}\end{split}\]

Parameters

axeslist[int] | None (default is None)

The axes along which to compute the gradient. If None, the gradient is computed along all axes.

Returns

fr.VectorField | fr.TensorField

The gradient of the field along the specified axes. The list contains the gradient components along each axis. Axis which are not included in axes will have a value of None. E.g. for a 3D grid, diff.grad(f, axes=[0, 2]) will return [df/dx, None, df/dz].

abstract laplacian(axes: tuple[int] | None = None) → T

Compute the Laplacian.

\[\nabla^2 f = \sum_{i=1}^n \partial_i^2 f\]

Parameters

axestuple[int] | None (default is None)

The axes along which to compute the Laplacian. If None, the Laplacian is computed along all axes.

Returns

fr.ScalarField | fr.VectorField | fr.TensorField

The Laplacian of the field.

abstract div() → fr.ScalarField | fr.VectorField

Compute the divergence.

\[\nabla \cdot f = \sum_{i=1}^n \partial_i f\]

Returns

fr.ScalarField | fr.VectorField

The divergence of the field.

abstract cumulative_integral(axis: int, direction: Literal['forward', 'backward'] = 'forward') → T

Compute the cumulative integral along an axis.

Description

The cumulative integral computes the integral starting at one end of the domain and accumulates the integral along the specified axis. The integral is computed in either the forward or backward direction.

Forward integral:

\[\int_{x_0}^{x} f(x') dx'\]

with axis \(x\) and \(x_0\) the lower bound of the domain.

Backward integral:

\[\int_{x}^{x_1} f(x') dx'\]

with axis \(x\) and \(x_1\) the upper bound of the domain.

Parameters

axisint

The axis along which to integrate.

directionstr (default is “forward”)

The direction of the integration. Can be “forward” or “backward”.

Returns

fr.ScalarField | fr.VectorField | fr.TensorField

The cumulative integral of the field along the specified axis.

abstract property xr: xr.DataArray | xr.Dataset

The xarray representation of the field.

Returns

xr.DataArray | xr.Dataset

The xarray representation of the field.

abstract property xrs: fr.utils.SliceableAttribute[xr.DataArray | xr.Dataset]

Convert a slice of the field to an xarray object.

Description

This method returns a sliceable attribute that allows to convert a slice of the field to an xarray object. This is useful when dealing with large fields and only a subset of the data is needed. For example, the top region of the field.

abstract classmethod from_xarray(mset: fr.ModelSettingsBase, ds: xr.DataArray | xr.Dataset) → T

Create a field from an xarray object.

Description

This method creates a field from an xarray object. The model settings are required to create the field.

Parameters

msetfr.ModelSettingsBase

The model settings.

dsxr.DataArray | xr.Dataset

The xarray object.

Returns

FieldBase

The field.

to_netcdf(path: str) → None

Save the field to a NetCDF file.

Description

This method saves the field to a NetCDF file.

Parameters

pathstr

The path to the NetCDF file.

classmethod from_netcdf(mset: fr.ModelSettingsBase, path: str) → T

Create a field from a NetCDF file.

Parameters

msetfr.ModelSettingsBase

The model settings.

pathstr

The path to the NetCDF file.

Returns

FieldBase

The field.

abstract property info: dict

Dictionary with information about the field.

property mset: fr.ModelSettingsBase

The model settings.

property grid: fr.grid.GridBase

The grid object.

abstract property is_spectral: bool

Flag indicating whether the field is in spectral space.

abstract property is_constant: bool

Flag indicating whether the field is constant.

abstract extend(topo: tuple[bool]) → T

Extend the field in the specified directions.

Description

This method extends the field in the specified directions. The field can be extended in any direction, but it cannot be shrunk. This means that if the field is extended in a direction, it has to be extended in all directions. Values in the extended directions are copied from the original field, such that:

\[f_{\text{new}}(x, y, z) = f_{\text{old}}(x, y)\]

where \(f_{\text{new}}\) is the new field extended in (x, y, z), and \(f_{\text{old}}\) is the old field, extended in (x, y).

Parameters

topotuple[bool]

The new topology of the field.

Returns

FieldBase

The extended field.

Raises

ValueError

If the field is shrunk in any direction.

abstract sum(axes: tuple[int] | None = None) → T

Sum of the Field over the whole domain in the specified axes.

Description

This method computes the sum of the Field over the whole domain (across all processes) in the specified axes. If no axes are specified, the sum is computed over all axes.

Note

We recommend using the f.integrate() method to integrate the field in certain directions. The integrate() method takes the grid spacing into account while the sum() method does not.

Parameters

axestuple[int] | None

The axes to sum over. If None, sum over all axes.

Returns

FieldBase

The sum of the field. The returned field has no extend in the specified axes.

abstract max(axes: tuple[int] | None = None) → T

Maximum value of the Field over the whole domain.

Description

This method computes the maximum value of the Field over the whole domain (across all processes) in the specified axes. If no axes are specified, the maximum is computed over all axes.

Parameters

axestuple[int] | None

The axes to compute the maximum over. If None, compute the maximum over all axes.

Returns

FieldBase

The maximum value of the Field over the specified axes. The returned field has no extend in the specified axes.

abstract min(axes: tuple[int] | None = None) → T

Minimum value of the Field over the whole domain.

Description

This method computes the minimum value of the Field over the whole domain (across all processes) in the specified axes. If no axes are specified, the minimum is computed over all axes.

Parameters

axestuple[int] | None

The axes to compute the minimum over. If None, compute the minimum over all axes.

Returns

FieldBase

The minimum value of the Field over the specified axes. The returned field has no extend in the specified axes.

abstract integrate(axes: tuple[int] | None = None) → T

Global integral of the Field in specified axes.

Description

Computes the global integral of the Field in the specified axes:

\[\sum_{i} \int_{x_i} f(\boldsymbol{x}) dx_i\]

If no axes are specified, the integral is computed over all axes.

Parameters

axestuple[int] | None

The axes to integrate over. If None, integrate over all axes.

Returns

FieldBase

The integral of the Field over the specified axes.

abstract mean(axes: tuple[int] | None = None) → T

Global mean of the Field in specified axes.

Description

Computes the global mean of the Field in the specified axes:

\[\frac{\sum_{i} \int_{x_i} f(\boldsymbol{x}) dx_i} {\sum_{i} \int_{x_i} dx_i}\]

If no axes are specified, the mean is computed over all axes.

Parameters

axestuple[int] | None

The axes to compute the mean over. If None, compute the mean over all axes.

Returns

FieldBase

The mean of the Field over the specified axes.

abstract dot(other: FieldBase) → FieldBase

Compute the dot product with another field.

Parameters

otherFieldBase

The other field.

Returns

FieldBase

The dot product.

Description

Computes the dot product with another field. The dot product is defined as

\[f \cdot g^*\]

where \(f\) and \(g\) are the fields and \(^*\) denotes the complex conjugate.

The return value depends on the type of the fields. The following table shows the possible return values:

Field Type	Field Type	Return Type
ScalarField	ScalarField	ScalarField
ScalarField	VectorField	VectorField
ScalarField	TensorField	TensorField
VectorField	ScalarField	VectorField
VectorField	VectorField	ScalarField
VectorField	TensorField	Error
TensorField	ScalarField	TensorField
TensorField	VectorField	VectorField
TensorField	TensorField	TensorField

abstract conj() → T

Compute the complex conjugate.

Returns

FieldBase

The complex conjugate. If the field is real, the field itself is returned.

abstract abs() → T

Map the field by taking the absolute value (\(|f|\)).

Returns

FieldBase

The absolute value of the field.

norm_l2() → float

Calculate the L2 norm of the field.

Description

The L2 norm of the vector field \(\boldsymbol{z}\) is defined as:

\[||f||_2 = \sqrt{\int f \cdot f \, dV\]

in practice, the integral is calculated as a sum over the grid cells and \(dV\) is the cell volume of each grid cell.

Returns

FieldBase

The L2 norm of the field