apsimNGpy: The Next-Generation Agro-ecosystem Simulation Library

Introduction

apsimNGpy is a cutting-edge, open-source Python framework designed for advanced modeling with APSIM process-based model. Built on object-oriented principles. apsimNGpy extends and augments APSIM Next Generation functionalities within the Python scientific ecosystem, turning GUI-centric workflows into scriptable, reproducible, and scalable pipelines. apsimNGpy functionalities include, but not limited to the following:

Scalable performance. Run large experiment sets efficiently via multiprocessing/multithreading (e.g., factorials, ensembles, calibrations) using a clean, high-level API.

Spatial & data integration. Leverage Python’s geospatial stack and built-in helpers to fetch and manage soil/weather inputs, enabling landscape-scale analyses.

Optimization & calibration. Access multi-objective optimization and sensitivity analysis to quantify trade-offs (e.g., yield vs. nitrate loss/GHG) and calibrate parameters.

Reproducible automation. Run APSIM using Jupyter/CLI/scripts; outputs land in pandas DataFrames for downstream analysis, plotting, and reporting.

Full model manipulation. A modular, object-oriented design supports inspection, editing, experiments, and custom reports without manual GUI interface.

Version resilience. rather than tying apsimNGpy to a fixed APSIM version, apsimNGpy is developed with forward- and backward-compatibility in mind and is actively synchronized with upstream APSIM.

Open and extensible. Apache-2.0 licensing, clear abstractions, and a plug-friendly architecture make it easy to extend and integrate into existing research pipelines.

Diverse model evaluation metrics. Built-in model prediction evaluation metrics: RMSE, RRMSE, Willmott’s Index of Agreement (WIA), Bias, MAE, Lin’s CCC, and R²

Discussion and Community Support

Users who wish to ask questions, report issues, request new features, or engage in general discussion about apsimNGpy are encouraged to visit the project’s official GitHub Discussions page.

This forum serves as the preferred place for:

• Troubleshooting and “how-to” questions

• Sharing workflows or examples

• Feature proposals and use-case discussions

• Clarification on model editing, optimization, and calibration

• Community-driven enhancements

• Collaboration with other APSIM users

If your question is not answered in the documentation, feel free to start a new discussion thread and tag it appropriately.

For reporting reproducible bugs or contributing code, please use the GitHub Issues tracker.

Table of Contents

• Home

RELEASE NOTES

• apsimNGpy 0.39.11.20 – Release Notes
  • 1) Temporally simulations using a context manager
  • 2) Temporary APSIM-bin path

Getting Started

• Installation
• Quick guides
• Locating the APSIM Binaries
• Changing/setting the APSIM installation binaries path
  • 1. Manually configure the APSIM binary path. To do this:
  • 2. Change based os.environ module
  • 3. Use the apsimNGpy config module:
  • 4. Use command line interface
• Instantiating apsimNGpy Model Objects
• Running and Retrieving Results
  • Running loaded models
  • Accessing Simulated Results
  • Saving the Simulation

VERSION CONTROL

• Version Control and APSIM Compatibility in apsimNGpy
• Managing apsimNGpy project environment
• Step 1 — Create .env in your project root
• Set 3.Use it in your app:

EDITING & INSPECTION

• Inspect Model
• Whole Model inspection
• Model Preview in GUI
  • Examples
• Inspect Model Parameters
• Editing model parameters
  • Selective editing
  • edit_method function signature
• More examples about edit_model_by_path
• Editing nested simulation models
• Quick and Simple Way to Run Factorial Experiments
  • Setting Up the Environment
  • Creating an Experiment
  • Adding Factors
  • Running the Experiment
  • Factorial Experiment with Cultivar Replacements
• Quick Overview
• Getting Started
• Adding Input Factors
• Finalizing the Experiment
• API Summary
• Further Reading
• Weather Data Replacement.
  • Get weather data from the web
  • Using local weather data

DISTRIBUTED COMPUTING

• Distributed Computing
• Instantiating and Running the Simulations
• Customization
  • Minimal example 1: Writing your own worker and data storage function
  • Minimal example 2: Writing your own worker and use data storage decorator from data_base_utils (only latest version)
• Running all jobs
• Working in notebooks (Jupyter/Colab)
  • Minimal Example 3: Run All Simulations Using the C# Backend

OPTIMIZATION & TRADE-OFF ANALYSIS

• Parameter calibration
  • Defining the Optimization Problem
  • Defining the factors
  • Submit optimization factors
  • Configure the optimizer
  • Use differential evolution
  • Local optimization examples
  • Differential Evolution Performance and Comparison with Local Optimizers
  • Full tutorial code:
  • Local optimization examples
• Multi-Objective Optimization with apsimNGpy
  • Step 1: Import required modules
  • Step 2: Initialize the APSIM model runner
  • Step 3: Define Objective Functions
  • Step 4a: Define decision variables (Approach 1 - direct List)
  • Step 3b: Define decision variables (Approach 2 - using add_control())
  • Step 5: Run the NSGA-II optimizer
  • Step 6: Plot the Pareto Front
  • Comparing objectives without mult-objective optimization

SUPPORT DEVELOPMENT

• Support apsimNGpy development
  • How You Can Support
  • Contact
    • How to Contribute to apsimNGpy
  • Reporting Issues
  • Contributing Code
  • Updating Documentation
  • Testing your pull request or your contribution
• How to Cite apsimNGpy

TUTORIALS

• Comparing cultivars yield
  • Variability across the simulation years

Sensitivity Analysis

• Sensitivity Analysis in apsimNGpy
  • Workflow Overview
  • Workflow Diagram

CHEATSHEET

• apsimNGpy cheatsheet

SIMULATED DATA PLOTTING & VISUALIZATION

• Plotting and Visualizing Simulated Output
  • Create the experiment
  • Adding factors to the experiment
• Moving average plots
  • Multi-year moving average for each experiment (line plot).
• Categorical Plots
  • Box plots
  • Maize yield variability by population density (mva plot).
  • Maize yield variability by population density and nitrogen fertilizer (box plot).
  • Bar Plots
  • Maize yield variability by population density (bar plot).
  • Maize yield variability by population density (bar plot, estimator =sum).
  • Maize yield variability by population density in Mg (bar plot, estimator =sum).
• Tidy up the plots for reporting
  • Maize yield labeled plot (bar plot).
• Passing a custom dataset
  • Maize yield ordered plot (Line plot)
  • Binned Maize yield (bar plot).
• Meta info

API REFERENCE

• apsimNGpy: API Reference
  • apsimNGpy.core.apsim
  • apsimNGpy.core.config
  • apsimNGpy.core.experimentmanager
  • apsimNGpy.core.mult_cores
  • apsimNGpy.core.pythonet_config
  • apsimNGpy.core.runner
  • apsimNGpy.core.senstivitymanager
  • apsimNGpy.core_utils.database_utils
  • apsimNGpy.exceptions
  • apsimNGpy.optimizer.minimize.single_mixed
  • apsimNGpy.optimizer.moo
  • apsimNGpy.optimizer.problems.back_end
  • apsimNGpy.optimizer.problems.smp
  • apsimNGpy.parallel.process
  • apsimNGpy.validation.evaluator