The Cardinal Optimizer ships with
copt_cmd executable on all supported
platforms, which let users solve optimization models in an interactive way.
Before running COPT command-line, please make sure that you have valid license
COPT command-line is a COPT API interpreter that executes commands read from the standard input or from a script file. COPT command-line interprets the following options when it is invoked:
-c: If the
'-c'option is present, it reads from an inline scripts, which is a quoted string and specified by the second argument.
-i: If the
'-i'option is present, it reads from an input script file, whose path is specified by the second argument.
-o: If the
'-o'option is present, it reads from standard input, while each valid command line is written to an output script file, whose path is specified by the second argument.
Regardless of arguments, the tool is interactive. Besides wrapping COPT API calls, it offers various features to help users move cursor around and edit lines. We try to provide as much user experience as standard command prompt (Windows console and Unix terminal).
This tool defines a number of commands to position the cursor, edit lines with combination keys on a standard keyboard. The following notes show you how to use the most important ones.
<Insert>: Toggle between inserting characters and replacing the existing ones.
<Esc>: Discard inputs and move the cursor to the beginning of line. Press
<ESC>twice on Linux/Mac platform to do the same thing.
<Home>/<End>: Jump to the beginning/end of line.
<Left>/<Right>Arrow: Move the cursor one character to the left/right.
<CTRL>+<Left>/<Right>Arrow: Move the cursor one word to the left/right.
Cut and Paste
An internal paste buffer is available for the following cut operations.
<Delete>: Cut the character under the cursor.
<Backspace>: Cut the character before the cursor.
<CTRL>+<H>: Cut from the cursor to the beginning of line.
<CTRL>+<E>: Cut from the cursor to the end of line.
<CTRL>+<Y>: Paste text in paste buffer at the cursor position.
Each of cut operations defines cut direction: cut forward or cut backward. Obviously,
<CTRL>+<H>cut backward. When two consecutive cut operations have the same cut direction, the cutting text is appended the paste buffer. Otherwise, the paste buffer is overwritten by the latest chopped text.
<Up>/<Down>: Move through the history of command lines in the older/newer direction. The tool remembers the history entry if the last executed line is in history.
<F8>: If you know what a previously executed line starts with, and you want to run it again, type prefix characters and then press
<F8>on Windows platform, to iterate through the history of commands with matching prefix.
<Tab>to complete shell commands, COPT paramters/attributes, or files under specified path. To cycle though multiple matches, just repeat pressing
If the cursor is over or right after the first word on the current command line, press
<Tab>to complete available shell commands with matching prefix (from the cursor to the first character of word).
<Tab>to complete COPT parameters/attributes, or file names under path with matching prefix. Specifically, if the prefix matches with COPT parameters as well as file under current working directory, only COPT parameters will be listed. In this case, to iterate file names, add relative path
'./'to start with.
For convenience, tab completion ignores case and support asterisk (
*) as wildcard to match file and directory pattern.
<Shift>+<Tab>: Complete the next one in an opposite direction.
There are two approaches to run scripts, a batch of commands, in COPT
command-line. One is to save scripts as a text file. The other is called
inline scripts, that is, a quoted string of commands separated by
Both of them can be loaded when COPT command-line is invoked, or loaded on fly
in the edit mode (see shell command
'load'). Below describes more details
about loading scripts as arguments.
This tool allows users to load a script file to do a batch job automatically.
As mentioned in Overview, a script file is read
when its file path is specified as arguments of the option
When reading a script file, COPT command-line double checks whether the first non-blank line starts with special text:
'#COPT script file'. This is to make sure users do not load an invalid script file by mistake. Indeed, only
'#COPT'is verified. In addition, any line in scripts is commented out if its first non-blank character is
After a script file is loaded, the tool keeps reading it as standard inputs, until reaching end of file or a special character
'?'. Here, we use question mark
'?'to pause scripts on purpose. To continue, users can type
'load'in command line. Afterwards, the tool picks whatever left in scripts and start to run from there, until reaching end of file or another question mark
'?'. Once current scripts finish, users can load any other script file on fly.
It also allows users to load special scripts, called inline scripts. The
only difference from a script file is that commands are separated by
'\n'. So inline scripts can be read by using arguments of the
'-c', or loaded on fly by specifying a quoted string, and special
'?' works in the same way.
In addition, this tool provides a feature of recording valid command lines
sequentially to a script file, if users specify an output script file as
argument of the option
'-o'. Here, valid command must use known shell
commands and do not exceed number of allowed parameters.
In particular, if users load a script file or inline scripts on fly, all
commands in scripts are written to the output script file. Note that
'load' itself is not written to output script file on purpose.
Because we’ve expanded and written all commands in scripts. On the other hand,
it may trigger infinity loop if the script file loaded is actually itself.
COPT command-line supports the following shell commands for users to manipulate optimization models. Moreover, shell commands are case-insensitive and support tab-completion.
General shell commands
The shell commands below are in support of interactions.
cd: This shell command works similar to DOS command
'cd'. That is, it changes current working directory, if its argument is valid relative or absolute path of a directory. Note that current working directory is the base directory for relative path and tab completion. It is initialized to current binary folder where
copt_cmdexist. Users can change it by shell command
'cd <dirpath>'. For example, if users change working directory to a folder having mps files, reading model becomes much easier because only filename is needed.
dir/ls: This shell command works similar to DOS command
'dir'or Bash command
'ls'. That is, it lists all files and directories under given relative or absolute path. To see files under current working directory, type
'ls'; To see files under parent folder, type
'dir ../'; To see files under home path, type
'dir ~/', etc. In addition, wildcard (
*) is supported as well. That is,
'dir net'lists all file names starting with
'net'under current working directory;
'dir /home/user/*.gz'lists all files of type of
'.gz'under path of
exit/quit: Leave COPT command-line.
help: It provides information on all shell commands. Typing
'help'followed by a shell command name gives you more details on shell commands. In particular, typing
'help'without arguments lists all shell commands with short descriptions. Right after overview of shell commands, the text
'help'with additional whitespace appear in the new prompt line. So users can directly type, or possibly
<Tab>complete, actual shell command to read more details.
load: Load a script file or inline scripts on fly and then execute a batch of commands. The syntax of
'load'command should be followed by either relative/absolute path of a script file, or quoted string of inline scripts. One special scenaio is when current script is paused, that is, hit question mark (
'?') during execution. In this case, type
'load'will continue the paused scripts. If users forgot having scripts in progress and try to load another scripts, it works as command
'load'and any additional argument is ignored. This behavior is back to normal after reaching the end of current scripts.
pwd: This shell command works similar to Bash command
'pwd'. That is, display current working directory to let users know where they are.
status: COPT command-line has a state machine on status of problem solving (see Fig. 10). This is used to guide users through steps. Typing
'status'shows you current interactive status. The status exposed to users are as follows:
Initial, initial status, either right after the tool is invoked, or shell command
Read, read an optimization model in format of mps successfully.
SetParam, set value of any COPT parameter successfully.
Optimize, shell command
optis called to solve current optimization model.
COPT shell commands
The shell commands below are related to COPT API calls.
display/get: Display current setting of any COPT parameter or attribute. Typing
'display'followed by COPT parameter or attribute name shows its current value. Typing
'display'only lists all COPT parameters and attributes with short descriptions. Right after overview of COPT parameters/attributes, the text
'display'with additional whitespace appear in the new prompt line. So users can directly type, or possibly
<Tab>complete, actual parameter/attribute name to see its current value.
opt/optimize: Solve optimization model and display results on screen. This command requires no parameter and its interactive status is set to
optlp/optimizelp: Solve optimization model as LP model. This command requires no parameter and its interactive status is set to
iis: Compute IIS for loaded model.
feasrelax: Do feasible relaxation for infeasible problem. Note that an optimization problem must exist before calling ‘feasrelax’.
'feasrelax all'means to relax all bounds of variables and constraints with penalty 1, while
'feasrelax vars'means to only relax bounds of variables with penalty 1, and
'feasrelax cons'means to only relax bounds of constraints with penalty 1.
tune: Tuning parameter automatically of the read-in model.
loadtuneparam: Loads the specified tuning results into the currently read-in model. The calling command is
'loadtuneparam idx', where
'idx'is the specified tuning result’s number. Use the command
'get TuneResults'to get the number of tuning results obtained after the current tuning.
read: Read optimization model, MIP solution, LP basis, MIP initial solution and COPT parametes from file under given relative/absolute path. It supports files including optimization problem file of type
'.mps'and compressed format
'.mps.gz', problem file of type
'.lp'and compressed format
'.lp.gz', problem file of type
'.dat-s'and compressed format
'.dat-s.gz', problem file of type
'.cbf'and compressed format
'.cbf.gz', problem file of type
'.bin'and compressed format
'.bin.gz', basis file of type
'.bas', solution file of type
'.sol', MIP initial solution file of type
'.mst', parameter file of type
'.par'and tuning file of type
readmps: Read optimization model in format of
'.mps.gz'from file. Note this command does not require file type
'.mps.gz'. That is, it is fine to have content in format of MPS, regardless of its file name. In addtion, the interactive status is set to
readlp: Read optimization model in format of
'.lp.gz'from file. Note this command does not require file type
'.lp.gz'. That is, it is fine to have content in format of LP, regardless of its file name. In addtion, the interactive status is set to
readsdpa: Read an optimization problem in format of
'.dat-s.gz'from file. Note that this command is similar to
'read'when the file type is
'readsdpa'does not require the file has type
'.dat-s'. It parses the file as SDPA format, no matter what file type it is.
readcbf: Read an optimization problem in format of
'.cbf.gz'from a file. Note that this command is similar to
'read'when the file type is
'readcbf'does not require the file has type
'.cbf'. It parses the file as CBF format, no matter what file type it is.
readbin: Read optimization model in format of
'.bin.gz'from file. Note this command does not require file type
'.bin'. That is, it is fine to have content in format of COPT binary format, regardless of its file name. In addtion, the interactive status is set to
readsol: Read MIP solution from file. Note this command does not require file type of
'.sol'. That is, it is fine to have content of solution, regardless of its file name.
readbasis: Read optimal basis from file. Note this command does not require file type of
'.bas'. That is, it is fine to have content of basis, regardless of its file name.
readmst: Read MIP initial solution from file. Note this command does not require file type of
'.mst'. That is, it is fine to have content of solution, regardless of its file name.
readparam: Read COPT parameters from file and set corresponding values. Note this command does not require file type of
'.par'. That is, it is fine to have content of COPT parameters, regardless of its file name.
readtune: Read the parameter file under the given relative or absolute path. Note this command does not require file type of
'.tune'. That is, it is fine that the file conforms to the COPT parameter tuning file format, regardless of its file name.
reset: Reset current optimization model and all parameters/attributes to defaults. In addtion, the interactive status is set to
set: Set value of any COPT parameter. The syntax of this command should be
'set', followed by COPT parameter name and an integer/double number. Moreover, Typing
'set'only lists all COPT parameters with short descriptions. Right after overview of COPT parameters, the text
'set'with additional whitespace appears in the new prompt line. So users can directly type, or possibly
<Tab>complete, actual parameter name to complete as partial command. If so, its current value, default value, min value, max value of given COPT parameter are displayed on screen. Now users know how to add correct value to complete the full command of
'set'. One tip of saving typing here is to get last history entry by pressing
<Up>. At last, the interactive status is set to
write: Output MPS/LP/CBF format model, COPT binary format model, IIS model, FeasRelax model, LP/MIP solution, optimal basis, settings of modified COPT parameters to file under given relative/absolution path. This command detects file types. For an instance,
'write diet.sol'outputs LP solution to file
'diet.sol'. An error message will be shown to users if file type do not match. Supported file types are:
writemps: Output current optimization model to a file of type
'.mps'is appended to the file name, if users do not add it.
writelp: Output current optimization model to a file of type
'.lp'is appended to the file name, if users do not add it.
writecbf: Output problem to a file of type
'.cbf'is appended to the file name, if users do not add it.
writebin: Output current optimization model to a file of type
'.bin'is appended to the file name, if users do not add it.
writeiis: Output computed IIS model to a file of type
'.iis'is appended to the file name, if users do not add it.
writerelax: Output feasibility relaxation problem to a file of type
'.relax'is appended to the file name, if users do not add it.
writesol: Output LP solution of problem to a file of type
'.sol'is appended to the file name, if users do not add it.
writepoolsol: For the current problem, save the solution with the specified number in the solution pool to the result file under the given relative or absolute path. If the file extension is not``’.sol’`` , the suffix
'.sol'is automatically added. The calling command is
'writepoolsol idx pool_idx.sol', where
'idx'is the specified solution number in solution pool. Use the command
'get PoolSols'to get the current number of solution pool results.
writebasis: Output optimal basis to a file of type
'.bas'is appended to the file name, if users do not add it.
writemst: Output current best MIP solution to a file of type
'.mst'is appended to the file name, if users do not add it.
writeparam: Output modified COPT parameters to a file of type
'.par'is appended to the file name, if users do not add it.
writetuneparam: Save the specified tuning result to the parameter setting file under the given relative or absolute path. The calling command is
'writetuneparam idx tune_idx.par', where
'idx'is the specified tuning result number. Use the command
'get TuneResults'to get the number of tuning results obtained after the current tuning.
This section shows how to use COPT command-line to interactively solve a well-known problem, called “Diet Problem”. Please refer to AMPL Interface - Example Usage for problem description in more detail.
With valid license, COPT command-line should run as follows, after entering
copt_cmd in command prompt.
If users are new to COPT command-line, always start with shell command
Cardinal Optimizer v6.5.9. Build date Mar 22 2023 Copyright Cardinal Operations 2023. All Rights Reserved COPT>
Suppose diet model has mps format and exits in the current working directory. In this way, we just type its file name to read, without worrying about its path.
COPT> read diet.mps Reading from '/home/username/copt/diet.mps' Reading finished (0.00s)
Before solving it, users are free to tune any COPT parameter. Below
is an example to set value of double parameter
TimeLimit to 10s.
If users are not familiar with COPT parameters, just type
'set' to list
all public COPT paramters and attributes with short description. Furthermore,
'set' with parameter name, for example
'set TimeLimit', displays its
current value, default value, min value and max value of the given parameter.
COPT> set timelimit 10 Setting parameter 'TimeLimit' to 10
After tuning parameters, it is time to solve the model. The messages during problem solving are shown as follows.
COPT> opt Model fingerprint: 129c032d Hardware has 4 cores and 8 threads. Using instruction set X86_NATIVE (1) Minimizing an LP problem The original problem has: 4 rows, 8 columns and 31 non-zero elements The presolved problem has: 4 rows, 8 columns and 31 non-zero elements Starting the simplex solver using up to 8 threads Method Iteration Objective Primal.NInf Dual.NInf Time Dual 0 0.0000000000e+00 4 0 0.01s Dual 1 8.8201991646e+01 0 0 0.01s Postsolving Dual 1 8.8200000000e+01 0 0 0.01s Solving finished Status: Optimal Objective: 8.8200000000e+01 Iterations: 1 Time: 0.01s
After solving the model, users might check results by using shell command
'get' with a parameter name. Note that, similar to
'get' to list all public parameters and attributes. In particular,
'get all' shows all parameters/attributes and their current value.
COPT> get TimeLimit DblParam: [Current] 10s COPT> get LpObjval DblAttr: [Current] 88.2 COPT> get LpStatus IntAttr: [Current] 1 optimal
Before leaving COPT command-line, users might output the model in format of mps, optimal basis, modified parameters, or LP solution to files. Below is an example to write LP solution to current directory.
COPT> writesol diet Writing solutions to /home/username/copt/diet.sol COPT> quit Leaving COPT...
Below is the script file
diet.in by putting everything together,
see Listing 1:
1#COPT script-in file 2 3read diet.mps 4set timelimit 10 5opt 6writesol diet 7quit
which is loaded by using the option
'-i' when starting
copt_cmd -i diet.in
or executing shell command
load on fly.
COPT> load diet.in