APSIM Tool Documentation

Version: v1.0.0
Date: 2024-12-19
Author: yuxi-research

1. Overview

This tool automates the batch configuration and execution of APSIM simulations.

• Content structure

.
├── 01_editAPSIM.ipynb          # Notebook to batch configure and run APSIMX simulations
├── 02_checkOutput.ipynb        # Notebook to inspect APSIMX simulation results
├── data/
    ├── data_management.csv     # Example management data
    ├── data_soil.csv           # Example soil data
    └── met/                    # Weather data
        ├── <site_id>.met       # APSIMX .met weather files     
        └── met_example.xlsx    # Template for preparing .met files
├── output/                     # Generated model configurations and outputs
├── example_apsimx/                # Sample APSIMX configuration files (JSON format).
        ├── <Crop>_Default.apsimx  # Base configuration for generating simulations
├── python_scripts/             # Shared Python scripts used by the notebooks
├── requirements.yaml           # Conda environment specification
└── README.md                   # Documentation (this file)

• Input files data/:

  • Weather data (met/<sample_id>.met)
  • Soil data (data_soil.csv)
  • Management data ( data_management.csv)

• Base configuration example_apsimx/:

  • (<Crop>_Default.apsimx)

• Output files output/:

  • Model configuration: <Crop>_Example.apsimx
  • Model output: <Crop>_Example.db

2. Installation

Install APSIM Next Generation

Please refer to the APSIM download page to install the latest version of APSIMX.

Install this tool

1. Download or clone github repo.
2. Setup apsim_tool environment with conda (installation):

   • if conda not installed yet, please install (see e.g., for conda-miniforge https://github.com/conda-forge/miniforge)

   • run following commands in your terminal, as shown here for conda (if other environment used, please adjust):

     # Create new env from a file
     conda env create --file apsim_tool.yaml
     # Activate env
     conda activate apsim_tool
     # Change directory to the notebooks folder
     cd notebooks

   • Alternatively, install packages to an existing env:

     # install packages to an existing env
     conda env update --name apsim_tool --file apsim_tool.yaml

   • If installation fails, try remove unused packages and clean cache.

     # Clean cache
     conda clean --all
     # Export env
     conda env export --name apsim_tool > apsim_tool.yaml

3. Open notebooks (see section below). Notebooks can be run, for example, in JupyterLab environment, or within VSCode (using Jupyter or Quarto plugin), or via jupyter notebook

The environment file apsim_tool.yaml includes all dependencies for this APSIMX tool.

3. Quick Guide

1. Create the .apsimx configuration file

   • Open and run 01_editAPSIM.ipynb. This will generate output/Wheat_Example.apsimx.
   • If you have specified the APSIMX installation location in the notebook, the simulations will run automatically after the file is generated.

2. Run the APSIM model and view results

   • Once the .apsimx file is created, open it in the APSIMX user interface to view, edit, and execute the simulation.
   • Simulation outputs are saved as output/Wheat_Example.db.

3. Analyze the data

   • Open 02_checkOutput.ipynb to perform a basic data analysis of the simulation results.

4. How to Configure Your Own Simulations

A site_id is a case-sensitive, unique identifier that links weather, soil, and management data for a single simulation. Ensure that the site_id is consistent and correctly spelled across all files.

4.1 Prepare Your Data

Weather data (<site_id>.met)

APSIM uses .met files for weather inputs. You can view and edit a .met file with any text editor. Columns in the .met file may be separated by commas, tabs, or spaces. Below is an example of a .met file:

[weather.met.weather]
latitude = -30.0 (DECIMAL DEGREES)
longitude = 116.0 (DECIMAL DEGREES)
tav = 18.96 (oC)   ! Annual average temperature
amp = 14.94 (oC)   ! Annual temperature amplitude

year day  radn   maxt   mint   rain   pan   vp    code
()   ()   (MJ/m^2) (°C)   (°C)   (mm)   (mm) (hPa) ()
2000  1   19.7   35.7   20.9   0.0   11.4  9.6   0
2000  2   31.9   37.5   19.5   0.0   10.6  10.9  0
2000  3   22.6   35.1   18.3   0.0   11.6  13.2  0
2000  4   28.2   34.5   19.5   1.5   11.1  13.5  0
2000  5   29.4   35.7   20.1   0.0   10.2  10.5  0
2000  6   18.8   34.4   19.9   0.0   11.0  15.8  0
2000  7   32.7   33.4   17.3   7.4   6.4   16.6  0
2000  8   29.9   35.7   18.1   0.0   9.3   15.1  0
2000  9   32.5   36.7   18.1   0.0   9.0   13.6  0
...

• The [weather.met.weather] block defines location and long-term climate statistics.
• Required daily columns are:
  • radn (solar radiation, MJ/m²)
  • maxt (daily maximum temperature, °C)
  • mint (daily minimum temperature, °C)
  • rain (rainfall, mm)
  • Additional columns like pan (pan evaporation), vp (vapour pressure), and code (weather code) can be included as needed.
• Each row’s date is specified by year and day (day of year).
• No missing values are allowed; gaps will cause the simulation to fail.

You can use data/met/met_example.xlsx as a template to prepare weather data. Once your spreadsheet is complete, export it as CSV and then rename the .csv extension to .met.

---

Soil data

File data_soil.csv are used to batch edit the APSIM input files.

DepthTop,DepthBot,Gravel,OC,Conductivity,pH,Clay,Sand,Silt,CEC,ESP,BD,DUL,LL15,PAWC,SAT,AirDry,SiteID,Thickness
0,5,5,0.9,0.052,5.6,13.64,71.2,10.16,2,4.6,1.828,0.101,0.044,0.127,0.31,0.044,S1,50
5,15,5,0.62,0.039,5.6,12.655,73.46,8.895,1.85,5.05,1.832,0.097,0.042,0.115,0.305,0.042,S1,100
15,30,5,0.34,0.026,5.6,11.67,75.72,7.63,1.7,5.5,1.835,0.093,0.039,0.102,0.3,0.039,S1,150
30,60,5,0,0.048,8.2,19.06,74.99,0.95,2.6,9.1,1.838,0.097,0.048,0.099,0.3,0.048,S1,300
60,100,5,0,0.048,8.2,19.06,74.99,0.95,2.6,9.1,1.838,0.097,0.048,0.099,0.3,0.048,S1,400
100,200,5,0,0.048,8.2,19.06,74.99,0.95,2.6,9.1,1.838,0.097,0.048,0.099,0.3,0.048,S1,1000
200,300,5,0,0.048,8.2,19.06,74.99,0.95,2.6,9.1,1.838,0.097,0.048,0.099,0.3,0.048,S1,1000
0,5,5,1.08,0.05,5.5,18.33,66.88,9.8,2.6,5.5,1.826,0.109,0.052,0.14,0.31,0.052,S2,50
5,15,5,0.745,0.04,5.75,22.13,65.85,7.03,2.9,6.15,1.83,0.111,0.058,0.133,0.305,0.058,S2,100
15,30,5,0.41,0.029,6,25.93,64.82,4.26,3.2,6.8,1.834,0.114,0.064,0.125,0.3,0.064,S2,150
30,60,5,0,0.043,7,31.94,62.11,0.95,4.5,9.5,1.838,0.12,0.075,0.116,0.3,0.075,S2,300
60,100,5,0,0.043,7,31.94,62.11,0.95,4.5,9.5,1.838,0.12,0.075,0.116,0.3,0.075,S2,400
100,200,5,0,0.043,7,31.94,62.11,0.95,4.5,9.5,1.838,0.12,0.075,0.116,0.3,0.075,S2,1000
200,300,5,0,0.043,7,31.94,62.11,0.95,4.5,9.5,1.838,0.12,0.075,0.116,0.3,0.075,S2,1000
...

• DepthTop: upper depth of the soil layer (cm)
• DepthBot: lower depth of the soil layer (cm)
• Gravel: soil gravel (%)
• OC: soil organic carbon
• pH: soil pH (range: 1-14)
• Clay: soil clay (%)
• Sand: soil sand (%)
• Silt: soil silt (%)
• BD: bulk density (g/cm^3)
• DUL: Drained upper limit (mm/mm)
• LL15: Lower limit at 15 bar (mm/mm)
• SAT: Saturated soil moisture (mm/mm)
• AirDry: Air-dry soil moisture (mm/mm)
• SiteID: Site ID
• Thickness: soil layer thickness (mm)

Management data

The data_management.csv file is used to modify APSIM configuration files (.apsimx).

SiteID,Season,Crop,PlantingDate,Variety,HarvestDate,Yield,Application
S1,2021,Wheat,2021-05-12,Devil,2021-12-02,5093,"[{'FertiliserType': 'Urea', 'FertiliserDates': '02-Jun', 'Amount': 80.0}]"
S2,2021,Wheat,2021-05-15,Devil,2021-11-30,3429,"[{'FertiliserType': 'Urea', 'FertiliserDates': '04-Jun', 'Amount': 80.0}]"
S3,2021,Wheat,2021-05-15,Devil,2021-12-01,3598,"[{'FertiliserType': 'Urea', 'FertiliserDates': '04-Jun', 'Amount': 77.4}]"
S4,2021,Wheat,2021-05-12,Devil,2021-12-02,3902,"[{'FertiliserType': 'Urea', 'FertiliserDates': '02-Jun', 'Amount': 43.7}]"
S5,2021,Wheat,2021-05-12,Devil,2021-12-03,4074,"[{'FertiliserType': 'Urea', 'FertiliserDates': '02-Jun', 'Amount': 98.6}]"
S6,2021,Wheat,2021-05-26,Havoc,2021-12-16,2817,"[{'FertiliserType': 'Urea', 'FertiliserDates': '01-Jul', 'Amount': 65.0}]"
S7,2021,Wheat,2021-05-26,Havoc,2021-12-18,3325,"[{'FertiliserType': 'Urea', 'FertiliserDates': '02-Jul', 'Amount': 64.9}]"
S8,2021,Wheat,2021-05-26,Havoc,2021-12-17,2544,"[{'FertiliserType': 'Urea', 'FertiliserDates': '01-Jul', 'Amount': 63.6}]"
S9,2021,Wheat,2021-05-27,Havoc,2021-12-18,3455,"[{'FertiliserType': 'Urea', 'FertiliserDates': '02-Jul', 'Amount': 64.2}]"
S10,2021,Wheat,2021-05-27,Havoc,2021-12-18,2568,"[{'FertiliserType': 'Urea', 'FertiliserDates': '02-Jul', 'Amount': 64.7}]"
...

• SiteID: site ID
• Season: year of the simulation
• Crop: crop type (e.g., Wheat, Barley, Canola)
• PlantingDate: planting date (YYYY-MM-DD)
• Variety: variety name
• HarvestDate: harvest date (YYYY-MM-DD), leave blank if not applicable
• Yield: yield. Leave blank if not applicable
• Application: fertiliser application (json format). Include fertiliser type, dates and amount. For muptiple fertiliser applications,seperate each entries with commas.
  • FertiliserType: text (e.g., Urea)
  • FertiliserDates: fertiliser date (format:DD-MMM, e.g., 02-Jun)
  • Amount: fertiliser amount (kg/ha)

Step 2: Run APSIM

The APSIM configuration file .apsimx defines all settings required for running APSIM simulations. You can view, edit, and execute .apsimx files directly in the APSIMX user interface using mouse clicks and keyboard input. For further guidance, please refer to APSIM’s official documentation and tutorials. Note that the .apsimx file is structured as a multi‐level JSON.

01_editAPSIM.ipynb

01_editAPSIM.ipynb enables you to generate multiple APSIMX simulations from a single base configuration and save them together as one combined .apsimx file.

The base configuration files are located in example_apsimx/<Crop>_Default.apsimx and include predefined setups for wheat, barley, canola, chickpea, and lentil. Each of these default files represents a single crop simulation for one season. The notebook duplicates a chosen default simulation and then updates its weather, soil, and management settings—using data from files in data/*—to create multiple simulations within a single .apsimx configuration.

Please make sure you specified the APSIMX installation location in the notebook. If the excutive APSIM model is not found, the notebook will only generate a .apsimx configuration file under the output folder but will not run the model. You can manually open the generated configuration file with the APSIMX user interface and run simulations with a mouse click.

Step 3: Understand your output

• APSIM configuration file: Wheat_Example.apsimx
• APSIM output file: Wheat_Example.db

Simulation results are saved in the same folder as the configuration file, using the same base name but with a .db extension. The easiest way to inspect and export the results is through the APSIMX user interface. You can also open the database file with a database viewer. For Python data analysts, 02_checkOutput.ipynb provided a demonstration of how to use package `sqlite3' to inspect and visualise the results.