Initial draft of BMI with parallel support

docs/source/bmi.control_funcs.rst

@@ -10,6 +10,38 @@ model -- a calling application is able to, for instance, update a
 model one time step at a time, change its state, and then continue
 updating.
 
+.. _parallel_initialize:
+
+*parallel_initialize*
+.....................
+
+.. code-block:: java
+
+    /* SIDL */
+    int parallel_initialize(in integer mpi_communicator);
+
+
+The `parallel_initialize` function initializes the model for running
+in a parallel environment.
+It initializes the MPI communicator that the model should use to
+communicate between all of its threads.
+The `parallel_initialize` function must be called before the
+`initialize` function.
+This communicator could be ``mpi_comm_world``,
+but it is typically a derived communicator across a subset of the
+MPI threads available for the whole simulation.
+
+**Implementation notes**
+
+* This function is only needed for MPI aware models.
+* Models should be refactored, if necessary, to accept the mpi_communicator
+  via the model API.
+* The MPI communicator is not in all environments represented by an integer.
+  **TODO**: check with experts.
+
+[:ref:`control_funcs` | :ref:`basic_model_interface`]
+
+
 .. _initialize:
 
 *initialize*
@@ -41,6 +73,9 @@ formatted.
   a string -- a basic type in these languages.
 * In C and Fortran, an integer status code indicating success (zero) or failure (nonzero)
   is returned. In C++, Java, and Python, an exception is raised on failure.
+* When a model runs across multiple MPI threads, the `parallel_initialize`
+  should be called first to make sure that the model can communicate with
+  the other MPI threads on which it runs.
 
 [:ref:`control_funcs` | :ref:`basic_model_interface`]
 

docs/source/bmi.getter_setter.rst

@@ -48,6 +48,8 @@ even if the model uses dimensional variables.
   variable may not be accessible after calling :ref:`finalize`.
 * In C and Fortran, an integer status code indicating success (zero) or failure
   (nonzero) is returned.
+* *Parallel*: the number of items may vary per MPI thread,
+  hence the size and content of the *dest* argument will vary per MPI thread.
 
 [:ref:`getter_setter_funcs` | :ref:`basic_model_interface`]
 
@@ -76,6 +78,8 @@ even if the model's state has changed.
 * In Python, a :term:`numpy` array is returned.
 * In C and Fortran, an integer status code indicating success (zero) or failure
   (nonzero) is returned.
+* *Parallel*: the reference returned will vary per MPI thread.
+  It refers only to the data for the thread considered.
 
 [:ref:`getter_setter_funcs` | :ref:`basic_model_interface`]
 
@@ -102,6 +106,9 @@ Additionally,
 
 * Both *dest* and *inds* are flattened arrays.
 * The *inds* argument is always of type integer.
+* *Parallel*: the indices are the *local* indices within the MPI thread.
+  The number of indices for which data is retrieved may vary per MPI thread.
+  The length and content of the *dest* argument will vary per MPI thread.
 
 [:ref:`getter_setter_funcs` | :ref:`basic_model_interface`]
 
@@ -137,6 +144,8 @@ even if the model uses dimensional variables.
   variable may not be accessible after calling :ref:`finalize`.
 * In C and Fortran, an integer status code indicating success (zero) or failure
   (nonzero) is returned.
+* *Parallel*: the number of items may vary per MPI thread,
+  hence the size and content of the *src* argument will vary per MPI thread.
 
 [:ref:`getter_setter_funcs` | :ref:`basic_model_interface`]
 
@@ -162,5 +171,8 @@ Additionally,
 
 * Both *src* and *inds* are flattened arrays.
 * The *inds* argument is always of type integer.
+* *Parallel*: the indices are the *local* indices within the MPI thread.
+  The number of indices for which data is set may vary per MPI thread.
+  The length and content of the *src* argument will vary per MPI thread.
 
 [:ref:`getter_setter_funcs` | :ref:`basic_model_interface`]