The pyaimms Library

The pyaimms library lets you run Python scripts and statements directly from AIMMS.

Features

  • Simple setup with a pyproject.toml for dependencies and Python version.

  • Execute Python code from AIMMS procedures using two functions.

Python Environment (UV)

pyaimms uses UV to manage the embedded Python environment and dependencies. UV creates the required environment the first time the library initializes, so you do not need to pre-install Python.

Note

Windows Store Python is not supported.

The Windows Store version of Python does not work with pyaimms because of the way it is packaged and isolated by Microsoft.

Configure UV in your pyproject.toml file to control which Python installations UV prefers. For example:

[tool.uv]
python-preference = "managed"

The python-preference setting controls whether UV uses managed (downloaded) or system Python installations:

  • only-managed: Only use managed Python installations; never use system Python installations.

  • managed: Prefer managed Python installations over system Python installations (default).

  • system: Prefer system Python installations over managed Python installations.

  • only-system: Only use system Python installations; never use managed Python installations.

For a full list of UV settings, see:

https://docs.astral.sh/uv/reference/settings/

You can also override settings with environment variables such as UV_MANAGED_PYTHON or UV_NO_MANAGED_PYTHON.

Getting Started

This guide shows how to run Python from AIMMS procedures using pyaimms. It includes:

  1. Setting up the pyproject.toml and singleton Python file.

  2. How to structure your project.

  3. Calling Python from AIMMS (statement and script execution).

Use the sample project to follow along:

1. Add a pyproject.toml File

Your project must include a pyproject.toml file in your AIMMS project directory. This file specifies the Python version and all dependencies required by your project. For example:

[project]
name = "your_project_name"
version = "0.1.0"
requires-python = "==3.13.*"
dependencies = [
    "aimmspy",
    "pytest",
    "colorama"
]

[tool.uv]
python-preference = "managed"

  • The requires-python field must match the Python version you want to use.

  • List all packages your Python code imports in the dependencies array.

  • Include the [tool.uv] section shown above to make UV’s Python selection explicit.

That’s it. You can now run Python code from AIMMS procedures.

2. Working with aimmspy

To avoid re-initializing the embedded Python runtime, create a singleton Python file (for example, singleton.py). This file should define global variables for your AIMMS Project and Model, which you can import elsewhere. For example:

from aimmspy.project.project import Project

project = Project(
    exposed_identifier_set_name="AllIdentifiers"
)

my_aimms = project.get_model("model_stub.py")

  • The project variable holds the AIMMS project context.

  • The my_aimms variable provides access to the AIMMS model from Python.

After this, you can import the project and my_aimms variables in any Python module you create. For example:

from singleton import my_aimms

def assign_my_data():
    my_aimms.demand.assign({
        "Houston": 50,
        "Phoenix": 60,
        "Philadelphia": 40,
    })
    my_aimms.supply.assign({
        "NewYork": 70,
        "LosAngeles": 80,
        "Chicago": 60,
    })
    my_aimms.unit_transport_cost.assign({
        ("NewYork", "Houston"): 5.0,
        ("NewYork", "Phoenix"): 6.0,
        ("NewYork", "Philadelphia"): 4.0,
        ("LosAngeles", "Houston"): 3.0,
        ("LosAngeles", "Phoenix"): 2.0,
        ("LosAngeles", "Philadelphia"): 7.0,
        ("Chicago", "Houston"): 4.0,
        ("Chicago", "Phoenix"): 5.0,
        ("Chicago", "Philadelphia"): 3.0,
    })

If you prefer data frames, the same assignments look like this:

import pandas as pd
from singleton import my_aimms

warehouses_set = ["NewYork", "LosAngeles", "Chicago"]
customers_set = ["Houston", "Phoenix", "Philadelphia"]

demand_df = pd.DataFrame({
    "c": customers_set,
    "demand": [50, 60, 40],
})

supply_df = pd.DataFrame({
    "w": warehouses_set,
    "supply": [70.0, 80.0, 60.0],
})

unit_transport_cost_df = pd.DataFrame({
    "c": [
        "Houston", "Phoenix", "Philadelphia",
        "Houston", "Phoenix", "Philadelphia",
        "Houston", "Phoenix", "Philadelphia",
    ],
    "w": [
        "NewYork", "NewYork", "NewYork",
        "LosAngeles", "LosAngeles", "LosAngeles",
        "Chicago", "Chicago", "Chicago",
    ],
    "unit_transport_cost": [5.0, 6.0, 4.0, 3.0, 2.0, 7.0, 4.0, 5.0, 3.0],
})

my_aimms.demand.assign(demand_df)
my_aimms.supply.assign(supply_df)
my_aimms.unit_transport_cost.assign(unit_transport_cost_df)

3. Calling Python from AIMMS

pyaimms provides two functions for executing Python code from AIMMS:

  • py::run_python_statement(<python_statement>): Execute a single Python statement (a string).

  • py::run_python_script(<script_filename>): Execute a Python script file (by filename).

These functions are available in your AIMMS model after importing the pyaimms library. The script path is relative to your AIMMS project directory.

Usage Examples

Below are examples of how to use pyaimms in your AIMMS procedures:

Executing a Python Statement

Use py::run_python_statement to run a single line of Python code, such as calling a function or modifying a variable.

py::run_python_statement("execute_main()");

Executing a Python Script

Use py::run_python_script to execute an entire Python script file. The script filename should be relative to your AIMMS project directory.

py::run_python_script("script_with_func.py");
py::run_python_script("global_assign.py");

Best Practices

  • Always ensure your pyproject.toml lists all dependencies your Python code uses.

  • Use the singleton pattern to avoid re-initializing the aimmspy Project and Model instances multiple times.

  • Keep Python scripts and modules organized and accessible from your AIMMS project directory.

Setting Up a Debugger for Embedded Python

To enable debugging for embedded Python code in AIMMS, you can use the debugpy library. Add the following snippet to your singleton file:

import os
if os.getenv("PYAIMMS_DEBUG"):
    import debugpy
    debugpy.listen(("0.0.0.0", 5678))
    print("Debug server has been opened on 0.0.0.0:5678")

Then, in VS Code, use the following launch configuration:

{
    "name": "Attach to Embedded Python",
    "type": "python",
    "request": "attach",
    "connect": {
        "host": "localhost",
        "port": 5678
    }
}

This starts a debug server on port 5678 when PYAIMMS_DEBUG is set. Change the port if needed. You can then attach and detach a debugger (such as VS Code) while the server is running.

Steps: 1. Ensure debugpy is listed in your pyproject.toml dependencies. 2. Set the environment variable PYAIMMS_DEBUG=1 before running your AIMMS project. 3. Add the code snippet above to your Python entry point or singleton file. 4. Attach your debugger to localhost:5678 from your IDE.

Note: This approach works for embedded Python and allows you to set breakpoints, inspect variables, and step through code interactively.

Note

  • Python identifier access is case-sensitive. If you get an AttributeError, check the identifier name in your AIMMS model.

  • The script path for run_python_script is always relative to your AIMMS project directory.

  • Because Python is embedded in AIMMS, standard multiprocessing may not work. Use threads instead unless you have configured multiprocessing explicitly.

  • AIMMS projects using pyaimms cannot be closed and reopened within the same IDE session. To restart the project, close the AIMMS IDE completely and reopen it.

  • If you change your model (for example, by adding new identifiers), call get_model() again to refresh the model in Python.