AIMMS Python library

This is a BETA version of the AIMMS Python library. Any feedback, bug reports, or feature requests are welcome.

With this library its possible to interact with AIMMS models from Python.

Features

• Seamless integration with AIMMS models from Python
• Assign and retrieve data using Python dicts, Pandas, Polars, or Arrow tables
• Execute AIMMS procedures and retrieve results programmatically
• Built with pybind11 for high-performance C++ integration
• Flexible data return types for different workflows

Note: The AIMMS Python library is tested with Python 3.10 or higher. Currently only the windows platform is supported.

Getting Started

To use the AIMMS Python library, you need to have an AIMMS installed and a correct organization license and an aimms project. Below is a step-by-step example of how to use the library to solve a simple transportation optimization problem.

Step 1: Initialize the AIMMS Project

First, initialize the AIMMS project by specifying the AIMMS executable path, project path, and other configurations.

Note: Ensure that the aimms_path points to a valid AIMMS bin folder of an installed AIMMS version. Additionally, you must have the appropriate AIMMS license configured. Failure to provide a valid path or license will result in errors.

The exposed_identifier_set_name parameter controls which AIMMS identifiers are accessible in Python. For example, setting it to "AllIdentifiers" exposes all identifiers in your AIMMS project which is an easy way to get started.

The data type preference can be set to DataReturnTypes.DICT, DataReturnTypes.ARROW DataReturnTypes.PANDAS or DataReturnTypes.POLARS. The default is DataReturnTypes.DICT.

import os
from aimms.project.project import Project

# Initialize the AIMMS project
my_aimms = Project(
    # path to the AIMMS Bin folder
    aimms_path=os.getenv("AIMMSPATH"),

    # path to the AIMMS project folder
    aimms_project_path=os.getenv("AIMMSPROJECTPATH"),

    # the name of an aimms set containing identifiers. 
    exposed_identifier_set_name="AllIdentifiers",  # Limit access to specific identifiers,
    data_type_preference=DataReturnTypes.DICT,
)

Step 2: Assign Data to Parameters

This is an example of assigning data to parameters with Pandas DataFrames.

demand_df = pd.DataFrame({
    "c": ["Houston", "Phoenix", "Philadelphia"],
    "demand": [50.0, 60.0, 40.0]
})

supply_df = pd.DataFrame(data={
    "w": ["NewYork", "LosAngeles", "Chicago"],
    "supply": [70.0, 80.0, 60.0]
})

unit_transport_cost_df = pd.DataFrame({
    "w": ["NewYork", "NewYork", "NewYork", "LosAngeles", "LosAngeles", "LosAngeles", "Chicago", "Chicago", "Chicago"],
    "c": ["Houston", "Phoenix", "Philadelphia", "Houston", "Phoenix", "Philadelphia", "Houston", "Phoenix", "Philadelphia"],
    "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)

You can assign doubles, integers, strings to AIMMS parameters. The library will automatically convert the data types to the appropriate AIMMS types. The sets will be filled automatically based on the data you assign to the parameters.

Step 3: Execute the Optimization Procedure

It is possible in AIMMS to define procedures that encapsulate the logic of your optimization model. These procedures can be executed from Python using the AIMMS Python library. In this example we run the main procedure in the AIMMS project to solve the optimization problem.

my_aimms.MainExecution()

It is also possible to run procedures with arguments for example:

my_aimms.run_procedure(test1=5.0, test2=10.0, test3="hallo")

Make sure the order of the arguments is correct as well as the types.

Step 4: Retrieve and Display Results

Retrieve the results of the optimization, such as the total transport cost and the transport plan.

# Retrieve results
print(f"Total Transport Cost: {my_aimms.total_transport_cost.data()}")
print(f"Transport Plan: {my_aimms.transport.data()}")

The .data() function is used to fetch the current value of an AIMMS identifier (e.g., a parameter, variable, or set) into Python. This function is efficient and only fetches data if it has changed since the last fetch.

Data Types Returned by .data()

depending on the data_type_preference you set in the Project constructor, the .data() function will return different types of Python objects:

Sets always return a list of strings.

For parameters and variables, .data() can return:

• A scalar value (e.g., float or int or string) if the parameter or variable is scalar.
• A dictionary where the keys are tuples of strings (representing indices) and the values are float, int, string.
• A Arrow Table or Pandas or Polars DataFrame depending on the data_type_preference set in the Project constructor.

Example Output

Depending on you return type preference the python object returned from the .data() function will be different, the output for dictionaries can look like this:

Total Transport Cost: 150.0
Transport: {("NewYork", "Houston"): 30, ("LosAngeles", "Phoenix"): 50, ...}

for Pandas DataFrames can look like this:

Total Transport Cost: 150.0
Transport:
        w               c               transport
    0   NewYork         Houston         30
    1   LosAngeles      Phoenix         50
    2   Chicago         Philadelphia    40
    3   NewYork         Philadelphia    20

extra

it is possible to generate a stub file for your project which can greatly help with autocompletion in your IDE. This stub file contains all the identifiers in your AIMMS project and their types. You can generate this stub file by running the following command:

my_aimms.generate_stub_file( "my_project_stub.py" )

To use this stub file you can the following to the top of your python script:

from typing import TYPE_CHECKING
if TYPE_CHECKING:
    from my_project_stub import Project

License

This project is licensed under the MIT License.

Support

For questions, bug reports, or feature requests, please contact AIMMS B.V. via support. Or post an question on the AIMMS Community. We are happy to help you with any issues or questions you may have.