跳转到内容

RustScript求解器与回调

本章用于在数值脚本中建立方程或优化模型。只需要配置DFF节点时,先看 DFF节点定义;需要回调、梯度或自定义数值程序时,再使用本章接口。

先确认当前MEMS版本提供所需求解器,再选择符号式建模或回调式建模。两种调用方式的参数、返回值和状态码不同。

本章函数用于TensorEval中的RustScript数值脚本。它们与DFF的Solve/NLSolve/MILP/NLP表格输入格式分别使用。

  1. 在编辑模式的设置项-报表中新建或编辑DFF,详情设为Manual触发、Memory保存。
  2. 新建TensorEval节点,将完整代码保存为.rss文件并在节点中上传;使用CSV/Excel配置时,写在节点参数1中。下面三个求解示例的输入已写在代码里,无需另接源节点。
  3. 只返回一个数值张量时,勾选是否矩阵,文件参数2用2。返回多个数值结果时,再勾选Multi-returns和自定义名称,文件参数2用10;界面列名用x|f|flag,文件第7列用x;f;flag。
  4. 输出多张表时,用同名边分别传给下游;报表展示的最终节点应接收选定结果。保存并加载流程,到事件-策略手动运行,再查看本次结果和状态。只有一个计算节点且返回一张表时,可直接作为流程输出。

可用函数包括线性/非线性方程的sp_linsolve/fsolve、混合整数规划的intlinprog、非线性优化的fmincon/optimoptions,以及记录访问函数struct/getfield/setfield/isfield/isstruct/isempty/error。具体函数与数值后端以当前安装版本为准;遇到未知函数或后端不可用提示时,先联系管理员确认功能包。

函数用途与返回值
sp_linsolve线性方程;返回[x..., status],数值核心也支持复数。
fsolve非线性方程;返回[x..., status]。
intlinprog混合整数线性规划;返回[x..., objective, status]。

调用格式:

sp_linsolve(left, b, initial, names)
fsolve(residuals, names)
fsolve(residuals, initial, names)
intlinprog(objective, constraints, types, names)
intlinprog(objective, constraints, lower, upper, types, names)

符号未知量应保留为表达式,例如用反引号引用名称;不要先把未知量代入成常数。sp_linsolve 的 left 是等式左端,b 是对应右端;b=[] 表示零向量,initial=[] 填充零初值。线性直接求解不利用初值迭代。fsolve 的每条输入是默认等于零的残差;省略初值时先读取上下文同名实数标量,未找到时为零。

以下非线性方程示例可直接放入数值脚本,参考结果接近[1,1,0],最后一项是状态:

return fsolve(
[`x1`^2-10*`x1`+`x2`^2+8, `x1`*`x2`^2+`x1`-10*`x2`+8],
[`x1`,`x2`]
);

intlinprog 类型码为 1=0/1、2=整数、3=连续实数。目标可写 min(expr)、max(expr),省略方向默认最小化;约束支持 <=、>=、==。当前稀疏目标提取器不接受独立常数项。HiGHS 包装中未指定边界的连续变量双侧无界;需要非负性时显式给下界或约束。

这些专用建模函数不同于直接矩阵 linsolve(A,b):前者返回附带状态的模型求解向量,后者直接计算矩阵方程。

第一实参为符号表达式时,沿用表达式建模和自动微分:

fmincon(objective, constraints, c_lower, c_upper, x_lower, x_upper, names)
fmincon(objective, constraints, c_lower, c_upper, x_lower, x_upper, names, initial)
fmincon(objective, constraints, c_lower, c_upper, x_lower, x_upper, names, parameter_keys, parameter_values)
fmincon(objective, constraints, c_lower, c_upper, x_lower, x_upper, names, initial, parameter_keys, parameter_values)

约束表达式、约束下界和上界长度须一致;变量名、变量下界、上界及显式初值长度须一致。末尾参数键/值列表按字符串内容传给 Ipopt 参数转换器;这套 7/8/9/10 实参协议不使用 callback 的 optimoptions 位置。

返回的是一个向量 [x..., objective, status]。方向支持 min、max,默认最小化;这里的符号式函数会把最大化目标值恢复为原目标的符号。其他求解入口应按各自的结果约定使用。

下面求解(a-3)^2+(b-5)^2的最小值,参考向量接近[3,5,0,0]:

f=(`a`-3)^2+(`b`-5)^2;
result=fmincon(min(`f`),[],[],[],[-10,-10],[10,10],[`a`,`b`],[0,0]);
return result;

第一实参为函数对象时进入回调适配器,协议为:

[x,fval,exitflag,output,lambda] = fmincon(fun,x0,A,b,Aeq,beq,lb,ub,nonlcon,options)

允许 2~10 个实参,末尾可省略;中间未用的位置填 []。x0 必须是非空有限实数标量或向量,返回的 x 保留其形状。线性约束是 A*x<=b、Aeq*x=beq,变量边界为 lb<=x<=ub。这套协议不再列符号未知量名称。

  • fun(x) 必须返回 两个值 (f,gradient):一个有限目标值和长度为变量数的有限梯度。此接口做最小化;最大化时由调用者对目标及梯度同时取负。
  • nonlcon(x) 若提供,必须返回 四个值 (c,ceq,GC,GCeq),分别代表 c(x)<=0、ceq(x)=0 及其导数。GC 形状为 n×不等式数、GCeq 为 n×等式数;列对应约束,行对应变量。约束数量在求解中不得改变。
  • 回调接口要求用户梯度,不提供自动数值差分;不能用仅返回目标值的函数代替。SpecifyObjectiveGradient=false 或 SpecifyConstraintGradient=false 会报错。
  • 默认未给 Hessian 回调时使用 Ipopt 的 limited-memory;可通过 HessianFcn 提供 H(x,lambda),返回完整拉格朗日 Hessian Hf+Σlambda_i*Hgi。适配器处理 Ipopt 的目标权重,不能只提供目标 Hessian 而遗漏非线性约束项。
  • ConstraintJacobianPattern 是 (不等式数+等式数)×n,排列先非线性不等式再非线性等式;与 GC/GCeq 的导数矩阵方向不同。HessianPattern 是 n×n,须同时提供 HessianFcn。实际非零导数不得越出声明结构;大问题应显式给稀疏模式,默认隐式结构最多 1,000,000 项。

optimoptions 当前只接受 fmincon 和成对选项名/值,返回结构体;Algorithm 仅接受 interior-point 或 ipopt,不支持据同名函数推断 MATLAB 的其他算法。别名包括 MaxIterations→max_iter、OptimalityTolerance→tol、ConstraintTolerance→constr_viol_tol、Display→print_level(off/none=0、final=3、iter=5)。同一个选项通过大小写或别名重复指定会报错,未知或非法参数也会报错。

以下完整片段以函数回调提供目标及梯度,最优x接近[3]、f接近0、flag>0:

fn objective(x) {
value=sum_all((x-3).^2);
gradient=2*(x-3);
return (value,gradient);
}
options=optimoptions(`fmincon`,`OptimalityTolerance`,1e-9);
[x,f,flag,output,lambda]=fmincon(objective,[0],[],[],[],[],[-10],[10],[],options);
return (x,f,flag);

方括号接收的是五个独立返回值;仅写 x=fmincon(...) 接收第一个返回值,不会获得符号式的拼接向量。output 和 lambda 是结构体,不能直接转换成 DFF DataFrame;应提取所需数值字段后返回。上例作为 DFF 普通 TensorEval 脚本输出三个值时,还须启用参数 2 的多返回值位 0x08,并使输出数量匹配。

output 包含 backend、raw_status、message、iterations、funcCount、constraint_calls、hessian_calls、constraint_violation、导数来源信息,若有迭代记录还包含 dual_infeasibility_scaled。lambda 包含 lower、upper、ineqlin、eqlin、ineqnonlin、eqnonlin;例如用 getfield(output,`constraint_violation`) 读取约束违反量。

入口状态解释
sp_linsolve、fsolve成功末项 0;模型已构造但求解失败时为 [0...,1];模型无法构造时返回单元素 [100]
intlinprog末项是后端状态;当前 HiGHS 最优码为 7,其他状态按 HiGHS 定义;CBC 使用自己的状态。无求解结果时末项为 101,构造失败为 [100]
符号式 fmincon末项为数值状态码:0=SolveSucceeded、1=SolvedToAcceptableLevel 都成功。其他状态分支返回 [0...,0,status];构造失败为 [100],AD/参数绑定等错误也可能直接成为 VM 运行错误
回调式 fmincon返回单独的 exitflag,并在 output.raw_status 保留状态名称;不使用拼接向量或 [100] 协议

符号式 fmincon 的其他常见枚举码为 2=FeasiblePointFound、3=InfeasibleProblemDetected、4=SearchDirectionBecomesTooSmall、5=DivergingIterates、6=UserRequestedStop、7=MaximumIterationsExceeded、8=MaximumCpuTimeExceeded;当前包装只把 0/1 当成功。这些状态码按上表解释,不能与回调式exitflag或其他求解器状态混用。

回调式 exitflag 的当前映射为:

值条件
1SolveSucceeded 或 SolvedToAcceptableLevel
2SearchDirectionBecomesTooSmall 且约束违反量不大于所配置容差
0MaximumIterationsExceeded 或 MaximumCpuTimeExceeded
-1UserRequestedStop
-2InfeasibleProblemDetected
-3其他状态

callback 数值求解未成功时仍保留最后的 x/fval 与诊断;输入、导数维数、选项等验证错误则抛 VM 错误。不要只看某个变量是否非零判断成功。intlinprog 的失败分支和符号式 NLP 的失败分支会填零,零不是参考解。

普通TensorEval数值脚本可使用日志与文件读取;DataFrame混合图的内嵌数值程序用于计算和日志,不读取文件或网络。

先准备以下数值文件data.csv,放到MEMS服务可读取的位置;这段脚本只输出一张表,参数2用2。运行后预期为10.5/21两行数值:

value
10
20
input=read_tensor(`data.csv`);
println(`message`); debug(input); info(input); warn(input);
ms=monotonic_ms();
scaled=input*1.05;
return scaled;

monotonic_ms()是进程内相对毫秒,不是Unix时间戳。read_tensor支持xls/xlsx/parquet/csv,其他扩展名按表达式文本尝试读取;网络读取另有read_tensor_url。

导出数值结果时,在计算节点后增加None输出节点,连接一条WriteFile边,参数1填写服务端结果路径,例如results/solution.csv或results/solution.parquet。先准备好父目录并确认可写,手动运行后检查文件内容。在仪表盘-报表选择本次执行记录,也可保存表格或图表的展示配置,详见运行结果展示。

write_tensor不作为本手册的结果导出方法。文件读取中的data.csv指服务端文件,浏览器本机数据可通过Source → Data上传,再用入边提供给脚本。混合图内嵌数值程序不读取文件或网络数据。

求解器脚本中的error(message)会中止脚本并报告错误。需要检查计算结果时,将残差、状态或约束违反量作为数值输出,在报表中核对;不要把某个非零变量当成求解成功的证明。

矩阵写法、零基下标、循环和求解函数的迁移对照已整理到从matlab迁移。完整函数名称与适用模式见支持的函数。