Skip to main content
Version: v0.6.0 (Chinese only)

代码生成

当完成问题定义后, 需通过OPTIMake的代码生成函数生成问题定义与求解器的C/C++代码. 该章节主要介绍了如何配置代码生成.

OPTIMake的代码生成流程如下:

Overview of code generation

其中, 代码生成分为问题生成与求解器生成两个步骤:

  • 问题生成: 生成问题相关的函数, 如约束的函数值及其梯度. 该过程在用户本地进行
  • 求解器生成: 生成问题对应的求解器. 该过程在OPTIMake服务器进行 (该过程需要联网). 当调用生成的求解器时, 不需要联网

在本地完成问题生成后, 客户端会将问题脱敏后发送至OPTIMake服务器进行求解器生成, 即用户的具体问题定义及数据不会被发送至OPTIMake服务器. 所有上传的数据均对用户透明 (客户端上传部分的代码开源) . 以下为具体发送至服务器的数据:

  • 脱敏后的问题 (masked_multi_stage_problem):
    • 维度
    • 稀疏性: 为0/1的矩阵, 用于稀疏求解加速运算
    • 性质 (如是否线性): 用于选择更好的求解策略
  • 用户信息 (user_info), 用于license check:
    • mac地址
    • 计算机名
    • OS
    • CPU
  • 代码生成option (codegen_option): 定义了需要生成的求解器类型, 硬件平台等信息

代码生成​

下面首先介绍代码生成的option, 主要可被分类为生成配置, 求解算法, 性能与代码风格.

生成配置​

codegen_path: 代码生成路径 (默认值为当前目录下名称与问题名称同名的文件夹)

overwrite: 是否overwrite已生成的代码 (默认True)

verbose: 是否打印代码生成相关的信息 (默认False)

source_file_extension: 生成代码的源文件后缀名

  • 'c' (默认)
  • 'cpp'
  • 'cxx'
  • 'cc'

header_file_extension: 生成代码的头文件后缀名

  • 'h' (默认)
  • 'hpp'
  • 'hxx'
  • 'hh'

enable_printing: 是否开启打印功能

  • True: 生成代码中包含printf函数, 在求解器print_level设置为非0时, 求解器可打印求解状态 (默认)
  • False: 生成代码中不包含printf函数, 即使在求解器print_level设置为非0时, 求解器亦不可以可打印求解状态

enable_timing: 是否在生成代码中包含计时功能 (默认True)

enable_serialization: 是否开启序列化功能 (可将求解设定存储为二进制文件并读取复现, 默认False)

platform: 求解器运行的平台及其编译器

  • 'host' (默认): 使用当前计算机的平台, OPTIMake会自动检测当前计算机的操作系统, 并选择以下具体的平台
  • 'linux-x86_64-gcc': Linux x86_64平台, gcc编译器
  • 'windows-x86_64-mingw': Windows x86_64平台, mingw编译器
  • 'windows-x86_64-msvc': Windows x86_64平台, msvc (Microsoft Visual C++) 编译器
  • 'linux-arm64-gcc': Linux ARM64平台, gcc编译器
  • 'linux-armv7-gcc': Linux ARMv7平台, gcc编译器
  • 'qnx-arm64-gcc': QNX ARM64平台, gcc编译器
info

OPTIMake使用交叉编译生成不同平台的求解器, 可支持多种平台的求解器生成.

如上述的平台或编译器不满足需求, 请联系OPTIMake获取支持.

lib_type

  • 'static': 生成求解器的静态链接库 (默认)
  • 'shared': 生成求解器的动态链接库

求解算法​

solver: 求解算法

  • 'pdipm': primal-dual interior-point method (默认)

hessian_approximation: Hessian计算方法

  • 'exact' (默认)
  • 'gauss-newton'
  • 'bfgs'
info
  1. 当objective为least square类型且残差较小, 或问题的非线性较低时, 选择'gauss-newton'. 当非上述情况, 需要计算Hessian才能收敛时, 选择'exact'或'bfgs'.
  2. 当Hessian很容易得到 (比如问题通过符号定义, OPTIMake会自动生成exact Hessian), 选择'exact'一般比'bfgs'更高效且鲁棒
  3. 如下的情况OPTIMake不能自动生成exact Hessian:
    • 外部函数, 此时Hessian需要用户自己提供. (见建模接口 > 外部C/C++函数支持了解OPTIMake中的外部函数)
    • differential_equation且discretization_method为'irk2'或'irk4'

bfgs_init_hessian: bfgs的Hessian初始值, 可以为常数或关于参数p的维度为[nv, nv]的对称矩阵 (通过list传入, list的元素为nv维的list)；其默认值单位矩阵

info

求解过程中计算的Hessian值被存储在workspace中, 可以求解优化问题后访问该值来优化bfgs_init_hessian的选取.

性能​

optimization_level: 编译优化等级

  • 0,1,2,3 (默认3)

common_subexpression_elimination: 提取公共表达式, 减少运算量

  • 'on'
  • 'off'
  • 'auto' (默认)

会导致计算顺序变化, 当问题对数值敏感时, 可以尝试不同的选项求解.

simplify_expression: 简化表达式, 可能会导致本地问题时间过长

  • True
  • False (默认)

default_tolerance_level: 默认的求解精度 (设置后求解精度亦可手动调整)

  • 'low'
  • 'medium' (默认)
  • 'high'

simd: 是否启用SIMD加速

  • 'off'
  • 'neon' : 启用NEON指令集加速 (仅platfrom为ARM架构时可用)

代码风格与检查​

code_format: 生成代码是否需要格式化

  • 'auto' (默认): 自动检测本地是否安装了clang-format, 若安装则使用clang-format格式化代码, 否则不格式化代码
  • 'clang-format': 使用clang-format格式化代码, 需确保本地已安装clang-format
  • 'off': 不格式化代码
info

当选择使用clang-format格式化代码时, 需确保本地已安装clang-format. 可参考以下方式安装 (安装完成后, 在终端输入clang-format --version能正确输出版本号即表示安装成功):

  • 在linux, 可通过包管理器安装clang-format, 例如在Ubuntu上可通过sudo apt install clang-format安装
  • 在windows平台, 可通过LLVM官网下载并安装LLVM, 其中包含了clang-format
  • 在macOS平台, 可通过brew install clang-format安装

clang_format_config_file: clang-format的配置文件路径, 默认'default', 使用如下的默认配置:

.clang-format
# base style
BasedOnStyle: Google

# Indent width set to 4 spaces
IndentWidth: 4

# Use spaces instead of tabs
UseTab: Never

# Set maximum line length to 80 characters
ColumnLimit: 80

# Brace wrapping settings
BreakBeforeBraces: Custom
BraceWrapping:
  AfterFunction: true   # function left brace on new line
  AfterClass: true      # class left brace on new line
  AfterControlStatement: false # if/for etc. no new line

# Do not allow short if statements on a single line
AllowShortIfStatementsOnASingleLine: false

# Pointer alignment (Left: int* p; Right: int *p;)
PointerAlignment: Right

如需使用自定义的代码风格, 可参考Clang-Format官方文档 编写配置文件并将其路径传入该选项.

static_check: 是否对生成代码进行静态代码检查 (只对linux系统有效, 需要本地安装cppcheck, 默认False)

示例​

下面为代码生成的例子:

option = codegen_option()
option.solver = 'pdipm' # primal-dual interior-point method
option.enable_printing = True
option.optimization_level = 3
option.platform = 'linux-x86_64-gcc'

codegen = code_generator()
codegen.codegen(prob, option)

假设问题的名称为 'vehicle', 生成platform为'linux-x86_64-gcc', OPTIMake会生成以下文件:

  • vehicle_prob.h: 问题的头文件, 定义了维度, 优化变量与参数index的enum值等
  • vehicle_prob.c: 问题的源码文件, 定义了各函数, 如objective及其梯度的实现
  • vehicle_prob_ext.c.template: 只当问题定义中出现外部函数时会生成该文件, 包含了外部函数的模板. 用户完成外部函数的实现后需要去掉.template后缀编译
  • vehicle_solver.h: 求解代码的接口头文件
  • libvehicle_solver_shared.so: 求解代码的动态链接库 (platform为Windows时后缀为.dll)
  • libvehicle_solver_static.a: 求解代码的静态链接库 (platform为Windows时后缀为.lib)
info

每一次代码生成都会有唯一的session uuid. 当前代码生成失败时, 请提供该id以及返回状态至OPTIMake以获取技术支持.