aimms-api-py 1.0.1.post13
Python bindings for the AIMMS optimization platform, built with pybind11 for seamless C++ integration. Enables efficient data exchange and interaction with AIMMS projects using pandas, polars, and pyarrow. Ideal for advanced optimization workflows requiring high-performance native code.
License: MIT
Requires Python: >=3.9
Keywords: AIMMS, API, Python, Optimization, Operations Research, pybind11, C++, bindings

# 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 optimization projects 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 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`.

```python
import os
from aimms.project.project import Project

# Initialize the AIMMS project
my_aimms = Project(
    # path to the AIMMS executable 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 3: Assign Data to Parameters

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

```python
demand_df = pd.DataFrame({
    "c": customers_set,
    "demand": [50.0, 60.0, 40.0]
})

supply_df = pd.DataFrame(data={
    "w": warehouses_set,
    "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 and calendars to AIMMS parameters. The library will automatically convert the data types to the appropriate AIMMS types.

### Step 4: 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.

```python
my_aimms.MainExecution()
```

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

```python
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 5: Retrieve and Display Results

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

```python
# 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` or `datetime`.
- 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:

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

for Pandas DataFrames can look like this:

```plaintext
Total Transport Cost: 150.0
Transport Plan:
  warehouses  customers  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:

```python
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:

```python
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 [https://www.aimms.com/contact/](https://www.aimms.com/contact/) or open an issue on the project repository.