The pyaimms Library

The pyaimms library repository enables seamless integration of Python and AIMMS. With pyaimms, you can 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 intuitive functions

Getting Started

This example uses pyaimms to execute Python code from AIMMS procedures. 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)

Feel free to use the following project to follow this article:

1. Add a pyproject File

Your project must include a pyproject.toml file in the directory of your AIMMS project. 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"
]

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

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

That is it! Now you can run Python code from AIMMS procedures.

2. Working with aimmspy

To prevent issues, it is highly recommended to create a singleton Python file (e.g., singleton.py). This file should define global variables for your AIMMS Project and Model, which can be imported by other Python modules. For example:

from aimmspy.project.project import Project, Model
from aimmspy.model.enums.data_return_types import DataReturnTypes

project = Project(
    exposed_identifier_set_name="AllIdentifiers"
)

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

  • The project 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,
    })

Or if using data frames it can 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(data={
"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 key functions for executing Python code from AIMMS:

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

  • py::run_python_script(<script_filename>): Executes 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 will use.

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

  • Keep Python scripts and modules organized and accessible from the AIMMS project folder 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 for example VS Code you can make the following launch configuration:

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

This will start a debug server on port 5678 (specify the port you want) when the PYAIMMS_DEBUG environment variable is set. You can then attach a debugger (such as VS Code) to this port for interactive debugging. You can attach and detach the debugger 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 attribute error, check the identifier name in your AIMMS model.

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

  • Multiprocessing will work differently because this has Python embedded in AIMMS. The result of this is that you can only use threading and multiprocessing will not work or only if configured correctly.

  • AIMMS projects using pyaimms cannot be closed and reopened within the IDE, because Python cannot be fully destructed and reinitialized in the same session. If you need to restart the project, close the AIMMS IDE completely and reopen it.

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