Iris: What are compatible cubes compatible for?

[rcomer]

The cube.is_compatible method and its associated iris.util.describe_diff function compare the metadata on two cubes to indicate whether they are compatible (and if not, why not). But it is not clear from the docs what you can do with compatible cubes that you cannot do with incompatible cubes.

The most obvious application is to get clues about why a cubelist won't merge (or concatenate). If this is the intended purpose, then it would be good to add comparisons of standard_name, long_name and var_name, instead of just name() as well as checking whether an attributes key exists in one but not the other. I was just about to make a branch to do this, but thought I'd better check first that these functions aren't designed for something else entirely!

[rcomer]

I've just noticed that coords also have an is_compatible method. Again it is clear what is checked, but not clear what the practical implications of compatibility are.

[pp-mo]

Personally I have always distrusted this method and its terminology precisely because it never was clear what it meant or was for !!
There is a bit more clarity in the documentation for iris.util.decribe_diff, which claims to be linked to this, and explains its relationship to "mergability".

Coord.is_compatible is a somewhat different thing, because Cube.is_compatible is really all about the non-dimensional metadata (which therefore excludes coords).
However, Coord.is_compatible also tests the similar 'non-dimensional' aspects of a Coord : name, units + attributes.

In the Iris codebase itself, AFAICT ...

• Cube compatibility is only used in (1) Cube.intersect, and (2) iris.util.describe_diff
• Coord compatibility is (?only) used in iris.analysis.RectilinearRegridder.

In fact, Cube.is_compatible basically tests the same things as are in Cube.metadata -- which concept I likewise dislike, for all the same reasons ...
However it differs from "cube.metadata" equivalence, in that it uses "name()" in place of comparing all names.
It also isn't _quite_ a simple phenomenon check, as two cubes can be the same phenomenon but with different units.

All of these different versions of equivalence and difference are, in my view, unnecessarily confusing!
However, we do need different equivalence concepts for different purposes.
I can think of:

• Cube/Coord equality testing
• merge and concatenate (I think they actually have slightly different rules ?)
• cube arithmetic
• Coord matching in regridding

I'd be up for improving any of this : either improving the clarity of what these things are + what they are for, or dropping them if possible !

[rcomer]

• merge and concatenate (I think they actually have slightly different rules ?)
• cube arithmetic

So we should resolve #3234 and #2599 before sorting this out? Seems pretty simple then 😆 .

[pp-mo]

resolve #3234 and #2599 before sorting this out?

🏃 😨 🐊

[bjlittle]

Heads-up @rcomer and @pp-mo ...

As part of #2599 I intend to deprecate iris.cube.Cube.is_compatible, iris.coords._DimensionalMetadata.is_compatible, iris.coords.Coord.is_compatible and iris.util.describe_diff in the forthcoming 2.3.0 release, and then remove them in 3.0.0.

Now's the time to do it 😁