wip documentation

Author: benbovy

doc/about.rst

@@ -3,59 +3,60 @@
 About xarray-simlab
 ===================
 
-xarray-simlab provides a framework for easily building custom models from a set
-of re-usable components (i.e., Python classes), called processes.
+xarray-simlab provides a framework for easily building custom computational
+models from a set of re-usable components (i.e., Python classes), called
+processes.
 
-The framework handles issues that scientists who develop models should not care
-too much about, like a model interface and its data structure as well as its
-overall workflow management. Both are automatically determined from the
-succint, declarative-like interfaces of the model processes.
+The framework handles issues that scientists who are developing models should
+not care too much about, like the model interface - including the data structure
+used - and the overall workflow management. Both are automatically determined
+from the succint, declarative-like interfaces of the model processes.
 
-Next versions of xarray-simlab will hopefully also handle other technical issues
-like logging, command line integration and running (many) simulations in
-parallel.
+Next versions of xarray-simlab will hopefully handle other technical issues
+like logging simulation progress, command line integration and running (many)
+simulations in parallel.
 
 Motivation
 ----------
+
 xarray-simlab is being developped with the idea of reducing the gap between the
-environment used for building and running a computational model and the one(s)
+environments used for building and running computational models and the ones
 used for processing and analysing simulation results. It also encourages
 building new models from re-usable components and avoid reinventing the wheel.
 
-Ultimately, it should reduce the time lag between the ideas that scientists have
-on how to model a particular phenomenon and the insights they get from exploring
-the behavior of the model, which often itself lead to new modeling ideas.
+The design of this tool is mainly focused on fast development and simulation
+setting(s), which would ultimately optimize the iterative, back-and-forth
+process between ideas on how to model a particular phenomenon and insights
+from the exploration of model behavior.
 
 Sources of inspiration
 ----------------------
 
-- xarray_: data structure
-- dask_: build and run task graphs (DAGs)
-- luigi_: use Python classes as re-usable units that help building complex
-  workflows.
-- django_: especially The Django's ORM part (i.e., django.db.models) for the
-  design of Process and Variable classes
-- param_: another source of inspiration for Process interface and Variable objects.
-- climlab_: another python package for process-oriented modeling, applied to
-  climate.
+xarray-simlab leverages the great number of packages that are part of the
+Python scientific ecosystem. More specifically, the packages below have been
+great sources of inspiration for this project.
+
+- xarray_: xarray-simlab actually provides an xarray extension for setting and
+  running models.
+- luigi_: the concept of Luigi is to use Python classes as re-usable units that
+  help building complex workflows. xarray-simlab's concept is similar, but
+  here it is specific to computational (numerical) modeling.
+- django_ (not really a scientific package): the way that model processes are
+  designed in xarray-simlab is heavily inspired from Django's ORM (i.e., the
+  ``django.db.models`` part).
+- param_: another source of inspiration for the interface of processes
+  (more specifically the variables that it defines).
+- climlab_: another python package for process-oriented modeling, which uses
+  the same approach although having a slightly different design/API, and which
+  is applied to climate modeling.
+- dask_: represents fine-grained processing tasks as Directed Acyclic Graphs
+  (DAGs). xarray-simlab models are DAGs too, where the nodes are interdepent
+  processes. In this project we actually borrow some code from dask
+  for resolving process dependencies and for model visualization.
 
 .. _xarray: https://github.com/pydata/xarray
 .. _dask: https://github.com/dask/dask
 .. _luigi: https://github.com/spotify/luigi
 .. _django: https://github.com/django/django
 .. _param: https://github.com/ioam/param
 .. _climlab: https://github.com/brian-rose/climlab
-
-**Draft: put this in create models section**
-
-The framework consists of a few base classes, e.g., :py:class:`xrsimlab.Variable`,
-:py:class:`xrsimlab.Process` and :py:class:`xrsimlab.Model`. The latter class
-represents a model with which we interact using the xarray's
-:py:class:`xarray.Dataset` structure.
-
-Variable.state (or value, rate, change) should not be used (get/set) outside
-of Process subclasses.
-
-ForeignVariable.state return the same object (usually a numpy array) than
-Variable.state (replace class names by variable names in processes).
-ForeignVariable.state is actually a shortcut to ForeignVariable.ref_var.state.

doc/create_model.rst

@@ -0,0 +1,44 @@
+.. _create_model:
+
+Creating models
+===============
+
+(WIP)
+
+The framework provides a few Python base classes, e.g.,
+:class:`~xrsimlab.Variable`, :class:`~xrsimlab.Process` and
+:class:`~xrsimlab.Model` that can used togheter to create fully operational
+models.
+
+A ``Model`` is a collection of processes that each define an interface with the
+all the "public" variables it needs, update or provide for its proper
+computation.
+
+Process
+-------
+
+
+
+Variable
+--------
+
+Generally, the ``state``, ``value``, ``rate`` and ``change`` properties should
+not be used (either get or set the value) outside of Process subclasses,
+or maybe only for debugging.
+
+Foreign Variable
+~~~~~~~~~~~~~~~~
+
+ForeignVariable.state return the same object (usually a numpy array) than
+Variable.state (replace class names by variable names in processes).
+ForeignVariable.state is actually a shortcut to ForeignVariable.ref_var.state.
+
+Variable List and Group
+~~~~~~~~~~~~~~~~~~~~~~~
+
+
+Model
+-----
+
+The latter class represents a model with which we interact using the xarray's
+:class:`~xarray.Dataset` structure.

doc/index.rst

@@ -8,7 +8,7 @@ extension for setting and running simulations using the
 
 .. _xarray: http://xarray.pydata.org
 
-Documentation Index
+Documentation index
 -------------------
 
 **Getting Started**
@@ -17,6 +17,8 @@ Documentation Index
 * :doc:`faq`
 * :doc:`installing`
 * :doc:`examples`
+* :doc:`create_model`
+* :doc:`run_model`
 
 .. toctree::
    :maxdepth: 1
@@ -27,6 +29,8 @@ Documentation Index
    faq
    installing
    examples
+   create_model
+   run_model
 
 **Help & reference**
 

doc/run_model.rst

@@ -0,0 +1,6 @@
+.. _run_model:
+
+Running models
+==============
+
+(TODO)