Iris: [PI] Implement new cube arithmetic proposal

[lbdreyer]

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

Reference:

• [FB] PR #3583
• [FB] PR #3739
• [FB] PR #3774
• PR #3785 (cube-arithmetic feature branch merge back to master)
• [FB] PR #3805
• [FB] PR #3806
• [FB] PR #3842
• [FB] PR #3869
• PR #3890 (cube-arithmetic-docs feature branch merge back to master)

---

Acceptance Criteria

Core deliverables

• [x] Add lenient infra-structure:
  
  
  
  • [x] client decorator
  
  
  • [x] service decorator
  
  
  • [x] context manager
  
  
  • [x] runtime options state manager (thread-safe)
  
  
  • [x] client/service active protocol
  
  
• [x] Support lenient metadata functionality:
  
  
  
  • [x] comparison
  
  
  • [x] combination
  
  
  • [x] difference
  
  
• [x] Support lenient coordinate (macroscopic) compliance checking
• [x] ~Add cube arithmetic switch to opt-in to previous/strict behaviour~
• [x] Remove AncillaryVariables and CellMeasures from resultant cube
• [x] Test coverage
• [ ] Discuss metadata rename to signature ? @pp-mo
• [x] Add associated ASV metrics
• [x] 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
    
    
    
  
  
• [x] Close connective tissue PRs/Issues
• [x] 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
  
  
• [x] 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
  
  
• [x] Unify metadata into a common API returning namedtuple derived classes:
  
  
  
  • [x] ~Use lru_cache for optimised LUT metadata generation~
    
    
    
    
    
    • Issues with non-hashable metadata :cry:
      
      
      
      
      
      
      
      • attributes
      
      
      
      
      • coord_system
      
      
      
      
    
    
    
  
  
  • [x] Create a common BaseMetadata class hierarchy
    
    
    
    
    
    • [x] Use a _BaseMeta metaclass
    
    
    
    • [x] Include Python2 < support of None
    
    
    
  
  
  • [x] iris.coords._DimensionalMetadata._is_defn -> iris.coords._DimensionalMetadata.metadata (BaseMetadata)
  
  
  • [x] iris.coords.AncillaryVariable.metadata (BaseMetadata)
  
  
  • [x] iris.coords.CellMeasure._as_defn -> iris.coords.CellMeasure.metadata (CellMeasureMetadata)
  
  
  • [x] iris.coords.Coord._as_defn -> iris.coords.Coord.metadata (CoordMetadata)
  
  
  • [x] iris.iterate._CoordWrapper._as_defn -> iris.iterate._CoordWrapper.metadata (CoordMetadata)
  
  
  • [x] iris.aux_factory.AuxCoordFactory._as_defn -> iris.aux_factory.AuxCoordFactory.metadata
  
  
  • [x] Resolve STASH only specific to iris.cube.Cube
    
    
    
    
    
    • [x] fix name() method
    
    
    
    • [x] fix names property
    
    
    
  
  
• [ ] Deprecate:
  
  
  
  • [ ] iris.cube.Cube.is_compatible
  
  
  • [ ] iris.coords.Coord.is_compatible
  
  
  • [ ] iris.util.as_compatible_shape
  
  
  • [ ] iris.util.describe_diff
  
  
• [x] ~Backport to 2.3.0:~
  
  
  
  • [x] ~Add future switch for new arithmetic~
  
  
  • [x] ~Add supporting documentation and examples etc~
  
  
  • [x] ~Add a whatsnew entry~
  
  

---

Future work

• [ ] Rename iris.coords._DimensionalMetadata to ...
• [ ] Rename iris.analysis._dimensional_metadata_comparison to ...
• [x] ~Rename STASH to stash in Names namedtuple~
• [x] Optimise performance by keeping metadata state not in the container classes
• [x] Default units clarification, see https://github.com/SciTools/iris/issues/3585
• [ ] Create iris.core with associated re-organisation
• [x] ~Remove circular from DimCoord equality and make it a calculated @property~
• [x] ~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