space

Geometry and variables of the model.

This module contains the objects that are used in Tunax to describe the geometry of the water column in Grid, the variables of the water column at one time-step in State and the time- series of the model computation in Trajectory. These classes can be obtained by the prefix tunax.space. or directly by tunax..

ArrNz

Type that describes a float Array of shape (nz).

ArrNzp1

Type that describes a float Array of shape (nz+1).

ArrNt

Type that describes a float Array of shape (nt).

ArrNzNt

Type that describes a float Array of shape (nz, nt).

TRACERS_NAMES: List[str] = ['t', 's', 'b', 'pt']

Names of the tracers, in the order of temperature, salinity, buoyancy and passive tracer.

VARIABLE_NAMES: List[str] = ['u', 'v', 't', 's', 'b', 'pt']

Names of all the variables, zonal and meridionnal velocities in addition of the tracers.

VARIABLE_SHAPES: Dict[str, str] = {'b': 'zr', 'pt': 'zr', 's': 'zr', 't': 'zr', 'u': 'zr', 'v': 'zr'}

Shapes of all the variables on the water column.

class Grid

One dimensional spatial geometry of a water column.

This mesh is made up of a number of nz of cells (zr) of potentially varying thickness (hz), separated by interface points (zw) and extending from the ocean surface at a depth of \(0\) to the ocean floor at a depth of hbot.

Parameters:

• zr (float Array of shape (nz)) – cf. zr.

• zw (float Array of shape (nz+1)) – cf. zw.

nz

Number of cells.

Type:

int

hbot

Depth of the water column \([\text m]\).

Type:

float

zr

Depths of cell centers from deepest to shallowest \([\text m]\)

Type:

float Array of shape (nz)

zw

Depths of cell interfaces from deepest to shallowest \([\text m]\).

Type:

float Array of shape (nz+1)

hz

Thickness of cells from deepest to shallowest \([\text m]\).

Type:

float Array of shape (nz)

Note

The constructor __init__ takes only zr and zw as as arguments and construct the other attributes from them. The centers of the cells zr are not necessarly the middle between the interfaces zw but should be between.

find_index(h)

Find the index of a depth.

Find the index i so that the depth h is in cell i, which means \(z^w_i \leqslant -h \leqslant z^w_{i+1}\) if \(h \leqslant 0\) and \(i=-1\) if \(h>0\).

Parameters:

h (float, positive) – The depth to search the index \([\text m]\).

Returns:

i – The index corresponding to the depth h.

Return type:

int

classmethod linear(nz, hbot)

Creates a grid with equal thickness cells.

The grid instance will have nz cells of equal thickness for a depth of hbot.

Parameters:

• nz (int) – Number of cells.

• hbot (float, positive) – Depth of the water column \([\text m]\).

Returns:

grid – The linear grid.

Return type:

Grid

classmethod analytic(nz, hbot, hc, theta=6.5)

Creates a grid of type analytic.

The grid instance will have a depth of hbot and nz cells of thickness almost equals above hc and wider under, the strecht parameter being defined by theta.

Parameters:

• nz (int) – Number of cells.

• hbot (float, positive) – Depth of the water column \([\text m]\).

• hc (float, positive) – Reference depth \([\text m]\).

• theta (float, default=6.5) – Stretching parameter toward the surface \([\text{dimensionless}]\).

Returns:

grid – The analytic grid.

Return type:

Grid

classmethod orca75(hbot)

Creates the ORCA75 grid from NEMO.

The whole grid is created then levels between the depth hbot and \(0\) are extracted.

Parameters:

hbot (float, positive) – Depth of the water column \([\text m]\).

Returns:

grid – The ORCA75 grid.

Return type:

Grid

classmethod load(ds)

Creates the grid defined by a dataset ds of an observation.

The dataset must be formated to have the variables corresponding to zr and zw.

Parameters:

ds (xarray.Dataset) – Dataset from which to extract the grid.

Returns:

grid – The loaded grid.

Return type:

Grid

class State

Water column state at one time-step.

This state is defined on a grid describing the geometry, and is composed of the variables of the water column : the values of the momentum variables u and v (which are mandatory) and the tracers variables t, s, b and pt (which are optionals). The constructor takes all the attributes as parameters.

grid

Geometry of the water column.

Type:

Grid

u

Zonal velocity on the center of the cells \(\left[\text m \cdot \text s^{-1}\right]\).

Type:

float Array of shape (nz)

v

Meridional velocity on the center of the cells \(\left[\text m \cdot \text s^{-1}\right]\).

Type:

float Array of shape (nz)

t

Temperature on the center of the cells \([° \text C]\).

Type:

float Array of shape (nz), optionnal, default=None

s

Salinity on the center of the cells \([\text{psu}]\).

Type:

float Array of shape (nz), optionnal, default=None

b

Buoyancy on the center of the cells \([\text{dimensionless}]\).

Type:

float Array of shape (nz), optionnal, default=None

pt

A passive tracer on the center of the cells \([\text{dimensionless}]\).

Type:

float Array of shape (nz), optionnal, default=None

classmethod zeros(grid, tracers)

Initialize an instance with all variables equals to zero from a grid.

Parameters:

• grid (Grid) – Geometry of the water column.

• tracers (List[str])

Returns:

state – An instance defined on the grid with all variables set to 0.

Return type:

State

init_u(hmxl=20.0, u_sfc=0.0)

Initialize zonal velocity with a classical wind stratification.

Return a State object where u is continuous and linear by part \(u(z) = \begin{cases} 0 & \text{if } z < h_{\text{mxl}}\\ u_{\text{sfc}} \left( 1 - \dfrac z {h_{\text{mxl}}}\right) & \text{else} \end{cases}\)

Parameters:

• hmxl (float, default=20.) – Mixed layer depth \([\text m]\).

• u_sfc (float, default=0.) – Surface zonal velocity \(\left[\text m \cdot \text s^{-1}\right]\).

Returns:

state – The self object with the the new value of zonal velocity.

Return type:

State

init_v(hmxl=20.0, v_sfc=0.0)

Initialize meridional velocity with a classical wind stratification.

Return a State object where v is continuous and linear by part \(v(z) = \begin{cases} 0 & \text{if } z < h_{\text{mxl}}\\ v_{\text{sfc}} \left( 1 - \dfrac z {h_{\text{mxl}}}\right) & \text{else} \end{cases}\)

Parameters:

• hmxl (float, default=20.) – Mixed layer depth \([\text m]\).

• u_sfc (float, default=0.) – Surface meridional velocity \(\left[\text m \cdot \text s^{-1}\right]\).

• v_sfc (float)

Returns:

state – The self object with the the new value of meridional velocity.

Return type:

State

init_t(hmxl=20.0, t_sfc=21.0, strat_t=0.051)

Initialize temperature with a classical tracer stratification.

Return a State object where t is linear by part and continous \(T(z) = \begin{cases} t_{\text{sfc}} + S_T(z-h_{\text{mxl}}) & \text{if } z < h_{\text{mxl}}\\ t_{\text{sfc}} & \text{else} \end{cases}\)

Parameters:

• hmxl (float, default=20.) – Mixed layer depth \([\text m]\).

• t_sfc (float, default=21.) – Surface temperature \([° \text C]\).

• strat_t (float, default=5.1e-2) – Thermal stratification above the mixed layer noted by \(S_T\) \([\text K \cdot \text m ^{-1}]\).

Returns:

state – The self object with the the new value of temperature.

Return type:

State

init_s(hmxl=20.0, s_sfc=35.0, strat_s=0.013)

Initialize salinity with a classical tracer stratification.

Return a State object where s is linear by part and continous \(S(z) = \begin{cases} s_{\text{sfc}} + S_S(z-h_{\text{mxl}}) & \text{if } z < h_{\text{mxl}}\\ s_{\text{sfc}} & \text{else} \end{cases}\)

Parameters:

• hmxl (float, default=20.) – Mixed layer depth \([\text m]\).

• s_sfc (float, default=21.) – Surface salinity \([\text{psu}]\).

• strat_s (float, default=5.1e-2) – Salinity stratification above the mixed layer noted by \(S_T\) \([\text{psu} \cdot \text m ^{-1}]\).

Returns:

state – The self object with the the new value of temperature.

Return type:

State

class Trajectory

Define the history of a simulation or an observation.

Contains the timeseries of the momentum (mandatory) variables and the tracers variables (optionals) throught the space of the grid and the time. The constructor takes all the attributes as parameters.

grid

Geometry of the water column.

Type:

Grid

time

Time at each steps of observation from the begining of the simulation \([\text s]\).

Type:

float Array of shape (nt)

u

Time-serie of zonal velocity \(\left[\text m \cdot \text s^{-1}\right]\).

Type:

float Array of shape (nz, nt)

v

Time-serie of meridional velocity \(\left[\text m \cdot \text s^{-1}\right]\).

Type:

float Array of shape (nz, nt)

t

Time-serie of temperature \([\text C°]\).

Type:

float Array of shape (nz, nt), optionnal, default=None

s

Time-serie of salinity \([\text{psu}]\).

Type:

float Array of shape (nz, nt), optionnal, default=None

b

Time-serie of buoyancy \([\text{dimensionless}]\).

Type:

float Array of shape (nz, nt), optionnal, default=None

pt

Time-serie a passive tracer \([\text{dimensionless}]\).

Type:

float Array of shape (nz, nt), optionnal, default=None

to_ds()

Exports the trajectory in an xarray.Dataset.

The dimensions of the dataset are time, grid.zr and grid.zw, the variables are u, v and the tracers that are not set to None, all defined on the dimensions (time, zr) or zw depending on VARIABLE_NAMES.

Returns:

ds – Dataset of the trajectory.

Return type:

xarray.Dataset

to_nc(nc_path)

Write on a NetCDF file.

The dimensions are time, grid.zr and grid.zw, the variables are u, v and the tracers that are not set to None, all defined on the dimensions (time, zr) or zw depending on VARIABLE_NAMES.

Parameters:

nc_path (str) – Path of the file on which write the trajectory.

Return type:

None

extract_state(i_time)

Extracts the water column state at one time index.

Parameters:

i_time (int) – The time index of the moment to extract the state.

Returns:

state – The state of the trajectory at the time of index i_time.

Return type:

State

cut(out_nt_cut)

Cut the trajectory in sub-trajectories of out_nt_cut output steps.

The first and last state of two consecutive trajectories are the same. out_nt_cut is the number of output steps, it means that the time dimension of the sub-trajectories have out_nt_cut+1 elements.

Parameters:

out_nt_cut (int) – Number of output steps of the sub-trajectories.

Returns:

traj_list – List of the sub-trajectories in the chronological order.

Return type:

List[Trajectory]

Warns:

Lost last trajectory – If out_nt_cut does not divide the number of output step of the initial trajectory. In this case the last part of the trajectory (which is too short) is abandonned.