Add function to get names of grid node coordinates

[mdpiper]

To help address #87 and #88, the BMI should have a function to return the names of the ~dimensions~ node coordinates of a grid.

[mdpiper]

In BMI 2.0, we implicitly assume grid dimensions are named x, y, and z. Not only may this be a misnomer (what if the model uses natural coordinates or geographic coordinates or sigma coordinates?) but when BMI is extended to more than three dimensions (#88), what will the additional dimensions be named?

By adding a new function to the BMI, we'll allow a model developer to explicitly name the dimensions of a model grid; e.g., s, t, n, or lon, lat, sigma.

[mdpiper]

The new function would provide the name parameter of the suggested get_grid_units function in #87 and get_grid_node_coordinates function in #88.

[mdpiper]

One possibility for this function, suggested here, is:

int get_grid_dimension_names(in int grid, out array<string, 1> names);

It could return ["x", "y", "z"] or ["x1", "x2", "x3"] or N names for grids with N dimensions.

This function name is kinda clumsy, though.

[hrajagers]

Following this discussion from a distance with interest ... but I just realized that there is a risk of mixing two concepts. You are here considering using the same names for both "grid_dimensions" and "coordinates" (or "coordinate dimensions"). In the case of a curvilinear (or unstructured) grid those two are not the same! Maybe we should have a look at the netCDF CF conventions regarding data "dimensions" (indicating -- optionally shared -- dimension lengths, array sizes) and "(auxiliary) coordinate variables" for inspiration and some consistency in naming. In case of an N dimensional data cube, you will often have

• 1, 2 or 3 grid dimensions linked to space (which may link to 1, 2 or 3 coordinates -- note a 1-dimensional data set may still be linked to a geometry in 3 spatial coordinates, but a 3-dimensional data set is very unlikely to map to just 1 or 2 spatial coordinates, so the number of coordinates is (always?) equal to or larger than the number of corresponding grid dimensions in the data set),
• possibly 1 time dimension, and
• several other dimensions which may correspond one-on-one to non-spatial coordinates (e.g. sediment fraction, frequency, etc).

I don't know whether the curvilinear and unstructured grid concepts should be generalized to extend into the other dimensions; although it could be done mathematically, I can't yet think of an application -- although for example the spatial grid could be time-dependent (it becomes really messy once the grid dimensions start changing over time). However, what can happen is that one dimension is used for multiple coordinates, e.g. a station index can be used to identify the station for each data value; the station may subsequently link to the name of the station (label coordinate), the x, y, z location (space coordinates), the time of the measurement, the device specifications, etc.

Best regards,

Bert

On Fri, Nov 12, 2021 at 10:53 PM Mark Piper @.***> wrote:

One possibility for this function, suggested here https://github.com/csdms/bmi/issues/87#issuecomment-961445180, is:

int get_grid_dimension_names(in int grid, out array<string, 1> names);

It could return ["x", "y", "z"] or ["x1", "x2", "x3"] or N names for grids with N dimensions.

This function name is kinda clumsy, though.

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub https://github.com/csdms/bmi/issues/90#issuecomment-967534853, or unsubscribe https://github.com/notifications/unsubscribe-auth/ABKKVWTJSOXPN7IEKGAHXKTULV5EBANCNFSM5H5UKS6Q . Triage notifications on the go with GitHub Mobile for iOS https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675 or Android https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub.

[mcflugen]

Thanks very much for your input @hrajagers! 🎉

I agree, when talking about a grid’s dimensions with respect to the spatial positions of its nodes, we should use coordinates rather than dimensions.

The following potential functions—much like the get_input_var_names and get_output_var_names—could return the names of each coordinate of a grid (e.g. x, y, etc.),

int get_grid_coordinate_count(in int grid, out int n_coordinates);
int get_grid_coordinates(in int grid, out array<string, 1> names);

Following on this, to get the units of a grid coordinate and its value at each grid node, we could have,

int get_grid_coordinate_units(in int grid, in string coordinate, out string units);
int get_grid_node_coordinate(in int grid, in string coordinate, out array<double> values);

where the coordinate argument would be one of the strings obtained from get_grid_coordinates.

Although they don’t strictly have to be, we intended for BMI grids to be spatial. In the case of time, BMI treats time specially through the update methods and the get_time functions. For a client to get a value of a quantity at a specific time, it would need to update the model to that time and then make a get_values call. An implementer can, however, extend the grid concept to non-spatial coordinates if they wish—get_grid_coordinates could return, for example, time, station_id, ensemble_number, etc.—but frameworks that try to interpret these sorts of grids could get confused, particularly when trying to map between model grids. For non-spatial dimensions we recommend those quantities be passed as separate quantities through get_values functions—that is, something like

get_values("grid_node__station_id", ids);

[mdpiper]

I updated the title and description based on the comments from @hrajagers and @mcflugen.