Getting started

Table of Contents

Operating System

  • Windows

  • Linux and macOS are also supported, provided APSIM is installed and running locally on your machine.

Python Requirements

  • Python ≥ 3.10 and < 3.14

    Note

    Python 3.14 is not currently supported due to upstream limitations in pythonnet. However, the development team is working around the clock to make sure it is also supported

Required Dependencies

  • APSIM (installed locally)

    • APSIM must be installed and accessible on the system.

    • A compatible APSIM version matching your workflow is required.

  • pythonnet ≥ 3.0.5

    • Used to interface with APSIM’s .NET runtime.

  • NumPy

  • Pandas

  • SQLAlchemy

  • matplotlib and seaborn

These dependencies are installed automatically via pip.

Installing apsimNGpy

Run APSIM simulation

You can install apsimNGpy using one of the methods below.

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 .

Editable installation (for developers)

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

Verifying the APSIM Binary Path

Using the command line to set or check the APSIM bin path

apsim_bin_path -s

Using Python

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

See also

API reference: get_apsim_bin_path()

How apsimNGpy Locates APSIM Binaries

Tip

apsimNGpy locates APSIM binaries using the following priority order:

  1. User-supplied binary path

  2. Environment variables

  3. System PATH

  4. 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

  1. Locate APSIMNGpy_meta_data in your home directory.

  2. Open apsimNGpy_config.ini.

  3. Update the apsim_location entry.

Option 3: 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.

The quickest alternative for all the above is to temporarily provide the APSIM bin path using a context manager. This approach is useful for short scripts or interactive sessions and assumes that you do not import any other apsimNGpy modules outside of the config module before entering the with block as shown below:

from apsimNGpy.config import apsim_bin_context
with apsim_bin_context(
    apsim_bin_path=r"your_apsim_binary_path"):
    from apsimNGpy.core.apsim import ApsimModel
    model = ApsimModel("Soybean")
    df = model.run()

Note

When using the APSIM bin context manager as shown above, the APSIM binaries are loaded only within the scope of that context, and the global APSIM binary configuration is not modified. This means the same context setup must be applied in each script where apsimNGpy is used. Whether this is an inconvenience depends on the use case—for example, it can be beneficial if you do not want to modify the global APSIM installation because it is used by other projects, or if you need to test or compare results across specific APSIM versions.

Attention

Due to the way APSIM binaries are initialized globally within the runtime environment, only one APSIM bin context manager can be active at a time. As a result, starting another APSIM bin context manager within or after an existing one will not behave as expected and may lead to difficult-to-diagnose errors. In simple terms, multiple APSIM bin context managers cannot be used sequentially or nested within the same process, and attempting to do so is strongly discouraged.