Formalise regridder file format

[stephenworsley]

No description provided.

[codecov]

Codecov Report

Merging #137 (25a6e40) into unstructured_scheme (a3e147b) will increase coverage by 0.00%.
The diff coverage is 100.00%.

@@                 Coverage Diff                  @@
##           unstructured_scheme     #137   +/-   ##
====================================================
  Coverage                99.53%   99.54%           
====================================================
  Files                       27       27           
  Lines                     1720     1741   +21     
====================================================
+ Hits                      1712     1733   +21     
  Misses                       8        8           

Impacted Files	Coverage Δ
esmf_regrid/esmf_regridder.py	94.54% <100.00%> (+0.42%)	⬆️
esmf_regrid/experimental/io.py	100.00% <100.00%> (ø)
.../tests/unit/experimental/io/test_round_tripping.py	100.00% <100.00%> (ø)

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update a3e147b...25a6e40. Read the comment docs.

[stephenworsley]

An example of the file format output:

netcdf regridder {
dimensions:
	latitude = 6 ;
	longitude = 5 ;
	bnds = 2 ;
	Mesh2d_node = 11 ;
	Mesh2d_face = 12 ;
	example_mesh_face_N_nodes = 4 ;
	dim0 = 64 ;
	dim0_0 = 2 ;
variables:
	double regridder_target_field(latitude, longitude) ;
		regridder_target_field:long_name = "regridder_target_field" ;
	double latitude(latitude) ;
		latitude:axis = "Y" ;
		latitude:bounds = "latitude_bnds" ;
		latitude:units = "degrees_north" ;
		latitude:standard_name = "latitude" ;
	double latitude_bnds(latitude, bnds) ;
	double longitude(longitude) ;
		longitude:axis = "X" ;
		longitude:bounds = "longitude_bnds" ;
		longitude:units = "degrees_east" ;
		longitude:standard_name = "longitude" ;
	double longitude_bnds(longitude, bnds) ;
	int example_mesh ;
		example_mesh:cf_role = "mesh_topology" ;
		example_mesh:topology_dimension = 2 ;
		example_mesh:long_name = "example mesh" ;
		example_mesh:node_coordinates = "longitude_0 latitude_0" ;
		example_mesh:face_coordinates = "longitude_1 latitude_1" ;
		example_mesh:face_node_connectivity = "mesh2d_face" ;
	double longitude_0(Mesh2d_node) ;
		longitude_0:standard_name = "longitude" ;
	double latitude_0(Mesh2d_node) ;
		latitude_0:standard_name = "latitude" ;
	double longitude_1(Mesh2d_face) ;
		longitude_1:standard_name = "longitude" ;
	double latitude_1(Mesh2d_face) ;
		latitude_1:standard_name = "latitude" ;
	int64 mesh2d_face(Mesh2d_face, example_mesh_face_N_nodes) ;
		mesh2d_face:_FillValue = -1LL ;
		mesh2d_face:cf_role = "face_node_connectivity" ;
		mesh2d_face:start_index = 0LL ;
	double regridder_source_field(Mesh2d_face) ;
		regridder_source_field:long_name = "regridder_source_field" ;
		regridder_source_field:mesh = "example_mesh" ;
		regridder_source_field:location = "face" ;
	double regridder_weights(dim0) ;
		regridder_weights:long_name = "regridder_weights" ;
		regridder_weights:coordinates = "weight_matrix_columns weight_matrix_rows" ;
	int weight_matrix_columns(dim0) ;
		weight_matrix_columns:long_name = "weight_matrix_columns" ;
	int weight_matrix_rows(dim0) ;
		weight_matrix_rows:long_name = "weight_matrix_rows" ;
	int64 weights_shape(dim0_0) ;
		weights_shape:long_name = "weights_shape" ;

// global attributes:
		:ESMF_version = "8.0.1" ;
		:esmf_regrid_version_on_initialise = "0.3.dev0" ;
		:esmf_regrid_version_on_save = "0.3.dev0" ;
		:mdtol = 0.5 ;
		:normalization = "fracarea" ;
		:regridder_type = "MeshToGridESMFRegridder" ;
		:title = "iris-esmf-regrid regridding scheme" ;
		:Conventions = "CF-1.7" ;
}

For reference, a file before this PR would look like:

netcdf regridder {
dimensions:
	latitude = 6 ;
	longitude = 5 ;
	bnds = 2 ;
	Mesh2d_node = 11 ;
	Mesh2d_face = 12 ;
	example_mesh_face_N_nodes = 4 ;
	dim0 = 64 ;
variables:
	double regridder_target_field(latitude, longitude) ;
		regridder_target_field:long_name = "regridder target field" ;
	double latitude(latitude) ;
		latitude:axis = "Y" ;
		latitude:bounds = "latitude_bnds" ;
		latitude:units = "degrees_north" ;
		latitude:standard_name = "latitude" ;
	double latitude_bnds(latitude, bnds) ;
	double longitude(longitude) ;
		longitude:axis = "X" ;
		longitude:bounds = "longitude_bnds" ;
		longitude:units = "degrees_east" ;
		longitude:standard_name = "longitude" ;
	double longitude_bnds(longitude, bnds) ;
	int example_mesh ;
		example_mesh:cf_role = "mesh_topology" ;
		example_mesh:topology_dimension = 2 ;
		example_mesh:long_name = "example mesh" ;
		example_mesh:node_coordinates = "longitude_0 latitude_0" ;
		example_mesh:face_coordinates = "longitude_1 latitude_1" ;
		example_mesh:face_node_connectivity = "mesh2d_face" ;
	double longitude_0(Mesh2d_node) ;
		longitude_0:standard_name = "longitude" ;
	double latitude_0(Mesh2d_node) ;
		latitude_0:standard_name = "latitude" ;
	double longitude_1(Mesh2d_face) ;
		longitude_1:standard_name = "longitude" ;
	double latitude_1(Mesh2d_face) ;
		latitude_1:standard_name = "latitude" ;
	int64 mesh2d_face(Mesh2d_face, example_mesh_face_N_nodes) ;
		mesh2d_face:_FillValue = -1LL ;
		mesh2d_face:cf_role = "face_node_connectivity" ;
		mesh2d_face:start_index = 0LL ;
	double regridder_source_field(Mesh2d_face) ;
		regridder_source_field:long_name = "regridder source field" ;
		regridder_source_field:mesh = "example_mesh" ;
		regridder_source_field:location = "face" ;
	double regridder_weights_and_metadata(dim0) ;
		regridder_weights_and_metadata:long_name = "regridder weights and metadata" ;
		regridder_weights_and_metadata:mdtol = 0.5 ;
		regridder_weights_and_metadata:regridder\ type = "MeshToGridESMFRegridder" ;
		regridder_weights_and_metadata:weights\ shape = 30LL, 12LL ;
		regridder_weights_and_metadata:coordinates = "dim0 dim0_0" ;
	int dim0(dim0) ;
		dim0:long_name = "weight matrix columns" ;
	int dim0_0(dim0) ;
		dim0_0:long_name = "weight matrix rows" ;

// global attributes:
		:Conventions = "CF-1.7" ;
}

[trexfeathers]

Good stuff @stephenworsley, there are some slick new patterns here.

Just a couple of small things. I definitely think it will be a good idea to move all the 'significant strings' into module constants, as mentioned in one of my comments.

[trexfeathers]

IMO the [relatively minor] IO performance slowdowns are worth it for the extra clarity in the NetCDF files. Any thoughts @stephenworsley?

[stephenworsley]

IMO the [relatively minor] IO performance slowdowns are worth it for the extra clarity in the NetCDF files. Any thoughts @stephenworsley?

I suspect that the slowdown is mostly overhead which doesn't scale with grid size. Either way, the changes here seem worth making.