wip documentation (framework section)

doc/framework.rst

@@ -3,7 +3,7 @@
 Modeling Framework
 ==================
 
-This section explains the design of the xarray-simlab's modeling
+This section explains the design of the xarray-simlab modeling
 framework. It is useful mostly for users who want to create new models
 from scratch or customize existing models. Users who only want to run
 simulations from existing models may skip this section.
@@ -14,26 +14,28 @@ run models, see the relevant sections of this user guide.
 Main concepts
 -------------
 
-The xarray-simlab's framework is built on only a few concepts that
-allow great flexibility for model developers:
+The xarray-simlab framework is built on a very few concepts that
+allow great flexibility in model customization:
 
-- **models**
-- **processes**
-- **variables**
+- models
+- processes
+- variables
+
+These are detailed here below.
 
 Models
 ------
 
 Models are instances of the :class:`~xsimlab.Model` class. They
-consist of ordered and immutable collections of processes. The
+consist of ordered, immutable collections of processes. The
 ordering is inferred automatically from the given processes (see below).
 
 The Model class also implements specific methods for:
 
 - introspection,
 - running simulations,
 - easy creation of new Model objects from existing ones by dropping,
-  adding or updating one or more processes.
+  adding or replacing one or more processes.
 
 Processes
 ---------
@@ -42,8 +44,8 @@ Processes are defined as custom Python classes that inherit from the
 base class :class:`~xsimlab.Process`. The role of a process is twofold:
 
 - declare a given subset of the variables used in a model,
-- define a specific set of instructions that use, initialize or update
-  the values of these variables during a model run.
+- define a specific set of instructions that use or compute values for
+  these variables during a model run.
 
 Conceptually, a process is a logical component of a computational
 model. It may for example represent a particular physical mechanism
@@ -71,17 +73,17 @@ attributes. They have the following properties:
 - data values (state, rate or change -- see below),
 - validators, i.e., callables for checking supplied data values,
 - labeled dimensions (or no dimension for scalars),
-- predefined attributes like description or default value,
-- custom attributes (e.g., units, math symbol).
+- predefined metadata attributes like description or default value,
+- user-defined metadata attributes (e.g., units, math symbol).
 
 .. note::
 
-   xarray-simlab does not distinguish between, e.g., model parameters
+   xarray-simlab does not distinguish between model parameters
    and state variables. Both are declared as Variable objects.
 
-.. [*] usually variables rather consist of objects of derived classes
-   like, e.g., ``FloatVariable`` or ``IntegerVariable`` depending on
-   their expected value type.
+.. [*] usually variables consist of objects of derived classes like,
+   e.g., ``FloatVariable`` or ``IntegerVariable`` depending on their
+   expected value type.
 
 Foreign variables
 -----------------
@@ -91,68 +93,68 @@ Like different physical mechanisms involve some common state variables
 common variables.
 
 In xarray-simlab, a variable is declared at a unique place, i.e.,
-within one and only one process. The issue of shared variables is
-addressed by the possibility of also declaring foreign
-variables. :class:`~xsimlab.ForeignVariable` objects are references to
-variables that are declared in other processes. It allows getting or
+within one and only one process. Using common variables across
+processes is achieved by declaring foreign variables.
+:class:`~xsimlab.ForeignVariable` objects are references to
+variables that are declared in other processes ; it allows getting or
 setting values just as if these references were the original
 variables.
 
 The great advantage of declaring variables at unique places is that
 all their metadata are defined once. However, a downside of this
 approach is that foreign variables may potentially add many hard-coded
-(one-way) links between processes, which makes harder reusing these
-processes independently of each other.
+links between processes, which makes harder reusing these processes
+independently of each other.
 
 Variable groups
 ---------------
 
 In some cases, using variables groups may provide an elegant
 alternative to hard-coded links between processes.
 
-Variable objects belong to the same group if they have the same name
-set for their ``group`` attribute. In a process, this group name can
-be used to declare a :class:`~xsimlab.VariableGroup` object. When a
-new Model object is created, this is automatically turned into an
-iterable of ForeignVariable objects pointing to each of the variables
-of the group. We thus avoid making explicit references to the
-processes in which these variables are declared.
+The membership of Variable objects to a group is defined via their
+``group`` attribute. If we want to use in a separate process all the
+variables of a group, instead of explicitly declaring foreign
+variables we can declare a :class:`~xsimlab.VariableGroup` object
+which behaves like an iterable of ForeignVariable objects pointing to
+each of the variables of the group.
 
 Variable groups are useful particularly in cases where we want to
 combine different processes that act on the same variable, e.g. in
-landscape evolution modeling, combine the effect of different erosion
-processes on the evolution of surface elevation. This way we can
-easily add or remove erosion processes to/from a model without having
-issues of broken links between processes.
+landscape evolution modeling combine the effect of different erosion
+processes on the evolution of the surface elevation. This way we can
+easily add or remove processes to/from a model and avoid missing or
+broken links between processes.
 
 Variable state, rate and change
 -------------------------------
 
-A single variable may accept up to 3 different values:
+A single variable may accept up to 3 concurrent values that have
+each a particular meaning:
 
-- a state, i.e., the value of the variable at a given time
-- a rate, i.e., the value of the time-derivative at a given time
+- a state, i.e., the value of the variable at a given time,
+- a rate, i.e., the value of the time-derivative at a given time,
 - a change, i.e., the value of the time-derivative integrated for a given
   time step.
 
 These are accessible as properties of Variable and ForeignVariable
-objects, respectively named ``state``, ``rate`` and ``change``. An
-additional property ``value`` is defined as an alias of ``state``.
+objects: ``state``, ``rate`` and ``change``. An additional property
+``value`` is defined as an alias of ``state``.
 
 .. note::
 
-   These properties are for convenience only, it avoids duplicating
-   Variable objects representing state variables. Their names and
-   descriptions serve only as conventions, i.e., there is no
-   restriction for model developers in using any of these properties
-   anywhere in a process.  It is good practice to follow these
-   conventions, though.
+   These properties are for convenience only, it avoids having to
+   duplicate Variable objects for state variables. The properties are
+   independent of each other and their given meanings serve only as
+   conventions. Although there is no restriction in using any of these
+   properties anywhere in a process, it is good practice to follow
+   these conventions.
 
 .. note::
 
    The ``rate`` and ``change`` properties should never be used for
    variables other than state variables.  Moreover, it is preferable
-   to use the property ``value`` instead of ``state`` as the latter is
+   to use the alias ``value`` instead of ``state`` as the latter is
    quite meaningless in this case.
 
 .. todo_move_this_elsewhere
@@ -188,9 +190,9 @@ for a given variable, then the execution of this process must happen
 before the execution of all other processes that use the same variable
 in their computation.
 
-Such role can be defined using the ``provided`` attribute of
-Variable and ForeignVariable objects, either set to True or
-False (note that a process may still update a variable value even if
+Such role can be defined using the ``provided`` attribute of Variable
+and ForeignVariable objects, which is either set to True or False
+(note that a process may still update a variable value even if
 ``provided`` is set to False, see Model inputs section below).
 
 In a model, the processes and their dependencies together form the
@@ -201,9 +203,9 @@ computationally consistent can then be obtained using topological
 sorting. This is done at Model object creation.  The same ordering
 is used at every stage of a model run.
 
-In theory, The DAG structure would also allow running the processes in
-parallel at every stage of a model run. This is not yet implemented,
-though.
+In principle, the DAG structure would also allow running the processes
+in parallel at every stage of a model run. This is not yet
+implemented, though.
 
 Model inputs
 ------------