Science calculations

Calculus

aeolus.calc.d_dx(cube, model=<class 'aeolus.model.base.Model'>(80 fields))[source]

Calculate a derivative w.r.t. x-coordinate.

aeolus.calc.d_dy(cube, model=<class 'aeolus.model.base.Model'>(80 fields))[source]

Calculate a derivative w.r.t. y-coordinate.

aeolus.calc.d_dz(cube, model=<class 'aeolus.model.base.Model'>(80 fields))[source]

Calculate a derivative w.r.t. z-coordinate.

aeolus.calc.deriv(cube, coord)[source]

Calculate a derivative w.r.t. the given coordinate.

Uses iris.analysis.calculus.differentiate and then interpolates the result to the grid points of the original cube.

Parameters
Returns

d(cube)/d(coord).

Return type

iris.cube.Cube

See also

aeolus.calc.calculus.d_dx, aeolus.calc.calculus.d_dy, aeolus.calc.calculus.d_dz

aeolus.calc.div_h(i_cube, j_cube, r_planet=None, model=<class 'aeolus.model.base.Model'>(80 fields))[source]

Calculate horizontal divergence.

Note: currently works only in spherical coordinates.

Parameters

  • i_cube – i-component (e.g. u-wind)

  • j_cube – j-component (e.g. v-wind)

  • r_planet (float, optional) – Radius of the planet (m). If not given, an attempt is made to get it from the cube metadata.

  • model (aeolus.model.Model, optional) – Model class with relevant variable names.

Returns

Cube of horizontal divergence.

Return type

iris.cube.Cube

Notes

Divergence in spherical coordinates is defined as

\[\nabla\cdot \vec A = \frac{1}{r cos \theta} ( \frac{\partial \vec A_\lambda}{\partial \lambda} + \frac{\partial}{\partial \theta} (\vec A_\theta cos \theta))\]

where lambda is longitude, theta is latitude.

aeolus.calc.integrate(cube, coord)[source]

Integrate the cube along a 1D coordinate using the trapezoidal rule.

Note: coord must be one of the dimensional coordinates of the cube.

Parameters
Returns

Integrated cube.

Return type

iris.cube.Cube

Statistics

aeolus.calc.abs_coord_mean(cube, coord)[source]

Calculate cube’s average over absolute values of a coordinate.

For example, applying this to a cube with N latitudes ranging from SP to NP returns a cube with (N+1)//2 latitudes.

Parameters
Returns

Cube with a reduced dimension.

Return type

iris.cube.Cube

aeolus.calc.cumsum(cube, axis, axis_weights=False, model=<class 'aeolus.model.base.Model'>(80 fields))[source]

Cumulative sum of a cube.

Parameters

  • cube (iris.cube.Cube) – Input cube.

  • axis (str) – Coordinate axis of operation (t|z|y|x).

  • axis_weights (bool, optional) – If True, multiply data by the coordinate spacings.

  • model (aeolus.model.Model, optional) – Model class with a relevant coordinate name.

Returns

Cube of cumulative sums with the same dimensions as the input cube.

Return type

iris.cube.Cube

aeolus.calc.last_n_day_mean(cube, days=365, model=<class 'aeolus.model.base.Model'>(80 fields))[source]

Average the cube over the last n days of its time dimension.

aeolus.calc.meridional_mean(cube, model=<class 'aeolus.model.base.Model'>(80 fields))[source]

Calculate cube’s meridional average.

Parameters

  • cube (iris.cube.Cube) – Cube with a latitude coordinate.

  • model (aeolus.model.Model, optional) – Model class with a relevant coordinate name.

Returns

Collapsed cube.

Return type

iris.cube.Cube

aeolus.calc.minmaxdiff(cubelist, name)[source]

Spatial maximum minus spatial minimum for a given cube.

Parameters
Returns

Difference between the extrema with collapsed spatial dimensions.

Return type

iris.cube.Cube

aeolus.calc.normalize_cube(cube)[source]

Normalize cube data, i.e. make the values range from 0 to 1.

\[z_i = (x_i - min(x)) / (max(x) - min(x))\]
Parameters

cube (iris.cube.Cube) – The input cube.

aeolus.calc.region_mean_diff(cubelist, name, region_a, region_b)[source]

Difference between averages over two regions for a given cube.

Parameters
Returns

Difference between the region averages with collapsed spatial dimensions.

Return type

iris.cube.Cube

aeolus.calc.spatial(cube, aggr, model=<class 'aeolus.model.base.Model'>(80 fields))[source]

Calculate spatial statistic with geographic grid weights.

Parameters

  • cube (iris.cube.Cube) – Cube with longitude and latitude coordinates.

  • aggr (str) – Statistical aggregator (see iris.analysis for available aggregators).

  • model (aeolus.model.Model, optional) – Model class with relevant coordinate names.

Returns

Collapsed cube.

Return type

iris.cube.Cube

Examples

>>> spatial(my_data_cube, "mean")
aeolus.calc.spatial_mean(cube, model=<class 'aeolus.model.base.Model'>(80 fields))[source]

Shortcut for spatial(cube, “mean”).

aeolus.calc.spatial_quartiles(cube, model=<class 'aeolus.model.base.Model'>(80 fields))[source]

Calculate quartiles over horizontal coordinates.

aeolus.calc.time_mean(cube, model=<class 'aeolus.model.base.Model'>(80 fields))[source]

Time average of a cube.

aeolus.calc.vertical_mean(cube, weight_by=None, model=<class 'aeolus.model.base.Model'>(80 fields))[source]

Vertical mean of a cube with optional weighting.

Parameters

  • cube (iris.cube.Cube) – Cube to average.

  • weight_by (str or iris.coords.Coord or iris.cube.Cube, optional) – Coordinate of the given cube or another cube used for weighting.

  • model (aeolus.model.Model, optional) – Model class with a relevant coordinate name.

Returns

Collapsed cube.

Return type

iris.cube.Cube

aeolus.calc.zonal_mean(cube, model=<class 'aeolus.model.base.Model'>(80 fields))[source]

Calculate cube’s zonal average.

Parameters

  • cube (iris.cube.Cube) – Cube with a latitude coordinate.

  • model (aeolus.model.Model, optional) – Model class with a relevant coordinate name.

Returns

Collapsed cube.

Return type

iris.cube.Cube

Diagnostics

aeolus.calc.air_density(cubelist, const=None, model=<class 'aeolus.model.base.Model'>(80 fields))[source]

Get air density from the given cube list.

If not present, it is attempted to calculate it from pressure and temperature.

Parameters

  • cubelist (iris.cube.CubeList) – Input list of cubes containing temperature.

  • const (aeolus.const.const.ConstContainer, optional) – Must have dry_air_gas_constant as an attribute. If not given, an attempt is made to retrieve it from cube attributes.

  • model (aeolus.model.Model, optional) – Model class with relevant variable names.

Returns

Cube of air density.

Return type

iris.cube.Cube

aeolus.calc.air_potential_temperature(cubelist, const=None, model=<class 'aeolus.model.base.Model'>(80 fields))[source]

Get the potential temperature from the given cube list.

If not present, it is attempted to calculate it from other variables, Exner pressure or air pressure, and real temperature.

Parameters

  • cubelist (iris.cube.CubeList) – Input list of cubes containing temperature.

  • const (aeolus.const.const.ConstContainer, optional) – Must have reference_surface_pressure and dry_air_gas_constant as attributes. If not given, an attempt is made to retrieve it from cube attributes.

  • model (aeolus.model.Model, optional) – Model class with relevant variable names.

Returns

Cube of air potential temperature.

Return type

iris.cube.Cube

aeolus.calc.air_temperature(cubelist, const=None, model=<class 'aeolus.model.base.Model'>(80 fields))[source]

Get the real temperature from the given cube list.

If not present, it is attempted to calculate it from other variables, Exner pressure or air pressure, and potential temperature.

Parameters

  • cubelist (iris.cube.CubeList) – Input list of cubes containing temperature.

  • const (aeolus.const.const.ConstContainer, optional) – Must have reference_surface_pressure and dry_air_gas_constant as attributes. If not given, an attempt is made to retrieve it from cube attributes.

  • model (aeolus.model.Model, optional) – Model class with relevant variable names.

Returns

Cube of air temperature.

Return type

iris.cube.Cube

aeolus.calc.bond_albedo(cubelist, const=None, model=<class 'aeolus.model.base.Model'>(80 fields))[source]

Bold albedo.

\[4 \frac{OSR_{TOA}}{S_{0}}\]
Parameters

  • cubelist (iris.cube.CubeList) – Input list of cubes.

  • const (aeolus.const.const.ConstContainer, optional) – Must have a scalar cube of solar_constant as an attribute. If not given, attempt to retrieve it from cube attributes.

  • model (aeolus.model.Model, optional) – Model class with relevant variable names.

Returns

Cube of bond albedo.

Return type

iris.cube.Cube

aeolus.calc.dry_lapse_rate(cubelist, model=<class 'aeolus.model.base.Model'>(80 fields))[source]

Dry lapse rate, or the change of air temperature with altitude.

\[\gamma = \partial T_{air} / \partial z\]
Parameters

  • cubelist (iris.cube.CubeList) – Input list of cubes containing temperature.

  • model (aeolus.model.Model, optional) – Model class with relevant variable names.

Returns

Cube of dT/dz.

Return type

iris.cube.Cube

aeolus.calc.flux(cubelist, quantity, axis, weight_by_density=True, model=<class 'aeolus.model.base.Model'>(80 fields))[source]

Calculate horizontal or vertical flux of some quantity.

\[F_{x} = u (\rho q), F_{y} = v (\rho q), F_{z} = w (\rho q)\]
Parameters

  • cubelist (iris.cube.CubeList) – Input list of cubes.

  • quantity (str or iris.Constraint) – Quantity (present in the cube list).

  • axis (str) – Axis of the flux component (x|y|z)

  • weight_by_density (bool, optional) – Multiply by a cube of air density (must be present in the input cube list).

  • model (aeolus.model.Model, optional) – Model class with relevant variable names.

Returns

Cube of a flux component with the same dimensions as input cubes.

Return type

iris.cube.Cube

aeolus.calc.geopotential_height(cubelist, const=None, model=<class 'aeolus.model.base.Model'>(80 fields))[source]

Get geopotential height from the given cube list.

If not present, the altitude coordinate is transformed into a cube.

Parameters

  • cubelist (iris.cube.CubeList) – Input list of cubes containing temperature.

  • const (aeolus.const.const.ConstContainer, optional) – Must have gravity as an attribute. If not given, an attempt is made to retrieve it from cube attributes.

  • model (aeolus.model.Model, optional) – Model class with relevant variable names.

Returns

Cube of geopotential height.

Return type

iris.cube.Cube

aeolus.calc.ghe_norm(cubelist, model=<class 'aeolus.model.base.Model'>(80 fields))[source]

Normalised greenhouse effect parameter.

\[GHE = 1 - \left(\frac{T_{eff}}{T_{sfc}}\right)^4\]
Parameters

  • cubelist (iris.cube.CubeList) – Input list of cubes.

  • model (aeolus.model.Model, optional) – Model class with relevant variable names.

Returns

Cube of greenhouse effect parameter.

Return type

iris.cube.Cube

aeolus.calc.heat_redist_eff(cubelist, region_a, region_b, model=<class 'aeolus.model.base.Model'>(80 fields))[source]

Heat redistribution efficiency (Leconte et al. 2013).

\[\eta=\frac{OLR_{TOA,night}}{OLR_{TOA,day}}\]
Parameters
Returns

Cube of eta parameter with collapsed spatial dimensions.

Return type

iris.cube.Cube

aeolus.calc.horiz_wind_cmpnts(cubelist, model=<class 'aeolus.model.base.Model'>(80 fields))[source]

Extract u and v wind components from a cube list and interpolate v on u’s grid if necessary.

Parameters

  • cubelist (iris.cube.CubeList) – List of cubes with horizontal wind components

  • model (aeolus.model.Model, optional) – Model class with relevant variable names.

Returns

u, v – Cubes of wind components.

Return type

iris.cube.Cube

aeolus.calc.meridional_mass_streamfunction(cubelist, const=None, model=<class 'aeolus.model.base.Model'>(80 fields))[source]

Calculate the mean meridional mass streamfunction.

  • In height coordinates

\[\Psi_M = - 2\pi cos\phi a \int_{z_{sfc}}^{z_{top}}\overline{\rho v} dz\]

  • In pressure coordinates

\[\Psi_M = 2\pi cos\phi a \int_{0}^{p_{sfc}}\overline{\rho v} dp / g\]
Parameters

  • cubelist (iris.cube.CubeList) – Input cubelist.

  • const (aeolus.const.const.ConstContainer, optional) – If not given, constants are attempted to be retrieved from attributes of a cube in the cube list.

  • model (aeolus.model.Model, optional) – Model class with relevant variable names.

Returns

Cube with collapsed spatial dimensions.

Return type

iris.cube.Cube

References

Haqq-Misra & Kopparapu (2015), eq. 4; Vallis (2017)

Examples

>>> from aeolus.calc import meridional_mass_streamfunction, time_mean
>>> from aeolus.const import init_const
>>> from aeolus.model import um
>>> earth_constants = init_const("earth")
>>> cubes = iris.cube.CubeList([time_mean(cube) for cube in input_cubes])
>>> mmsf = meridional_mass_streamfunction(cubes, const=earth_constants, model=um)
aeolus.calc.precip_sum(cubelist, ptype='total', const=None, model=<class 'aeolus.model.base.Model'>(80 fields))[source]

Calculate a sum of different types of precipitation [\(mm~day^{-1}\)].

Parameters

  • cubelist (iris.cube.CubeList) – Input list of cubes.

  • ptype (str, optional) – Precipitation type (total|stra|conv|rain|snow).

  • const (aeolus.const.const.ConstContainer, optional) – Must have a scalar cube of condensible_density as an attribute. If not given, attempt to retrieve it from cube attributes.

  • model (aeolus.model.Model, optional) – Model class with relevant variable names.

Returns

Sum of cubes of precipitation with units converted to mm per day.

Return type

iris.cube.Cube

aeolus.calc.sfc_net_energy(cubelist, model=<class 'aeolus.model.base.Model'>(80 fields))[source]

Calculate domain-average surface energy flux.

Parameters

  • cubelist (iris.cube.CubeList) – Input list of cubes with net LW and SW radiation, sensible and latent surface fluxes.

  • model (aeolus.model.Model, optional) – Model class with relevant variable names.

Returns

Cube of total surface downward energy flux.

Return type

iris.cube.Cube

aeolus.calc.sfc_water_balance(cubelist, const=None, model=<class 'aeolus.model.base.Model'>(80 fields))[source]

Calculate domain-average precipitation minus evaporation.

Parameters

  • cubelist (iris.cube.CubeList) – Input list of cubes.

  • const (aeolus.const.const.ConstContainer, optional) – Must have a scalar cube of condensible_density as an attribute. If not given, attempt is made to retrieve it from cube attributes.

  • model (aeolus.model.Model, optional) – Model class with relevant variable names.

Returns

Cube of total surface downward water flux (P-E).

Return type

iris.cube.Cube

aeolus.calc.superrotation_index(cubelist, const=None, model=<class 'aeolus.model.base.Model'>(80 fields))[source]

Local superrotation index.

\[ \begin{align}\begin{aligned}s = \frac{m}{\Omega a^2} - 1,\\m = a cos\phi(\Omega a cos\phi + u)\end{aligned}\end{align} \]
Parameters

  • cubelist (iris.cube.CubeList) – List of cubes containing a cube of zonal velocity (u).

  • const (aeolus.const.const.ConstContainer, optional) – Constainer with the relevant planetary constants. If not given, attempt is made to retrieve it from cube attributes.

  • model (aeolus.model.Model, optional) – Model class with relevant variable names.

Returns

s_idx – Cubes of superrotation index.

Return type

iris.cube.Cube

References

Read (1986), https://doi.org/10.1002/qj.49711247114

aeolus.calc.toa_cloud_radiative_effect(cubelist, kind, model=<class 'aeolus.model.base.Model'>(80 fields))[source]

Calculate domain-average TOA cloud radiative effect (CRE).

\[CRE_{TOA} = F_{up,clear-sky} - F_{up,all-sky}\]
Parameters

  • cubelist (iris.cube.CubeList) – Input list of cubes

  • kind (str) – Shortwave (‘sw’), longwave (‘lw’), or ‘total’ CRE

Returns

Cube of CRE.

Return type

iris.cube.Cube

aeolus.calc.toa_eff_temp(cubelist, model=<class 'aeolus.model.base.Model'>(80 fields))[source]

Calculate effective temperature from TOA OLR.

Parameters

  • cubelist (iris.cube.CubeList) – Input list of cubes.

  • model (aeolus.model.Model, optional) – Model class with relevant variable names.

Returns

Cube of \(T_{eff}\).

Return type

iris.cube.Cube

aeolus.calc.toa_net_energy(cubelist, model=<class 'aeolus.model.base.Model'>(80 fields))[source]

Calculate domain-average TOA energy flux.

Parameters

  • cubelist (iris.cube.CubeList) – Input list of cubes.

  • model (aeolus.model.Model, optional) – Model class with relevant variable names.

Returns

Cube of total TOA downward energy flux.

Return type

iris.cube.Cube

aeolus.calc.water_path(cubelist, kind='water_vapour', model=<class 'aeolus.model.base.Model'>(80 fields))[source]

Water vapour or condensate path, i.e. a vertical integral of a water phase.

\[WP = \int_{z_{sfc}}^{z_{top}} \rho q dz\]
Parameters

  • cubelist (iris.cube.CubeList) – Input list of cubes containing appropriate mixing ratio and air density.

  • kind (str, optional) – Short name of the water phase to be integrated. Options are water_vapour (default) | liquid_water | ice_water | cloud_water cloud_water is the sum of liquid and ice phases.

  • model (aeolus.model.Model, optional) – Model class with relevant coordinate names. model.z is used as a vertical coordinate for integration.

Returns

Cube of water path with collapsed vertical dimension.

Return type

iris.cube.Cube

aeolus.calc.wind_speed(*components)[source]

Calculate the wind speed (magnitude of the wind vector).

Parameters

  • args (iris.cube.Cube) – Cubes of u, v, w wind components.

  • math:: (.) – sqrt{u^2 + v^2 + w^2}

aeolus.calc.zonal_mass_streamfunction(cubelist, const=None, model=<class 'aeolus.model.base.Model'>(80 fields))[source]

Calculate mean zonal mass streamfunction.

\[\Psi_Z = 2\pi a \int_{z_{sfc}}^{z_{top}}\overline{\rho}^* \overline{u}^* dz\]

References

Haqq-Misra & Kopparapu (2015), eq. 5; Hartmann (1994), Global Physical Climatology, eq. 6.21

Examples

>>> lat_band_constr = iris.Constraint(
    latitude=lambda x: -30 <= x.point <= 30, longitude=lambda x: True
)
>>> mzsf = zonal_mass_streamfunction(cubes.extract(lat_band_constr))

Horizontal fluxes

aeolus.calc.net_horizontal_flux_to_region(scalar_cube, region, u, v, r_planet=None, vertical_constraint=None, model=<class 'aeolus.model.base.Model'>(80 fields))[source]

Calculate horizontal fluxes of scalar_cube quantity and add them to get the net result.

Tidally-locked coordinates

aeolus.calc.regrid_to_rotated_pole_coordinates(cube, pole_lon, pole_lat, model=<class 'aeolus.model.base.Model'>(80 fields))[source]

Regrid a cube to rotated-pole coordinates.

Note: non-dimensional coordinates are lost.

Parameters

  • cube (iris.cube.Cube) – Input cube.

  • pole_lon (float) – New North Pole longitude.

  • pole_lat (float) – New North Pole latitude.

  • model (aeolus.model.Model, optional) – Model class with relevant coordinate and variable names.

aeolus.calc.regrid_to_tidally_locked_coordinates(cube, pole_lon=0, pole_lat=0, model=<class 'aeolus.model.base.Model'>(80 fields))[source]

Regrid a cube to tidally locked coordinates.

The substellar and antistellar point become the north and south pole, respectively. By default, the substellar point is assumed to be at (0, 0).

Parameters

  • cube (iris.cube.Cube) – Input cube.

  • pole_lon (float, optional) – New North Pole longitude.

  • pole_lat (float, optional) – New North Pole latitude.

  • model (aeolus.model.Model, optional) – Model class with relevant coordinate and variable names.

aeolus.calc.rotate_winds_to_tidally_locked_coordinates(u, v, pole_lon=0, pole_lat=0)[source]

Rotate the horizontal wind components to tidally locked coordinates.

The substellar and antistellar point become the north and south pole, respectively. By default, the substellar point is assumed to be at (0, 0).

Parameters