Science calculations#

Calculus#

Generic calculus functions.

aeolus.calc.calculus.d_dx(cube, model=Model [99 fields])[source]#

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

aeolus.calc.calculus.d_dy(cube, model=Model [99 fields])[source]#

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

aeolus.calc.calculus.d_dz(cube, model=Model [99 fields])[source]#

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

aeolus.calc.calculus.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.div_h(i_cube, j_cube, r_planet=None, model=Model [99 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 A_\lambda}{\partial \lambda} + \frac{\partial}{\partial \theta} (A_\theta cos \theta))\]

where lambda is longitude, theta is latitude.

aeolus.calc.calculus.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

Diagnostics#

Some commonly used diagnostics in atmospheric science.

aeolus.calc.diag.air_density(cubelist, const=None, model=Model [99 fields])[source]#

Get air density from the given cube list.

If not present, try 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.diag.air_potential_temperature(cubelist, const=None, model=Model [99 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. 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.diag.air_pressure(cubelist, const=None, model=Model [99 fields])[source]#

Get pressure from the given cube list.

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

Parameters:

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

  • const (aeolus.const.const.ConstContainer, optional) – Must have reference_surface_pressure and dry_air_gas_constant. 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 pressure.

Return type:

iris.cube.Cube

aeolus.calc.diag.air_temperature(cubelist, const=None, model=Model [99 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. 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.diag.bond_albedo(cubelist, const=None, model=Model [99 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.diag.calc_derived_cubes(cubelist, const=None, model=Model [99 fields])[source]#

Calculate additional variables.

aeolus.calc.diag.dry_lapse_rate(cubelist, model=Model [99 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.diag.flux(cubelist, quantity, axis, weight_by_density=True, model=Model [99 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 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.diag.geopotential_height(cubelist, const=None, model=Model [99 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.diag.ghe_norm(cubelist, model=Model [99 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.diag.greenhouse_effect(cubelist, kind='all_sky', const=None, model=Model [99 fields])[source]#

Calculate the greenhouse effect [K].

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

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

  • kind (str, optional) – Type of GHE: “all_sky” or “clear_sky”

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

Returns:

Cube of greenhouse effect parameter.

Return type:

iris.cube.Cube

aeolus.calc.diag.heat_redist_eff(cubelist, region_a, region_b, model=Model [99 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.diag.horiz_wind_cmpnts(cubelist, model=Model [99 fields])[source]#

Extract u and v winds 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.diag.meridional_mass_streamfunction(cubelist, const=None, model=Model [99 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{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)
aeolus.calc.diag.precip_sum(cubelist, ptype='total', const=None, model=Model [99 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.diag.sfc_net_energy(cubelist, model=Model [99 fields])[source]#

Calculate domain-average surface energy flux.

Parameters:

  • cubelist (iris.cube.CubeList) – Input cubes with net LW and SW, 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.diag.sfc_water_balance(cubelist, const=None, model=Model [99 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.diag.sigma_p(cubelist, model=Model [99 fields])[source]#

Calculate sigma (normalised pressure coordinate) from a cube of pressure.

\[\sigma = p / p_{sfc}\]
Parameters:

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

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

aeolus.calc.diag.toa_cloud_radiative_effect(cubelist, kind, model=Model [99 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.diag.toa_eff_temp(cubelist, model=Model [99 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.diag.toa_net_energy(cubelist, model=Model [99 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.diag.water_path(cubelist, kind='water_vapour', model=Model [99 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 mixing ratio and air density.

  • kind (str, optional) – Short name of the water phase to be integrated. Options: water_vapour (default) | liquid_water | ice_water | cloud_water where 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.diag.wind_rot_div(u, v, truncation=None, const=None, model=Model [99 fields])[source]#

Split the horizontal wind field into divergent and rotational parts.

The Helmholtz decomposition method uses the windspharm library: https://ajdawson.github.io/windspharm/latest/

Parameters:

  • u (iris.cube.Cube) – Eastward wind.

  • v (iris.cube.Cube) – Northward wind.

  • truncation (int) – Truncation for the spherical harmonic computation (See windspharm docs for details).

  • 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:

out –

Dictionary of cubes of:

  • input wind components (for convenience),

  • divergent components,

  • rotational components,

  • zonal mean rotational components,

  • zonal eddy rotational components.

Return type:

dict

References

Hammond and Lewis (2021), https://doi.org/10.1073/pnas.2022705118.

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

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

\[\sqrt{u^2 + v^2 + w^2}\]
Parameters:

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

Return type:

iris.cube.Cube

aeolus.calc.diag.zonal_mass_streamfunction(cubelist, const=None, model=Model [99 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#

Integrated fluxes.

aeolus.calc.flux_h.horizontal_fluxes_through_region_boundaries(scalar_cube, region, u, v, r_planet=None, vertical_constraint=None, warn_thresh=10, model=Model [99 fields])[source]#

Calculate horizontal fluxes through planes of a rectangular region.

aeolus.calc.flux_h.net_horizontal_flux_to_region(scalar_cube, region, u, v, r_planet=None, vertical_constraint=None, model=Model [99 fields])[source]#

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

Statistics#

Statistical functions.

aeolus.calc.stats.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.stats.after_n_day_mean(cube, days=365, model=Model [99 fields])[source]#

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

aeolus.calc.stats.between_day_mean(cube, day_start, day_end, model=Model [99 fields])[source]#

Average the cube over a subset of days.

aeolus.calc.stats.cumsum(cube, axis, axis_weights=False, model=Model [99 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.stats.last_n_day_mean(cube, days=365, model=Model [99 fields])[source]#

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

aeolus.calc.stats.meridional_mean(cube, model=Model [99 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.stats.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.stats.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.stats.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 dims.

Return type:

iris.cube.Cube

aeolus.calc.stats.spatial(cube, aggr, model=Model [99 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.stats.spatial_mean(cube, model=Model [99 fields])[source]#

Shortcut for spatial(cube, “mean”).

aeolus.calc.stats.spatial_quartiles(cube, model=Model [99 fields])[source]#

Calculate quartiles over horizontal coordinates.

aeolus.calc.stats.time_mean(obj, squeeze=False, model=Model [99 fields])[source]#

Time average of a cube or a container with cubes.

aeolus.calc.stats.vertical_mean(cube, weight_by=None, model=Model [99 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.stats.zonal_mean(cube, model=Model [99 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

Tidally-locked coordinates#

Operations in tidally-locked coordinates.

aeolus.calc.tl.regrid_to_rotated_pole_coordinates(cube, pole_lon, pole_lat, model=Model [99 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.tl.regrid_to_tidally_locked_coordinates(cube, pole_lon=0, pole_lat=0, model=Model [99 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.tl.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: