apsimNGpy: The Next-Generation Agro-ecosystem Simulation Library

Introduction

apsimNGpy is an 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:

• Run large experiment sets efficiently using multiprocessing or multithreading.

• Integrate geospatial data with automated soil and weather input retrieval.

• Perform multi-objective optimization and sensitivity analysis for model calibration.

• Execute APSIM through Jupyter, CLI, or python scripts with results returned as pandas DataFrames.

• Inspect, edit, and manage APSIM models programmatically without the GUI.

• Maintain forward and backward compatibility with evolving APSIM versions.

• Extend and integrate workflows using an open, Apache-2.0 licensed architecture.

• Evaluate model predictions using built-in metrics such as RMSE, RRMSE, WIA, MAE, CCC, and R².

• Port complete projects across machines using containerized execution with referenced binaries.

Table of Contents

• Home

Getting Started

• Getting started
  • Operating System
  • Python Requirements
  • Required Dependencies
  • Installing apsimNGpy
  • Method 1: Install from PyPI (stable releases)
  • Method 2: Clone the development repository
  • Method 3: Install directly from GitHub (Recommended)
  • Editable installation (for developers)
  • Important APSIM installation and tutorial links
  • Verifying the APSIM Binary Path
  • Using the command line to set or check the APSIM bin path
  • Automatic search
  • Using Python
  • How apsimNGpy Locates APSIM Binaries
  • Setting or Updating the APSIM Binary Path
  • Option 1: Manual configuration file
  • Option 2: Using the apsimNGpy config API (recommended)
  • Option 3: Command-line update
  • Verifying Successful Configuration
• Instantiating apsimNGpy Model Objects
  • What comes next after editing
• Running and Retrieving Results
  • Running loaded models
  • Accessing Simulated Results
  • Using a context manager for class ApsimModel
  • Saving the Simulation
  • Reloading Saved Models
  • Controlling Reload Behavior
  • Example: Reload Enabled (Default Behavior)
  • Example: Reload Disabled
  • Using save Inside a Context Manager

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
  • Editing requirements
  • Selective editing
  • edit_method function signature
  • More examples about edit_model_by_path
  • Editing nested simulation models
• Weather Data Replacement.
  • Get weather data from the web
  • Using local weather data
• Soil Parameter Value Replacement
  • Overview
  • Example workflow
  • 1. ISRIC Soil Database
  • 2. SSURGO Soil Database
  • Targeting a specific simulation
  • Soil profile layer thickness

FACTORIAL EXPERIMENTS

• Quick and Simple Way to Run Factorial Experiments
  • Why apsimNGpy for factorial experiments
  • Quick Overview
  • Step 1. Import the API and initialize it
  • Step 2. Adding Factors
  • Step 3. Running the Experiment
  • Step 4. Visualization and other analysis
  • Factorial Experiment with Cultivar Replacements
  • API Summary
  • Further Reading

BATCH SIMULATIONS

• Distributed Computing
  • What is distributed computed ?
  • Job batching
  • 1. Plain job batching (no metadata, no edits)
  • 2. Job batching with metadata
  • 3. Job batching with internal model edits
  • Instantiating and Running the batches
  • Tracking completed jobs
  • Retrieving results
  • csharp or python engine selections
  • Benchmarking computation speed across the different simulation engines

OPTIMIZATION & TRADE-OFF ANALYSIS

• Automatic Parameter calibration
  • Defining the Optimization Problem
  • Defining the factors
  • Submit optimization factors
  • Submitting untyped 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

MODEL EVALUATION

• Evaluate Model on Observed Dataset
  • Import Observed Data
  • Initialize and Run the Model
  • Output
  • Returned Metrics

SUPPORT DEVELOPMENT

• Support apsimNGpy development
  • How You Can Support
  • Contact
• How to Contribute to apsimNGpy
  • Reporting Issues
  • Contributing Code
  • Forking the Repository
  • Clone Your Fork
  • Updating Documentation
  • Testing your pull request or your contribution
    • Options
  • Notes
• How to Cite apsimNGpy

TUTORIALS

• Comparing cultivars yield
  • Variability across the simulation years
• Application of Multiprocessing
  • Problem Description
  • Simulation Design
  • Why Multiprocessing?

Sensitivity Analysis

• Sensitivity Analysis in apsimNGpy Part 1
• Sensitivity Analysis in apsimNGpy Part 1
  • Workflow Overview
  • Workflow Diagram
• Sensitivity analysis workflow Part 2 (SALib driven workflow)
  • Conceptual overview
  • Computational considerations
  • Define APSIM model inputs
  • Initialize the problem
  • Generate samples
  • Sample matrix and evaluation
  • Saltelli sampling behavior
  • Running the APSIM model
  • Evaluation output
  • Perform Analysis
  • Converting outputs to pandas

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).
  • Changing statistical estimators.
  • 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

Changes

• Version 1.5.2
  • Improvements
  • Bug Fixes
  • Tests
  • Version 1.5
• APSIM Runtime Loading Improvements
  • Examples

API REFERENCE

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