Configure Commands

Introduction

After connecting your optimization server to PIFOP for the first time (see Hosting an Optimization Server), you have to configure the commands supported by your server. What solvers do you support? For instance, if you want your server to be able to run the AMPL processor, you have to configure an ampl command.

Your optimization server can support multiple commands: ampl, gams, oplrun and whatever other command line solver/interpreter you like. All commands are configured in the same way, which we explain below.

Adding a new command

Your optimization server looks at the configuration file config.json to know what commands it supports. The configuration file needs "commands" entry with a list of command configurations (a JSON array of objects).

A basic command configuration has at least two fields: a "name" and "executable". For instance, if you want to support ampl, your configuration should look like this: 

{
    "server-name" : "My Server",
    "commands" : [
        {
            "name"       : "ampl",
            "executable" : "/path/to/ampl"
        }
    ]
}

The command "name" is what the users type into the PIFOP terminal in order to execute the command. The "executable" is the path to the executable that is invoked by that command.

TIP: It is a good practice to make a command's "name" match the executable's name. That way you make it clear to the users of your optimization server what program they are actually running with that command.

Often times, this is all the configuration you need for a command to work. Save the file, restart your optimization server and try to use the command in a PIFOP project.

Support multiple commands

You can configure multiple commands supported by your optimization server. Just add the new command to the "commands" list of your config.json file. For instance, if aside from ampl you also want to support gams in your optimization server, this is how your configuration file should look like (don't forget the comma , between the command configurations): 

{
    "server-name" : "My Server",
    "commands" : [
        {
            "name"       : "ampl",
            "executable" : "/path/to/ampl"
        },
        {
            "name"       : "gams",
            "executable" : "/path/to/gams"
        }
    ]
}

Command Properties

Aside from the required "name" and "executable" properties, there are also optional ones that can be set. The complete list of properties is displayed below.

PROPERTY TYPE DESCRIPTION "name" string Name of the optimization server. This is what appears to the users in the optimization server selector at the PIFOP IDE. "executable" string Path to the executable that is invoked when the command is executed. "append-options" string String that is appended to every call of that command. For instance, if an user of the optimization server enters the command line gams model.gams and this property is set to "execMode=4", the command line that is actually invoked is this: gams model.gams execMode=4 "preprend-options" string String that is inserted immediatelly after the command name. For instance, if an user of the optimization server enters the command line ampl model.mod and this property is set to "-R", the command line that is actually invoked is this: ampl -R model.mod "mount-paths" array of string List of paths that should be mounted into the sandbox of the spawned process. Use it to make files and directories readable (but not writeable) by the process. Each entry should follow the pattern "/original/path:/path/within/sandbox". The :/path/within/sandbox part is not required. If ommited, the path within the sandbox will be the same as the original one. "environment-variables" array of string List of environment variables that should be set upon running the command. Each string entry should be an environment variable assignment following the pattern "VAR_NAME=value". For instance, if you want to set the PATH environment variable, the "environment-variables" array should contain an entry like this: "PATH=/my/first/path:/my/second/path" "mount-dependencies" string String indicating how executable dependencies should be mounted into the sandbox. It can be one of these: "DIRECTORIES", "FILES" or "DISABLED". "DIRECTORIES" is the default, and means that the Opt-Server will mount the directories in which the shared library dependencies of the executable live. "FILES" is more restrictive and means that the Opt-Server will mount only the specific shared library dependency files that the executable depends on. "DISABLED" means that the Opt-Server will not mount any executable dependency automatically, so you are expected to mount them yourself using the "mount-paths" property.
© PIFOP Solutions