Introduction To Apsim UI
Introduction To Apsim UI
Welcome to the first training module for the Agricultural Production Systems Simulator
(APSIM). This first module will introduce you to the Apsim User Interface (Apsim UI) and take
you through the process of building, running and graphing a simulation.
The primary buttons that you will be working with are highlighted above. They generally do
what you would expect and will be examined in more detail below. The dimmed ones contain
more advanced features that are not looked at in this module. Briefly, Export allows you to
export a graph in a number of formats. Checkpoint creates a snapshot of a simulation allowing
you to do before and after comparisons or to revert a change. Insert a new graph brings up the
add new graph wizard. Excel allows you to export output files as comma delimited text files.
Factorials are an advanced topic that will be looked at in a separate module. Run on cluster is for
those people with access to the Toowoomba HPC cluster. Help directs you to the local help files;
however there are a number of support options that are discussed in a separate module.
1. Press the new button to create a new simulation. You will be presented with the following
screen:
Because all simulations generally share the same base components, we do not recommend
starting from scratch. The best method is to choose the simulation closest to the one you want to
build then modify it. For the purpose of this exercise we will use the Continuous Wheat
simulation. Click “Continuous Wheat.apsim” then click Open.
The Toolbox
All available components in Apsim are included in toolboxes. Whenever you need to add a new
component to your simulations you will find it in one of the toolboxes along the bottom of the
screen. It is possible to add your own toolboxes; for instance, you might have a few components
that you use often and want to make them easier to access. Maybe you’ve written some scripts
that you would like to share with a colleague. Or perhaps you have customised some of the
standard components and wish to reuse them. We are going to load a pre made toolbox to make
it easier to access some soil data.
3. Click the options button. Click on “Add a toolbox”. Navigate to your APSIM installation
folder (by default it will be in C:\Program Files (x86)\APSIM 76-r3376), then open the
UserInterface\Toolboxes folder. Click Training.xml and click Open. You should now see the
following (your path will be different):
Click OK and you will see the new toolbox in the toolbox bar at the bottom of the APSIM
window.
You can add your own components by dragging and dropping from a simulation. You can also
copy them directly from another toolbox. Note that you can't add anything to this training
toolbox as the Program Files folder is write protected.
Building a simulation
4. First we will make sure we’re using the right weather data. Click the met component in the
simulation view. You should be able to see weather data for Goondiwindi loaded.
5. Next we’ll set the start and end dates for the simulation. In the clock component, set the start
date to 1/1/1989 and the end date to 31/12/1989.
6. Now we’re going to change the soil. Click the Training toolbox that you loaded earlier. Drag
the Heavy Clay soil node from the toolbox and drop it on the paddock node in your simulation.
7. Delete the old soil by clicking it and pressing delete. You can reorder components by right
clicking and choosing Move Up/Down.
8. We need to set the starting water and nitrogen conditions for the soil. Expand the new soil
node and click Initial Water. Make sure “Filled from top” is selected and set the fraction
available to 10%.
9. Click the Initial Nitrogen component and set the starting NO3 to 50 kg/ha and starting NH4 to 3
kg/ha. We’ll spread it evenly through the entire soil profile. First, we need to tell Apsim that we
want to work in units of kg/ha, not ppm. You can change units by right clicking the column
header. Change NO3 and NH4 to kg/ha then enter the values below.
10. We wanted the nitrogen spread evenly through the entire soil profile. To find out how deep
the profile is, click the Water node under Soil.
We can see the soil profile is 180cm deep and is split into seven layers. Go back to the Initial
nitrogen node and change Depth to read 0-180.
11. In the SurfaceOrganicMatter node, check that the “Organic Matter type” is wheat and the
“Initial surface residue” is 1000 kg/ha. This means we start the simulation with 1000kg/ha of
wheat stubble on the surface. This will decay over time putting nutrients back in the soil. It will
also reduce surface evaporation.
12. Delete the Fertiliser, Wheat and Manager components as we do not need them for a fallow
simulation. It should now look like this:
13. Rename the simulation. To do this, right click Continuous Wheat and choose “rename”. Type
in “Clay Fallow”.
14. Results for the simulation are found in the “outputfile” node. This is also where you set what
variables you want reported and how often. Click the “outputfile” node and delete all the default
variables except the first one.
There are two ways to enter new variables. You can type them directly into the “Output file
columns” list or select them (double click or drag) from the pane on the right. This pane shows
all the available variables for the chosen component. You can change their order in the list by
right clicking and choosing move up/down.
Enter the following variables to report:
15. Click “Reporting Frequency” to specify how often you want the variables written to the
output file. You can choose a regular interval such as every day or once a month/year, etc, or you
specify an event. For instance you might want to output on sowing, harvesting or fertilising. You
can have multiple events in an output file but this will result in duplicated writes if a day meets
both criteria.
For this simulation we want to output daily so delete “harvesting” (there’s no crop to harvest so
it would never write) and type in “end_day”.
16. We’ve finished building the simulation. Click the “Run” button on the main toolbar.
17. Once the run is complete, click the “outputfile” component to view the results. This is just a
text file so you can easily import it into other programs for analysis. It will be saved in the same
directory your simulation is in with the file name being <simulation_name>.out. If there is no
file available it means the run failed. Check the “summaryfile” for errors.
Creating a Graph
Apsim has the ability to do basic visualisation and analysis right in the user interface. Let’s use
the inbuilt APSIM graphs to display the output file in a graph.
2. Expand the Graph folder then the Graphs folder. (Click on the “+” symbol next to
the Graphs folder to expand the node.)
3. Then drag in an XY component onto the output file in your simulation.
6. Now in the Plot window click on the “X variables” square to make sure the
background of the square is pink.
7. Now click on the “Date” column heading. It should appear in the list in the square.
8. Now click on the “Y variables” square to make its background pink.
9. Then click on the esw column heading, then the rain column heading. They should
be added to the list in the square.
10. Now to make “rain” appear on the right hand axis, click rain in the square to highlight
it, and then right click on it.
12. Now we want a nice clean line to be plotted with no points so now under “Point type”
choose “None”.
13. Now just click on the top level XY component to view the graph. The graph should
show the ESW (in mm) increasing with day of year. The sudden increases are due to
rainfall events and the declines to evaporation and drainage loss. Daily rainfall will
show this more clearly.
Try to create a graph of Date vs Runoff and Rain (right hand axis). Change the
graph type to “dot line” and set the point type to “none. Tip: you can copy a graph
by dragging it to the node where you want it to appear. Try copying your graph to
the outputfile node and then edit the new one. To delete a variable, click it and
press delete. It should look like this:
TIP: You can zoom in on a specific area by dragging a box down and to the right. To
zoom back out simply drag in the opposite direction.
Comparing Simulations
Quite often you will want to examine differences between multiple simulations. Let’s examine the
effect of runoff on the water balance of two different soil types. To do this, we’ll copy our simulation
to create a new one exactly the same.
1. Drag the Clay Fallow node up to the top simulations node.
3. Drag the Sand soil from the Training toolbox onto the paddock under the new Sand
Fallow simulation.
4. Delete the Heavy Clay soil. We do it in this order as other components that reference the
soil would lose their link if there is no soil component. If this happens you’ll need to set them
again.
5. Since we have a new soil we need to set initial Water and Nitrogen again. Change Water
to 10% filled from top. NO3 to 50 kg/ha, NH4 to 3 kg/ha and depth to 0-180.
7. Graph both simulations together by dragging an XY graph onto the top ”simulations” node
in the tree. Rename it to Runoff.
8. Create a graph of day vs. runoff(cumulative) and rain (right hand axis). To make runoff
cumulative, use the same procedure as for right hand axis, only select “cumulative” from the
pop-up menu. Set point type to “none”.
APSIM simulates the influence of crop residues on the efficiency with which water is captured
and retained during fallows. Residue cover declines as residues decompose.Residue
decomposition is simulated in APSIM in response to weather, as well as the chemical
composition of the residues. By doing this simulation you will reinforce skills learned in
previous exercises and learn to do some basic editing of default values to "customise" your
simulations.
This module assumes you have completed the previous module: Introduction to APSIM UI. It
will introduce you to the Surface Organic Matter module and demonstrate how surface residue
decomposes over time.
1. For this module we will use the simulation we created in module 1 as a base. There is also
a completed example in the training toolbox if you would prefer to use that. Open the file
Module1.apsim.
2. Save the file as Module2.apsim in the Core 2 –Surface Organic Matter folder. Remember
to use “Save As” not “Save” or you will overwrite the old file.
3. Remove the “Sand Fallow” simulation. We’ll use “Clay Fallow” as the starting point.
Remove the graph.
4. Make a copy of “Clay Fallow” by dragging it to the simulations node in the tree
6. Expand the new simulation then expand the paddock node. Click the
SurfaceOrganicMatter module and change the initial surface residue to 3000 kg/ha.
8. Create a graph of Date vs surface organic matter cover (surfaceom_cover) and rain (right
hand axis) for the “Clay Residue” simulation. To do this, open the “outputfile” node and delete
the two previous graphs then drag a new one in from the graphs toolbox. Change the name to
Organic Matter Cover.
The Effect of Cover Decline on Runoff and Evaporation
We will compare the effect that ground cover has on runoff. Graph both output files with Date vs
runoff (cumulative) and rain (right axis). Rename the graph to Runoff. If you only get one graph
it means that one simulation has not been run yet. Click the simulations node then click Run to
run them both.
1. Create another copy of the “Clay Residue” simulation. Rename it to “Clay Chickpea
Residue”. Remove the graph component.
2. Change the residue parameters to 3000 kg/ha of Chickpea residue. Also change the organic
matter pool name to “Chickpea”.
5. Graph all three residue simulations with residue cover as a function of time. Call the
graph “Cover”.
The Nitrogen Cycle
Exercise 3: Nitrogen Cycling
In this exercise you will observe the cycle of fertiliser nitrogen in a fallow situation; urea to
ammonium, ammonium to nitrate and the loss of soil nitrate via denitrification. This simulation
will introduce editing a simple Manager rule and to more advanced features of graphing
simulation results.
4. Click the met module and select Dalby weather (C:\Program Files(x86)\Apsim75\
Examples\MetFiles\ by default).
5. Change the starting date to 1/1/1989 and the end date to 31/12/1989
6. Add the heavy clay soil from the Training toolbox (see module 1 if you're not sure how to
do this).
8. Set starting nitrogen to 19kg/ha NO3 and 0 NH4, evenly distributed. Don’t forget to change
units to kg/ha (right click the column header). Make the depth equal to the entire soil profile
(check Water node for the profile depth).
10. Remove all manager scripts under the Manager folder, but leave the folder itself.
11. Drag a “Fertilise on fixed date” script to the Manager folder. You will find it in the
Management toolbox under Manager (Common Tasks).
12. Change the fertiliser management parameters to apply 100 kg/ha of urea_N on 10-Jan.
Leave the "Don't add fertiliser if N in top 2 layers exceeds (kg/ha)" property, and use the drop
down box to set "Module used to apply the fertiliser" to "fertiliser".
13. Make sure you have a fertiliser component in your simulation. Even though it doesn’t have
any changeable properties it’s needed to tell APSIM that you want to use fertiliser.
14. Remove all output Variables except Date (the first one). Enter the following variables into
the outputfile Variable list:
dnit()
urea()
Denitrification summed over profile.
Urea summed over profile.
17. Create a graph of day vs urea, total ammonium and total nitrate, changing the name to
Nitrogen. Set “Point type” to “None”.
18. Create a new graph of day vs rain, dnit(right axis), esw and NO3Total.
From this chart you can see that significant nitrogen is lost via denitrification when large
amounts of nitrate are available in saturated soil conditions.
1. Drag a depth graph from the Graph toolbox onto the simulation.
2. Expand the Plot node and click the Depth node.
3. We want to examine the profile on 31/01/1989 and 16/06/1989. Tick those two dates.
4. In the Plot node, add no3 and nh4 as the X variable. Leave the Y variable as Depth.
5. Click on the graph and untick the two nh4 lines so we can see nitrate only.
You can see the distribution of nitrate in the soil profile 21 days after the addition of fertiliser
and at 5 months. Note that the nitrogen has moved down through the soil.
Sowing A Crop
Exercise 4: A Sorghum Crop Simulation
In this exercise you will observe the growth a crop over a single season. You will learn a bit
more about how to use APSIM to do a "what-if" experiment with fertiliser rates. These skills can
not only be used to experiment with fertiliser rates but also variables such as:
Time of planting.
Rate of sowing.
Crop comparisons and different starting soil moisture conditions.
1. Start a new simulation using "Continuous Sorghum.apsim"
2. Rename the simulation as Sorghum 0kg Fertiliser. Save the file as "Module4.apsim"
3. Choose the Dalby met file and set the start and end dates of the simulation to 1/1/1988 -
30/6/1988.
4. Select the Clay soil from the Training toolbox. If you do not see this toolbox, see Module
1 to add it.
5. Set the Starting water to 25% full - filled from top.
6. Set the Starting nitrogen to 12 kg/ha of NO3 and 3 kg/ha of NH4, evenly distributed.
By setting the sowing window start and end to the same data and changing ‘must sow’ to yes, we
force the crop to be sown on that particular day. For other crops there is a specific "sow on a
fixed date" rule that is simpler than this one, but we're sowing sorghum which has extra options
so we need to use this one.
8. Check that the harvest rule indicates that Sorghum should be harvested.
9. Add a “Fertilise at sowing rule”. Set the starting fertiliser to 0 and change wheat to
sorghum. We are including this rule here as it will be used later when linked simulations are
introduced.
Linking Simulations
Often you will find yourself making a large number of simulations that have only very minor
differences between them. For example, in this exercise we will make three simulations and the
only difference between them will be the amount of fertiliser used. We can easily do this by
cloning the simulation then changing the fertiliser amount. But what if we later find out that
we’ve used the wrong cultivar or would like to try a different starting nitrogen value or report
different variables? If we’ve cloned the simulations then we would need to go through each one
and change the value. This may not be such a problem if we’re only looking at three simulations
like this exercise, but if we have tens or even hundreds this becomes a prohibitive task. The
solution is to link simulations together so that changes made to one simulation affect all linked
simulations.
11. To create a linked simulation, hold down the ALT key and drag Sorghum Nil Fertiliser to
the Simulations component at the top of the simulation tree. You should see the new simulation
appear as a blue link:
This means that the two are linked. You can make changes to either simulation and it will
affect the other one. There is no limit to the number of simulations that can be linked and
it is possible to link from a linked simulation.
IMPORTANT: Deleting many linked simulations can be very slow as all components
need to be unlinked. Do not delete more than one or two at a time or APSIM will become
unresponsive.
13. Right click the linked fertiliser sowing rule and select “unlink this node”. You can now edit
the rule without changing any of the other linked simulations.
15. Make another linked copy of the simulation, this time adding 60 kg/ha of fertiliser (don’t
forget to unlink the node). Call the simulation "Sorghum 60kg N Fertiliser"
16. Run all 3 simulations. You can run all 3 simulations by clicking on the top Simulations
component then clicking the Run button. If you just click on one of the simulation sub
components (e.g. Sorghum Nil Fertiliser or any sub component under it) then click the Run
button, it will only run that simulation.
17. Graph all 3 output files creating a Date vs Yield graph using a graph component. Click on
the Graph toolbox. Drag an XY graph component onto the top component Simulations and call it
Yield.
By default, in long term simulations (i.e. longer than one year), the end of one years’ simulation
becomes the starting point of the next year. This is useful if you are interested in seeing the
degradation or improvement of the soil over a long time period. But what if you wanted to work
out what the best strategy would be for the current year using weather scenarios from the past 40
years? To do this we could create 40 different simulations all with the same starting conditions
but a different weather file (which would be a lot of work), or we could run the same simulation
over 40 years and just reset the starting conditions each year (much simpler).
We can then try different management strategies to see which one would have worked best under
the past 10 years weather scenarios.
3. Change the simulation start and end dates to 1/01/1940 - 31/12/1980
4. Select the Heavy Clay soil from the Training Soils toolbox. If you can’t see it, see Module
1 to add it. Delete the old soil.
5. Set the Starting water to 50% full - filled from top.
6. Set the Starting nitrogen to 20 kg/ha NO3 and 0 kg/ha NH4, evenly distributed.
7. Change the surface residue type to sorghum (don't forget to rename the pool name to
"sorghum" as well), initial surface residue: 550 kg/ha, C:N ratio of 76, leave the Fraction of
residue standing as is.
8. Replace the wheat crop with chickpea. (Standard toolbox -> Crops)
9. Replace the Sowing rule with the "Sow using a variable" rule from the toolbox and enter
the values below:
The last three criteria mean that for a crop to sow within the given window at least 15mm of rain
must have fallen in the last three days and there must be a minimum of 200mm soil water
available.
10. Run the simulation. You will notice it runs very quickly. Have a look at the summary file.
You will see the following:
This means Apsim is unable to find certain crop properties in the soil. This is because we’re
using a crop that has not been parameterised for this particular soil.
Every crop used in a simulation must have an entry in the Water node that specifies crop specific
limits. To add extra crops, click “Manage crops”. Click ‘wheat’ and rename it to ‘chickpea’.
Copy the values from sorghum. The real values entered must be determined experimentally, but
they really only affect the output in severe water stress so it won’t matter here. Also note the
PAWC column will update automatically when you click another node.
12. Now we’ve fixed the error we can continue. Remove the sowing fertiliser rule.
13. Make sure the harvesting rule will harvest chickpea, not wheat.
14. Add the rule: Reset water, nitrogen, surfaceOM and phosphorus on fixed date. Use 1-
may for the reset. Make sure the name of the soil module and the name of the surface organic
matter module is correct. We want to reset water, nitrogen and surface organic matter to remove
the year to year effects. Move it up to make sure it’s the first rule under the Manager component.
The order is important in the Manager folder. It is the order the rules are run in (right click on the
rule and select "Move up". You can also use the shortcut Ctrl + Up).
15. Report the following variables:
Component Variable
Clock year
Chickpea yield
17. Make a copy of the simulation and create a new one with 15 plants/m2
20. Graph both output files creating a Year vs Yield by using a Graph component. Drag an XY
graph onto the Simulations component from the Graph toolbox. To get a bar graph, in the Plot
component select "Bar" in the "Type" drop down list.
21. Create a Probability Exceedence plot of Yield by using a Graph component. Drag a
Probability Exceedence component onto the Simulations component from the Graph toolbox.
Select the Yield as the X variable and leave Probability as the Y variable.
Creating an APSIM met file using Excel
APSIM met files consist of a section name, which is always weather.met.weather, several
constants consisting of name = value, followed by a headings line, a units line and then the data.
Spacing in the file is not relevant. Comments can be inserted using the ! character.
At a minimum three constants must be included in the file: latitude, tav and amp. The last two of
these refer to the annual average ambient temperature and annual amplitude in mean monthly
temperature.
The met file must also have a year and day column (or date formatted as yyyy/mm/dd), solar
radiation (MJ/m2), maximum temperature (oC), minimum temperature (oC) and rainfall. The
column headings to use for these are year and day (or date), radn, maxt, mint, rain.
Other constants or columns can be added to the file. These then become available to APSIM as
variables that can be reportted or used in manager script.
weather.met.weather
latitude = -33.78 (DECIMAL DEGREES)
tav = 16.47 (oC) ! annual average ambient temperature
amp = 13.71 (oC) ! annual amplitude in mean monthly temperature
To create one of these files in Microsoft EXCEL, open EXCEL and enter data into columns like
this:
It is important that the column widths are a bit wider than the data in them. Notice in the figure
the maxt column is wider than it needs to be.
The next step is to save the file as a Formatted Text (Space delimited)(*.prn) file, giving it a .met
file extension. It is recommended that you keep your toolboxes, met files etc in a folder not
under the APSIM installation directory. Perhaps you could create a folder called
c:/apsim_toolboxes for storing these types of files.
The software team provides a tool called TAV_AMP that will calculate these 2 constants and
insert them into a met file. DOWNLOAD
1. Create a new simulation using “Continuous Wheat with Climate Change” as a base. Save
it as “Climate.apsim”.
2. Change the start date to 1/1/1970. This will give us a 20 year run.
3. Add a “Reset water, nitrogen and surfaceOM on fixed date” rule and set the date to 1-jan.
Don’t forget to set the soil and surfaceOM modules as well.
4. Rename the simulation as 350ppm and click on the ClimateControl module.
Here you will find the settings that control how the climate can be varied. We’ll look at changes
to CO2 and rainfall.
5. Create a linked simulation (see module 4), rename it to 600ppm then unlink the
ClimateControl module and change the CO2 concentration to 600 ppm. Change both temperature
deltas to 2 and change in rainfall to -10.
6. Run and graph the simulations using a Probability Exceedence chart. You can see that the
elevated levels of CO2 along with the increase in temperature offset the drop in rainfall and end
up increasing the grain yield.
The Big Picture
When modelling, you need to remember that the data you get out of your model is only as good
as the data you put into it. The above graph shows that yields will increase as the climate gets
hotter, but it doesn’t reflect water usage properly. Remember that we’re using a full water profile
on a soil that has a high water holding capacity and we’re resetting that each year. Even though
we’ve reduced rainfall by 10% to reflect drier conditions we still end up with high yields. This is
because the crop is using all the stored water so the smaller amount of rainfall has no effect on
yields.
If we’re reducing rainfall and we expect more drought conditions because of it, it is unlikely that
we’re going to end up with a full profile at sowing. Let’s see what happens if we assume that the
profile is only 30% full due to drought.
1. In the 600ppm simulation, unlink the ‘Initial water’ node and change the profile to 30%
full.