diff --git a/AUTHORS.rst b/AUTHORS.rst index e8ba109..876b2c8 100644 --- a/AUTHORS.rst +++ b/AUTHORS.rst @@ -24,6 +24,7 @@ Contributors * Greg Tucker * Ben van Werkhoven * Martijn Visser +* Rolf Hut If you have contributed to the BMI project and your name is missing, please send an email to the coordinators, or open a pull request diff --git a/bmi.sidl b/bmi.sidl index 950451a..71bc938 100644 --- a/bmi.sidl +++ b/bmi.sidl @@ -1,7 +1,7 @@ // // The Basic Model Interface (BMI) // -package csdms version 2.0 { +package csdms version 2.1 { interface bmi { // Initialize, run, finalize (IRF) @@ -37,11 +37,15 @@ package csdms version 2.0 { int get_value_ptr(in string name, out array<> dest_ptr); int get_value_at_indices(in string name, in array<> dest, in array inds); + int get_state(out string state); + int get_state_ptr(out array<> dest_ptr); // Setters int set_value(in string name, in array<> src); int set_value_at_indices(in string name, in array inds, in array<> src); + int set_state(in string state); + int set_state_ptr(in array<> src); // Grid information int get_grid_rank(in int grid, out int rank); diff --git a/docs/source/bmi.getter_setter.rst b/docs/source/bmi.getter_setter.rst index 4bfa28e..a01c495 100644 --- a/docs/source/bmi.getter_setter.rst +++ b/docs/source/bmi.getter_setter.rst @@ -79,7 +79,6 @@ even if the model's state has changed. [:ref:`getter_setter_funcs` | :ref:`basic_model_interface`] - .. _get_value_at_indices: *get_value_at_indices* @@ -105,6 +104,31 @@ Additionally, [:ref:`getter_setter_funcs` | :ref:`basic_model_interface`] +.. _get_state: + +*get_state* +........... + +.. code-block:: java + + /* SIDL */ + int get_state(out string); + +The `get_state` function collects all information that forms the +state of the model and presents that as a single string. The formatting +of the output string is wholly upon the modeller. Best practices include +formatting as NETCDF or JSON. + +**Implementation notes** + +* In C++ and Java, `get_state` is a void function. +* Depending on how a model is written, the state may not be + accessible until after the call to :ref:`initialize`. Likewise, the + state may not be accessible after calling :ref:`finalize`. +* In C and Fortran, an integer status code indicating success (zero) or failure + (nonzero) is returned. + +[:ref:`getter_setter_funcs` | :ref:`basic_model_interface`] .. _set_value: diff --git a/docs/source/bmi.spec.rst b/docs/source/bmi.spec.rst index be94038..28bfc94 100644 --- a/docs/source/bmi.spec.rst +++ b/docs/source/bmi.spec.rst @@ -115,8 +115,12 @@ grouped by functional category. :ref:`get_value` Get a copy of values of a given variable. :ref:`get_value_ptr` Get a reference to the values of a given variable. :ref:`get_value_at_indices` Get variable values at specific locations. + :ref:`get_state` Get all the variables that together form the state of the model. + :ref:`get_state_pr` Get a reference to the value of the state. :ref:`set_value` Set the values of a given variable. :ref:`set_value_at_indices` Set the values of a variable at specific locations. + :ref:`set_state` Set all the variables that together form the state of the model. + :ref:`set_state_pr` Set the state by providing a reference. :ref:`get_grid_rank` Get the number of dimensions of a computational grid. :ref:`get_grid_size` Get the total number of elements of a computational grid. :ref:`get_grid_type` Get the grid type as a string.