Documentation for running with MPI (#493)

This PR closes #491 .

While #483 has added information on how to build nextsim with MPI, the
information about how to run it was still only present in issues (e.g.,
#490) .

I have added that info to the "Getting started" part of the
documentation, and also added an example partition file to the `run`
directory to enable users to run the simple example without having to
install the decomp tool.

docs/getting_started.rst

@@ -41,4 +41,27 @@ An example of a launching script ``run_simple_example.sh`` can be found in the `
 
 The model will produce an output file named ``output.nc``, which contains the result of applying the model physics to the initial state over the specified number of time steps.
 
+Running with MPI
+~~~~~~~~~~~~~~~~
+To run the model with MPI you have to have it built with MPI or use one of the `*_MPI` Dockerfiles. In addition, you will need a partition NetCDF file as created by the `Domain Decomposition tool <https://github.com/nextsimhub/domain_decomp>`_. This partition file has to either be added to the config file (`*.cfg`) by adding the line `partition_file = partition.nc` or provided as an argument to `nextsim`.
+
+An example ``partition.cdl`` file and a ``partition_metadata_2.cdl`` file for the simple example are added to the ``run`` directory. Those can be used to generate the necessary netcdf files by running, for example, ``ncgen partition.cdl -o partition.nc``. You can then run the code with
+
+.. code::
+
+    mpirun -n 1 ./nextsim --config-file config_simple_example.cfg --model.partition_file partition.nc
+
+or
+
+.. code::
+
+    mpirun -n 2 ./nextsim --config-file config_simple_example.cfg --model.partition_file partition_metadata_2.nc
+    
+, respectively.    
+
+For more information on the format of the partition files and how to create them, see `the documentation for the decomposition tool <https://github.com/nextsimhub/domain_decomp>`_ . Note that you will need a specific partition file depending on the number of processes you want to run, which will, by default, be named ``partition_metadata_<num_mpi_processes>.nc``.
+
+
+
 .. _Installation: https://nextsim-dg.readthedocs.io/en/latest/installation.html
+

run/partition.cdl

@@ -0,0 +1,26 @@
+// partition.cdl
+netcdf partition {
+dimensions:
+        P = 1 ;
+        L = 1 ;
+        globalX = 30 ;
+        globalY = 30 ;
+
+group: bounding_boxes {
+  variables:
+        int global_x(P) ;
+        int global_y(P) ;
+        int local_extent_x(P) ;
+        int local_extent_y(P) ;
+  data:
+
+   global_x = 0 ;
+
+   global_y = 0 ;
+
+   local_extent_x = 30 ;
+
+   local_extent_y = 30 ;
+  } // group bounding_boxes
+}
+

run/partition_metadata_2.cdl

@@ -0,0 +1,62 @@
+// partition_metadata_2.cdl
+netcdf partition_metadata_2 {
+dimensions:
+	globalX = 30 ;
+	globalY = 30 ;
+	P = 2 ;
+	T = UNLIMITED ; // (0 currently)
+	B = UNLIMITED ; // (0 currently)
+	L = 1 ;
+	R = 1 ;
+
+group: bounding_boxes {
+  variables:
+  	int global_x(P) ;
+  	int global_y(P) ;
+  	int local_extent_x(P) ;
+  	int local_extent_y(P) ;
+  data:
+
+   global_x = 0, 0 ;
+
+   global_y = 0, 16 ;
+
+   local_extent_x = 30, 30 ;
+
+   local_extent_y = 16, 14 ;
+  } // group bounding_boxes
+
+group: connectivity {
+  variables:
+  	int top_neighbors(P) ;
+  	int top_neighbor_ids(T) ;
+  	int top_neighbor_halos(T) ;
+  	int bottom_neighbors(P) ;
+  	int bottom_neighbor_ids(B) ;
+  	int bottom_neighbor_halos(B) ;
+  	int left_neighbors(P) ;
+  	int left_neighbor_ids(L) ;
+  	int left_neighbor_halos(L) ;
+  	int right_neighbors(P) ;
+  	int right_neighbor_ids(R) ;
+  	int right_neighbor_halos(R) ;
+  data:
+
+   top_neighbors = 0, 0 ;
+
+   bottom_neighbors = 0, 0 ;
+
+   left_neighbors = 0, 1 ;
+
+   left_neighbor_ids = 0 ;
+
+   left_neighbor_halos = 30 ;
+
+   right_neighbors = 1, 0 ;
+
+   right_neighbor_ids = 1 ;
+
+   right_neighbor_halos = 30 ;
+  } // group connectivity
+}
+