Review Z dimension for SpaceDomain

[ThibHlln]

At the moment, an optional Z dimension can be included in SpaceDomain. The original intention of adding it was to be able to check for the Z axis of a dataset provided to the Component (e.g. measurement level). But having a third dimension is problematic at the science level. The compoment developper may be given a 2D or a 3D array. If the Z dimension was limited to a size of 1, a systematic "squeeze" could be performed before giving the data array to the component, but there is no such enforcement for size 1 at the moment.

This third dimension is important nonetheless. For instance, layers for taking into account different vegetation heights or soil moisture layers could be needed. When these are about holding multi-layer states, this is alredy accommodated for by using the 'divisions' key in _states_info (so no need for a Z dimension in SpaceDomain), if this is about getting multi-layer inputs, then there is a gap at the moment, and there may be a need for a Z dimension to remain in SpaceDomain.

This is also problematic for Fortran and C extensions if the rank of the array is varying between 2 and 3.

I am opening this issue to register the problem, and start a discussion on this. Until this problem is solved, it may be good to remove the possibility for a Z dimension in SpaceDomain to avoid problems when arriving in the science component code and assume only a 2D array can be given.

[rich-HJ]

Currently it looks like "divisions" can cope with things like veg types and even soil layers. The issues may come if things like altitude tiling is to be implemented in a similar way to JULES. In this case the meteorological driving data might vary depending on height.

[rich-HJ]

I guess another issue is if we have multiple dimensions. Soil layers and soil tiles in the same grid box. Can dimensions be a multiple value tuple?

[ThibHlln]

Currently it looks like "divisions" can cope with things like veg types and even soil layers.

I think "divisions" should only be used for information that remains internal to the component. It is a value that is specific to a component, and potentially customisable (although not yet supported), but that should not be known by another component for these two reasons. So it would be fine for soil layers, but not for vegetation types - vegetation types is some information that we are likely to standardise so that it can be passed between components (i.e. subgrid heterogeneity) because it makes sense for two components to be aware of it (unlike soil layers to me).

The issues may come if things like altitude tiling is to be implemented in a similar way to JULES. In this case the meteorological driving data might vary depending on height.

Yes, if the Component needs data with a Z dimension, we need a solution for this. This is why I am not sure whether to drop the Z dimension or not.

I guess another issue is if we have multiple dimensions. Soil layers and soil tiles in the same grid box. Can dimensions be a multiple value tuple?

As I envisage it, soil layers would be under the "divisions" axis while soil tiles would be under the "area_type" axis (i.e. the subgrid heterogeneity one), so I think it should be fine once we have sorted out the subgrid heterogeneity aspect. E.g. the states of a Component with a 2D SpaceDomain with some subgrid heterogeneity and soil tiles would have the following dimensions: [area_type, Y, X, divisions].

[ThibHlln]

I think a component needs to be offered 3 ways of having a vertical dimension:

1. using state "divisions" (e.g. for conceptual soil moisture layers)
   → only usable for (some to all) component state variables
   → requires component contributor to specify expected dimension length (with potential user customisation through a component constant if contributor allows)
2. using size-1 vertical dimension (e.g. for measurement height)
   → usable for (some to all) component input variables
   → vertical dimension data check between user-provided information (input data and spacedomain) and contributor-expected information
   → requires component contributor to provide dimension data (e.g. expected measurement height)
   → vertical dimension needs to be dropped (i.e. field squeezed) during component instantiation to work with horizontal dimension(s) only
3. using any size vertical dimension (e.g. a "true" 3D component with explicit soil horizons)
   → to be used across all component variables (except component transfers, which remain through a 2D interface)
   → vertical dimension data check between user-provided information (input data and spacedomain)
   → requires component to be able to work with a vertical dimension of any length (or to indicate the dimension length it can work with)

Are there any other situations for the vertical dimension that need to be covered?
e.g. I am wondering whether we need an explicit version of 1 for component state variables?

We need to decide which situations (if not all) we want to support at this stage.

[ThibHlln]

Also, would this vertical dimension be used if we want to have both surface flow direction, and subsurface flow direction? And if so, how?

[ThibHlln]

After discussing with Rich, we have split what we think is required now for v0.1 and what will be required in a later version.

For v0.1, we want to support two situations where a vertical dimension is involved:

• An implicit Z discretisation of the domain, which can be handled by the current "divisions" option of component states, although it needs to be extended to apply to inputs / parameters / outputs as well. These divisions will be transparent to the SpaceDomain, the framework will only need to check for the size of the extra dimension in the user-provided inputs/parameters to make sure the right "amount" is provided. There is a priori no reason to require the "divisions" to be the same across all inputs / parameters / outputs.
• A way to check whether the measurement height expected by component contributor for the inputs is matched in the user dataset (which is expected to have a Z dimension featuring one coordinate). If the user dataset does not contain a Z dimension, a warning (rather than an error) should be sent to indicate to the user that the contributor-defined measurement height was assumed. Again, this will be transparent to the SpaceDomain which will remain as 2D.

For a later version, we want to support:

• An explicit Z discretisation of the domain, so that component contributors can develop 3D models. We anticipate this will require:
  • a vertical dimension to be present in the SpaceDomain
  • the component contributor to specify whether it supports 3D spacedomains, and if so, how flexible it is about the number of coordinates along the vertical axis
  • the component inputs to be a variety of 2D and 3D fields if the spacedomain is 3D (e.g. 2D fields could be some boundary conditions)

In any situation, we agree that transfers through the interface will always be 2D.

At the moment, the user can define a Z dimension in their Grid. It would probably be a shame to drop this functionality to reintroduce it later, so it may be better to silently ignore the Z dimension everywhere, while documenting this behaviour?

[ThibHlln]

After thinking about this further, I think the two first situations mentioned in the previous post (i.e. those for v0.1) are a bit "hacky" and will need to be revised in a later iteration (in #70). For now and the imminent release of v0.1, I don't think a third dimension is required (beyond the divisions of states already supported), and so it is preferable to "deactivate" the vertical dimension of space domains altogether until a clean solution is found.