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

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

CHEATSHEET

• apsimNGpy cheatsheet

API REFERENCE

• apsimNGpy: API Reference
• ApsimModel
• ContinuousVariable
• CoreModel
• ExperimentManager
• MixedVariable
• ModelTools
• MultiCoreManager
• MultiObjectiveProblem
• apsimNGpy.core.base_data
• apsimNGpy.core.load_model
• apsimNGpy.core.runner
• apsimNGpy.core_utils.database_utils
• apsimNGpy.exceptions
• apsimNGpy.manager.soilmanager
• apsimNGpy.manager.weathermanager
• apsimNGpy.parallel.process
• apsimNGpy.validation.evaluator