COPT Command-Line

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

Overview

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

Edit mode

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.

  • Basic commands

    1. <Insert>: Toggle between inserting characters and replacing the existing ones.

    2. <Esc>: Discard inputs and move the cursor to the beginning of line. Press <ESC> twice on Linux/Mac platform to do the same thing.

  • Moving around

    1. <Home>/<End>: Jump to the beginning/end of line.

    2. <Left>/<Right> Arrow: Move the cursor one character to the left/right.

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

    1. <Delete>: Cut the character under the cursor.

    2. <Backspace>: Cut the character before the cursor.

    3. <CTRL>+<H>: Cut from the cursor to the beginning of line.

    4. <CTRL>+<E>: Cut from the cursor to the end of line.

    5. <CTRL>+<Y>: Paste text in paste buffer at the cursor position.

    Each of cut operations defines cut direction: cut forward or cut backward. Obviously, <Delete> and <CTRL>+<E> cut forward; <Backspace> and <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.

  • Command history

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

    2. <CTRL>+<R> or <F8>: If you know what a previously executed line starts with, and you want to run it again, type prefix characters and then press <CTRL>+<R>, or <F8> on Windows platform, to iterate through the history of commands with matching prefix.

  • Tab completion

    Use <Tab> to complete shell commands, COPT paramters/attributes, or files under specified path. To cycle though multiple matches, just repeat pressing <Tab>.

    1. 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).

    2. Otherwise, press <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.

    3. For convenience, tab completion ignores case and support asterisk (*) as wildcard to match file and directory pattern.

    4. <Shift>+<Tab>: Complete the next one in an opposite direction.

Script mode

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 '-i'.

  • 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 ';', instead of '\n'. So inline scripts can be read by using arguments of the option '-c', or loaded on fly by specifying a quoted string, and special character '?' 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 command '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.

Shell commands

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_cmd exist. 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 'dir' or '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 '/home/user/'.

  • 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 reset is called.

    • Read, read an optimization model in format of mps successfully.

    • SetParam, set value of any COPT parameter successfully.

    • Optimize, shell command opt is called to solve current optimization model.

    _images/cmdline-state.png

    Fig. 10 Status of COPT command-line

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 'Optimize'.

  • optlp/optimizelp: Solve optimization model as LP model. This command requires no parameter and its interactive status is set to 'Optimize'.

  • iis: Compute IIS for the loaded model.

  • feasrelax: Do feasible relaxation for infeasible problem. Note that an optimization problem must exist before calling ‘feasrelax’. 'feasrelax' or '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 loaded model.

  • loadtuneparam: Loads the specified tuning results into the currently loaded 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 '.tune'.

  • readmps: Read optimization model in format of '.mps' or '.mps.gz' from file. Note this command does not require file type '.mps' or '.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 'Read'.

  • readlp: Read optimization model in format of '.lp' or '.lp.gz' from file. Note this command does not require file type '.lp' or '.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 'Read'.

  • readsdpa: Read an optimization problem in format of '.dat-s' or '.dat-s.gz' from file. Note that this command is similar to 'read' when the file type is '.dat-s' . However, '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' or '.cbf.gz' from a file. Note that this command is similar to 'read' when the file type is '.cbf' . However, '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' or '.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 'Read'.

  • 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 'Initial'.

  • 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 'SetParam'.

  • 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: '.mps', '.lp', '.bin', 'cbf', '.iis', '.relax', '.sol', '.bas', '.mst' and '.par'.

  • writemps: Output current optimization model to a file of type '.mps'. Note '.mps' is appended to the file name, if users do not add it.

  • writelp: Output current optimization model to a file of type '.lp'. Note '.lp' is appended to the file name, if users do not add it.

  • writecbf: Output problem to a file of type '.cbf'. Note '.cbf' is appended to the file name, if users do not add it.

  • writebin: Output current optimization model to a file of type '.bin'. Note '.bin' is appended to the file name, if users do not add it.

  • writeiis: Output computed IIS model to a file of type '.iis'. Note '.iis' is appended to the file name, if users do not add it.

  • writerelax: Output feasibility relaxation problem to a file of type '.relax'. Note '.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'. Note '.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'. Note '.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'. Note '.mst' is appended to the file name, if users do not add it.

  • writeparam: Output modified COPT parameters to a file of type '.par'. Note '.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.

Example Usage

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.

copt_cmd

If users are new to COPT command-line, always start with shell command 'help'.

Cardinal Optimizer v7.1.1. Build date Mar 04 2024
Copyright Cardinal Operations 2024. 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 'set', type '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:

Listing 1 diet.in
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:

copt_cmd -i diet.in

or executing shell command load on fly.

COPT> load diet.in