iris.analysis.calculus#

Calculus operations on iris.cube.Cube instances.

See also: NumPy.

iris.analysis.calculus.DIRECTIONAL_NAMES = (('u', 'v', 'w'), ('x', 'y', 'z'), ('i', 'j', 'k'), ('eastward', 'northward', 'upward'), ('easterly', 'northerly', 'vertical'), ('easterly', 'northerly', 'radial'))#: Acceptable X-Y-Z standard name combinations that curl() can use (via spatial_vectors_with_phenom_name()).

iris.analysis.calculus.cube_delta(cube, coord)[source]#

Given a cube calculate the difference between each value in the coord’s direction.

Parameters:: coord – Either a Coord instance or the unique name of a coordinate in the cube. If a Coord instance is provided, it does not necessarily have to exist in the cube.

Examples

change_in_temperature_wrt_pressure = cube_delta(temperature_cube, 'pressure')

Notes

Note

Missing data support not yet implemented.

Note

This function does not maintain laziness when called; it realises data. See more at Real and Lazy Data.

iris.analysis.calculus.curl(i_cube, j_cube, k_cube=None)[source]#

Calculate the 2 or 3-dimensional spherical or cartesian curl.

Calculate the 2-dimensional or 3-dimensional spherical or cartesian curl of the given vector of cubes.

The cube standard names must match one of the combinations in DIRECTIONAL_NAMES.

As well as the standard x and y coordinates, this function requires each cube to possess a vertical or z-like coordinate (representing some form of height or pressure). This can be a scalar or dimension coordinate.

Parameters:

i_cube – The i cube of the vector to operate on.
j_cube – The j cube of the vector to operate on.
k_cube (optional) – The k cube of the vector to operate on.

Return type:

List of cubes i_cmpt_curl_cube, j_cmpt_curl_cube, k_cmpt_curl_cube

Notes

If the k-cube is not passed in then the 2-dimensional curl will be calculated, yielding the result: [None, None, k_cube]. If the k-cube is passed in, the 3-dimensional curl will be calculated, returning 3 component cubes.

All cubes passed in must have the same data units, and those units must be spatially-derived (e.g. ‘m/s’ or ‘km/h’).

The calculation of curl is dependent on the type of CoordSystem() in the cube. If the CoordSystem() is either GeogCS or RotatedGeogCS, the spherical curl will be calculated; otherwise the cartesian curl will be calculated:

Cartesian curl
- When cartesian calculus is used, i_cube is the u component, j_cube is the v component and k_cube is the w component.
  
  The Cartesian curl is defined as:
  
  \[\nabla\times \vec u = (\frac{\delta w}{\delta y} - \frac{\delta v}{\delta z})\vec a_i - (\frac{\delta w}{\delta x} - \frac{\delta u}{\delta z})\vec a_j + (\frac{\delta v}{\delta x} - \frac{\delta u}{\delta y})\vec a_k\]
Spherical curl
- When spherical calculus is used, i_cube is the \(\phi\) vector component (e.g. eastward), j_cube is the \(\theta\) component (e.g. northward) and k_cube is the radial component.
  
  The spherical curl is defined as:
  
  \[\nabla\times \vec A = \frac{1}{r cos \theta} (\frac{\delta}{\delta \theta} (\vec A_\phi cos \theta) - \frac{\delta \vec A_\theta}{\delta \phi}) \vec r + \frac{1}{r}(\frac{1}{cos \theta} \frac{\delta \vec A_r}{\delta \phi} - \frac{\delta}{\delta r} (r \vec A_\phi))\vec \theta + \frac{1}{r} (\frac{\delta}{\delta r}(r \vec A_\theta) - \frac{\delta \vec A_r}{\delta \theta}) \vec \phi\]
  
  where phi is longitude, theta is latitude.

Note

This function does not maintain laziness when called; it realises data. See more at Real and Lazy Data.

iris.analysis.calculus.differentiate(cube, coord_to_differentiate)[source]#

Calculate the differential of a given cube.

Calculate the differential of a given cube with respect to the coord_to_differentiate.

Parameters:: coord_to_differentiate – Either a Coord instance or the unique name of a coordinate which exists in the cube. If a Coord instance is provided, it does not necessarily have to exist on the cube.

Examples

u_wind_acceleration = differentiate(u_wind_cube, 'forecast_time')

The algorithm used is equivalent to:

\[d_i = \frac{v_{i+1}-v_i}{c_{i+1}-c_i}\]

Where d is the differential, v is the data value, c is the coordinate value and i is the index in the differential direction. Hence, in a normal situation if a cube has a shape (x: n; y: m) differentiating with respect to x will result in a cube of shape (x: n-1; y: m) and differentiating with respect to y will result in (x: n; y: m-1). If the coordinate to differentiate is circular then the resultant shape will be the same as the input cube.

In the returned cube the coord_to_differentiate object is redefined such that the output coordinate values are set to the averages of the original coordinate values (i.e. the mid-points). Similarly, the output lower bounds values are set to the averages of the original lower bounds values and the output upper bounds values are set to the averages of the original upper bounds values. In more formal terms:

C[i] = (c[i] + c[i+1]) / 2
B[i, 0] = (b[i, 0] + b[i+1, 0]) / 2
B[i, 1] = (b[i, 1] + b[i+1, 1]) / 2

where c and b represent the input coordinate values and bounds, and C and B the output coordinate values and bounds.

Note

Difference method used is the same as cube_delta() and therefore has the same limitations.

Note

Spherical differentiation does not occur in this routine.

Note

This function does not maintain laziness when called; it realises data. See more at Real and Lazy Data.