Hexaly Modeler¶

Create a module

First, you have to create a HexalyModeler environment. It is the main class of the Modeler library and allows you to create a module in one of two ways:

• You can load a module from an existing HXM file with the method HexalyModeler::loadModule().
• Or you can create an empty module with the method HexalyModeler::createModule().

Both of these methods return an instance of HxmModule which will enable you to interact with the module’s variables and functions.

Launch a module

There are two launch modes for a module:

• Optimization mode: This is the classic and default mode for the modeler. At the very least, you must implement a model method in your module that will build an HxModel. You can then call HxmModule::run() to start the execution of the module. This function takes as first argument a Hexaly Optimizer instance that you have to create beforehand using the HexalyModeler::createOptimizer() method. After the Hexaly Optimizer model has been built, the resolution process will be started automatically.

  Note that the run method also accepts as a parameter a list of arguments that will be passed as global variables to your module:

  HexalyModeler modeler;
  HexalyOptimizer hx = modeler.createOptimizer();
  HxmModule module = modeler.loadModule("module_name", "my_file.hxm");
  module.run(hx, {"hxIterationLimit=100", "hxTimeLimit=10"});
  

• Main mode: In this mode, the modeler behaves like a classical programming language. To use this mode, you have to implement a function named main in which you are free to do anything you want without being limited by the formalism of the functions input, model, param, display and output. You can then call HxmModule::runMain() to start the execution of the module.

  Note that unlike the optimization mode, it is your responsibility to manually create the optimizer instances, close your models and launch the resolutions. In return, you are free to run several successive resolutions or none at all if you just want to use Hexaly Modeler for its pure programming features.

For more details on the differences between the optimization and the main mode, read Main Mode.

Interacting with variables

You can interact with the variables inside a module thanks to getters and setters on the HxmModule class. Values can be obtained in their native type or retrieved as HxmValue which is a container that can hold any type of value inside a module. For more information on value types available in the modeler you can look at HxmType.

You can create maps from the modeler instance with HexalyModeler::createMap(). A Map is a data structure holding (key, value) pairs that can also be used as an array. For more information on maps you can look at the map module.

Using external functions

You can expose your own C++ functions to Hexaly Modeler and turns them into Hexaly functions thanks to the method HexalyModeler::createFunction(). First you have to extend the HxmFunctor class and implement the call() function:

class MyHxmFunction : public HxmFunctor {
    HxmValue call(HexalyModeler& modeler, const std::vector<HxmValue>& arguments) {
        hxdouble result = arguments[0].asDouble() + arguments[1].asDouble();
        return modeler.createDouble(result);
    }
}

MyHxmFunction myFunc;
HxmFunction hxmFunc = modeler.createFunction(&myFunc);
HxmValue args[2] = {modeler.createDouble(1.5), modeler.createDouble(2.3)};
HxmValue result = hxmFunc.call(args, 2);
std::cout << "result = " << result.asDouble() << std::endl; // prints "result = 3.8"

In the snippet above we declare a C++ function that takes two doubles as input, adds them together and returns the result. We can then call the function with HxmFunction::call() to execute the function and retrieve the result.

You can also assign the function to a variable in a module with HxmModule::setFunction(). After doing so, the function will be callable within any function of the module.