[PI] Implement new cube arithmetic proposal

[lbdreyer]

Following the decision from #2599, we need to implement the approach we decide on

Reference:

• [FB] PR [FB] [PI-3478] Common metadata API #3583
• [FB] PR [FB] [PI-3478] Lenient metadata #3739
• [FB] PR [FB] [PI-3478] Lenient cube arithmetic #3774
• PR [PI-3478] Merge cube arithmetic feature branch #3785 (cube-arithmetic feature branch merge back to master)
• [FB] PR [FB] [PI-3478] Fix resolve free flip of src/tgt mapping #3805
• [FB] PR [FB] [PI-3478] cube arithmetic whatsnew entries #3806
• [FB] PR [FB] [PI-3478] Add resolve doc-strings #3842
• [FB] PR [FB] [PI-3478] Metadata and cube maths documentation #3869
• PR Cube arithmetic docs to master #3890 (cube-arithmetic-docs feature branch merge back to master)

---

Acceptance Criteria

Core deliverables

• Add lenient infra-structure:
  • client decorator
  • service decorator
  • context manager
  • runtime options state manager (thread-safe)
  • client/service active protocol
• Support lenient metadata functionality:
  • comparison
  • combination
  • difference
• Support lenient coordinate (macroscopic) compliance checking
• Add cube arithmetic switch to opt-in to previous/strict behaviour
• Remove AncillaryVariables and CellMeasures from resultant cube
• Test coverage
• Discuss metadata rename to signature ? @pp-mo
• Add associated ASV metrics
• Resolve dilemma of whether circular is part of DimCoord metadata
  • what are the implications of this?
    • require DimCoordMetadata, AuxCoordMetadata and CoordMetadata (common parent) support
    • utility of supporting cross-metadata setting for DimCoord and AuxCoord
• Close connective tissue PRs/Issues
• Add supporting documentation and examples etc
  • Clarify metadata name vs identity
  • Define lenient/strict operations for __eq__, combine and difference
  • <container>.metadata setter/getter patterns
• Add whatsnew entry

---

Optional deliverables

Not sure whether some of these may get pulled into the core deliverables...

• Support lenient coodinate metadata in iris.cube.Cube.coords
  • iris.cube.Cube.replace_coord
  • iris.cube.Cube.remove_coord
• Unify metadata into a common API returning namedtuple derived classes:
  • Use lru_cache for optimised LUT metadata generation
    • Issues with non-hashable metadata 😢
      • attributes
      • coord_system
  • Create a common BaseMetadata class hierarchy
    • Use a _BaseMeta metaclass
    • Include Python2 < support of None
  • iris.coords._DimensionalMetadata._is_defn -> iris.coords._DimensionalMetadata.metadata (BaseMetadata)
  • iris.coords.AncillaryVariable.metadata (BaseMetadata)
  • iris.coords.CellMeasure._as_defn -> iris.coords.CellMeasure.metadata (CellMeasureMetadata)
  • iris.coords.Coord._as_defn -> iris.coords.Coord.metadata (CoordMetadata)
  • iris.iterate._CoordWrapper._as_defn -> iris.iterate._CoordWrapper.metadata (CoordMetadata)
  • iris.aux_factory.AuxCoordFactory._as_defn -> iris.aux_factory.AuxCoordFactory.metadata
  • Resolve STASH only specific to iris.cube.Cube
    • fix name() method
    • fix names property
• Deprecate:
  • iris.cube.Cube.is_compatible
  • iris.coords.Coord.is_compatible
  • iris.util.as_compatible_shape
  • iris.util.describe_diff
• Backport to 2.3.0:
  • Add future switch for new arithmetic
  • Add supporting documentation and examples etc
  • Add a whatsnew entry

---

Future work

• Rename iris.coords._DimensionalMetadata to ...
• Rename iris.analysis._dimensional_metadata_comparison to ...
• Rename STASH to stash in Names namedtuple
• Optimise performance by keeping metadata state not in the container classes
• Default units clarification, see Default units #3585
• Create iris.core with associated re-organisation
• Remove circular from DimCoord equality and make it a calculated @property
• Unified treatment of attributes STASH/GRIB_CODE
• Support @lenient_client and @lenient_service on same function/method

[bjlittle]

Ref #1911

[abooton]

See PR #3558

[bjlittle]

Closed by #3785