Orchestrating Contract Allocation AIMMS App from Python

This guide shows you how to use the AIMMS Python-Bridge to control an AIMMS application from a Python script. This approach is ideal for running an AIMMS model as a “headless” optimization service within a larger data pipeline.

Please refer to the Contract Allocation example to follow along with this article. This article illustrates the process, which consists of the following steps:

1. Prepare the link between Python and the AIMMS app.

2. Pass data from Python to the AIMMS app.

3. Run the solver.

4. Retrieve the solution.

5. Write the results back to Excel.

Prepare Link Between Python and AIMMS

First, ensure you have the aimmspy library installed. You can install it using pip:

pip install aimmspy

To use the aimmspy library, import it as follows:

from aimmspy.project.project import DataReturnTypes, Project, AimmsException, AimmsPyException, Model
from aimmspy.utils import find_aimms_path

Next, initialize the Project and get a reference to your AIMMS model. This sets up the communication link.

# Initialize the AIMMS project connection.
project = Project(
    # Path to the AIMMS Bin folder (required for API connection).
    aimms_path=find_aimms_path("25"),

    # Path to the AIMMS project file to be opened.
    aimms_project_file=os.path.join(projectroot, 'AIMMS-project', 'ContractAllocation.aimms'),

    # The name of the AIMMS set containing all identifiers exposed to Python.
    exposed_identifier_set_name="AllIdentifiers",

    # Default data type for multi-dimensional data retrieval (Pandas DataFrame is preferred).
    data_type_preference=DataReturnTypes.PANDAS,

    # license_url: Fill license URL if using a network license.
)

# Get a reference to the active AIMMS model instance for data transfer and execution.
aimms_model : Model = project.get_model(__file__)

Remarks:

• Line 4: aimms_path is the path to the AIMMS installation. The find_aimms_path utility helps to locate your AIMMS installation.

• Line 7: aimms_project_file is the path to your AIMMS project file. In this example it happens to be relative to the Python script:

  .
  ├── AIMMS-project
  │   ├── MainProject
  │   ├── ....
  │   └── ContractAllocation.aimms
  │
  └── python-bridge
      ├── main.py
      └── requirements.txt
  

• Line 10: exposed_identifier_set_name controls which model identifiers the Python script can access. AllIdentifiers provides full access.

• Line 13: data_type_preference specifies the default data structure for data exchange. We use pandas as it also provides seamless integration with Excel files. Python polars also provide seamless integration with Excel files and might have been used as well.

Passing Input Data

Importing Producers Data

This example reads data from a sheet called Producers and renames the columns to match the corresponding AIMMS identifiers.

# 1. Load and Assign Producer Data (i_producer, capacities)
datainput_pd_producer = pd.read_excel(datainput, sheet_name='Producers')

# Rename columns to match exact AIMMS identifiers for seamless assignment.
datainput_pd_producer.rename(columns={
    'Producers'             : 'i_producer',
    'Available Capacity'    : 'p_availableCapacity',
    'Minimal Delivery'      : 'p_minimalDelivery'
    }, inplace=True)

# Assign data to the corresponding AIMMS identifiers.
aimms_model.multi_assign(datainput_pd_producer)

Remarks:

• Line 3: Reading the data using the Panda’s read_excel method.

• Line 6-14: Usually, the column names of tables are not the same as the identifier names in an AIMMS model. In this example too. Therefor, Panda’s rename is used.

• Line 17: The multi_assign method efficiently passes the entire DataFrame to the AIMMS model in a single, concise statement.

Note that the data for the other sheets are read in and passed to AIMMS similarly.

Running the Optimization Inside the AIMMS App

After loading all data, you can execute the optimization logic within your AIMMS model by calling the corresponding procedure.

# 4. Execute the AIMMS Optimization
# Calls the main procedure in AIMMS to solve the optimization problem.
aimms_model.MainExecution()

This single line tells the AIMMS model to run its MainExecution procedure, which typically contains the solver calls and other logic.

Retrieving the Solution and Writing to Excel

Once the solver finishes, you can retrieve the results from the AIMMS model and write them to a new Excel workbook.

Retrieving Contract Allocation

The multi_data method retrieves data from multiple AIMMS identifiers at once.

# Get the total contract fulfillment results.
df_contract_allocation = aimms_model.multi_data(["i_contractExport","p_totalGeneration"])

The rename function then prepares the data for export.

# Rename columns for user-friendly export to Excel.
df_contract_allocation.rename(columns={
    'i_contractExport'      : 'Contract',
    'p_totalGeneration'     : 'Total Generation'
    }, inplace=True)

Finally, use the ExcelWriter from pandas to save all your result DataFrames into a single Excel file, with each DataFrame on its own sheet.

# Use ExcelWriter to write multiple DataFrames to separate sheets in a single file.
with pd.ExcelWriter(excel_file_path, engine='openpyxl') as writer:
    df_producer_allocation.to_excel(writer, sheet_name='Allocation per Producer', index=False)
    df_contract_allocation.to_excel(writer, sheet_name='Contract Allocation', index=False)

See also

• Python Bridge.

• PyPI aimmspy.