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.

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.