small documentation update and other fixes

Author: ajwdewit

doc/code.rst

@@ -303,7 +303,7 @@ The CGMS12 database
 ...................
 
 The CGMS12 tools are for reading data from a CGMS12 database structure that
- is used by CGMS executable version 11 and BioMA 2014.
+is used by CGMS executable version 11 and BioMA 2014.
 
 
 .. automodule:: pcse.db.cgms12
@@ -351,14 +351,12 @@ The NASA POWER database
 Convenience routines
 --------------------
 
-These routines are there for conveniently starting a WOFOST simulation. They
-are mainly used in the tutorial and examples but can be used to further
-elaborating on when writing your own scripts.
+These routines are there for conveniently starting a WOFOST simulation
+for the demonstration and tutorials. They can serve as an example to
+build your own script but have no further relevance.
 
 .. autofunction:: pcse.start_wofost.start_wofost
 
-.. autofunction:: pcse.run_wofost.run_wofost
-
 
 Miscelaneous utilities
 ----------------------

doc/index.rst

@@ -27,7 +27,7 @@ nowadays (XML, databases, web, etc).
 Like so many other software packages, PCSE was developed to facilitate my own research work. I wanted something
 that was more easy to work with, more interactive and more flexible while still implementing
 the sound computational approach of FSE. For this reason PCSE was developed in Python
-which is quickly becoming an important language for scientific purposes.
+hsa become an important programming language for scientific purposes.
 
 Traditionally, crop simulation models in Wageningen have been provided including the
 full source code. PCSE is no exception and its source code is open and licensed under the

doc/installing.rst

@@ -13,7 +13,7 @@ Python through the native package manager. For Windows users the most straightfo
 Python is through one of the prepackaged Python distributions such as `Enthought Canopy`_,
 `Anaconda`_ or `PythonXY`_. The advantage of the prepackaged distributions is that they provide a working
 version of Numpy out-of-the-box which can be difficult to install on Windows. Mac OSX users can most easily
-install Python and Numpy using `HomeBrew`_, i.e brew install Python Numpy
+install Python and Numpy using `HomeBrew`_, i.e ``brew install Python Numpy``.
 
 The dependencies of PCSE are the following:
 
@@ -72,14 +72,17 @@ After installing MiniConda you should open a command box and check that conda is
         is foreign system : False
 
 Now we will use a Conda environment file to recreate the python environment that we use to develop and run
-PCSE. First you should download the conda environment file :download:`downloads/py2_pcse.yml` and save
-it on a temporary location such as ``d:\temp\make_env\``. We will now create a dedicated virtual environment
-using the command ``conda env create`` and tell conda to use the environment file with the option ``-f p2_pcse.yml``
+PCSE. First you should download the conda environment file which comes in two flavours, a bare minimum
+environment for running PCSE (:download:`downloads/py2_pcse.yml`) and a more complete environment which
+includes the Jupyter notebook, Pandas and IPython (:download:`downloads/py2_pcse_full.yml`). If you intend
+to run the 'Getting started' section, you should take the latter one. Save the environment file
+on a temporary location such as ``d:\temp\make_env\``. We will now create a dedicated virtual environment
+using the command ``conda env create`` and tell conda to use the environment file with the option ``-f p2_pcse_full.yml``
 as show below:
 
 .. code-block:: doscon
 
-    D:\temp\make_env>conda env create -f py2_pcse.yml
+    D:\temp\make_env>conda env create -f py2_pcse_full.yml
     Fetching package metadata: ....
     .Solving package specifications: .........
     Linking packages ...
@@ -186,7 +189,7 @@ For testing the PCSE package we need to start python and import pcse:
 
 .. code-block:: doscon
 
-    [py2_pcse_b] D:\temp\make_env>python
+    [py2_pcse] D:\temp\make_env>python
     Python 2.7.11 |Continuum Analytics, Inc.| (default, Mar  4 2016, 15:18:41) [MSC v.1500 32 bit (Intel)] on win32
     Type "help", "copyright", "credits" or "license" for more information.
     Anaconda is brought to you by Continuum Analytics.
@@ -195,7 +198,6 @@ For testing the PCSE package we need to start python and import pcse:
     Building PCSE demo database at: C:\Users\wit015\.pcse\pcse.db
     >>>
 
-
 Next, the tests can be executed by calling the `test()` function at the top of the package::
 
     >>> pcse.test()

doc/pcse_intro.rst

@@ -81,8 +81,8 @@ PCSE also has its limitations, in fact there are several:
   time-step. Although the internal time-step of modules can be made more fine-grained if needed.
 
 * No graphical user interface. However the lack of a user interface is partly compensated by using PCSE with the
-  `pandas <http://pandas.pydata.org/>`_ package and the `IPython notebook <https://ipython.org/notebook.html>`_.
-  PCSE output can be easily converted to a pandas `DataFrame` which can be used to display charts in an IPython
+  `pandas <http://pandas.pydata.org/>`_ package and the `Jupyter notebook <https://jupyter.org/>`_.
+  PCSE output can be easily converted to a pandas `DataFrame` which can be used to display charts in an Jupyter
   notebook.
 
 License

doc/quickstart.rst

@@ -100,12 +100,15 @@ and have a look at these as well::
 Running PCSE/WOFOST with custom input data
 ==========================================
 
-For setting up PCSE/WOFOST with your
-own data sources you should understand that WOFOST uses 3 different types of
-inputs: 1) model parameters for the crop, soil and site; 2) Daily weather observations
-for running the simulation and 3) agromanagement data that define the agromanagement
-practices such as sowing, harvesting and irrigation. PCSE provides several tools for
-reading these inputs from files, databases or internet resources.
+For running PCSE/WOFOST (and PCSE models in general) with your own data sources you need three different types of
+inputs:
+
+1. Model parameters that parameterize the different model components. These parameters usually
+   consist of a set of crop parameters (or multiple sets in case of crop rotations), a set of soil parameters
+   and a set of site parameters. The latter provide ancillary parameters that are specific for a location.
+2. Driving variables represented by weather data which can be derived from various sources.
+3. Agromanagement actions which specify the farm activities that will take place on the field that is simulated
+   by PCSE.
 
 For the second example we will run a simulation for sugar beet in
 Wageningen (Netherlands) and we will read the input data step by step from
@@ -138,7 +141,7 @@ Wageningen are often provided in the CABO format that could be read
 with the `TTUTIL <http://edepot.wur.nl/17847>`_ FORTRAN library. PCSE
 tries to be backward compatible as much as possible and provides the
 :ref:`CABOFileReader <CABOFileReader>` for reading parameter files in CABO format.
-the `CABOFileReader` returns a dictionary with the parameter name/value pairs::
+the CABOFileReader returns a dictionary with the parameter name/value pairs::
 
     >>> from pcse.fileinput import CABOFileReader
     >>> cropfile = os.path.join(data_dir, 'sug0601.crop')
@@ -339,15 +342,8 @@ First we will import the necessary modules and define the data directory. We als
 .. _pandas: http://pandas.pydata.org
 .. _PyYAML: http://pyyaml.org/wiki/PyYAML
 
-For running the PCSE/LINTUL3 (and PCSE models in general), you need three types of inputs:
-
-1. Model parameters that parameterize the different model components. These parameters usually
-   consist of a set of crop parameters (or multiple sets in case of crop rotations), a set of soil parameters
-   and a set of site parameters. The latter provide ancillary parameters that are specific for a location.
-2. Driving variables represented by weather data which can be derived from various sources.
-3. Agromanagement actions which specify the farm activities that will take place on the field that is simulated
-   by PCSE. For defining the agromanagement we will use the new `AgroManager` which replaces the `timerdata`
-   definition that was used previously.
+Similar to the previous example, for running the PCSE/LINTUL3 model we need to define the tree types of inputs
+(parameters, weather data and agromanagement).
 
 Reading model parameters
 ------------------------

doc/reference_guide.rst

@@ -144,7 +144,7 @@ for potential crop production::
 
     from pcse.soil.classic_waterbalance import WaterbalancePP
     from pcse.crop.wofost import Wofost
-    from pcse.agromanagement import AgroManagementSingleCrop
+    from pcse.agromanager import AgroManager
 
     # Module to be used for water balance
     SOIL = WaterbalancePP
@@ -153,7 +153,7 @@ for potential crop production::
     CROP = Wofost
 
     # Module to use for AgroManagement actions
-    AGROMANAGEMENT = AgroManagementSingleCrop
+    AGROMANAGEMENT = AgroManager
 
     # variables to save at OUTPUT signals
     # Set to an empty list if you do not want any OUTPUT
@@ -192,9 +192,17 @@ The second part is for defining the
 variables (*OUTPUT_VARS*) that should be stored during the model run
 (during OUTPUT signals) and the details of the regular output interval.
 Next, summary output *SUMMARY_OUTPUT_VARS* can be defined that will be generated at the end
-of each crop cycle. Finall, output can be collected at the end of the
+of each crop cycle. Finally, output can be collected at the end of the
 entire simulation (*TERMINAL_OUTPUT_VARS*).
 
+.. note::
+    Model configuration files for models that are included in the PCSE package
+    reside in the 'conf/' folder inside the package. When the Engine is started
+    with the name of a configuration file, it searches this folder to locate the file.
+    This implies that if you want the start the Engine with your own (modified)
+    configuration file, you *must* specify it as an absolute or relative path
+    otherwise the Engine will not find it.
+
 The relationship between models and the engine
 ----------------------------------------------
 
@@ -366,9 +374,12 @@ Similarly, state variables can only be changed during the state update while the
 of change are locked. This mechanism ensures that rate/state updates are carried out
 in the correct order.
 
-Finally, instances of rate variables have one additional method, called `zerofy()`.
+Finally, instances of RatesTemplate have one additional method, called `zerofy()` while
+instances of StatesTemplate have one additional method called `touch()`.
 Calling `zerofy()` is normally done by the Engine and explicitly sets all rates of change
-to zero.
+to zero. Calling `touch()` on a states object is only useful when the states variables
+do not need to be updated, but you do want to be sure that any published state variables
+will remain available in the VariableKiosk.
 
 
 The AgroManager
@@ -402,7 +413,7 @@ or twice in the growing cycle. So for a 200-day growing cycle there will be
 198 days where the parameters do not carry any information. Nevertheless, they
 would still be present in the function call, thereby decreasing the computational
 efficiency and the readability of the code. Therefore, PCSE uses a very different
-approach for agromanagement events which is based on signals (see XXX).
+approach for agromanagement events which is based on signals (see :ref:`Broadcasting signals`).
 
 .. _refguide_agromanagement:
 
@@ -703,6 +714,8 @@ initializing rate/state variables, while retrieving values from the VariableKios
 through the normal dictionary look up. For more details on the VariableKiosk see the
 description in the :ref:`BaseClasses` section.
 
+.. _Broadcasting signals:
+
 Broadcasting signals
 --------------------
 

doc/whatsnew.rst

@@ -13,15 +13,14 @@ PCSE version 5.2 brings the following new features:
   campaigns. The AgroManager uses a new format based on YAML to store agromanagement definitions.
 - The water-limited production simulation with WOFOST now supports irrigation using the new AgroManager.
   An example notebook has been added to explain the different irrigation options.
-- Support for reading input data from a CGMS14 database
+- Support for reading input data from a CGMS8 and CGMS14 database
 
 What's new in PCSE 5.1
 ======================
 
 PCSE version 5.1 brings the following new features:
 
-- Support for reading input data (weather, soil, crop parameters) from a
-CGMS12 database. CGMS is the acronym for
+- Support for reading input data (weather, soil, crop parameters) from a CGMS12 database. CGMS is the acronym for
   Crop Growth Monitoring System and was developed by Alterra in cooperation with the MARS unit of the Joint Research
   Centre for crop monitoring and yield forecasting in Europe. It uses a database structure for storing weather
   data and model simulation results which can be read by PCSE. See the MARSwiki_ for the database definition.

pcse/db/cgms12/data_providers.py

@@ -230,9 +230,10 @@ class AgroManagementDataProvider(list):
            campaign. Note that by default the campaign_start_date is set equal to the
            crop_start_date which means that the simulation starts when the crop starts.
            This default behaviour can be changed using this keyword. It can have multiple meanings:
-           - if a date object is passed, the campaign is assumed to start on this date.
-           - if an int/float is passed, the campaign_start_date is calculated as the
-             crop_start_date minus the number of days provided by campaign_start.
+
+               - if a date object is passed, the campaign is assumed to start on this date.
+               - if an int/float is passed, the campaign_start_date is calculated as the
+                 crop_start_date minus the number of days provided by campaign_start.
 
     For adjusting the campaign_start_Date, see also the `set_campaign_start_date(date)` method
     to update the campaign_start_date on an existing AgroManagementDataProvider.

pcse/soil/classic_waterbalance.py

@@ -128,8 +128,7 @@ class WaterbalanceFD(SimulationObject):
     WDRT      Amount of water added to root zone by increase    N    cm
               of root growth
     TOTINF    Total amount of infiltration                      N    cm
-    TOTIRR    Total amount of irrigation (not implemented       N    cm
-              yet)
+    TOTIRR    Total amount of effective irrigation              N    cm
     PERCT     Total amount of water percolating from rooted     N    cm
               zone to subsoil
     LOSST     Total amount of water lost to deeper soil         N    cm
@@ -153,8 +152,8 @@ class WaterbalanceFD(SimulationObject):
              the evapotranspiration module 
     RAIN     Rainfall rate for current day                      N    |cmday-1|
     RIN      Infiltration rate for current day                  N    |cmday-1|
-    RIRR     Irrigation rate for current day. Is always set     N    |cmday-1|
-             to zero as irrigation is not handled currently
+    RIRR     Effective irrigation rate for current day,         N    |cmday-1|
+             computed as irrigation amount * efficiency.
     PERC     Percolation rate to non-rooted zone                N    |cmday-1|
     LOSS     Rate of water loss to deeper soil                  N    |cmday-1|
     DW       Change in amount of water in rooted zone as a      N    |cmday-1|

pcse/tests/test_data/lintul3_springwheat.soil

@@ -1,7 +1,6 @@
 # Soil hydraulic properties
-WCAD   = 0.10 			
-WCWP   = 0.20
-WCFC   = 0.40
-WCWET  = 0.45
-WCST   = 0.50
+WCAD   = 0.10 			# Water content at air dry
+WCWP   = 0.20           # Water content at wilting point    
+WCFC   = 0.40           # Water content at field capacity
+WCST   = 0.50           # Water content at saturation
 DRATE  = 30.  			# Maximum drainage rate of the soil (mm/day)