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²

Table of Contents

• Home

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
• Inspect Model Parameters
• Editing Model Parameters
• 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)

OPTIMIZATION & TRADE-OFF ANALYSIS

• Single-Objective Optimization with apsimNGpy
  • Demonstration
  • Minimizing continuous variables
  • Adding control variables
• Mixed-Variable Optimization in apsimNGpy
  • Using MixedVariable in Practice
  • Review optimization results
  • Summary
• 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

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_utils.database_utils
  • apsimNGpy.exceptions
  • apsimNGpy.optimizer.moo
  • apsimNGpy.optimizer.single
  • apsimNGpy.parallel.process
  • apsimNGpy.validation.evaluator