Hexaly Modeler API

The Hexaly Modeler API allows you to interact with the virtual machine powering the Hexaly modeling language: developers with prototypes written with the modeler are able to integrate them fully into Python, Java, C#, and C++ environments. With these new bindings, you can, for example:

  • Load existing HXM files into modules and execute them.

  • Interact with functions and variables contained in modules.

  • Expose methods developed in your language of choice to Hexaly Modeler.

Thus, integrating the knapsack HXM program in a Python environment is now possible. First, we need to instantiate the API’s main class, the HexalyModeler, which will enable us to interact with modules, maps, and functions. Given that the model above is available to us in a file named knapsack.hxm, we can load the module into the modeler with the following snippet:

from hexaly.modeler import HexalyModeler

with HexalyModeler() as modeler:
    knapsack_module = modeler.load_module("knapsack", "knapsack.hxm")

This makes all variables and functions contained in knapsack.hxm available to us through the knapsack_module object (see the HxmModule reference). It also enables us to execute this module, which means running the model function and starting the resolution process. As we have seen before, we need to initialize a few variables beforehand.

To set a value for integer variables like nbItems and knapsackBound, we can do the following:

# Declares a variable named `nbItems` and sets its value to 5.
knapsack_module["nbItems"] = 5

Next, we need to input the weights and the prices. They are both collections of numbers, so they should be objects of type HxmMap:

# `weights_data` is the data we want to input.
weights_data = [5, 4, 6, 3, 1]
# `weights_map` is the HxmMap that will hold the values in the HXM program.
weights_map = modeler.create_map()

for value in weights_data:
    weights_map.append(value)

knapsack_module["weights"] = weights_map

With all variables set, we can create an optimizer and execute the module by calling either knapsack_module.run() or knapsack_module.runMain() depending on the Hexaly Modeler mode (classic or main). This method replicates the behavior we would get by executing the module from the command line, and we can pass down arguments like hxTimeLimit:

optimizer = modeler.create_optimizer()
knapsack_module.run(optimizer, "hxTimeLimit=10")

Once the resolution process is done, we can extract solution data:

# First we extract the HxExpression created within the HXM program.
obj_expression = knapsack_module["knapsackValue"]
# We can then extract the objective value using the regular Hexaly Optimizer Python API.
obj_value = obj_expression.value

Using the modeler API, you can thus benefit from the ease of modeling in Hexaly Modeler whilst still being able to integrate models in Python, Java, C#, and C++ applications.

Complete example

from hexaly.modeler import *

with HexalyModeler() as modeler:
    knapsack_module = modeler.load_module("knapsack", "knapsack.hxm")

    # Declares a variable and sets its value.
    knapsack_module["nbItems"] = 8
    knapsack_module["knapsackBound"] = 102

    # Data we want to input
    weights_data = [10, 60, 30, 40, 30, 20, 20, 2]
    prices_data = [1, 10, 15, 40, 60, 90, 100, 15]
    # HxmMap that will hold the values in the modeling program
    weights_map = modeler.create_map()
    prices_map = modeler.create_map()

    for value in weights_data:
        weights_map.append(value)
    for value in prices_data:
        prices_map.append(value)

    knapsack_module["weights"] = weights_map
    knapsack_module["prices"] = prices_map

    optimizer = modeler.create_optimizer()
    knapsack_module.run(optimizer, "hxTimeLimit=10")

    # First we extract the HxExpression created by Hexaly Modeler.
    obj_expression = knapsack_module["knapsackValue"]
    # We can then extract the objective value using the regular Hexaly Optimizer Python API.
    obj_value = obj_expression.value
    print("The final knapsack value is", obj_value)

#include "optimizer/hexalyoptimizer.h"
#include "modeler/hexalymodeler.h"
#include <iostream>

using namespace hexaly;

int main(int argc, char** argv) {
    HexalyModeler modeler;
    HxmModule knapsackModule = modeler.loadModule("knapsack", "knapsack.hxm");

    // Declares a variable and sets its value.
    knapsackModule.setInt("nbItems", 8);
    knapsackModule.setInt("knapsackBound", 102);

    // Data we want to input
    std::vector<int> weights {10, 60, 30, 40, 30, 20, 20, 2};
    std::vector<int> prices {1, 10, 15, 40, 60, 90, 100, 15};
    // HxmMap that will hold the values in the modeling program
    HxmMap weightsMap = modeler.createMap();
    HxmMap pricesMap = modeler.createMap();

    for (int value : weights)
        weightsMap.addInt(value);
    for (int value : prices)
        pricesMap.addInt(value);

    knapsackModule.setMap("weights", weightsMap);
    knapsackModule.setMap("prices", pricesMap);

    HexalyOptimizer optimizer = modeler.createOptimizer();
    std::vector<string> arguments {"hxTimeLimit=10"};
    knapsackModule.run(optimizer, arguments);

    // First we extract the HxExpression created by Hexaly Modeler.
    HxExpression objExpression = knapsackModule.getExpression("knapsackValue");
    // We can then extract the objective value using the regular Hexaly Optimizer C++ API.
    int objValue = objExpression.getValue();
    std::cout << "The final knapsack value is " << objValue << std::endl;

    return 0;
}

using System;
using System.Collections.Generic;
using Hexaly.Optimizer;
using Hexaly.Modeler;

public class ModelerTest : IDisposable
{
    public void Dispose() {}

    public static void Main(string[] args)
    {
        HexalyModeler modeler = new HexalyModeler();
        HxmModule knapsackModule = modeler.LoadModule("knapsack", "knapsack.hxm");

        // Declares a variable and sets its value.
        knapsackModule.SetInt("nbItems", 8);
        knapsackModule.SetInt("knapsackBound", 102);

        // Data we want to input
        List<int> weights = new List<int>() {10, 60, 30, 40, 30, 20, 20, 2};
        List<int> prices = new List<int>() {1, 10, 15, 40, 60, 90, 100, 15};
        // HxmMap that will hold the values in the modeling program
        HxmMap weightsMap = modeler.CreateMap();
        HxmMap pricesMap = modeler.CreateMap();

        foreach (int value in weights)
            weightsMap.AddInt(value);
        foreach (int value in prices)
            pricesMap.AddInt(value);

        knapsackModule.SetMap("weights", weightsMap);
        knapsackModule.SetMap("prices", pricesMap);

        HexalyOptimizer optimizer = modeler.CreateOptimizer();
        List<string> arguments = new List<string>() {"hxTimeLimit=10"};
        knapsackModule.Run(optimizer, arguments);

        // First we extract the HxExpression created by Hexaly Modeler.
        HxExpression objExpression = knapsackModule.GetExpression("knapsackValue");
        // We can then extract the objective value using the regular Hexaly Optimizer C# API.
        long objValue = objExpression.GetValue();
        Console.WriteLine("The final knapsack value is " + objValue);
    }
}

import java.util.Arrays;
import java.util.List;
import com.hexaly.optimizer.*;
import com.hexaly.modeler.*;

public class ModelerTest {
    public static void main(String[] args) {
        try (HexalyModeler modeler = new HexalyModeler()) {
            HxmModule knapsackModule = modeler.loadModule("knapsack", "knapsack.hxm");

            // Declares a variable and sets its value.
            knapsackModule.setInt("nbItems", 8);
            knapsackModule.setInt("knapsackBound", 102);

            // Data we want to input
            List<Integer> weights = Arrays.asList(10, 60, 30, 40, 30, 20, 20, 2);
            List<Integer> prices = Arrays.asList(1, 10, 15, 40, 60, 90, 100, 15);
            // HxmMap that will hold the values in the modeling program
            HxmMap weightsMap = modeler.createMap();
            HxmMap pricesMap = modeler.createMap();

            for (int value : weights)
                weightsMap.addInt(value);
            for (int value : prices)
                pricesMap.addInt(value);

            knapsackModule.setMap("weights", weightsMap);
            knapsackModule.setMap("prices", pricesMap);

            HexalyOptimizer optimizer = modeler.createOptimizer();
            List<String> arguments = Arrays.asList("hxTimeLimit=10");
            knapsackModule.run(optimizer, arguments);

            // First we extract the HxExpression created by Hexaly Modeler.
            HxExpression objExpression = knapsackModule.getExpression("knapsackValue");
            // We can then extract the objective value using the regular Hexaly Optimizer Java API.
            long objValue = objExpression.getValue();
            System.out.println("The final knapsack value is " + objValue);

        } catch (Exception ex) {
            System.err.println(ex);
            ex.printStackTrace();
            System.exit(1);
        }
    }
}