Quick tour of Hexaly Modeler

Hexaly Modeler is Hexaly’s built-in modeling and programming language. The programs are written in HXM files (.hxm extension). This page presents the main specificities of Hexaly Modeler’s programming style. For more details, we encourage you to read the full documentation for Hexaly Modeler.

Structure of an HXM file

HXM files are structured around five predefined functions: input(), model(), param(), display(), and output(). These functions, called in this order, induce the flow of the program launched by the Hexaly executable:

  • input: for declaring your data or reading it from files.

  • model: for declaring your optimization model.

  • param: for parameterizing the solver before running.

  • display: for displaying some information in console or in some files during the resolution.

  • output: for writing results in console or in some files once the resolution is finished.

Loops and iterated assignments

Ranges and loops

A range is declared using the ... operator: the syntax a...b represents a range from a (included) to b (excluded). Iterating over a range in a for loop is done using the following syntax:

for [i in a...b] {
    // iterate over [a, b-1]
}

Nested loops

Nested for loops can be written on a single line. For example:

for [i in 0...m][j in 0...n] {
    // do something...
}

is a more compact equivalent of:

for [i in 0...m] {
    for [j in 0...n] {
        // do something...
    }
}

Iterated assignments and n-ary operators

To help make models shorter and clearer, Hexaly Modeler enables “iterated assignments”. Iterated assignments can be nested. For example, the syntax:

x[i in 0...n] = myFunction(i);
y[i in 0...m][j in 0...n] = i + j;

is a more compact equivalent to:

for [i in 0...n]
    x[i] = myFunction(i);
for [i in 0...m][j in 0...n]
    y[i][j] = i + j;

A similar syntax is used to apply n-ary operators. For example, computing the sum of n terms is done by writing:

totalWeight = sum[i in 0...n](weight[i]);

The “model” function

Expression assignments

While constant terms are assigned using the = operator, another operator is used to assign modeling expressions. Indeed, the decision variables and intermediate expressions, whose values can vary during the search, are declared in the “model” function using the <- operator. Iterated assignments and nested iterated assignments are also allowed for declaring modeling expressions. For example:

x[i in 0...nbItems] <- bool();
totalWeight <- sum[i in 0...nbItems](x[i] * weight[i]);

Decision variables

Decision variables are defined using the bool, int, float, set, list, and interval functions:

x[i in 0...n] <- bool();
quantity[i in 0...n] <- float(ub, lb);

Intermediate expressions

Intermediate expressions are defined from decisions variables, or from other intermediate expressions:

totalWeight <- sum[i in 0...n](x[i] * weight[i]);
capacityRespected <- totalWeight <= capacity;

Constraints

Constraints are defined using the constraint keyword:

constraint totalWeight <= capacity;
constraint capacityRespected;

Objectives

Objective functions are defined using the minimize and maximize keywords:

minimize totalCost;
maximize totalGain;

If several objective functions are declared, they are optimized lexicographically, by order of appearance in the model.

Retrieving the solution value

It is possible to display useful information throughout the search (in the “display” function) or at the end of the search (in the “output” function). The current value of a decision variable or intermediate expression (its value in the best solution found so far) can be retrieved using the value attribute. Displaying information in the console is done using the print and println functions:

println("Total weight = ", totalWeight.value);

Passing arguments from the command line

An HXM file is executed with the following command in a terminal:

$ hexaly file.hxm [arguments]

Each argument will be available in the Hexaly Modeler progam as a global variable. They can be built-in global variables, such as hxTimeLimit, which defines the maximum time limit after which the solver must stop. You can also define your own global variables. For example, you can define a global variable named inFileName, corresponding to the path of your input file:

$ hexaly file.hxm inFileName=instances/instance_1.txt hxTimeLimit=10