Two new big features in Hexaly Modeler

Announcement

Frédéric, Ph.D. Senior Optimization Scientist May 10, 2021

With the release of Hexaly 10.0, one of the key features we wanted to push forward was integrating your Hexaly Modeler (HXM) code into full production-ready applications. The Hexaly Modeler JSON module and the Hexaly Modeler API were introduced to facilitate data processing in and out of an HXM program. In this article, we present these features with small examples. We recommend looking at the language reference if you are unfamiliar with Hexaly Modeler (HXM).

Let’s take the Knapsack HXM program from the example tour and see how these features can help us.

// HXM model for the Knapsack Problem
function model() {
    // 0-1 decisions
    x[i in 0..nbItems-1] <- bool();

    // weight constraint
    knapsackWeight <- sum[i in 0..nbItems-1](weights[i] * x[i]);
    constraint knapsackWeight <= knapsackBound;

    // maximize value
    knapsackValue <- sum[i in 0..nbItems-1](prices[i] * x[i]);
    maximize knapsackValue;
}

Hexaly Modeler JSON module

The newly added JSON module allows the parsing of JSON data into HXM values. Reading the input data for a problem and exporting its solution afterward can be handy. Looking at our program, we can see that the model function requires some variables to be initialized before it can be executed. Specifically, the variables nbItems, weights, prices, and knapsackBound need to be set. We could take JSON data file of the form:

{
  "nbItems": 5,
  "weights": [5, 3, 2, 1, 3],
  "prices": [10, 9, 5, 6, 3],
  "knapsackBound": 10
}

This file can be converted to HXM values thanks to the parse method. The code below will correctly initialize the variables necessary for the model function.

use json;

function input() {
    data = json.parse("data.json");
    nbItems = data["nbItems"];
    weights = data["weights"];
    prices = data["prices"];
    knapsackBound = data["knapsackBound"];
}

After the problem has been solved, the dump method can be used to export the solution data.

function output() {
    out = {
        "value": knapsackValue.value,
        "decisions": map[i in 0..nbItems-1](x[i].value)
    };
    json.dump(out, "out.json");
}

For more information about the module and parsing options, look at its reference.

Hexaly Modeler API

The modeler API allows you to interact with the virtual machine powering the HXM language: developers with prototypes written in HXM will now fully integrate them in 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 as HXM functions.

Thus, integrating the knapsack HXM program in a Python environment is now possible. First, we need to instantiate the API’s main class, 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:

with HexalyModeler() as modeler:
    knapsack_module = modeler.load_module("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 run 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 a solver and execute the module by calling knapsack_module.run(). This method replicates the behavior we would get by executing the module from the command line, and we can pass down arguments like hxmTimeLimit.

solver = modeler.create_solver()
knapsack_module.run(solver, "hxmTimeLimit=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 Python API.
obj_value = obj_expression.value

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

Putting all this together

Below is an example of how an HXM model can be integrated into a Flask web app. It contains a single endpoint that takes JSON data as input, sets the correct variables in the HxmModule, and outputs the final objective value and decisions in JSON.

from flask import Flask, request, jsonify

app = Flask(__name__)

def create_map(modeler, data):
    map_ = modeler.create_map()
    for val in data:
        map_.append(val)
    return map_

@app.route("/", methods=["POST"])
def index():
    data = request.json
    with HexalyModeler() as modeler:
        module = modeler.load_module("knapsack.hxm")

        module["nbItems"] = data["nbItems"]
        module["knapsackBound"] = data["knapsackBound"]
        module["weights"] = create_map(modeler, data["weights"])
        module["prices"] = create_map(modeler, data["prices"])

        solver = modeler.create_solver()
        module.run(solver)

        return jsonify({
            "value": module["knapsackValue"].value,
            "decisions": [x_i.value for _, x_i in module["x"]]
        })

We are at your disposal to accompany you in the discovery of Hexaly. Just ask for your free trial license by registering here. In the meantime, don’t hesitate to contact us for any further information or support.