docs small corrections

Author: ben1post

docs/workflow1_framework.rst

@@ -3,17 +3,26 @@ Introduction to the framework
 
 The Xarray-simlab-ODE (``xso``) is a Python framework that allows users to construct and customize, in a modular fashion, models based on ordinary differential equations (ODEs). It is technically a wrapper around the modeling framework `xarray-simlab <https://xarray-simlab.readthedocs.io/en/latest/>`__, additionally providing a functional set of variables, processes and a solver backend for ODE-based models.
 
-It is a non-opinionated framework, i.e., it does not provide a fixed notion of how the model should be implemented, instead it attempts to remove the redundant boilerplate code, allowing a user to construct and work with ODE-based models.
+It is a non-opinionated framework, i.e., it does not provide a fixed notion of how the model should be structured, instead it attempts to remove the redundant boilerplate code, allowing a user to construct and work with ODE-based models.
 
-XSO was developed as the technical foundation of the `Phydra library <https://github.com/ben1post/phydra>`__, but is not limited to any particular domain and can be used to create ODE-based models of any type.
+XSO was developed as the technical foundation of the `Phydra library <https://github.com/ben1post/phydra>`__ for marine ecosystem modeling, but is not limited to any particular domain and can be used to create ODE-based models of any type.
 
 
 Building blocks
 ===============
 
-The XSO framework provides several *variable types*, which directly correspond to the basic mathematical components of models based on ordinary differential equations (e.g., state variables, parameters, forcing, and partial equations).
+The XSO framework is built around these concepts:
 
-Every aspect of the model needs to be defined at the level of *variable types*. Model *components* can be flexibly constructed from the provided set of *variable types* and wrap a logical component of the model as users see fit.
+* Model data (setup and output)
+* Model objects
+* Components
+* Variable types
+
+The XSO framework provides several *variable types*, which directly correspond to the basic terms of models based on ordinary differential equations, e.g., state variables, parameters, forcing, and mathematical terms (here called *fluxes*) building the system of equations.
+
+Every aspect of the model needs to be defined at the level of *variable types*. Model *components* can be flexibly constructed from the provided set of *variable types* and wrap a logical component of the model as users see fit. These components can then be modularly assembled to a *model object*, which defines the model structure.
+
+The *model object* is then used to create a *model setup* dataset, which contains all relevant information needed at runtime, such as the solver algorithm to be used, as well as time steps and model parameterization. With both the *model object* and the corresponding *model setup*, the model can be exectued. Output is returned as an Xarray dataset with all metadata, which can be easily stored and shared.
 
 State variables, forcing and parameters need to be initialized in one *component*, but can be referenced across the model (using the :code:`foreign=True` argument). The system of differential equations is constructed from the *fluxes* contained in the model *components* via the supplied labels at model setup.
 
@@ -37,7 +46,7 @@ These can be used to define variables in compact Python classes, to construct fu
 Components
 __________
 
-*Components* are the general building-blocks of a model that declare a subset of variables and define a specific set of mathematical functions computed for these variables during model runtime. More specifically, a *component* refers to a Python class containing *variable types* that is decorated with :deco:`xso.component`.
+*Components* are the general building-blocks of a model that declare a subset of variables and define a specific set of mathematical functions computed for these variables during model runtime. More specifically, a *component* refers to a Python class containing XSO *variable types* that is decorated with :deco:`xso.component`.
 
 For example, a *component* could define a specific nutrient uptake function, e.g. Monod-type phytoplankton growth on a single nutrient. The decorating function registers the *variable types* within the framework, reducing boilerplate code and creating fully functional model building blocks. *Components* can be reused within a model.
 

docs/workflow2_variables_components.rst

@@ -41,7 +41,7 @@ The XSO framework allows structuring a model into modular components. The specif
 Anatomy of a component
 ======================
 
-A :class:`xso.component` is essentially a wrapper around a :class:`xsimlab:xsimlab.process` class, the main building block of the Xarray-simlab framework. There is a lot of additional functionality provided by ``xso`` through the *variable types* and the :deco:`xso.component` decorator. The following sections will explain the anatomy of a component via examples.
+A :class:`xso.component` is essentially a wrapper around the :deco:`xsimlab:xsimlab.process` class decorator, represents a logical unit in a computational model. There is a lot of additional functionality provided by ``xso`` through the *variable types* and the :deco:`xso.component` decorator. The following sections will explain the anatomy of an XSO component via examples.
 
 Component defining a variable
 -----------------------------
@@ -126,7 +126,7 @@ One of the more powerful features is the dimensionality and vectorization functi
             return var_list * rate
 
 
-In this component, we define a single flux for multiple variables that are flowing out of the system. The ``list_input=True`` argument indicates that the variable labels can be supplied at *model setup* as a list. The XSO backend aggregates all labeled variables into an array, with the dimension label supplied via ``dims='flow_list'``. We need to make sure, that this dimension is also present in the ``dims`` argument of the :func:`xso.flux` decorator, so that the flux function knows how to handle the aggregated variables. The backend automatically routes the flux values to the appropriate variables, here as a negative function.
+In this component, we define a single flux for multiple variables that are flowing out of the system. The ``list_input=True`` argument indicates that the variable labels can be supplied at *model setup* as a list. The XSO backend aggregates all labeled variables into an array, with the dimension label supplied via ``dims='flow_list'``. We need to make sure, that this dimension is also present in the ``dims`` argument of the :deco:`xso.flux` decorator, so that the flux function knows how to handle the aggregated variables. The backend automatically routes the flux values to the appropriate variables, here as a negative function.
 
 This allows for highly flexible complex model setups, as we can easily remove and add state variables, without overcomplicating our model structure.
 

docs/workflow3_models.rst

@@ -65,7 +65,7 @@ As can be seen from the ``__repr__`` of the model object, there are two perhaps
 #.   The number of variables does not exactly correspond to the number of variable types in the model. Each :func:`xso.variable` initialized within a *component* requires two input arguments. E.g., for the ``value`` variable, it is  ``value_label`` and ``value_init``. The ``value_label`` is the label of the variable, and the ``value_init`` is the initial value of the variable. The label supplied here can be used to reference the variable in another component within the same model (where the input parameter is a ``label reference``).
 #. There are three model processes automatically added to the model object. These are the ``Solver``, ``Core`` and ``Time`` components provided by :mod:`xso.backendcomps`, that allow the model system to be setup and solved.
 
-In order to setup the model with a custom unit for time (e.g. per month, per year) this can be supplied to the :func:`xso.create` function as the ``time_unit`` argument. The ``time_unit`` argument is a string that can be parsed by the :func:`pint:pint.Unit` function. The default unit for time is ``'d'`` for days.
+In order to setup the model with a custom unit for time (e.g. per month, per year) this can be supplied to the :func:`xso.create` function as the ``time_unit`` argument. The default unit for time is ``'d'`` for days.
 
 Setup a model
 =============
@@ -98,7 +98,7 @@ A model is setup by calling the :func:`xso.setup` function. The :func:`xso.setup
                 })
 
 
-The :func:`xso.setup` function returns an :class:`xarray:Dataset` with the input variables and model components as data variables.
+The :func:`xso.setup` function returns an :class:`xarray:xarray.Dataset` with the input variables and model components as data variables.
 
 ..  code-block:: python