Science calculations — aeolus 0.4.9+9.g5a71939.dirty documentation

# Science calculations

## Calculus

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

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

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

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

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

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

aeolus.calc.deriv(cube, coord)

  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

    - cube (iris.cube.Cube) – Input cube containing the given coordinate.

    - coord (str or iris.coords.Coord) – Coordinate for differentiation.

  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))

  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)

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

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

  Parameters

    - cube (iris.cube.Cube) – Input cube containing the given coordinate.

    - coord (str or iris.coords.Coord) – Coordinate for integration.

  Returns

    Integrated cube.

  Return type

    iris.cube.Cube

## Statistics

aeolus.calc.abs_coord_mean(cube, coord)

  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

    - cube (iris.cube.Cube) – Cube with the specified coordinate.

    - coord (str or iris.coords.Coord) – Coordinate to apply abs().

  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))

  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))

  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))

  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)

  Spatial maximum minus spatial minimum for a given cube.

  Parameters

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

    - name (str) – Cube name.

  Returns

    Difference between the extrema with collapsed spatial dimensions.

  Return type

    iris.cube.Cube

aeolus.calc.normalize_cube(cube)

  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)

  Difference between averages over two regions for a given cube.

  Parameters

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

    - name (str) – Cube name.

    - region_a (aeolus.region.Region) – First region.

    - region_b (aeolus.region.Region) – Second region.

  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))

  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))

  Shortcut for spatial(cube, “mean”).

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

  Calculate quartiles over horizontal coordinates.

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

  Time average of a cube.

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

  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))

  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))

  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))

  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))

  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))

  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))

  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))

  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))

  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))

  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))

  Heat redistribution efficiency (Leconte et al. 2013).

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

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

    - region_a (aeolus.region.Region) – First region (usually nightside).

    - region_b (aeolus.region.Region) – Second region (usually dayside).

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

  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))

  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))

  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))

  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))

  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))

  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))

  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))

  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))

  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))

  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))

  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)

  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))

  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))

  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))

  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))

  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)

  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

    - u (iris.cube.Cube) – An instance of `iris.cube.Cube` that contains the x-component of the vector.

    - v (iris.cube.Cube) – An instance of `iris.cube.Cube` that contains the y-component of the vector.

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

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