healresearch/heuristiclab-json-cli repository overview

⁠HeuristicLab JSON Command Line Interface (HL JSON CLI)

The HeuristicLab JSON command line interface is a new type of application for HeuristicLab. The intended use is the execution of configurable tasks on a command line interface (CLI). We use JSON files to define such tasks.

⁠Supported tags and respective Dockerfile links

• latest
• 0.3

⁠Quick reference

• Maintained by: HEAL⁠
• Download and Documentation of the standalone version: HeuristicLab⁠
• Build on top of: mono⁠

⁠Usage

Step - 1: Prepare your template⁠ and configuration⁠ file.

Step - 2: Run the container with the following command:

docker run --rm -it -v <path-to-template-and-config-files>:/files healresearch/heuristiclab-json-cli:latest /files/<template>.json /files/<config>.json /files/<out>.json

• Replace <path-to-template-and-config-files> with the path of the folder which contains the template (with the linked .hl-file) and configuration files.
• Replace <template> with your template JSON file.
• Replace <config> with your configuration JSON file.
• Replace <out> with a desired output JSON file (this file is overwritten if it already exists).

This command starts the execution of the template file with the desired configuration, and saves the generated results into the <out>.json file.

NOTE: The algorithm saves the results of finished runs continuously, this can cause the creation of output files while the algorithm is still running.

⁠Create a template

Step - 1 Checkout the GitHub-Branch⁠ and build the solution files HeuristicLab.ExtLibs.sln and HeuristicLab 3.3.sln. After the build process, the binaries are located in the folder bin.

Step - 2: Start HeuristicLab with the application Optimizer and configure the desired problem/algorithm combination.

Step - 3: Navigate to: File -> Export -> Json-Template to open the JSON template export dialog.

Step - 4: The first tab Parameters lists every configurable parameter. Each selected parameter is saved in the template and is dynamically changeable with a configuration later on. All other (unselected) parameters are fixed and cannot be modified with a configuration file.

Step - 5 (optional): In the second tab Result Collection Modifiers, it is possible to configure modifiers/filters for the result collection. These modifications are an automatic way to alter the result collection after the algorithm run has completed. The configuration for these modifiers is fixed for a template and cannot be changed later on.

Step - 6: Set a name for the template and save it to the desired destination. This generates two files (e.g. Template.json and Template.hl), both of them represent the template. It is possible to move those files into different folders, but you need to adapt the property HLFileLocation in the JSON file.

⁠Create a configuration

Step - 1: Create a new JSON file, e.g. Config.json.

Step - 2: The content of Config.json is an array of JSON objects. Copy all desired Parameters of the template JSON file into your configuration file and adapt the values to fit your needs. The following code shows an exemplary content of Config.json:

[
  {
    "Name": "PopulationSize",
    "Description": "The size of the population of solutions.",
    "Path": "Genetic Algorithm (GA).Parameters.PopulationSize",
    "Value": 250
  },
  {
    "Name": "MutationProbability",
    "Description": "The probability that the mutation operator is applied on a solution.",
    "Path": "Genetic Algorithm (GA).Parameters.MutationProbability",
    "Value": 0.35
  }
]

This example shows the dynamic change of the properties PopulationSize to 250 and MutationProbability to 0.35.

NOTE - A: Every parameter needs to be part of the list Parameters of the template JSON file.

NOTE - B: The property Path is necessary to be able to assign it with the associated object in HeuristicLab (works like a unique identifier). Everything else should be optional.

⁠License

HeuristicLab is licensed under the GNU GPL v3⁠. More information can be found here⁠.

As with all Docker images, these likely also contain other software which may be under other licenses (such as Bash, etc. from the base distribution, along with any direct or indirect dependencies of the primary software being contained).

As for any pre-built image usage, it is the image user's responsibility to ensure that any use of this image complies with any relevant licenses for all software contained within.