Installation

apsimNGpy is under active development. Stable releases are available, but new features and bug fixes are introduced frequently. You can install the package using one of the methods below.

Installing apsimNGpy

Method 1: Install from PyPI (stable releases)

pip install apsimNGpy

Method 2: Clone the development repository

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

Method 3: Install directly from GitHub (recommended)

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

Tip

Installing directly from GitHub is strongly recommended, as the repository is actively maintained and receives continuous bug fixes as soon as issues are reported by users.

Editable installation (for developers)

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

Prerequisites

Important

Before using apsimNGpy, APSIM Next Generation must be installed.

Windows: https://www.apsim.info/download-apsim/downloads/
macOS / Linux: https://apsimnextgeneration.netlify.app/install/
APSIM documentation: https://docs.apsim.info/

apsimNGpy assumes users have a basic understanding of APSIM as a process-based crop model. The goal of this package is to provide a programmatic and reproducible interface.

Tip

Use the pinned APSIM release shown on the apsimNGpy home page (Download it here) to avoid forward-compatibility issues.

Verifying the APSIM Binary Path

Using the command line

apsim_bin_path -s

Automatic search

apsim_bin_path --auto_search

Hint

Shortcut:

apsim_bin_path -a

Using Python

from apsimNGpy.core import config
print(config.get_apsim_bin_path())

How apsimNGpy Locates APSIM Binaries

Tip

apsimNGpy locates APSIM binaries using the following priority order:

User-supplied binary path
Environment variables
System PATH
Known installation directories

If no valid path is found, a ValueError is raised.

Setting or Updating the APSIM Binary Path

Option 1: Manual configuration file

Locate APSIMNGpy_meta_data in your home directory.
Open apsimNGpy_config.ini.
Update the apsim_location entry.

Option 2: Environment variable (temporary)

import os
os.environ["APSIM"] = r"path/to/your/apsim/binary/folder/bin"

Caution

This approach must be executed before importing apsimNGpy.

Option 3: Using the apsimNGpy config API (recommended)

from apsimNGpy.core.config import set_apsim_bin_path
set_apsim_bin_path(r"path/to/your/apsim/binary/folder/bin")

Option 4: Command-line update

apsim_bin_path -u "path/to/your/apsim/binary/folder/bin"

or

apsim_bin_path --update "path/to/your/apsim/binary/folder/bin"

Verifying Successful Configuration

from apsimNGpy.core.apsim import ApsimModel

Attention

If this import fails, verify the APSIM binary path and Python.NET setup.

Final Note

The APSIM binary path only needs to be set once and can be reused across projects. apsimNGpy also supports switching between multiple APSIM versions when required.

Containerization and Portability

apsimNGpy simplifies containerization and project portability. Entire projects can be transferred to another machine without reinstalling APSIM, provided the APSIM binaries are correctly referenced.