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.
"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.