COPT交互式命令行工具

COPT交互式命令行工具 copt_cmd 是一个由杉数求解器提供的，与Windows、Linux和MacOS下 终端无缝连接的、可以直接调用杉数求解器编程接口进行模型求解与分析的工具。使用该工具前， 请用户确保已正确安装杉数求解器，并成功配置授权文档。

概述

简单来说，COPT交互式命令行工具是一个对从终端输入或脚本读入的命令行进行解释并执行的程序。 它调用相应的杉数求解器编程接口进行求解与分析，并提供了以下启动参数：

  • -c: 该选项读取并执行指定的内联脚本内容。注意，内联脚本需要带双引号。

  • -i: 该选项读取并执行指定的脚本文件。

  • -o: 该选项提供了脚本录制功能。任何在“交互模式”下“执行正确”的命令都会输出到指定的脚本 文件中，文件后缀无特殊要求。

若不提供任何启动参数，则进入“交互模式”。在操作上，该工具目前支持多种键盘功能键、组合键和自定义键， 以尽量满足用户的便捷使用需求，达到类似系统终端的使用体验。

交互模式

命令行工具定义了一些命令和功能键以方便用户进行快速光标定位，也定义了一些组合键 以方便用户编辑命令行。目前这些定义是基于标准键盘的，而不是MAC键盘。 下面对具体功能进行介绍。

  • 基本命令

    1. <Insert>: 切换“插入”和“覆盖”模式。

    2. <Esc>: 取消当前行的所有输入，且光标回到起始位置，等待输入。Linux和MacOS下使用需 连续按两次 <Esc> 。

  • 光标定位

    1. <Home>/<End>: 光标跳转到输入行首/尾后，等待输入。

    2. <Left>/<Right> 方向键: 光标前/后移动一个字符，等待输入。

    3. <CTRL>+<Left>/<Right> 方向键: 光标跳转到前一个单词和后一个单词，等待输入。

  • 简单的剪切和粘贴

    以下剪切操作需要用到内部用来粘贴的缓存。

    1. <Delete>: 剪切当前光标下字符，并缓存留待后续粘贴操作。

    2. <Backspace>: 剪切当前光标前一位字符，并缓存留待后续粘贴操作。

    3. <CTRL>+<H>: 剪切当前光标至行首的所有字符，并缓存留待后续粘贴操作。

    4. <CTRL>+<E>: 剪切当前光标至行尾的所有字符，并缓存留待后续粘贴操作。

    5. <CTRL>+<Y>: 粘贴当前缓存中的剪切内容。

    每个剪切操作都定义了一个剪切方向，即向前剪切或者向后剪切。显然，<Delete> 和 <CTRL>+<H> 属于向前剪切；<Backspace> 和 <CTRL>+<E> 属于向后剪切。如果 当前剪切操作的方向和前一个剪切操作的方向一致，剪切部分会追加到粘贴缓存尾部，否者则覆盖 原来的缓存内容。

  • 命令行历史记录

    1. <Up>/<Down>: 相对于当前位置，显示上一个或下一个历史命令。如果上一次执行命令是已有的 历史记录，当前位置为该历史记录所在条目，否则当前位置为最近执行的命令。

    2. <CTRL>+<R> 或 <F8>: 如果用户在已知命令前缀的情形下调用历史记录，则可以通过 前缀遍历匹配的历史记录进行查找。即首先输入命令前缀，然后按 <CTRL>+<R> 组合键，或者 Windows系统下标准键盘的 <F8> 键，遍历所有匹配前缀的历史记录。

  • Tab补全功能

    以当前光标位置的前一个字符到光标所在单词的字首作为前缀，可以补全交互式工具命令、COPT参数名或 属性名、当前或指定路径所在的文件和文件夹。如果有多个匹配结果，重复按 <Tab> 以遍历所有匹配。

    1. 补全功能会根据光标所在位置进行简单识别，在两种情形下，补全工具命令名。一种情形是当前光标 位于命令行的第一个单词，另一种情形是使用 help 命令查阅命令的基本介绍。

    2. 其余情形下，根据匹配前缀补全COPT参数名或属性名、当前或指定路径所在的文件和文件夹。特别地， 如果用户输入的前缀同时匹配当前工作路径下的某个文件名和某个COPT参数名或属性名，则按COPT参数名 或属性名进行补全。若用户需要补全文件名，可通过添加 './' 前缀，再用 <Tab> 补全， 避免优先补全COPT参数名或属性名。

    3. 易用性方面，工具支持补全的前缀检验忽略大小写，也支持以字符(*)作为通配符筛选文件和 文件夹。例如：命令 'set t<Tab>' ，补全为 'set TimeLimit' 。命令 'read ~/*.gz<Tab>' ，补全为用户目录下所有以 '.gz' 为后缀的文件名。

    4. <Shift>+<Tab>: 补全到前一个匹配，和 <Tab> 方向相反。

脚本模式

命令行工具的脚本模式主要有两种形式：一是脚本文件，二是带双引号的内联脚本，即以 ';' 分隔的命令行组成的文本。这两种脚本都可以在启动交互式工具时，使用参数选项进行加载，也可以在 交互模式下随时加载。下面介绍如何加载脚本文件。

前文概述中，我们介绍了在启动工具时，使用选项 '-i' 可以加载指定脚本文件，下面进一步阐述 相关细节。

  • 加载脚本文件时，除了检查指定文件是否打开成功，还会检查文件内容中首个非空行是否以 '#COPT script file' 起始，以避免执行无关的文件。事实上，工具仅检查以否以 '#COPT' 起始。任意首个非空格字符为 '#' 的中间行都会被忽略，一般用于添加注释。

  • 加载脚本文件成功后，会逐条执行脚本中的命令，直到文件结尾，或者读到字符 '?' 。工具以字符 '?' 表示暂停脚本执行。如果用户需要继续执行，可以通过手动输入命令 load 继续执行 当前脚本，直到文件结尾或者下一个 '?' 。只有在当前脚本中命令全部执行后（有提示），才可以 加载其它脚本文件。

工具支持加载一种特殊的脚本，即带引号的内联脚本。内联脚本与脚本文件的区别是两者的命令行分隔符 分别是 ';' 和 '\n' 。对于内联脚本，可以在启动时使用选项 '-c' 指定的方式加载， 也可以在交互模式下使用命令 load 随时加载，字符 '?' 仍表示暂停脚本执行。

用户还可以通过选项 '-o' 指定脚本输出文件，用于记录用户在交互模式下的所有“执行正确”的命令行。 其中，“正确”是指命令行使用的是已知的工具命令，且命令语法使用正确。

特别地，load 命令本身不被写入输出脚本。由于被加载脚本的具体内容会在执行过程中展开， 并写入到输出脚本，不写入 load 命令可以避免可能的脚本执行死循环。

工具命令

COPT交互式命令行工具目前支持以下命令，方便用户求解与分析优化模型。所有命令均大小写无关，并支持 <Tab> 补全。

普通工具命令

普通工具命令提供了命令帮助说明查阅、脚本加载等通用功能，不直接调用杉数求解器编程接口进行操作， 包括以下命令：

  • cd: 类似DOS命令 'cd' ，该命令改变 '当前工作目录' 。这里要求其参数是一个有效的目录路径， 可以是相对目录路径，也可以是绝对目录路径。注意下面工具命令中用到的相对路径或路径补全功能都 是基于当前工作目录的。其初始值设为 copt_cmd 所在的目录，之后用户可以通过命令 cd <dirpath> 来改变工作路径。例如，如果用户把当前工作目录设为求解问题模型所在目录，那 么读取模型就变得很简洁，只需要模型文件名即可。

  • dir/ls: 类似DOS命令 dir 和Bash命令 ls ，该命令列出给定的相对或绝对路径下的所有文件 和文件夹。设计该命令是为了方便用户定位待求解的模型文件、脚本文件等。例如：使用 dir 命令 或者 ls 命令列出当前工作目录下的所有文件和文件夹；使用 'dir ../' 列出 上一层目录下的所有文件和文件夹；使用 'dir ~/' 列出用户目录下的所有文件和文件夹。

    该命令还支持使用通配符(*)筛选出符合条件的文件和文件夹。例如：使用 'dir ~/net' 命令， 列出用户目录下所有前缀为 'net' 的文件；使用 'dir d:/problems/*.mps.gz' 命令， 列出 'd:/problems' 目录下的所有后缀为 '.mps.gz' 的模型文件。

  • exit/quit: 退出COPT命令行模式。

  • help: 提供COPT命令的使用说明。查阅单个命令的详细使用说明，需要在 help 命令后指定COPT命令名称， 例如：使用 'help display' 命令，查看 display 命令的使用说明。特别地，对于不带 参数的 help 命令调用，将列出所有COPT命令以及对应的简单说明，方便用户查看，并在新的提示符 所在行，自动加上 help 命令调用，用户只需补充待查询的COPT命令名即可。输入COPT命令时， 可以 <Tab> 补全，且不区分大小写。

  • load: 读入给定路径下的脚本文件或者带引号的内联脚本，执行直到文件结尾或暂停字符 '?' 。暂停后， 如果继续输入 load 命令，无论是否带参数（实际上任何参数都会被忽略），均继续执行被暂停的 脚本。之前加载的脚本执行完成后，才可以加载其它脚本。

  • pwd: 类似Bash命令 'pwd' ，该命令显示当前工作目录，可以让用户查看目前在什么位置。

  • status: 交互工具通过状态机表示交互过程中的状态(参看 图 10)。 其一是为了避免用户的误操作，同时也可以提示用户下一步 可进行的操作。输入 status 命令返回交互工具当前的状态，分为以下几种：

    1. Initial ：未读取模型，可能在工具刚启动时，或者用户调用 reset 命令后。

    2. Read ：成功读取给定模型文件。

    3. SetParam ：用户通过 set 命令成功设置了求解参数。

    4. Optimize ：用户调用 optimize/optimizelp 等求解命令求解模型。

    _images/cmdline-state.png

    图 10 命令行工具的内部状态

COPT工具命令

COPT工具命令是求解与分析优化模型的核心命令集，它直接调用杉数求解器编程接口进行相关操作， 包括以下命令：

  • display/get: 获取给定的参数或属性的当前值。特别地，对于不带参数名的调用，会列出目前所有支持的参数和属性名称， 方便不熟悉COPT参数和属性名的用户查看其所需的信息，并在新的提示符所在行，自动添加 display 命令调用，用户只需补充待查询的参数或属性名即可。在输入参数或属性名称时，支持 <Tab> 补全， 且不区分大小写，自动补全显示的名字是标准形式。例如：使用 'get so<Tab>' 命令，补全后的命令 是 'get SolvingTime'。

  • opt/optimize: 求解已读入的模型，并将工具状态置为 'Optimize'。

  • optlp/optimizelp: 将已读入的模型当成LP问题求解，并将工具状态置为 'Optimize'。

  • iis: 计算已读入模型的IIS。

  • feasrelax: 计算已读入模型的可行化松弛。其中， 'feasrelax' 或 'feasrelax all' 表示松弛模型中 所有的变量和约束，则惩罚因子均为1； 'feasrelax vars' 表示仅松弛模型中变量的上下界， 且惩罚因子均为1； 'feasrelax cons' 表示仅松弛模型中约束的上下界，且惩罚因子均为1。

  • tune: 对已读入模型进行自动参数调优。

  • loadtuneparam: 加载指定的调优结果到当前已读入模型。调用命令为 'loadtuneparam idx'，其中 'idx' 为指定的调优结果编号。通过命令 'get TuneResults' 获取当前调优后获取的调优结果数目。

  • read: 读取给定的相对或绝对路径下的模型文件、结果文件、基文件、初始解文件和参数设置文件。目前支持 '.mps' 、 '.mps.gz' 、 '.lp' 和 '.lp.gz' 、 '.dat-s' 和 '.dat-s.gz' 、 '.cbf' 和 '.cbf.gz' 、 '.bin' 和 '.bin.gz' 模型文件格式； 以 '.sol' 为后缀的结果文件；以 '.bas' 为后缀的基解文件； 以 '.mst' 为后缀的初始解文件；以 '.par' 为后缀的参数设置文件； 以 '.tune' 为后缀的调参文件。 若文件类型不匹配，则报告相应错误信息。

  • readmps: 读取给定的相对或绝对路径下的模型文件。该命令不要求待读取的文件后缀为 '.mps' 或 '.mps.gz' ，只要文件本身符合MPS格式即可。命令调用完成后将工具状态置为 'Read' 。

  • readlp: 读取给定的相对或绝对路径下的模型文件。该命令不要求待读取的文件后缀为 '.lp' 或 '.lp.gz' ，只要文件本身符合LP格式即可。命令调用完成后将工具状态置为 'Read' 。

  • readsdpa: 读取给定的相对或绝对路径下的模型文件。该命令不要求待读取的文件后缀为 '.dat-s' 或 '.dat-s.gz' ，只要文件本身符合SDPA格式即可。命令调用完成后将工具状态置为 'Read' 。

  • readcbf: 读取给定的相对或绝对路径下的模型文件。该命令不要求待读取的文件后缀为 '.cbf' 或 '.cbf.gz' ，只要文件本身符合CBF格式即可。命令调用完成后将工具状态置为 'Read' 。

  • readbin: 读取给定的相对或绝对路径下的模型文件。该命令不要求待读取的文件后缀为 '.bin' 或 '.bin.gz' ，只要文件本身符合COPT二进制格式即可。命令调用完成后工具状态置为 'Read' 。

  • readsol: 读取给定的相对或绝对路径下的结果文件。该命令不要求待读取的文件后缀为 '.sol' ， 只要文件本身符合COPT的结果文件格式即可。

  • readbasis: 读取给定的相对或绝对路径下的基解文件。该命令不要求待读取的文件后缀为 '.bas' ， 只要文件本身符合COPT的基解文件格式即可。

  • readmst: 读取给定的相对或绝对路径下的初始解文件。该命令不要求待读取的文件后缀为 '.mst' ， 只要文件本身符合COPT的初始解文件格式即可。

  • readparam: 读取给定相对或绝对路径下的参数设置文件。该命令不要求待读取的文件后缀为 '.par' ， 只要文件本身符合COPT的参数设置文件格式即可。

  • readtune: 读取给定相对或绝对路径下的调参文件。该命令不要求待读取的文件后缀为 '.tune' ， 只要文件本身符合COPT的调参文件格式即可。

  • reset: 重置模型中的解信息，以及初始解等其它信息。工具的状态设为 'Initial' 。

  • resetparam: 重置优化参数为默认值。工具的状态设为 'Initial' 。

  • set: 设置给定的COPT参数的当前值。该命令的完整语法形如：'set TimeLimit 100' 。 特别地，对于不带参数名的调用，将列出目前所有参数的名称和简介，方便不熟悉COPT参数的 用户查看其所需信息，并在新的提示符所在行，自动添加 set 命令调用，用户只需要补充待查询的 参数名称即可。在输入参数名称时，支持 <Tab> 补全，且不区分大小写，自动补全的 名字是标准形式。

    例如：用户需要设置求解器的求解时间为1000秒，完整命令为：'set TimeLimit 1e3' ，若用户 不确定待设置参数的允许范围，可在输入命令 'set TimeLimit' 后按 <Enter> 键，交互 工具会反馈 TimeLimit 参数的当前值、默认值、最小值和最大值，以便用户正确输入。

    对于不允许设置的属性，或者输入了错误的参数名称，则报告相应的错误。命令正确完成后将工具 的状态 置为 'SetParam' 。

  • write: 输出模型文件、结果文件、IIS文件、可行化松弛文件、基文件、初始解文件和参数设置文件。该命令根据指定的输出文件的后缀执行相应的输出任务， 即如果文件后缀是 '.mps' ，则自动将当前加载的模型输出为MPS格式的模型文件，功能相当于命令 writemps ； 如果文件后缀是 '.lp' ，则自动将当前加载的模型输出为LP格式的模型文件，功能相当于命令 writelp ； 如果文件后缀是 '.bin' ，则自动将当前加载的模型输出为COPT二进制格式的模型文件，功能相当于命令 writebin ； 如果文件后缀是 '.cbf' ，则自动将当前加载的模型输出为CBF格式的模型文件，功能相当于命令 writecbf ； 如果文件后缀是 '.iis'，则将输出计算得到的IIS模型到IIS文件，功能相当于命令 writeiis ； 如果文件后缀是 '.relax'，则将输出计算得到的松弛模型到Relax文件，功能相当于命令 writerelax ； 如果文件后缀是 '.sol' ，则自动将模型求解的最终结果输出到结果文件，功能相当于命令 writesol ； 如果文件后缀为 '.bas' ，则自动将模型求解后最终的基状态输出到基文件，功能相当于命令 writebasis ； 如果文件后缀为 '.mst' ，则自动输出初始解信息到文件，功能相当于命令 writemst ； 如果文件后缀为 '.par' ，则自动将求解当前模型时修改过的COPT参数设置输出到文件，功能相当于命令 writeparam 。 除此之外，不匹配的文件类型会提示出错。

  • writemps: 将当前求解问题输出为给定的相对或绝对路径下的MPS格式模型文件。如果文件后缀名不是 '.mps' ，则自动添加后缀 '.mps' 。

  • writelp: 将当前求解问题输出为给定的相对或绝对路径下的LP格式模型文件。如果文件后缀名不是 '.lp' ，则自动添加后缀 '.lp' 。

  • writecbf: 把（半定）问题输出到'.cbf'文件。如果文件后缀名不是 '.cbf' ，则自动添加后缀 '.cbf' 。注意不支持输出带有二次目标或者二次约束的问题。

  • writebin: 将当前求解问题输出为给定的相对或绝对路径下的COPT二进制格式模型文件。如果文件后缀名不是 '.bin' ，则自动添加后缀 '.bin' 。

  • writeiis: 将当前读入问题的IIS模型保存至给定的相对或绝对路径下的IIS文件。如果文件后缀名不是 '.iis' ，则自动添加后缀 '.iis' 。

  • writerelax: 把具有可行解的松弛问题输出到'.relax'文件。如果文件后缀名不是 '.relax' ，则自动添加后缀 '.relax' 。

  • writesol: 将当前求解问题的结果保存至给定的相对或绝对路径下的结果文件。如果文件后缀名不是 '.sol' ，则自动添加后缀 '.sol' 。

  • writepoolsol: 将当前求解问题解池中指定编号的结果保存至给定的相对或绝对路径下的结果文件。如果文件后缀名不是 '.sol' ，则自动添加后缀 '.sol' 。调用命令为 'writepoolsol idx pool_idx.sol'， 其中 'idx' 为指定的解池结果编号。通过命令 'get PoolSols' 获取当前解池结果数目。

  • writebasis: 将当前求解问题模型的基状态信息保存至给定的相对或绝对路径下的基文件。如果文件后缀名不是 '.bas' ，则自动添加后缀 '.bas' 。

  • writemst: 将当前求解问题模型的初始解信息保存至给定的相对或绝对路径下的初始解文件。如果文件后缀名不是 '.mst' ，则自动添加后缀 '.mst' 。

  • writeparam: 将当前修改过的COPT参数设置保存至给定的相对或绝对路径下的参数设置文件。如果文件后缀名不是 '.par' ，则自动添加后缀 '.par' 。

  • writetuneparam: 将指定的调优结果保存至给定的相对或绝对路径下的参数设置文件。调用命令为 'writetuneparam idx tune_idx.par'， 其中 'idx' 为指定的调优结果编号。通过命令 'get TuneResults' 获取当前调优后获取的调优结果数目。

使用示例

本节以著名的“Diet问题”为例，演示如何使用 copt_cmd 交互式命令行工具求解优化问题。关于 该问题的具体描述，请参考 AMPL接口 - 使用示例。

首先请用户按照 安装说明 安装杉数求解器并配置许可文件，然后在Windows的 命令行或者Linux和MacOS的终端中输入下述命令：

copt_cmd

若屏幕输出如下，则表示调用成功。用户可在交互式界面中输入 help 查看命令使用说明。

Cardinal Optimizer v7.1.1. Build date Mar 04 2024
Copyright Cardinal Operations 2024. All Rights Reserved

COPT>

假定待求解问题模型为 diet.mps ，且位于当前工作目录下，在交互式界面中输入下述 命令读取待求解模型：

COPT> read diet.mps
Reading from '/home/username/copt/diet.mps'
Reading finished (0.00s)

求解具体问题模型之前，用户可以任意设置COPT的求解参数。例如：设置求解时间限制为 10秒，则在交互界面输入下述命令：

COPT> set timelimit 10
Setting parameter 'TimeLimit' to 10

如果用户不熟悉COPT支持的求解参数，可以输入 set 命令列出所有COPT支持的参数和属性名，以及 相应的简单说明。如果在 set 命令后加上参数名，比如：'set TimeLimit' ，则会显示指定 参数的当前值、默认值、最小值和最大值。

设置完求解参数后，可以使用工具命令 opt 或 optimize 求解当前优化模型，求解过程中 显示的日志信息如下：

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

求解完成后，用户可以通过工具命令 get 加上具体的参数名或属性名查看相关信息。与工具命令 set 类似, 直接使用 get 命令将列出所有COPT支持的参数名和属性名，及其简单介绍。 特别地，使用 'get all' 命令将显示所有COPT支持的参数名和属性名，及其当前值。

COPT> get TimeLimit
  DblParam: [Current]  10s
COPT> get LpObjval
  DblAttr:  [Current] 88.2
COPT> get LpStatus
  IntAttr:  [Current] 1 optimal

退出交互界面之前，用户可以选择把求解结果、修改过的参数和基状态输出到指定文件。下面演示了将求解 结果输出到当前路径下的 diet.sol 文件中，然后退出交互界面。由于未指定后缀为 '.sol' ， 则 copt_cmd 在输出时自动追加后缀 '.sol' 。

COPT> writesol diet
  Writing solutions to /home/username/copt/diet.sol
COPT> quit
  Leaving COPT...

用户也可以将上述步骤对应的命令写入脚本文件 diet.in 中，详见 代码 1:

代码 1 diet.in
1#COPT script-in file
2
3read diet.mps
4set timelimit 10
5opt
6writesol diet
7quit

然后在启动 copt_cmd 时使用选项 '-i' 加载上述脚本文件，如下所示：

copt_cmd -i diet.in

也可以在交互模式下使用工具命令 load 直接加载，如下所示：

COPT> load diet.in