# 选择求解路径

三类求解入口共用 `OptModel`，求解能力均随 OptAgent 提供。通常先用 `solve()`；需要指定求解方式时，再选择启发式或 OptX 精确求解。显式入口不自动互相回退。

## 路径对照

| 路径 | 适用场景 | 配置 | 不兼容时 |
| --- | --- | --- | --- |
| 混合求解 `solve()` | 通用优化模型，自动协调适用的启发式与精确求解能力 | `time_limit_s`、`threads` 等命名参数 | 返回停止状态或抛出对应异常 |
| 启发式求解 `solve_heuristic()` | 希望独立使用遗传算法，且符合所选搜索方案要求的模型 | 通用参数直接传入，遗传参数使用 `ga=GaOptions(...)` | `HeuristicUnsupportedError`，附带原因 |
| OptX `solve_optx()` | HiGHS 或 CP-SAT 各自支持的模型 | `HighsConfig` 或 `CpSatConfig` | `OptxUnsupportedError`，附带问题位置 |

OptX 可选择内置 HiGHS 或 OR-Tools CP-SAT，无须另装 Python `ortools` 或 `highspy`。
两个精确后端均不要求提供初始可行解。CP-SAT 面向整数兼容模型，不会自动将不支持的连续变量离散化。
包含外部 Python 函数的模型可使用混合或启发式求解，需设置 `deterministic=False`。

## 准备模型

完整声明业务中的变量、约束与目标即可，无须选择特定问题模板。初始值可以帮助搜索，但不能替代约束。

求解后先检查 `solution.feasible`，再读取变量值。限时搜索可能尚未找到可行解，`feasible=False` 不能单独证明模型无解。

## 配置时间预算

=== "混合求解"

    ```python
    solution = model.solve(time_limit_s=10.0, log_level="off")
    ```

    默认 30 秒，包含序列化与原生编译。可选日志为 `off`、`on`（默认）、`debug`。

=== "启发式求解"

    ```python
    solution = model.solve_heuristic(time_limit_s=10.0, threads=4)
    ```

    默认 30 秒，包含模型准备、搜索、结果校验和返回。该入口只使用遗传算法。
    专用参数见 [启发式求解参数](../api/solve.md#solve_heuristic)。

=== "OptX / HiGHS"

    ```python
    from optagent import HighsConfig

    solution = model.solve_optx(config=HighsConfig(time_limit_s=10.0))
    ```

    默认 30 秒，覆盖序列化、模型转换、求解及结果验证和交付。

=== "OptX / CP-SAT"

    ```python
    from optagent import CpSatConfig

    solution = model.solve_optx(config=CpSatConfig(time_limit_s=10.0, threads=4))
    ```

    默认 30 秒，包含模型准备、求解、结果校验和返回。预算耗尽且没有已验证的可行解时，返回 `unknown`，不可读取变量值。

时间预算用于请求停止，正在执行的操作与结果清理可能使调用稍晚返回。各入口的完整参数见[求解与配置](../api/solve.md)。

## 目标阈值和外部评价次数

三个入口均支持 `objective_threshold`，用从零开始的目标索引映射到数值阈值，例如 `{0: 100}`。阈值必须有限，索引必须存在；精确求解的整数阈值还须落在 `[-2^53, 2^53]` 内。

混合和启发式求解均支持 `external_evaluation_limit`，用正整数限制实际启动的外部回调次数，失败调用也计入；已知结果和复用不额外消耗次数。默认 `None` 表示不设置次数上限，时间预算仍然有效。

[查询完整求解参数 →](../api/solve.md)

## HiGHS 后端的转换边界

HiGHS 适合线性和混合整数线性模型。部分集合、序列、逻辑、索引、分段线性及有界离散非线性表达式也可转换求解；是否支持取决于具体组合、取值范围和模型规模。

二次目标支持连续凸二次最小化或凹二次最大化，约束须为线性，未固定变量须为连续变量。多目标中，二次目标必须放在最后，之前的目标须为线性。混合整数二次规划、非凸二次规划、一般连续非线性约束和外部回调不在支持范围内。

多目标按声明顺序求解，只有前级确认最优且未启用正间隙停止条件时才继续。达到目标阈值、时间或间隙限制，不代表全部目标已经最优。逐接口条件见[求解器支持矩阵](../api/solver-support.md)。