You are viewing the latest unreleased documentation v3.2.dev0. You may prefer a stable version.

Source code for iris.common.resolve

# Copyright Iris contributors
#
# This file is part of Iris and is released under the LGPL license.
# See COPYING and COPYING.LESSER in the root of the repository for full
# licensing details.
"""
Provides the infrastructure to support the analysis, identification and
combination of metadata common between two :class:`~iris.cube.Cube`
operands into a single resultant :class:`~iris.cube.Cube`, which will be
auto-transposed, and with the appropriate broadcast shape.

"""

from collections import namedtuple
from collections.abc import Iterable
import logging

from dask.array.core import broadcast_shapes
import numpy as np

from . import LENIENT
from ..config import get_logger

__all__ = ["Resolve"]


# Configure the logger.
logger = get_logger(__name__, fmt="[%(funcName)s]")


_AuxCoverage = namedtuple(
    "AuxCoverage",
    [
        "cube",
        "common_items_aux",
        "common_items_scalar",
        "local_items_aux",
        "local_items_scalar",
        "dims_common",
        "dims_local",
        "dims_free",
    ],
)

_CategoryItems = namedtuple(
    "CategoryItems",
    ["items_dim", "items_aux", "items_scalar"],
)

_DimCoverage = namedtuple(
    "DimCoverage",
    ["cube", "metadata", "coords", "dims_common", "dims_local", "dims_free"],
)

_Item = namedtuple("Item", ["metadata", "coord", "dims"])

_PreparedFactory = namedtuple("PreparedFactory", ["container", "dependencies"])

_PreparedItem = namedtuple(
    "PreparedItem",
    ["metadata", "points", "bounds", "dims", "container"],
)

_PreparedMetadata = namedtuple("PreparedMetadata", ["combined", "src", "tgt"])


[docs]class Resolve: """ At present, :class:`~iris.common.resolve.Resolve` is used by Iris solely during cube maths to combine a left-hand :class:`~iris.cube.Cube` operand and a right-hand :class:`~iris.cube.Cube` operand into a resultant :class:`~iris.cube.Cube` with common metadata, suitably auto-transposed dimensions, and an appropriate broadcast shape. However, the capability and benefit provided by :class:`~iris.common.resolve.Resolve` may be exercised as a general means to easily and consistently combine the metadata of two :class:`~iris.cube.Cube` operands together into a single resultant :class:`~iris.cube.Cube`. This is highlighted through the following use case patterns. Firstly, creating a ``resolver`` instance with *specific* :class:`~iris.cube.Cube` operands, and then supplying ``data`` with suitable dimensionality and shape to create the resultant resolved :class:`~iris.cube.Cube`, e.g., .. testsetup:: import iris import numpy as np from iris.common import Resolve cube1 = iris.load_cube(iris.sample_data_path("A1B_north_america.nc")) cube2 = iris.load_cube(iris.sample_data_path("E1_north_america.nc"))[0] cube2.transpose() cube3, cube4 = cube1, cube2 data = np.zeros(cube1.shape) data1 = data * 10 data2 = data * 20 data3 = data * 30 .. doctest:: >>> print(cube1) air_temperature / (K) (time: 240; latitude: 37; longitude: 49) Dimension coordinates: time x - - latitude - x - longitude - - x Auxiliary coordinates: forecast_period x - - Scalar coordinates: forecast_reference_time 1859-09-01 06:00:00 height 1.5 m Cell methods: mean time (6 hour) Attributes: Conventions CF-1.5 Model scenario A1B STASH m01s03i236 source Data from Met Office Unified Model 6.05 >>> print(cube2) air_temperature / (K) (longitude: 49; latitude: 37) Dimension coordinates: longitude x - latitude - x Scalar coordinates: forecast_period 10794 hours forecast_reference_time 1859-09-01 06:00:00 height 1.5 m time 1860-06-01 00:00:00, bound=(1859-12-01 00:00:00, 1860-12-01 00:00:00) Cell methods: mean time (6 hour) Attributes: Conventions CF-1.5 Model scenario E1 STASH m01s03i236 source Data from Met Office Unified Model 6.05 >>> print(data.shape) (240, 37, 49) >>> resolver = Resolve(cube1, cube2) >>> result = resolver.cube(data) >>> print(result) air_temperature / (K) (time: 240; latitude: 37; longitude: 49) Dimension coordinates: time x - - latitude - x - longitude - - x Auxiliary coordinates: forecast_period x - - Scalar coordinates: forecast_reference_time 1859-09-01 06:00:00 height 1.5 m Cell methods: mean time (6 hour) Attributes: Conventions CF-1.5 STASH m01s03i236 source Data from Met Office Unified Model 6.05 Secondly, creating an *empty* ``resolver`` instance, that may be called *multiple* times with *different* :class:`~iris.cube.Cube` operands and *different* ``data``, e.g., .. doctest:: >>> resolver = Resolve() >>> result1 = resolver(cube1, cube2).cube(data1) >>> result2 = resolver(cube3, cube4).cube(data2) Lastly, creating a ``resolver`` instance with *specific* :class:`~iris.cube.Cube` operands, and then supply *different* ``data`` *multiple* times, e.g., >>> payload = (data1, data2, data3) >>> resolver = Resolve(cube1, cube2) >>> results = [resolver.cube(data) for data in payload] """ def __init__(self, lhs=None, rhs=None): """ Resolve the provided ``lhs`` :class:`~iris.cube.Cube` operand and ``rhs`` :class:`~iris.cube.Cube` operand to determine the metadata that is common between them, and the auto-transposed, broadcast shape of the resultant :class:`~iris.cube.Cube`. This includes the identification of common :class:`~iris.common.metadata.CubeMetadata`, :class:`~iris.coords.DimCoord`, :class:`~iris.coords.AuxCoord`, and :class:`~iris.aux_factory.AuxCoordFactory` metadata. .. note:: Resolving common :class:`~iris.coords.AncillaryVariable` and :class:`~iris.coords.CellMeasure` metadata is not supported at this time. (:issue:`3839`) .. note:: A :class:`~iris.common.resolve.Resolve` instance is **callable**, allowing two new ``lhs`` and ``rhs`` :class:`~iris.cube.Cube` operands to be resolved. Note that, :class:`~iris.common.resolve.Resolve` only supports resolving **two** operands at a time, and no more. .. warning:: :class:`~iris.common.resolve.Resolve` attempts to preserve commutativity, but this may not be possible when auto-transposition or extended broadcasting is involved during the operation. For example: .. doctest:: >>> cube1 <iris 'Cube' of air_temperature / (K) (time: 240; latitude: 37; longitude: 49)> >>> cube2 <iris 'Cube' of air_temperature / (K) (longitude: 49; latitude: 37)> >>> result1 = Resolve(cube1, cube2).cube(data) >>> result2 = Resolve(cube2, cube1).cube(data) >>> result1 == result2 True Kwargs: * lhs: The left-hand-side :class:`~iris.cube.Cube` operand. * rhs: The right-hand-side :class:`~iris.cube.Cube` operand. """ #: The ``lhs`` operand to be resolved into the resultant :class:`~iris.cube.Cube`. self.lhs_cube = None # set in __call__ #: The ``rhs`` operand to be resolved into the resultant :class:`~iris.cube.Cube`. self.rhs_cube = None # set in __call__ #: The transposed/reshaped (if required) ``lhs`` :class:`~iris.cube.Cube`, which #: can be broadcast with the ``rhs`` :class:`~iris.cube.Cube`. self.lhs_cube_resolved = None #: The transposed/reshaped (if required) ``rhs`` :class:`~iris.cube.Cube`, which #: can be broadcast with the ``lhs`` :class:`~iris.cube.Cube`. self.rhs_cube_resolved = None #: Categorised dim, aux and scalar coordinate items for ``lhs`` :class:`~iris.cube.Cube`. self.lhs_cube_category = None # set in _metadata_resolve #: Categorised dim, aux and scalar coordinate items for ``rhs`` :class:`~iris.cube.Cube`. self.rhs_cube_category = None # set in _metadata_resolve #: Categorised dim, aux and scalar coordinate items **local** to the #: ``lhs`` :class:`~iris.cube.Cube` only. self.lhs_cube_category_local = None # set in _metadata_resolve #: Categorised dim, aux and scalar coordinate items **local** to the #: ``rhs`` :class:`~iris.cube.Cube` only. self.rhs_cube_category_local = None # set in _metadata_resolve #: Categorised dim, aux and scalar coordinate items **common** to both #: the ``lhs`` :class:`~iris.cube.Cube` and the ``rhs`` :class:`~iris.cube.Cube`. self.category_common = None # set in _metadata_resolve #: Analysis of dim coordinates spanning the ``lhs`` :class:`~iris.cube.Cube`. self.lhs_cube_dim_coverage = None # set in _metadata_coverage #: Analysis of aux and scalar coordinates spanning the ``lhs`` :class:`~iris.cube.Cube`. self.lhs_cube_aux_coverage = None # set in _metadata_coverage #: Analysis of dim coordinates spanning the ``rhs`` :class:`~iris.cube.Cube`. self.rhs_cube_dim_coverage = None # set in _metadata_coverage #: Analysis of aux and scalar coordinates spanning the ``rhs`` :class:`~iris.cube.Cube`. self.rhs_cube_aux_coverage = None # set in _metadata_coverage #: Map **common** metadata from the ``rhs`` :class:`~iris.cube.Cube` to #: the ``lhs`` :class:`~iris.cube.Cube` if ``lhs-rank`` >= ``rhs-rank``, #: otherwise map **common** metadata from the ``lhs`` :class:`~iris.cube.Cube` #: to the ``rhs`` :class:`~iris.cube.Cube`. self.map_rhs_to_lhs = None # set in __call__ #: Mapping of the dimensions between **common** metadata for the :class:`~iris.cube.Cube` #: operands, where the direction of the mapping is governed by #: :attr:`~iris.common.resolve.Resolve.map_rhs_to_lhs`. self.mapping = None # set in _metadata_mapping #: Cache containing a list of dim, aux and scalar coordinates prepared #: and ready for creating and attaching to the resultant resolved #: :class:`~iris.cube.Cube`. self.prepared_category = None # set in _metadata_prepare #: Cache containing a list of aux factories prepared and ready for #: creating and attaching to the resultant resolved #: :class:`~iris.cube.Cube`. self.prepared_factories = None # set in _metadata_prepare # The shape of the resultant resolved cube. self._broadcast_shape = None # set in _as_compatible_cubes if lhs is not None or rhs is not None: # Attempt to resolve the cube operands. self(lhs, rhs)
[docs] def __call__(self, lhs, rhs): """ Resolve the ``lhs`` :class:`~iris.cube.Cube` operand and ``rhs`` :class:`~iris.cube.Cube` operand metadata. Involves determining all the common coordinate metadata shared between the operands, and the metadata that is local to each operand. Given the common metadata, the broadcast shape of the resultant resolved :class:`~iris.cube.Cube`, which may be auto-transposed, can be determined. Args: * lhs: The left-hand-side :class:`~iris.cube.Cube` operand. * rhs: The right-hand-side :class:`~iris.cube.Cube` operand. """ from iris.cube import Cube emsg = ( "{cls} requires {arg!r} argument to be a 'Cube', got {actual!r}." ) clsname = self.__class__.__name__ if not isinstance(lhs, Cube): raise TypeError( emsg.format(cls=clsname, arg="LHS", actual=type(lhs)) ) if not isinstance(rhs, Cube): raise TypeError( emsg.format(cls=clsname, arg="RHS", actual=type(rhs)) ) # Initialise the operand state. self.lhs_cube = lhs self.rhs_cube = rhs # Determine the initial direction to map operands. # This may flip for operands with equal rank, particularly after # later analysis informs the decision. if self.lhs_cube.ndim >= self.rhs_cube.ndim: self.map_rhs_to_lhs = True else: self.map_rhs_to_lhs = False self._metadata_resolve() self._metadata_coverage() if self._debug: self._debug_items(self.lhs_cube_category_local, title="LHS local") self._debug_items(self.rhs_cube_category_local, title="RHS local") self._debug_items(self.category_common, title="common") logger.debug(f"map_rhs_to_lhs={self.map_rhs_to_lhs}") self._metadata_mapping() self._metadata_prepare() return self
def _as_compatible_cubes(self): """ Determine whether the ``src`` and ``tgt`` :class:`~iris.cube.Cube` can be transposed and/or broadcast successfully together. If compatible, the ``_broadcast_shape`` of the resultant resolved cube is calculated, and the ``_src_cube_resolved`` (transposed/broadcast ``src`` cube) and ``_tgt_cube_resolved`` (same as the ``tgt`` cube) are calculated. An exception will be raised if the ``src`` and ``tgt`` cannot be broadcast, even after a suitable transpose has been performed. .. note:: Requires that **all** ``src`` cube dimensions have been mapped successfully to an appropriate ``tgt`` cube dimension. """ from iris.cube import Cube src_cube = self._src_cube tgt_cube = self._tgt_cube assert src_cube.ndim == len(self.mapping) # Use the mapping to calculate the new src cube shape. new_src_shape = [1] * tgt_cube.ndim for src_dim, tgt_dim in self.mapping.items(): new_src_shape[tgt_dim] = src_cube.shape[src_dim] new_src_shape = tuple(new_src_shape) dmsg = ( f"new src {self._src_cube_position} cube shape {new_src_shape}, " f"actual shape {src_cube.shape}" ) logger.debug(dmsg) try: # Determine whether the tgt cube shape and proposed new src # cube shape will successfully broadcast together. self._broadcast_shape = broadcast_shapes( tgt_cube.shape, new_src_shape ) except ValueError: emsg = ( "Cannot resolve cubes, as a suitable transpose of the " f"{self._src_cube_position} cube {src_cube.name()!r} " f"will not broadcast with the {self._tgt_cube_position} cube " f"{tgt_cube.name()!r}." ) raise ValueError(emsg) new_src_data = src_cube.core_data().copy() # Use the mapping to determine the transpose sequence of # src dimensions in increasing tgt dimension order. order = [ src_dim for src_dim, tgt_dim in sorted( self.mapping.items(), key=lambda pair: pair[1] ) ] # Determine whether a transpose of the src cube is necessary. if order != sorted(order): new_src_data = new_src_data.transpose(order) logger.debug( f"transpose src {self._src_cube_position} cube with order {order}" ) # Determine whether a reshape is necessary. if new_src_shape != new_src_data.shape: new_src_data = new_src_data.reshape(new_src_shape) logger.debug( f"reshape src {self._src_cube_position} cube to new shape {new_src_shape}" ) # Create the new src cube. new_src_cube = Cube(new_src_data) new_src_cube.metadata = src_cube.metadata def add_coord(coord, dim_coord=False): src_dims = src_cube.coord_dims(coord) tgt_dims = [self.mapping[src_dim] for src_dim in src_dims] if dim_coord: new_src_cube.add_dim_coord(coord, tgt_dims) else: new_src_cube.add_aux_coord(coord, tgt_dims) # Add the dim coordinates to the new src cube. for coord in src_cube.dim_coords: add_coord(coord, dim_coord=True) # Add the aux and scalar coordinates to the new src cube. for coord in src_cube.aux_coords: add_coord(coord) # Add the aux factories to the new src cube. for factory in src_cube.aux_factories: new_src_cube.add_aux_factory(factory) # Set the resolved cubes. self._src_cube_resolved = new_src_cube self._tgt_cube_resolved = tgt_cube @staticmethod def _aux_coverage( cube, cube_items_aux, cube_items_scalar, common_aux_metadata, common_scalar_metadata, ): """ Determine the dimensions covered by each of the local and common auxiliary coordinates of the provided :class:`~iris.cube.Cube`. The cube dimensions not covered by any of the auxiliary coordinates is also determined; these are known as `free` dimensions. The scalar coordinates local to the cube are also determined. Args: * cube: The :class:`~iris.cube.Cube` to be analysed for coverage. * cube_items_aux: The list of associated :class:`~iris.common.resolve._Item` metadata for each auxiliary coordinate owned by the cube. * cube_items_scalar: The list of associated :class:`~iris.common.resolve._Item` metadata for each scalar coordinate owned by the cube. * common_aux_metadata: The list of common auxiliary coordinate metadata shared by both the LHS and RHS cube operands being resolved. * common_scalar_metadata: The list of common scalar coordinate metadata shared by both the LHS and RHS cube operands being resolved. Returns: :class:`~iris.common.resolve._AuxCoverage` """ common_items_aux = [] common_items_scalar = [] local_items_aux = [] local_items_scalar = [] dims_common = [] dims_local = [] dims_free = set(range(cube.ndim)) for item in cube_items_aux: [dims_free.discard(dim) for dim in item.dims] if item.metadata in common_aux_metadata: common_items_aux.append(item) dims_common.extend(item.dims) else: local_items_aux.append(item) dims_local.extend(item.dims) for item in cube_items_scalar: if item.metadata in common_scalar_metadata: common_items_scalar.append(item) else: local_items_scalar.append(item) return _AuxCoverage( cube=cube, common_items_aux=common_items_aux, common_items_scalar=common_items_scalar, local_items_aux=local_items_aux, local_items_scalar=local_items_scalar, dims_common=sorted(set(dims_common)), dims_local=sorted(set(dims_local)), dims_free=sorted(dims_free), ) @staticmethod def _aux_mapping(src_coverage, tgt_coverage): """ Establish the mapping of dimensions from the ``src`` to ``tgt`` :class:`~iris.cube.Cube` using the auxiliary coordinate metadata common between each of the operands. The ``src`` to ``tgt`` common auxiliary coordinate mapping is held by the :attr:`~iris.common.resolve.Resolve.mapping`. Args: * src_coverage: The :class:`~iris.common.resolve._DimCoverage` of the ``src`` :class:`~iris.cube.Cube` i.e., map from the common ``src`` dimensions. * tgt_coverage: The :class:`~iris.common.resolve._DimCoverage` of the ``tgt`` :class:`~iris.cube.Cube` i.e., map to the common ``tgt`` dimensions. Returns: Dictionary of ``src`` to ``tgt`` dimension mapping. """ mapping = {} for tgt_item in tgt_coverage.common_items_aux: # Search for a src aux metadata match. tgt_metadata = tgt_item.metadata src_items = tuple( filter( lambda src_item: src_item.metadata == tgt_metadata, src_coverage.common_items_aux, ) ) if src_items: # Multiple matching src metadata must cover the same src # dimensions. src_dims = src_items[0].dims if all(map(lambda item: item.dims == src_dims, src_items)): # Ensure src and tgt have equal rank. tgt_dims = tgt_item.dims if len(src_dims) == len(tgt_dims): for src_dim, tgt_dim in zip(src_dims, tgt_dims): mapping[src_dim] = tgt_dim logger.debug(f"{src_dim}->{tgt_dim}") else: # This situation can only occur due to a systemic internal # failure to correctly identify common aux coordinate metadata # coverage between the cubes. emsg = ( "Failed to map common aux coordinate metadata from " "source cube {!r} to target cube {!r}, using {!r} on " "target cube dimension{} {}." ) raise ValueError( emsg.format( src_coverage.cube.name(), tgt_coverage.cube.name(), tgt_metadata, "s" if len(tgt_item.dims) > 1 else "", tgt_item.dims, ) ) return mapping @staticmethod def _categorise_items(cube): """ Inspect the provided :class:`~iris.cube.Cube` and group its coordinates and associated metadata into dimension, auxiliary and scalar categories. Args: * cube: The :class:`~iris.cube.Cube` that will have its coordinates and metadata grouped into their associated dimension, auxiliary and scalar categories. Returns: :class:`~iris.common.resolve._CategoryItems` """ category = _CategoryItems(items_dim=[], items_aux=[], items_scalar=[]) # Categorise the dim coordinates of the cube. for coord in cube.dim_coords: item = _Item( metadata=coord.metadata, coord=coord, dims=cube.coord_dims(coord), ) category.items_dim.append(item) # Categorise the aux and scalar coordinates of the cube. for coord in cube.aux_coords: dims = cube.coord_dims(coord) item = _Item(metadata=coord.metadata, coord=coord, dims=dims) if dims: category.items_aux.append(item) else: category.items_scalar.append(item) return category @staticmethod def _create_prepared_item( coord, dims, src_metadata=None, tgt_metadata=None ): """ Convenience method that creates a :class:`~iris.common.resolve._PreparedItem` containing the data and metadata required to construct and attach a coordinate to the resultant resolved cube. Args: * coord: The coordinate with the ``points`` and ``bounds`` to be extracted. * dims: The dimensions that the ``coord`` spans on the resulting resolved :class:`~iris.cube.Cube`. * src_metadata: The coordinate metadata from the ``src`` :class:`~iris.cube.Cube`. * tgt_metadata: The coordinate metadata from the ``tgt`` :class:`~iris.cube.Cube`. Returns: The :class:`~iris.common.resolve._PreparedItem`. """ if src_metadata is not None and tgt_metadata is not None: combined = src_metadata.combine(tgt_metadata) else: combined = src_metadata or tgt_metadata if not isinstance(dims, Iterable): dims = (dims,) prepared_metadata = _PreparedMetadata( combined=combined, src=src_metadata, tgt=tgt_metadata ) bounds = coord.bounds result = _PreparedItem( metadata=prepared_metadata, points=coord.points.copy(), bounds=bounds if bounds is None else bounds.copy(), dims=dims, container=type(coord), ) return result @property def _debug(self): result = False level = logger.getEffectiveLevel() if level != logging.NOTSET: result = logging.DEBUG >= level return result @staticmethod def _debug_items(items, title=None): def _show(items, heading): logger.debug(f"{title}{heading}:") for item in items: dmsg = f"metadata={item.metadata}, dims={item.dims}, bounds={item.coord.has_bounds()}" logger.debug(dmsg) title = f"{title} " if title else "" _show(items.items_dim, "dim") _show(items.items_aux, "aux") _show(items.items_scalar, "scalar") @staticmethod def _dim_coverage(cube, cube_items_dim, common_dim_metadata): """ Determine the dimensions covered by each of the local and common dimension coordinates of the provided :class:`~iris.cube.Cube`. The cube dimensions not covered by any of the dimension coordinates is also determined; these are known as `free` dimensions. Args: * cube: The :class:`~iris.cube.Cube` to be analysed for coverage. * cube_items_dim: The list of associated :class:`~iris.common.resolve._Item` metadata for each dimension coordinate owned by the cube. * common_dim_metadata: The list of common dimension coordinate metadata shared by both the LHS and RHS cube operands being resolved. Returns: :class:`~iris.common.resolve._DimCoverage` """ ndim = cube.ndim metadata = [None] * ndim coords = [None] * ndim dims_common = [] dims_local = [] dims_free = set(range(ndim)) for item in cube_items_dim: (dim,) = item.dims dims_free.discard(dim) metadata[dim] = item.metadata coords[dim] = item.coord if item.metadata in common_dim_metadata: dims_common.append(dim) else: dims_local.append(dim) return _DimCoverage( cube=cube, metadata=metadata, coords=coords, dims_common=sorted(dims_common), dims_local=sorted(dims_local), dims_free=sorted(dims_free), ) @staticmethod def _dim_mapping(src_coverage, tgt_coverage): """ Establish the mapping of dimensions from the ``src`` to ``tgt`` :class:`~iris.cube.Cube` using the dimension coordinate metadata common between each of the operands. The ``src`` to ``tgt`` common dimension coordinate mapping is held by the :attr:`~iris.common.resolve.Resolve.mapping`. Args: * src_coverage: The :class:`~iris.common.resolve._DimCoverage` of the ``src`` :class:`~iris.cube.Cube` i.e., map from the common ``src`` dimensions. * tgt_coverage: The :class:`~iris.common.resolve._DimCoverage` of the ``tgt`` :class:`~iris.cube.Cube` i.e., map to the common ``tgt`` dimensions. Returns: Dictionary of ``src`` to ``tgt`` dimension mapping. """ mapping = {} for tgt_dim in tgt_coverage.dims_common: # Search for a src dim metadata match. tgt_metadata = tgt_coverage.metadata[tgt_dim] try: src_dim = src_coverage.metadata.index(tgt_metadata) mapping[src_dim] = tgt_dim logger.debug(f"{src_dim}->{tgt_dim}") except ValueError: # This exception can only occur due to a systemic internal # failure to correctly identify common dim coordinate metadata # coverage between the cubes. emsg = ( "Failed to map common dim coordinate metadata from " "source cube {!r} to target cube {!r}, using {!r} on " "target cube dimension {}." ) raise ValueError( emsg.format( src_coverage.cube.name(), tgt_coverage.cube.name(), tgt_metadata, (tgt_dim,), ) ) return mapping def _free_mapping( self, src_dim_coverage, tgt_dim_coverage, src_aux_coverage, tgt_aux_coverage, ): """ Attempt to update the :attr:`~iris.common.resolve.Resolve.mapping` with ``src`` to ``tgt`` :class:`~iris.cube.Cube` mappings from unmapped ``src`` dimensions that are free from coordinate metadata coverage to ``tgt`` dimensions that have local metadata coverage (i.e., is not common between the ``src`` and ``tgt``) or dimensions that are free from coordinate metadata coverage. If the ``src`` :class:`~iris.cube.Cube` does not have any free dimensions, the attempt to map unmapped ``tgt`` dimensions that have local metadata coverage to ``src`` dimensions that are free from coordinate metadata coverage. An exception will be raised if there are any ``src`` :class:`~iris.cube.Cube` dimensions not mapped to an associated ``tgt`` dimension. Args: * src_dim_coverage: The :class:`~iris.common.resolve.._DimCoverage` of the ``src`` :class:`~iris.cube.Cube`. * tgt_dim_coverage: The :class:`~iris.common.resolve.._DimCoverage` of the ``tgt`` :class:`~iris.cube.Cube`. * src_aux_coverage: The :class:`~iris.common.resolve._AuxCoverage` of the ``src`` :class:`~iris.cube.Cube`. * tgt_aux_coverage: The :class:`~iris.common.resolve._AuxCoverage` of the ``tgt`` :class:`~iris.cube.Cube`. .. note:: All unmapped dimensions with an extend >1 are mapped before those with an extent of 1, as such dimensions cannot be broadcast. It is important to map specific non-broadcastable dimensions before generic broadcastable dimensions otherwise we are open to failing to map all the src dimensions as a generic src broadcast dimension has been mapped to the only tgt dimension that a specific non-broadcastable dimension can be mapped to. .. note:: A local dimension cannot be mapped to another local dimension, by definition, otherwise this dimension would be classed as a common dimension. """ src_cube = src_dim_coverage.cube tgt_cube = tgt_dim_coverage.cube src_ndim = src_cube.ndim tgt_ndim = tgt_cube.ndim # mapping src to tgt, involving free dimensions on either the src/tgt. free_mapping = {} # Determine the src/tgt dimensions that are not mapped, # and not covered by any metadata. src_free = set(src_dim_coverage.dims_free) & set( src_aux_coverage.dims_free ) tgt_free = set(tgt_dim_coverage.dims_free) & set( tgt_aux_coverage.dims_free ) if src_free or tgt_free: # Determine the src/tgt dimensions that are not mapped. src_unmapped = set(range(src_ndim)) - set(self.mapping) tgt_unmapped = set(range(tgt_ndim)) - set(self.mapping.values()) # Determine the src/tgt dimensions that are not mapped, # but are covered by a src/tgt local coordinate. src_unmapped_local = src_unmapped - src_free tgt_unmapped_local = tgt_unmapped - tgt_free src_shape = src_cube.shape tgt_shape = tgt_cube.shape src_max, tgt_max = max(src_shape), max(tgt_shape) def _assign_mapping(extent, unmapped_local_items, free_items=None): result = None if free_items is None: free_items = [] if extent == 1: # Map to the first available unmapped local dimension or # the first available free dimension. # Dimension shape doesn't matter here as the extent is 1, # therefore broadcasting will take care of any discrepency # between src and tgt dimension extent. if unmapped_local_items: result, _ = unmapped_local_items.pop(0) elif free_items: result, _ = free_items.pop(0) else: def _filter(items): return list( filter(lambda item: item[1] == extent, items) ) def _pop(item, items): dim, _ = item index = items.index(item) items.pop(index) return dim items = _filter(unmapped_local_items) if items: result = _pop(items[0], unmapped_local_items) else: items = _filter(free_items) if items: result = _pop(items[0], free_items) return result if src_free: # Attempt to map src free dimensions to tgt unmapped local or free dimensions. tgt_unmapped_local_items = [ (dim, tgt_shape[dim]) for dim in tgt_unmapped_local ] tgt_free_items = [(dim, tgt_shape[dim]) for dim in tgt_free] # Sort by decreasing src dimension extent and increasing src dimension # as we want broadcast src dimensions to be mapped last. src_key_func = lambda dim: (src_max - src_shape[dim], dim) for src_dim in sorted(src_free, key=src_key_func): tgt_dim = _assign_mapping( src_shape[src_dim], tgt_unmapped_local_items, tgt_free_items, ) if tgt_dim is None: # Failed to map the src free dimension # to a suitable tgt local/free dimension. dmsg = ( f"failed to map src free dimension ({src_dim},) from " f"{self._src_cube_position} cube {src_cube.name()!r} to " f"{self._tgt_cube_position} cube {tgt_cube.name()!r}." ) logger.debug(dmsg) break free_mapping[src_dim] = tgt_dim else: # Attempt to map tgt free dimensions to src unmapped local dimensions. src_unmapped_local_items = [ (dim, src_shape[dim]) for dim in src_unmapped_local ] # Sort by decreasing tgt dimension extent and increasing tgt dimension # as we want broadcast tgt dimensions to be mapped last. tgt_key_func = lambda dim: (tgt_max - tgt_shape[dim], dim) for tgt_dim in sorted(tgt_free, key=tgt_key_func): src_dim = _assign_mapping( tgt_shape[tgt_dim], src_unmapped_local_items ) if src_dim is not None: free_mapping[src_dim] = tgt_dim if not src_unmapped_local_items: # There are no more src unmapped local dimensions. break # Determine whether there are still unmapped src dimensions. src_unmapped = ( set(range(src_cube.ndim)) - set(self.mapping) - set(free_mapping) ) if src_unmapped: plural = "s" if len(src_unmapped) > 1 else "" emsg = ( "Insufficient matching coordinate metadata to resolve cubes, " f"cannot map dimension{plural} {tuple(sorted(src_unmapped))} " f"of the {self._src_cube_position} cube {src_cube.name()!r} " f"to the {self._tgt_cube_position} cube {tgt_cube.name()!r}." ) raise ValueError(emsg) # Update the mapping. self.mapping.update(free_mapping) logger.debug(f"mapping free dimensions gives, mapping={self.mapping}") def _metadata_coverage(self): """ Using the pre-categorised metadata of the cubes, determine the dimensions covered by their associated dimension and auxiliary coordinates, and which dimensions are free of metadata coverage. This coverage analysis clarifies how the dimensions covered by common metadata are related, thus establishing a dimensional mapping between the cubes. It also identifies the dimensions covered by metadata that is local to each cube, and indeed which dimensions are free of metadata. """ # Determine the common dim coordinate metadata coverage. common_dim_metadata = [ item.metadata for item in self.category_common.items_dim ] self.lhs_cube_dim_coverage = self._dim_coverage( self.lhs_cube, self.lhs_cube_category.items_dim, common_dim_metadata, ) self.rhs_cube_dim_coverage = self._dim_coverage( self.rhs_cube, self.rhs_cube_category.items_dim, common_dim_metadata, ) # Determine the common aux and scalar coordinate metadata coverage. common_aux_metadata = [ item.metadata for item in self.category_common.items_aux ] common_scalar_metadata = [ item.metadata for item in self.category_common.items_scalar ] self.lhs_cube_aux_coverage = self._aux_coverage( self.lhs_cube, self.lhs_cube_category.items_aux, self.lhs_cube_category.items_scalar, common_aux_metadata, common_scalar_metadata, ) self.rhs_cube_aux_coverage = self._aux_coverage( self.rhs_cube, self.rhs_cube_category.items_aux, self.rhs_cube_category.items_scalar, common_aux_metadata, common_scalar_metadata, ) def _metadata_mapping(self): """ Ensure that each ``src`` :class:`~iris.cube.Cube` dimension is mapped to an associated ``tgt`` :class:`~iris.cube.Cube` dimension using the common dim and aux coordinate metadata. If the common metadata does not result in a full mapping of ``src`` to ``tgt`` dimensions then free dimensions are analysed to determine whether the mapping can be completed. Once the ``src`` has been mapped to the ``tgt``, the cubes are checked to ensure that they will successfully broadcast, and the ``src`` :class:`~iris.cube.Cube` is transposed appropriately, if necessary. The :attr:`~iris.common.resolve.Resolve._broadcast_shape` is set, along with the :attr:`~iris.common.resolve.Resolve._src_cube_resolved` and :attr:`~iris.common.resolve.Resolve._tgt_cube_resolved`, which are the broadcast/transposed ``src`` and ``tgt``. .. note:: An exception will be raised if a ``src`` dimension cannot be mapped to a ``tgt`` dimension. .. note:: An exception will be raised if the full mapped ``src`` :class:`~iris.cube.Cube` cannot be broadcast or transposed with the ``tgt`` :class:`~iris.cube.Cube`. .. note:: The ``src`` and ``tgt`` may be swapped in the case where they both have equal dimensionality and the ``tgt`` does have the same shape as the resolved broadcast shape (and the ``src`` does) or the ``tgt`` has more free dimensions than the ``src``. """ # Initialise the state. self.mapping = {} # Map RHS cube to LHS cube, or smaller to larger cube rank. if self.map_rhs_to_lhs: src_cube = self.rhs_cube src_dim_coverage = self.rhs_cube_dim_coverage src_aux_coverage = self.rhs_cube_aux_coverage tgt_cube = self.lhs_cube tgt_dim_coverage = self.lhs_cube_dim_coverage tgt_aux_coverage = self.lhs_cube_aux_coverage else: src_cube = self.lhs_cube src_dim_coverage = self.lhs_cube_dim_coverage src_aux_coverage = self.lhs_cube_aux_coverage tgt_cube = self.rhs_cube tgt_dim_coverage = self.rhs_cube_dim_coverage tgt_aux_coverage = self.rhs_cube_aux_coverage # Use the dim coordinates to fully map the # src cube dimensions to the tgt cube dimensions. self.mapping.update( self._dim_mapping(src_dim_coverage, tgt_dim_coverage) ) logger.debug( f"mapping common dim coordinates gives, mapping={self.mapping}" ) # If necessary, use the aux coordinates to fully map the # src cube dimensions to the tgt cube dimensions. if not self.mapped: self.mapping.update( self._aux_mapping(src_aux_coverage, tgt_aux_coverage) ) logger.debug( f"mapping common aux coordinates, mapping={self.mapping}" ) if not self.mapped: # Attempt to complete the mapping using src/tgt free dimensions. # Note that, this may not be possible and result in an exception. self._free_mapping( src_dim_coverage, tgt_dim_coverage, src_aux_coverage, tgt_aux_coverage, ) # Attempt to transpose/reshape the cubes into compatible broadcast shapes. # Note that, this may not be possible and result in an exception. self._as_compatible_cubes() # Given the resultant broadcast shape, determine whether the # mapping requires to be reversed. # Only applies to equal src/tgt dimensionality. broadcast_flip = ( src_cube.ndim == tgt_cube.ndim and self._tgt_cube_resolved.shape != self.shape and self._src_cube_resolved.shape == self.shape ) # Given the number of free dimensions, determine whether the # mapping requires to be reversed. # Only applies to equal src/tgt dimensionality. src_free = set(src_dim_coverage.dims_free) & set( src_aux_coverage.dims_free ) tgt_free = set(tgt_dim_coverage.dims_free) & set( tgt_aux_coverage.dims_free ) free_flip = src_cube.ndim == tgt_cube.ndim and len(tgt_free) > len( src_free ) # Reverse the mapping direction. if broadcast_flip or free_flip: flip_mapping = { tgt_dim: src_dim for src_dim, tgt_dim in self.mapping.items() } self.map_rhs_to_lhs = not self.map_rhs_to_lhs dmsg = ( f"reversing the mapping from {self.mapping} to {flip_mapping}, " f"now map_rhs_to_lhs={self.map_rhs_to_lhs}" ) logger.debug(dmsg) self.mapping = flip_mapping # Now require to transpose/reshape the cubes into compatible # broadcast cubes again, due to possible non-commutative behaviour # after reversing the mapping direction. self._as_compatible_cubes() def _metadata_prepare(self): """ Populate the :attr:`~iris.common.resolve.Resolve.prepared_category` and :attr:`~iris.common.resolve.Resolve.prepared_factories` with the necessary metadata to be constructed and attached to the resulting resolved :class:`~iris.cube.Cube`. """ # Initialise the state. self.prepared_category = _CategoryItems( items_dim=[], items_aux=[], items_scalar=[] ) self.prepared_factories = [] # Map RHS cube to LHS cube, or smaller to larger cube rank. if self.map_rhs_to_lhs: src_cube = self.rhs_cube src_category_local = self.rhs_cube_category_local src_dim_coverage = self.rhs_cube_dim_coverage src_aux_coverage = self.rhs_cube_aux_coverage tgt_cube = self.lhs_cube tgt_category_local = self.lhs_cube_category_local tgt_dim_coverage = self.lhs_cube_dim_coverage tgt_aux_coverage = self.lhs_cube_aux_coverage else: src_cube = self.lhs_cube src_category_local = self.lhs_cube_category_local src_dim_coverage = self.lhs_cube_dim_coverage src_aux_coverage = self.lhs_cube_aux_coverage tgt_cube = self.rhs_cube tgt_category_local = self.rhs_cube_category_local tgt_dim_coverage = self.rhs_cube_dim_coverage tgt_aux_coverage = self.rhs_cube_aux_coverage # Determine the resultant cube dim coordinate/s. self._prepare_common_dim_payload(src_dim_coverage, tgt_dim_coverage) # Determine the resultant cube aux coordinate/s. self._prepare_common_aux_payload( src_aux_coverage.common_items_aux, # input tgt_aux_coverage.common_items_aux, # input self.prepared_category.items_aux, # output ) # Determine the resultant cube scalar coordinate/s. self._prepare_common_aux_payload( src_aux_coverage.common_items_scalar, # input tgt_aux_coverage.common_items_scalar, # input self.prepared_category.items_scalar, # output ignore_mismatch=True, ) self._prepare_local_payload( src_dim_coverage, src_aux_coverage, tgt_dim_coverage, tgt_aux_coverage, ) self._prepare_factory_payload( tgt_cube, tgt_category_local, from_src=False ) self._prepare_factory_payload(src_cube, src_category_local) def _metadata_resolve(self): """ Categorise the coordinate metadata of the cubes into three distinct groups; metadata from coordinates only available (local) on the LHS cube, metadata from coordinates only available (local) on the RHS cube, and metadata from coordinates common to both the LHS and RHS cubes. This is only applicable to coordinates that are members of the 'aux_coords' or 'dim_coords' of the participating cubes. """ # Determine the cube dim, aux and scalar coordinate items # for each individual cube. self.lhs_cube_category = self._categorise_items(self.lhs_cube) self.rhs_cube_category = self._categorise_items(self.rhs_cube) # Categorised dim, aux and scalar coordinate items local to LHS cube only. self.lhs_cube_category_local = _CategoryItems( items_dim=[], items_aux=[], items_scalar=[] ) # Categorised dim, aux and scalar coordinate items local to RHS cube only. self.rhs_cube_category_local = _CategoryItems( items_dim=[], items_aux=[], items_scalar=[] ) # Categorised dim, aux and scalar coordinate items common to both # LHS cube and RHS cube. self.category_common = _CategoryItems( items_dim=[], items_aux=[], items_scalar=[] ) def _categorise( lhs_items, rhs_items, lhs_local_items, rhs_local_items, common_items, ): rhs_items_metadata = [item.metadata for item in rhs_items] # Track common metadata here as a temporary convenience. common_metadata = [] # Determine items local to the lhs, and shared items # common to both lhs and rhs. for item in lhs_items: metadata = item.metadata if metadata in rhs_items_metadata: # The metadata is common between lhs and rhs. if metadata not in common_metadata: common_items.append(item) common_metadata.append(metadata) else: # The metadata is local to the lhs. lhs_local_items.append(item) # Determine items local to the rhs. for item in rhs_items: if item.metadata not in common_metadata: rhs_local_items.append(item) # Determine local and common dim category items. _categorise( self.lhs_cube_category.items_dim, # input self.rhs_cube_category.items_dim, # input self.lhs_cube_category_local.items_dim, # output self.rhs_cube_category_local.items_dim, # output self.category_common.items_dim, # output ) # Determine local and common aux category items. _categorise( self.lhs_cube_category.items_aux, # input self.rhs_cube_category.items_aux, # input self.lhs_cube_category_local.items_aux, # output self.rhs_cube_category_local.items_aux, # output self.category_common.items_aux, # output ) # Determine local and common scalar category items. _categorise( self.lhs_cube_category.items_scalar, # input self.rhs_cube_category.items_scalar, # input self.lhs_cube_category_local.items_scalar, # output self.rhs_cube_category_local.items_scalar, # output self.category_common.items_scalar, # output ) # Sort the resultant categories by metadata name for consistency, # in-place. categories = ( self.lhs_cube_category, self.rhs_cube_category, self.lhs_cube_category_local, self.rhs_cube_category_local, self.category_common, ) key_func = lambda item: item.metadata.name() for category in categories: category.items_dim.sort(key=key_func) category.items_aux.sort(key=key_func) category.items_scalar.sort(key=key_func) def _prepare_common_aux_payload( self, src_common_items, tgt_common_items, prepared_items, ignore_mismatch=None, ): """ Populate the ``prepared_items`` with a :class:`~iris.common.resolve._PreparedItem` containing the necessary metadata for each auxiliary coordinate to be constructed and attached to the resulting resolved :class:`~iris.cube.Cube`. .. note:: For mixed ``src`` and ``tgt`` coordinate types with matching metadata, an :class:`~iris.coords.AuxCoord` will be nominated for construction. Args: * src_common_items: The list of :attr:`~iris.common.resolve._AuxCoverage.common_items_aux` metadata for the ``src`` :class:`~iris.cube.Cube`. * tgt_common_items: The list of :attr:`~iris.common.resolve._AuxCoverage.common_items_aux` metadata for the ``tgt`` :class:`~iris.cube.Cube`. * prepared_items: The list of :class:`~iris.common.resolve._PreparedItem` metadata that will be used to construct the auxiliary coordinates that will be attached to the resulting resolved :class:`~iris.cube.Cube`. Kwargs: * ignore_mismatch: When ``False``, an exception will be raised if a difference is detected between corresponding ``src`` and ``tgt`` coordinate ``points`` and/or ``bounds``. When ``True``, the coverage metadata is ignored i.e., a coordinate will not be constructed and added to the resulting resolved :class:`~iris.cube.Cube`. Defaults to ``False``. """ from iris.coords import AuxCoord if ignore_mismatch is None: # Configure ability to ignore coordinate points/bounds # mismatches between common items. ignore_mismatch = False for src_item in src_common_items: src_metadata = src_item.metadata tgt_items = tuple( filter( lambda tgt_item: tgt_item.metadata == src_metadata, tgt_common_items, ) ) if not tgt_items: dmsg = ( f"ignoring src {self._src_cube_position} cube aux coordinate " f"{src_metadata}, does not match any common tgt " f"{self._tgt_cube_position} cube aux coordinate metadata" ) logger.debug(dmsg) elif len(tgt_items) > 1: dmsg = ( f"ignoring src {self._src_cube_position} cube aux coordinate " f"{src_metadata}, matches multiple [{len(tgt_items)}] common " f"tgt {self._tgt_cube_position} cube aux coordinate metadata" ) logger.debug(dmsg) else: (tgt_item,) = tgt_items src_coord = src_item.coord tgt_coord = tgt_item.coord points, bounds = self._prepare_points_and_bounds( src_coord, tgt_coord, src_item.dims, tgt_item.dims, ignore_mismatch=ignore_mismatch, ) if points is not None: src_type = type(src_coord) tgt_type = type(tgt_coord) # Downcast to aux if there are mixed container types. container = src_type if src_type is tgt_type else AuxCoord prepared_metadata = _PreparedMetadata( combined=src_metadata.combine(tgt_item.metadata), src=src_metadata, tgt=tgt_item.metadata, ) prepared_item = _PreparedItem( metadata=prepared_metadata, points=points.copy(), bounds=bounds if bounds is None else bounds.copy(), dims=tgt_item.dims, container=container, ) prepared_items.append(prepared_item) def _prepare_common_dim_payload( self, src_coverage, tgt_coverage, ignore_mismatch=None ): """ Populate the ``items_dim`` member of :attr:`~iris.common.resolve.Resolve.prepared_category_items` with a :class:`~iris.common.resolve._PreparedItem` containing the necessary metadata for each :class:`~iris.coords.DimCoord` to be constructed and attached to the resulting resolved :class:`~iris.cube.Cube`. Args: * src_coverage: The :class:`~iris.common.resolve._DimCoverage` metadata for the ``src`` :class:`~iris.cube.Cube`. * tgt_coverage: The :class:`~iris.common.resolve._DimCoverage` metadata for the ``tgt`` :class:`~iris.cube.Cube`. Kwargs: * ignore_mismatch: When ``False``, an exception will be raised if a difference is detected between corresponding ``src`` and ``tgt`` :class:`~iris.coords.DimCoord` ``points`` and/or ``bounds``. When ``True``, the coverage metadata is ignored i.e., a :class:`~iris.coords.DimCoord` will not be constructed and added to the resulting resolved :class:`~iris.cube.Cube`. Defaults to ``False``. """ from iris.coords import DimCoord if ignore_mismatch is None: # Configure ability to ignore coordinate points/bounds # mismatches between common items. ignore_mismatch = False for src_dim in src_coverage.dims_common: src_metadata = src_coverage.metadata[src_dim] src_coord = src_coverage.coords[src_dim] tgt_dim = self.mapping[src_dim] tgt_metadata = tgt_coverage.metadata[tgt_dim] tgt_coord = tgt_coverage.coords[tgt_dim] points, bounds = self._prepare_points_and_bounds( src_coord, tgt_coord, src_dim, tgt_dim, ignore_mismatch=ignore_mismatch, ) if points is not None: prepared_metadata = _PreparedMetadata( combined=src_metadata.combine(tgt_metadata), src=src_metadata, tgt=tgt_metadata, ) prepared_item = _PreparedItem( metadata=prepared_metadata, points=points.copy(), bounds=bounds if bounds is None else bounds.copy(), dims=(tgt_dim,), container=DimCoord, ) self.prepared_category.items_dim.append(prepared_item) def _get_prepared_item( self, metadata, category_local, from_src=True, from_local=False ): """ Find the :attr:`~iris.common.resolve._PreparedItem` from the :attr:`~iris.common.resolve.Resolve.prepared_category` that matches the provided ``metadata``. Alternatively, the ``category_local`` is searched to find a :class:`~iris.common.resolve._Item` with matching ``metadata`` from either the local ``src`` or ``tgt`` :class:`~iris.cube.Cube`. If a match is found, then a new `~iris.common.resolve._PreparedItem` is created and added to :attr:`~iris.common.resolve.Resolve.prepared_category` and returned. See ``from_local``. Args: * metadata: The target metadata of the prepared (or local) item to retrieve. * category_local: The :class:`~iris.common.resolve._CategoryItems` containing the local metadata of either the ``src`` or ``tgt`` :class:`~iris.cube.Cube`. See ``from_local``. Kwargs: * from_src: Boolean stating whether the ``metadata`` is from the ``src`` (``True``) or ``tgt`` :class:`~iris.cube.Cube`. Defaults to ``True``. * from_local: Boolean controlling whether the ``metadata`` is used to search the ``category_local`` (``True``) or the :attr:`~iris.common.resolve.Resolve.prepared_category`. Defaults to ``False``. Returns: The :class:`~iris.common.resolve._PreparedItem` matching the provided ``metadata``. """ result = None if from_local: category = category_local match = lambda item: item.metadata == metadata else: category = self.prepared_category if from_src: match = lambda item: item.metadata.src == metadata else: match = lambda item: item.metadata.tgt == metadata for member in category._fields: category_items = getattr(category, member) matched_items = tuple(filter(match, category_items)) if matched_items: if len(matched_items) > 1: dmsg = ( f"ignoring factory dependency {metadata}, multiple {'src' if from_src else 'tgt'} " f"{'local' if from_local else 'prepared'} metadata matches" ) logger.debug(dmsg) else: (item,) = matched_items if from_local: src = tgt = None if from_src: src = item.metadata dims = tuple( [self.mapping[dim] for dim in item.dims] ) else: tgt = item.metadata dims = item.dims result = self._create_prepared_item( item.coord, dims, src_metadata=src, tgt_metadata=tgt, ) getattr(self.prepared_category, member).append(result) else: result = item break return result def _prepare_factory_payload(self, cube, category_local, from_src=True): """ Populate the :attr:`~iris.common.resolve.Resolve.prepared_factories` with a :class:`~iris.common.resolve._PreparedFactory` containing the necessary metadata for each ``src`` and/or ``tgt`` auxiliary factory to be constructed and attached to the resulting resolved :class:`~iris.cube.Cube`. .. note:: The required dependencies of an auxiliary factory may not all be available in the :attr:`~iris.common.resolve.Resolve.prepared_category` and therefore this is a legitimate reason to add the associated metadata of the local dependency to the ``prepared_category``. Args: * cube: The :class:`~iris.cube.Cube` that may contain an auxiliary factory to be prepared. * category_local: The :class:`~iris.common.resolve._CategoryItems` of all metadata local to the provided ``cube``. Kwargs: * from_src: Boolean stating whether the provided ``cube`` is either a ``src`` or ``tgt`` :class:`~iris.cube.Cube` - used to retrieve the appropriate metadata from a :class:`~iris.common.resolve._PreparedMetadata`. """ for factory in cube.aux_factories: container = type(factory) dependencies = {} prepared_item = None found = True if tuple( filter( lambda item: item.container is container, self.prepared_factories, ) ): # debug: skipping, factory already exists dmsg = ( f"ignoring {'src' if from_src else 'tgt'} {container}, " f"a similar factory has already been prepared" ) logger.debug(dmsg) continue for ( dependency_name, dependency_coord, ) in factory.dependencies.items(): metadata = dependency_coord.metadata prepared_item = self._get_prepared_item( metadata, category_local, from_src=from_src ) if prepared_item is None: prepared_item = self._get_prepared_item( metadata, category_local, from_src=from_src, from_local=True, ) if prepared_item is None: dmsg = f"cannot find matching {metadata} for {container} dependency {dependency_name}" logger.debug(dmsg) found = False break dependencies[dependency_name] = prepared_item.metadata if found and prepared_item is not None: prepared_factory = _PreparedFactory( container=container, dependencies=dependencies ) self.prepared_factories.append(prepared_factory) else: dmsg = f"ignoring {'src' if from_src else 'tgt'} {container}, cannot find all dependencies" logger.debug(dmsg) def _prepare_local_payload_aux(self, src_aux_coverage, tgt_aux_coverage): """ Populate the ``items_aux`` member of :attr:`~iris.common.resolve.Resolve.prepared_category_items` with a :class:`~iris.common.resolve._PreparedItem` containing the necessary metadata for each ``src`` or ``tgt`` local auxiliary coordinate to be constructed and attached to the resulting resolved :class:`~iris.cube.Cube`. .. note:: In general, lenient behaviour subscribes to the philosophy that it is easier to remove metadata than it is to find then add metadata. To those ends, lenient behaviour supports metadata richness by adding both local ``src`` and ``tgt`` auxiliary coordinates. Alternatively, strict behaviour will only add a ``tgt`` local auxiliary coordinate that spans dimensions not mapped to by the ``src`` e.g., extra ``tgt`` dimensions. Args: * src_aux_coverage: The :class:`~iris.common.resolve.Resolve._AuxCoverage` for the ``src`` :class:`~iris.cube.Cube`. * tgt_aux_coverage: The :class:~iris.common.resolve.Resolve._AuxCoverage` for the ``tgt`` :class:`~iris.cube.Cube`. """ # Determine whether there are tgt dimensions not mapped to by an # associated src dimension, and thus may be covered by any local # tgt aux coordinates. extra_tgt_dims = set(range(tgt_aux_coverage.cube.ndim)) - set( self.mapping.values() ) if LENIENT["maths"]: mapped_src_dims = set(self.mapping.keys()) mapped_tgt_dims = set(self.mapping.values()) # Add local src aux coordinates. for item in src_aux_coverage.local_items_aux: if all([dim in mapped_src_dims for dim in item.dims]): tgt_dims = tuple([self.mapping[dim] for dim in item.dims]) prepared_item = self._create_prepared_item( item.coord, tgt_dims, src_metadata=item.metadata ) self.prepared_category.items_aux.append(prepared_item) else: dmsg = ( f"ignoring local src {self._src_cube_position} cube " f"aux coordinate {item.metadata}, as not all src " f"dimensions {item.dims} are mapped" ) logger.debug(dmsg) else: # For strict maths, only local tgt aux coordinates covering # the extra dimensions of the tgt cube may be added. mapped_tgt_dims = set() # Add local tgt aux coordinates. for item in tgt_aux_coverage.local_items_aux: tgt_dims = item.dims if all([dim in mapped_tgt_dims for dim in tgt_dims]) or any( [dim in extra_tgt_dims for dim in tgt_dims] ): prepared_item = self._create_prepared_item( item.coord, tgt_dims, tgt_metadata=item.metadata ) self.prepared_category.items_aux.append(prepared_item) else: dmsg = ( f"ignoring local tgt {self._tgt_cube_position} cube " f"aux coordinate {item.metadata}, as not all tgt " f"dimensions {tgt_dims} are mapped" ) logger.debug(dmsg) def _prepare_local_payload_dim(self, src_dim_coverage, tgt_dim_coverage): """ Populate the ``items_dim`` member of :attr:`~iris.common.resolve.Resolve.prepared_category_items` with a :class:`~iris.common.resolve._PreparedItem` containing the necessary metadata for each ``src`` or ``tgt`` local :class:`~iris.coords.DimCoord` to be constructed and attached to the resulting resolved :class:`~iris.cube.Cube`. .. note:: In general, a local coordinate will only be added if there is no other metadata competing to describe the same dimension/s on the ``tgt`` :class:`~iris.cube.Cube`. Lenient behaviour is more liberal, whereas strict behaviour will only add a local ``tgt`` coordinate covering an unmapped "extra" ``tgt`` dimension/s. Args: * src_dim_coverage: The :class:`~iris.common.resolve.Resolve._DimCoverage` for the ``src`` :class:`~iris.cube.Cube`. * tgt_dim_coverage: The :class:`~iris.common.resolve.Resolve._DimCoverage` for the ``tgt`` :class:`~iris.cube.Cube`. """ mapped_tgt_dims = self.mapping.values() # Determine whether there are tgt dimensions not mapped to by an # associated src dimension, and thus may be covered by any local # tgt dim coordinates. extra_tgt_dims = set(range(tgt_dim_coverage.cube.ndim)) - set( mapped_tgt_dims ) if LENIENT["maths"]: tgt_dims_conflict = set() # Add local src dim coordinates. for src_dim in src_dim_coverage.dims_local: tgt_dim = self.mapping[src_dim] # Only add the local src dim coordinate iff there is no # associated local tgt dim coordinate. if tgt_dim not in tgt_dim_coverage.dims_local: metadata = src_dim_coverage.metadata[src_dim] coord = src_dim_coverage.coords[src_dim] prepared_item = self._create_prepared_item( coord, tgt_dim, src_metadata=metadata ) self.prepared_category.items_dim.append(prepared_item) else: tgt_dims_conflict.add(tgt_dim) if self._debug: src_metadata = src_dim_coverage.metadata[src_dim] tgt_metadata = tgt_dim_coverage.metadata[tgt_dim] dmsg = ( f"ignoring local src {self._src_cube_position} cube " f"dim coordinate {src_metadata}, as conflicts with " f"tgt {self._tgt_cube_position} cube dim coordinate " f"{tgt_metadata}, mapping ({src_dim},)->({tgt_dim},)" ) logger.debug(dmsg) # Determine whether there are any tgt dims free to be mapped # by an available local tgt dim coordinate. tgt_dims_unmapped = ( set(tgt_dim_coverage.dims_local) - tgt_dims_conflict ) else: # For strict maths, only local tgt dim coordinates covering # the extra dimensions of the tgt cube may be added. tgt_dims_unmapped = extra_tgt_dims # Add local tgt dim coordinates. for tgt_dim in tgt_dims_unmapped: if tgt_dim in mapped_tgt_dims or tgt_dim in extra_tgt_dims: metadata = tgt_dim_coverage.metadata[tgt_dim] if metadata is not None: coord = tgt_dim_coverage.coords[tgt_dim] prepared_item = self._create_prepared_item( coord, tgt_dim, tgt_metadata=metadata ) self.prepared_category.items_dim.append(prepared_item) def _prepare_local_payload_scalar( self, src_aux_coverage, tgt_aux_coverage ): """ Populate the ``items_scalar`` member of :attr:`~iris.common.resolve.Resolve.prepared_category_items` with a :class:`~iris.common.resolve._PreparedItem` containing the necessary metadata for each ``src`` or ``tgt`` local scalar coordinate to be constructed and attached to the resulting resolved :class:`~iris.cube.Cube`. .. note:: In general, lenient behaviour subscribes to the philosophy that it is easier to remove metadata than it is to find then add metadata. To those ends, lenient behaviour supports metadata richness by adding both local ``src`` and ``tgt`` scalar coordinates. Alternatively, strict behaviour will only add a ``tgt`` local scalar coordinate when the ``src`` is a scalar :class:`~iris.cube.Cube` with no local scalar coordinates. Args: * src_aux_coverage: The :class:`~iris.common.resolve.Resolve._AuxCoverage` for the ``src`` :class:`~iris.cube.Cube`. * tgt_aux_coverage: The :class:~iris.common.resolve.Resolve._AuxCoverage` for the ``tgt`` :class:`~iris.cube.Cube`. """ # Add all local tgt scalar coordinates iff the src cube is a # scalar cube with no local src scalar coordinates. # Only for strict maths. src_scalar_cube = ( not LENIENT["maths"] and src_aux_coverage.cube.ndim == 0 and len(src_aux_coverage.local_items_scalar) == 0 ) if src_scalar_cube or LENIENT["maths"]: # Add any local src scalar coordinates, if available. for item in src_aux_coverage.local_items_scalar: prepared_item = self._create_prepared_item( item.coord, item.dims, src_metadata=item.metadata ) self.prepared_category.items_scalar.append(prepared_item) # Add any local tgt scalar coordinates, if available. for item in tgt_aux_coverage.local_items_scalar: prepared_item = self._create_prepared_item( item.coord, item.dims, tgt_metadata=item.metadata ) self.prepared_category.items_scalar.append(prepared_item) def _prepare_local_payload( self, src_dim_coverage, src_aux_coverage, tgt_dim_coverage, tgt_aux_coverage, ): """ Populate the :attr:`~iris.common.resolve.Resolve.prepared_category_items` with a :class:`~iris.common.resolve._PreparedItem` containing the necessary metadata from the ``src`` and/or ``tgt`` :class:`~iris.cube.Cube` for each coordinate to be constructed and attached to the resulting resolved :class:`~iris.cube.Cube`. Args: * src_dim_coverage: The :class:`~iris.common.resolve.Resolve._DimCoverage` for the ``src`` :class:`~iris.cube.Cube`. * src_aux_coverage: The :class:`~iris.common.resolve.Resolve._AuxCoverage` for the ``src`` :class:`~iris.cube.Cube`. * tgt_dim_coverage: The :class:`~iris.common.resolve.Resolve._DimCoverage` for the ``tgt`` :class:`~iris.cube.Cube`. * tgt_aux_coverage: The :class:~iris.common.resolve.Resolve._AuxCoverage` for the ``tgt`` :class:`~iris.cube.Cube`. """ # Add local src/tgt dim coordinates. self._prepare_local_payload_dim(src_dim_coverage, tgt_dim_coverage) # Add local src/tgt aux coordinates. self._prepare_local_payload_aux(src_aux_coverage, tgt_aux_coverage) # Add local src/tgt scalar coordinates. self._prepare_local_payload_scalar(src_aux_coverage, tgt_aux_coverage) def _prepare_points_and_bounds( self, src_coord, tgt_coord, src_dims, tgt_dims, ignore_mismatch=None ): """ Compare the points and bounds of the ``src`` and ``tgt`` coordinates to ensure that they are equivalent, taking into account broadcasting when appropriate. .. note:: An exception will be raised if the ``src`` and ``tgt`` coordinates cannot be broadcast. .. note:: An exception will be raised if either the points or bounds are different, however appropriate lenient behaviour concessions are applied. Args: * src_coord: The ``src`` :class:`~iris.cube.Cube` coordinate with metadata matching the ``tgt_coord``. * tgt_coord: The ``tgt`` :class`~iris.cube.Cube` coordinate with metadata matching the ``src_coord``. * src_dims: The dimension/s of the ``src_coord`` attached to the ``src`` :class:`~iris.cube.Cube`. * tgt_dims: The dimension/s of the ``tgt_coord`` attached to the ``tgt`` :class:`~iris.cube.Cube`. Kwargs: * ignore_mismatch: For lenient behaviour only, don't raise an exception if there is a difference between the ``src`` and ``tgt`` coordinate points or bounds. Defaults to ``False``. Returns: Tuple of equivalent ``points`` and ``bounds``, otherwise ``None``. """ from iris.util import array_equal if ignore_mismatch is None: # Configure ability to ignore coordinate points/bounds # mismatches between common items. ignore_mismatch = False points, bounds = None, None if not isinstance(src_dims, Iterable): src_dims = (src_dims,) if not isinstance(tgt_dims, Iterable): tgt_dims = (tgt_dims,) # Deal with coordinates that have been sliced. if src_coord.ndim != tgt_coord.ndim: if tgt_coord.ndim > src_coord.ndim: # Use the tgt coordinate points/bounds. points = tgt_coord.points bounds = tgt_coord.bounds else: # Use the src coordinate points/bounds. points = src_coord.points bounds = src_coord.bounds # Deal with coordinates spanning broadcast dimensions. if ( points is None and bounds is None and src_coord.shape != tgt_coord.shape ): # Check whether the src coordinate is broadcasting. dims = tuple([self.mapping[dim] for dim in src_dims]) src_shape_broadcast = tuple([self.shape[dim] for dim in dims]) src_cube_shape = self._src_cube.shape src_shape = tuple([src_cube_shape[dim] for dim in src_dims]) src_broadcasting = src_shape != src_shape_broadcast # Check whether the tgt coordinate is broadcasting. tgt_shape_broadcast = tuple([self.shape[dim] for dim in tgt_dims]) tgt_cube_shape = self._tgt_cube.shape tgt_shape = tuple([tgt_cube_shape[dim] for dim in tgt_dims]) tgt_broadcasting = tgt_shape != tgt_shape_broadcast if src_broadcasting and tgt_broadcasting: # TBD: Extend capability to support attempting to broadcast two-way multi-dimensional coordinates. emsg = ( f"Cannot broadcast the coordinate {src_coord.name()!r} on " f"{self._src_cube_position} cube {self._src_cube.name()!r} and " f"coordinate {tgt_coord.name()!r} on " f"{self._tgt_cube_position} cube {self._tgt_cube.name()!r} to " f"broadcast shape {tgt_shape_broadcast}." ) raise ValueError(emsg) elif src_broadcasting: # Use the tgt coordinate points/bounds. points = tgt_coord.points bounds = tgt_coord.bounds elif tgt_broadcasting: # Use the src coordinate points/bounds. points = src_coord.points bounds = src_coord.bounds if points is None and bounds is None: # Note that, this also ensures shape equality. eq_points = array_equal( src_coord.points, tgt_coord.points, withnans=True ) if eq_points: points = src_coord.points src_has_bounds = src_coord.has_bounds() tgt_has_bounds = tgt_coord.has_bounds() if src_has_bounds and tgt_has_bounds: src_bounds = src_coord.bounds eq_bounds = array_equal( src_bounds, tgt_coord.bounds, withnans=True ) if eq_bounds: bounds = src_bounds else: if LENIENT["maths"] and ignore_mismatch: # For lenient, ignore coordinate with mis-matched bounds. dmsg = ( f"ignoring src {self._src_cube_position} cube " f"{src_coord.metadata}, unequal bounds with " f"tgt {self._tgt_cube_position} cube, " f"{src_dims}->{tgt_dims}" ) logger.debug(dmsg) else: emsg = ( f"Coordinate {src_coord.name()!r} has different bounds for the " f"LHS cube {self.lhs_cube.name()!r} and " f"RHS cube {self.rhs_cube.name()!r}." ) raise ValueError(emsg) else: # For lenient, use either of the coordinate bounds, if they exist. if LENIENT["maths"]: if src_has_bounds: dmsg = ( f"using src {self._src_cube_position} cube " f"{src_coord.metadata} bounds, tgt has no bounds" ) logger.debug(dmsg) bounds = src_coord.bounds else: dmsg = ( f"using tgt {self._tgt_cube_position} cube " f"{tgt_coord.metadata} bounds, src has no bounds" ) logger.debug(dmsg) bounds = tgt_coord.bounds else: # For strict, both coordinates must have bounds, or both # coordinates must not have bounds. if src_has_bounds: emsg = ( f"Coordinate {src_coord.name()!r} has bounds for the " f"{self._src_cube_position} cube {self._src_cube.name()!r}, " f"but not the {self._tgt_cube_position} cube {self._tgt_cube.name()!r}." ) raise ValueError(emsg) if tgt_has_bounds: emsg = ( f"Coordinate {tgt_coord.name()!r} has bounds for the " f"{self._tgt_cube_position} cube {self._tgt_cube.name()!r}, " f"but not the {self._src_cube_position} cube {self._src_cube.name()!r}." ) raise ValueError(emsg) else: if LENIENT["maths"] and ignore_mismatch: # For lenient, ignore coordinate with mis-matched points. dmsg = ( f"ignoring src {self._src_cube_position} cube " f"{src_coord.metadata}, unequal points with tgt " f"{src_dims}->{tgt_dims}" ) logger.debug(dmsg) else: emsg = ( f"Coordinate {src_coord.name()!r} has different points for the " f"LHS cube {self.lhs_cube.name()!r} and " f"RHS cube {self.rhs_cube.name()!r}." ) raise ValueError(emsg) return points, bounds @property def _src_cube(self): assert self.map_rhs_to_lhs is not None if self.map_rhs_to_lhs: result = self.rhs_cube else: result = self.lhs_cube return result @property def _src_cube_position(self): assert self.map_rhs_to_lhs is not None if self.map_rhs_to_lhs: result = "RHS" else: result = "LHS" return result @property def _src_cube_resolved(self): assert self.map_rhs_to_lhs is not None if self.map_rhs_to_lhs: result = self.rhs_cube_resolved else: result = self.lhs_cube_resolved return result @_src_cube_resolved.setter def _src_cube_resolved(self, cube): assert self.map_rhs_to_lhs is not None if self.map_rhs_to_lhs: self.rhs_cube_resolved = cube else: self.lhs_cube_resolved = cube @property def _tgt_cube(self): assert self.map_rhs_to_lhs is not None if self.map_rhs_to_lhs: result = self.lhs_cube else: result = self.rhs_cube return result @property def _tgt_cube_position(self): assert self.map_rhs_to_lhs is not None if self.map_rhs_to_lhs: result = "LHS" else: result = "RHS" return result @property def _tgt_cube_resolved(self): assert self.map_rhs_to_lhs is not None if self.map_rhs_to_lhs: result = self.lhs_cube_resolved else: result = self.rhs_cube_resolved return result @_tgt_cube_resolved.setter def _tgt_cube_resolved(self, cube): assert self.map_rhs_to_lhs is not None if self.map_rhs_to_lhs: self.lhs_cube_resolved = cube else: self.rhs_cube_resolved = cube def _tgt_cube_prepare(self, data): cube = self._tgt_cube # Replace existing tgt cube data with the provided data. cube.data = data # Clear the aux factories. for factory in cube.aux_factories: cube.remove_aux_factory(factory) # Clear the cube coordinates. for coord in cube.coords(): cube.remove_coord(coord) # Clear the cube cell measures. for cm in cube.cell_measures(): cube.remove_cell_measure(cm) # Clear the ancillary variables. for av in cube.ancillary_variables(): cube.remove_ancillary_variable(av)
[docs] def cube(self, data, in_place=False): """ Create the resultant :class:`~iris.cube.Cube` from the resolved ``lhs`` and ``rhs`` :class:`~iris.cube.Cube` operands, using the provided ``data``. Args: * data: The data payload for the resultant :class:`~iris.cube.Cube`, which **must match** the expected resolved :attr:`~iris.common.resolve.Resolve.shape`. Kwargs: * in_place: If ``True``, the ``data`` is inserted into the ``tgt`` :class:`~iris.cube.Cube`. The existing metadata of the ``tgt`` :class:`~iris.cube.Cube` is replaced with the resolved metadata from the ``lhs`` and ``rhs`` :class:`~iris.cube.Cube` operands. Otherwise, a **new** :class:`~iris.cube.Cube` instance is returned. Default is ``False``. Returns: :class:`~iris.cube.Cube` .. note:: :class:`~iris.common.resolve.Resolve` will determine whether the ``lhs`` :class:`~iris.cube.Cube` operand is mapped to the ``rhs`` :class:`~iris.cube.Cube` operand, or vice versa. In general, the **lower rank** operand (``src``) is mapped to the **higher rank** operand (``tgt``). Therefore, the ``src`` :class:`~iris.cube.Cube` may be either the ``lhs`` or the ``rhs`` :class:`~iris.cube.Cube` operand, given the direction of the mapping. See :attr:`~iris.common.resolve.Resolve.map_rhs_to_lhs`. .. warning:: It may not be possible to perform an ``in_place`` operation, due to any transposition or extended broadcasting that requires to be performed i.e., the ``tgt`` :class:`~iris.cube.Cube` **must match** the expected resolved :attr:`~iris.common.resolve.Resolve.shape`. For example: .. testsetup:: in-place import iris import numpy as np from iris.common import Resolve cube1 = iris.load_cube(iris.sample_data_path("A1B_north_america.nc")) cube2 = iris.load_cube(iris.sample_data_path("E1_north_america.nc"))[0] cube2.transpose() zeros = np.zeros(cube1.shape, dtype=cube1.dtype) .. doctest:: in-place >>> resolver = Resolve(cube1, cube2) >>> resolver.map_rhs_to_lhs True >>> cube1.data.sum() 124652160.0 >>> zeros.shape (240, 37, 49) >>> zeros.sum() 0.0 >>> result = resolver.cube(zeros, in_place=True) >>> result is cube1 True >>> cube1.data.sum() 0.0 """ from iris.cube import Cube expected_shape = self.shape # Ensure that we have been provided with candidate cubes, which are # now resolved and metadata is prepared, ready and awaiting the # resultant resolved cube. if expected_shape is None: emsg = ( "Cannot resolve resultant cube, as no candidate cubes have " "been provided." ) raise ValueError(emsg) if not hasattr(data, "shape"): data = np.asanyarray(data) # Ensure that the shape of the provided data is the expected # shape of the resultant resolved cube. if data.shape != expected_shape: emsg = ( "Cannot resolve resultant cube, as the provided data must " f"have shape {expected_shape}, got data shape {data.shape}." ) raise ValueError(emsg) if in_place: result = self._tgt_cube if result.shape != expected_shape: emsg = ( "Cannot resolve resultant cube in-place, as the " f"{self._tgt_cube_position} tgt cube {result.name()!r} " f"requires data with shape {result.shape}, got data " f"shape {data.shape}. Suggest not performing this " "operation in-place." ) raise ValueError(emsg) # Prepare target cube for in-place population with the prepared # metadata content and the provided data. self._tgt_cube_prepare(data) else: # Create the resultant resolved cube with provided data. result = Cube(data) # Add the combined cube metadata from both the candidate cubes. result.metadata = self.lhs_cube.metadata.combine( self.rhs_cube.metadata ) # Add the prepared dim coordinates. for item in self.prepared_category.items_dim: coord = item.container(item.points, bounds=item.bounds) coord.metadata = item.metadata.combined result.add_dim_coord(coord, item.dims) # Add the prepared aux and scalar coordinates. prepared_aux_coords = ( self.prepared_category.items_aux + self.prepared_category.items_scalar ) for item in prepared_aux_coords: coord = item.container(item.points, bounds=item.bounds) coord.metadata = item.metadata.combined try: result.add_aux_coord(coord, item.dims) except ValueError as err: scalar = dims = "" if item.dims: plural = "s" if len(item.dims) > 1 else "" dims = f" with tgt dim{plural} {item.dims}" else: scalar = "scalar " dmsg = ( f"ignoring prepared {scalar}coordinate " f"{coord.metadata}{dims}, got {err!r}" ) logger.debug(dmsg) # Add the prepared aux factories. for prepared_factory in self.prepared_factories: dependencies = dict() for ( dependency_name, prepared_metadata, ) in prepared_factory.dependencies.items(): coord = result.coord(prepared_metadata.combined) dependencies[dependency_name] = coord factory = prepared_factory.container(**dependencies) result.add_aux_factory(factory) return result
@property def mapped(self): """ Boolean state representing whether **all** ``src`` :class:`~iris.cube.Cube` dimensions have been associated with relevant ``tgt`` :class:`~iris.cube.Cube` dimensions. .. note:: :class:`~iris.common.resolve.Resolve` will determine whether the ``lhs`` :class:`~iris.cube.Cube` operand is mapped to the ``rhs`` :class:`~iris.cube.Cube` operand, or vice versa. In general, the **lower rank** operand (``src``) is mapped to the **higher rank** operand (``tgt``). Therefore, the ``src`` :class:`~iris.cube.Cube` may be either the ``lhs`` or the ``rhs`` :class:`~iris.cube.Cube` operand, given the direction of the mapping. See :attr:`~iris.common.resolve.Resolve.map_rhs_to_lhs`. If no :class:`~iris.cube.Cube` operands have been provided, then ``mapped`` is ``None``. For example: .. doctest:: >>> print(cube1) air_temperature / (K) (time: 240; latitude: 37; longitude: 49) Dimension coordinates: time x - - latitude - x - longitude - - x Auxiliary coordinates: forecast_period x - - Scalar coordinates: forecast_reference_time 1859-09-01 06:00:00 height 1.5 m Cell methods: mean time (6 hour) Attributes: Conventions CF-1.5 Model scenario A1B STASH m01s03i236 source Data from Met Office Unified Model 6.05 >>> print(cube2) air_temperature / (K) (longitude: 49; latitude: 37) Dimension coordinates: longitude x - latitude - x Scalar coordinates: forecast_period 10794 hours forecast_reference_time 1859-09-01 06:00:00 height 1.5 m time 1860-06-01 00:00:00, bound=(1859-12-01 00:00:00, 1860-12-01 00:00:00) Cell methods: mean time (6 hour) Attributes: Conventions CF-1.5 Model scenario E1 STASH m01s03i236 source Data from Met Office Unified Model 6.05 >>> Resolve().mapped is None True >>> resolver = Resolve(cube1, cube2) >>> resolver.mapped True >>> resolver.map_rhs_to_lhs True >>> resolver = Resolve(cube2, cube1) >>> resolver.mapped True >>> resolver.map_rhs_to_lhs False """ result = None if self.mapping is not None: result = self._src_cube.ndim == len(self.mapping) return result @property def shape(self): """ Proposed shape of the final resolved cube given the ``lhs`` :class:`~iris.cube.Cube` operand and the ``rhs`` :class:`~iris.cube.Cube` operand. If no :class:`~iris.cube.Cube` operands have been provided, then ``shape`` is ``None``. For example: .. doctest:: >>> print(cube1) air_temperature / (K) (time: 240; latitude: 37; longitude: 49) Dimension coordinates: time x - - latitude - x - longitude - - x Auxiliary coordinates: forecast_period x - - Scalar coordinates: forecast_reference_time 1859-09-01 06:00:00 height 1.5 m Cell methods: mean time (6 hour) Attributes: Conventions CF-1.5 Model scenario A1B STASH m01s03i236 source Data from Met Office Unified Model 6.05 >>> print(cube2) air_temperature / (K) (longitude: 49; latitude: 37) Dimension coordinates: longitude x - latitude - x Scalar coordinates: forecast_period 10794 hours forecast_reference_time 1859-09-01 06:00:00 height 1.5 m time 1860-06-01 00:00:00, bound=(1859-12-01 00:00:00, 1860-12-01 00:00:00) Cell methods: mean time (6 hour) Attributes: Conventions CF-1.5 Model scenario E1 STASH m01s03i236 source Data from Met Office Unified Model 6.05 >>> Resolve().shape is None True >>> Resolve(cube1, cube2).shape (240, 37, 49) >>> Resolve(cube2, cube1).shape (240, 37, 49) """ return self._broadcast_shape