docs: add ascii diagram of domain decomp

README.md

@@ -169,4 +169,44 @@ group: connectivity {
 
 ```
 
-The netCDF variables `global_x/y` are defined as the coordinates of the upper left corner of the bounding box for each MPI process using zero-based indexing and `local_extent_x/y` are the extents in the corresponding dimensions of the bounding box for each MPI process. The file also defines the variables `X_neighbors(P)`, `X_neighbor_ids(X_dim)` and `X_neighbor_halos(X_dim)`, where `X` is `top/bottom/left/right`, which correspond to the number of neighbors per process, the neighbor IDs and halo sizes of each process sorted from lower to higher MPI rank.
+The netCDF variables `global_x/y` are defined as the coordinates of the upper left corner of the bounding box for each MPI process using zero-based indexing and `local_extent_x/y` are the extents in the corresponding dimensions of the bounding box for each MPI process. The file also defines the variables `X_neighbors(P)`, `X_neighbor_ids(X_dim)` and `X_neighbor_halos(X_dim)`, where `X` is `top/bottom/left/right`, which correspond to the number of neighbors per process, the neighbor IDs and halo sizes of each process sorted from lower to higher MPI rank.
+
+## Layout
+
+The original version of `decomp` used a TBLR naming convention (top, down, left, right), but this was confusing in how it
+related to x and y co-ordinates.
+
+To remove disambiguity we renamed the outputs produced in the `partition_metadata_<num_mpi_processes>.nc` file.
+
+```
+netcdf partition_metadata_3 {
+dimensions:
+ globalX = 30 ; (NX)
+ globalY = 24 ; (NY)
+ P = 3 ;
+ T = 2 ;                                              0            12        24
+ B = 2 ;                                               ┌──────────────────────►  y
+ L = 1 ;                                               │
+ R = 1 ;                                               │  ┌─────────┬─────────┐
+group: bounding_boxes {                                │  │         │         │
+   global_x = 0, 0, 20 ;  (domain_x)                   │  │         │         │
+   global_y = 0, 12, 0 ;  (domain_y)                   │  │         │         │
+   local_extent_x = 20, 20, 10 ; (domain_extent_x)     │  │    0    │    1    │
+   local_extent_y = 12, 12, 24 ; (domain_extent_y)     │  │         │         │
+  } // group bounding_boxes                            │  │         │         │
+group: connectivity {                                  │  │         │         │
+   top_neighbors = 0, 0, 2 ;                        20 │  ├─────────┴─────────┤
+   top_neighbor_ids = 0, 1 ;                           │  │                   │
+   top_neighbor_halos = 12, 12 ;                       │  │                   │
+   bottom_neighbors = 1, 1, 0 ;                        │  │         2         │
+   bottom_neighbor_ids = 2, 2 ;                        │  │                   │
+   bottom_neighbor_halos = 12, 12 ;                    │  │                   │
+   left_neighbors = 0, 1, 0 ;                       30 ▼  └───────────────────┘
+   left_neighbor_ids = 0 ;
+   left_neighbor_halos = 20 ;                          x
+   right_neighbors = 1, 0, 0 ;
+   right_neighbor_ids = 1 ;
+   right_neighbor_halos = 20 ;
+  } // group connectivity
+}
+```