Note: This is documentation for version 5.0 of Source. For a different version of Source, select the relevant space by using the Spaces menu in the toolbar above

Crop Table style Planting Decisions

 Release Notes

V 2.0.09

Changed plugin names to take advantage of new '.' syntax


Removed in-dialog help

Removed Perennial Crop Mix.

Allowed multiple Perennials.


Added help documentation. Minor fixes.


Added persistence


Changes to dialogs and underlying data structures in preparation for changes.


First version added to eWater repository.

Name of custom functions cleaned up

How to use

There are two components of the Functionality.

  • A Crop Table Plugin Dialog
  • A Crop Table Planting Decision Custom Function.

Overall Concept

The plugin works  by configuring a “Crop Table” for each water user. These are 'paired' together.

This Crop Table specifies the summer and winter usage of two crop mixes.

  • Summer Crop Mix
  • Winter Crop Mix

The Crop Mixes are assumed to be constant over time (each year has the same summer crop mix, for example).

In the paired water user (the water user connected to this crop table) the first crop for each season should be a proportion of the crop mix.

The custom function returns the area of crop mix to plant for that season.

Any subsequent crops for that season can plant a proportion of the first crop’s area.

Crop Table Plugin Dialog

The purpose of the dialog is to specify the usage of the two crop mixes (Summer and Winter).

To this end it has the user specify the season dates, the (seasonal) proportion of each crop in a crop mix and the summer and winter usage of each crop.

There is an “Autogenerate” tool to assist in preparing this data. This will also show the usage for perennials.

To bring up the dialog

Ensure the Plugin is loaded in Plugin Manager (Tools > Plugin Manager).

Click on Tools > Crop Table Generator.

This will bring up a dialog. The dialog has several parts.

Document out of date as of

Green (far left)

A list of water users that a crop table can be attached to. Clicking on a water user will bring up the crop table for that water user.

Red (top)

This gives the seasonal information. In order;

  • The name of the water user
  • The details on the evaporation time series for this node.
  • The summer start date; the planting date of the first crop for the summer season.
  • The winter start date; the planting date of the first crop for the winter season.
  • The seasonal break up. If there is only one season this will be indicated here.

Purple (2nd from top)

The details on each crop.

The table here specifies the following information

  • Name: the name of the crop (in this simple example the names are letters, but a better example would be “Rice” or “Winter Cereal”)
  • Season: The season this crop belongs to, given the planting date and the configured season dates.
  • Type: Whether Annual or Perennial. 
  • Planting Date: This is the planting date specified in the water user.
  • Proportion: The proportion of the relevant crop mix made up of this crop (A Rice proportion of “2” and a Corn proportion of “3” would mean the crop is 40% Rice and 60% Corn)
  • Summer Usage: The amount of water expected to be used by 1 hectare of this crop without rain over the period of the year allocated as summer.
  • WinterUsage: The amount of water expected to be used by 1 hectare of this crop without rain over the period of the year allocated as winter.

At the bottom is an “Autogenerate” button. This will run a simulation of the crops with zero rainfall and the evaporation from the time series specified. Optionally it can save the time series from the simulation to a file as csv - once clicked the user will be asked to specify whether to save, and if so, where.

Blue (3rd from top)

This is the data on the crop mix. It should not be entered directly. Instead as the crop data is entered this will be updated.

In Situations where there is no data for a crop the numbers will be marked NaN. For example if there is no Winter Crop Mix the numbers for that crop mix will be NaN.

Orange (bottom)

These are the controls.

  • Save: will save all details to the model (not to the file) and close the dialog.
  • Cancel: will close the dialog without making any changes to the file.
  • Rebuild: will rebuild a crop table; if you make changes to a water user after creating a crop table it may be necessary to rebuild it.
  • Help: will bring up a help dialog.

Crop Table Planting Decision Custom Function

To use the data in the crop table you will need to go into the water user.

For the first crop to be planted in each season;

Go to the Planting Decision.

We want to set the area.

This is the area underneath the area for underirrigation.

  • Click on Function editor.
  • Create a context variable for the id of the water user.
    • Click “+”
    • Select Context Variable
    • Set Model Type to Node > Water User
    • Select Id
    • It is recommended but not required you give the variable a meaningful name. E.g. “Wateruser3_id”
  • Create a function.
    • Click “+”
    • Select Function
    • Call the custom function proto_CropTablePlantingDecision
    • Parameter 1 is the context variable for the water user id
    • Parameter 2 is the season (0 = summer, 1 = winter)
    • Parameter 3 is the available water (typically a function) (in ML)
    • Parameter 4 is the expected rainfall over a period equal to the growing period of the crop mix (in mm)
    • Parameter 5 is the reserve water to keep aside (in ML)
    • Then multiply the function (which returns the crop mix area) by the proportion of the crop mix made up by this crop.
    • Set the Result Unit to “hectare”.
    • A simple example might be: proto_CropTablePlantingDecision($wateruser3_id, 0, 10000, 4, 100)*0.4
    • Note that if you click on the custom function in the select box on the left there is documentation
    • Note that because this function uses a context variable it is not possible to record it directly, nor to test it. A hardwired id is required in that situation.
    • Note that you may wish to limit this crop to a maximum area.
    • It is recommended but not required you give the function a meaningful name
  • Select function
    • Right click on the function created and select “Select and Lock Usage”

For subsequent crops in the same season the process is much easier. We only need to calculate the relative proportion of rop mix.

  • Click on the planting decision for that crop
  • Create a modelled variable
    • Click on “+”
    • Select Modelled Variable
    • Node > Water User > (name of your water user) > Demand Model > Crops > (name of your primary crop) > Area
    • It is recommended you give the variable a meaningful name like wateruser3_rice_area
  • Create a function
    • Click on “+”
    • Select Function
    • Multiply the modelled variable by the relative proportion compared to the primary crop. (Divide by the primary proportion to get crop mix area, multiply by the proportion of the current crop)
    • A simple example might be $wateruser3_rice_area*(60/40)
    • It is recommended you give the function a meaningful name
  • Select function
    • Right click on the function created and select “Select and Lock Usage”


If your primary crop dies before your secondary crops are planted, then the planting function will be incorrect. It is possible to set a function to look “backwards” at what the area was on a given date.