Links

Documentation

Publication.

Version 1.5.5 passed unit tests under Python 3.14+

For the complete list of new features, improvements, and bug fixes, see the v1.5.3 release notes.

apsimNGpy: The Next Generation Agroe-cosystem Simulation Library

apsimNGpy is an open-source framework for advanced agroecosystem modeling, built entirely in Python. It enables object-oriented, data-driven workflows for interacting with APSIM Next Generation models, offering capabilities for:

• Batch file simulation and model evaluation
• APSIMX file editing and parameter inspection
• Weather data retrieval and pre-processing
• Optimization and performance diagnostics
• Efficient soil profile development and validation
• Parameter sensitivity analysis

Python serves as the execution environment, integrating scientific computing, data analysis, and automation for sustainable agricultural systems.

Requirements

1. .NET SDK — install from https://learn.microsoft.com/en-us/dotnet/core/install/
2. Python 3.10+
3. APSIM Next Generation — ensure the directory containing Models.exe is added to your system PATH.
4. (Optional) Use the official APSIM installer for easiest setup.
5. Minimum 8 GB RAM recommended.

Installation

## Run APSIM in Python

Option 1 – Install from PyPI (stable)

pip install apsimNGpy

If using the uv virtual environment manager:

uv pip install apsimNGpy

Option 2 – Clone the development repository

git clone https://github.com/MAGALA-RICHARD/apsimNGpy.git
cd apsimNGpy
pip install .

Option 3 – Install directly from GitHub

pip install git+https://github.com/MAGALA-RICHARD/apsimNGpy.git

APSIM Next Generation (NG) Installation Tip

Use the pinned APSIM release indicated on the documentation homepage to avoid forward-compatibility issues. The pinned version represents the latest APSIM NG build verified against apsimNGpy’s API and unit tests.

Projects and Agentic Systems Built With or Inspired by apsimNGpy

• apsim-mcp: Natural-Language Agent Interface for APSIM Next Generation by Briggs599 (2026). This MCP server allows an LLM to operate APSIM Next Generation using natural language. The agent can open APSIM models, inspect their structure, modify model parameters, attach soil and weather data, configure report variables, execute individual or factorial experiments, and retrieve simulation outputs. Its engine dependency explicitly includes apsimNGpy, making apsimNGpy the bridge between MCP/LLM tool calls and APSIM/.NET. The project has been tested with Claude Desktop and Claude Code and has also been presented in the APSIM community as an LLM interface for APSIM.
• Coupled Process-Based and Machine-Learning Ensemble Modeling for Agricultural N2O Flux Prediction by Kyungdoe Han / Terminal-Bench Science (2026). This AI-for-science benchmark requires an autonomous agent to use apsimNGpy >= 1.5.3 to repeatedly execute APSIM, extract SOC, NH4, NO3, soil moisture/WFPS, and temperature, align those mechanistic outputs with field N2O observations, and train an XGBoost model for blind N2O prediction. It is particularly interesting because apsimNGpy is not merely supporting a researcher—the AI agent itself is expected to learn and operate apsimNGpy as a scientific tool. The proposal was subsequently approved for implementation by Terminal-Bench Science.
• Nitrogen Digital Twin by Taylor Sharpe / BEEM Lab, University of Colorado Boulder (2026). This project develops a farm-scale nitrogen digital twin combining low-cost soil sensors, Ensemble Kalman Filter data assimilation, spatial kriging, forecasting, nitrogen balance calculations, and mechanistic modeling. Its project specification identifies apsimNGpy + APSIM-X as the intended production replacement for the current simplified nitrogen-cycle ODE model.
• apsimNGpy-soils: APSIM-ready Soil Profile Construction Tools by Abhi-Plant (2026). Downstream apsimNGpy ecosystem extension. This independent project provides tools for creating APSIM-ready soil profiles using SSURGO and SoilGrids data, pedotransfer functions, polygon queries, and APSIM soil-parameter editors.