{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Branin 函数\n",
    "\n",
    "**类别：** 非线性优化\n",
    "\n",
    "使用 OptAgent 的 Python 接口描述变量、约束与目标。\n",
    "\n",
    "问题与原始示例来源：[Hexaly Code Templates](https://www.hexaly.com/templates/branin-function)。\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "319d1be7",
   "metadata": {},
   "source": [
    "## 问题描述\n",
    "\n",
    "**Branin 函数** 是一个二维函数,由如下方程定义:\n",
    "\n",
    "$$f(x) = a\\left(x_2 - b x_1^2 + c x_1 - r\\right)^2 + s(1-t)\\cos(x_1) + s$$\n",
    "\n",
    "推荐的参数取值为 $a = 1$,$b = \\frac{5.1}{4\\pi^2}$,$c = \\frac{5}{\\pi}$,$r = 6$,$s = 10$,以及 $t = \\frac{1}{8\\pi}$。该函数通常在 $x_1 \\in [-5, 10]$,$x_2 \\in [0, 15]$ 的定义域上求值。\n",
    "\n",
    "该函数具有三个全局最小值,问题的目标是找到其中之一。更多细节,请参阅 [Virtual Library of Simulation Experiments](http://www.sfu.ca/~ssurjano/branin.html)。\n",
    "\n",
    "### 学习要点\n",
    "\n",
    "- 添加 [浮点决策变量](https://optagent.pages.dev/guide/modeling/)\n",
    "- 使用 [`cos` 与 `pow` 算子](https://optagent.pages.dev/guide/modeling/) 构建非线性表达式\n",
    "- 了解 OptAgent 的建模风格:[区分决策变量与中间表达式](https://optagent.pages.dev/guide/modeling/)\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5a351ac9",
   "metadata": {},
   "source": [
    "## 建模思路\n",
    "\n",
    "常数取为推荐值:$a = 1$,$b = \\frac{5.1}{4\\pi^2}$,$c = \\frac{5}{\\pi}$,$r = 6$,$s = 10$,以及 $t = \\frac{1}{8\\pi}$。$x_1$ 与 $x_2$ 的定义域分别为 $[-5, 10]$ 与 $[0, 15]$。\n",
    "\n",
    "Branin 函数问题的 OptAgent 模型非常直接。它使用两个浮点决策变量,分别表示 $x_1$ 与 $x_2$。借助 OptAgent 丰富的非线性数学算子集合,我们可以直接计算该函数的值。使用 **cos** 与 **pow** 等算子,我们能够以非常自然的方式表达 Branin 函数。\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8b35d420",
   "metadata": {},
   "source": [
    "## Python 实现\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "branin-model",
   "metadata": {},
   "outputs": [],
   "source": [
    "from pathlib import Path\n",
    "\n",
    "from optagent import OptModel, solve\n",
    "\n",
    "\n",
    "\n",
    "\n",
    "def main(output_file=None, time_limit=6):\n",
    "    pi = 3.14159265359\n",
    "    a = 1\n",
    "    b = 5.1 / (4 * pi**2)\n",
    "    c = 5 / pi\n",
    "    r = 6\n",
    "    s = 10\n",
    "    t = 1 / (8 * pi)\n",
    "\n",
    "    model = OptModel()\n",
    "    x1 = model.float(-5.0, 10.0)\n",
    "    x2 = model.float(0.0, 15.0)\n",
    "\n",
    "    branin = a * (x2 - b * x1**2 + c * x1 - r) ** 2 + s * (1 - t) * model.cos(x1) + s\n",
    "    model.minimize(branin)\n",
    "\n",
    "    solution = solve(model, time_limit_s=float(time_limit))\n",
    "    result_values = {'objective': branin.value, 'x1': x1.value, 'x2': x2.value}\n",
    "    result_text = (\n",
    "        f\"Status = {solution.feasible}; Objective = {result_values['objective']}\\n\"\n",
    "        f\"x1 = {result_values['x1']}\\n\"\n",
    "        f\"x2 = {result_values['x2']}\"\n",
    "    )\n",
    "    print(result_text)\n",
    "    if output_file is not None:\n",
    "        Path(output_file).write_text(result_text + \"\\n\", encoding=\"utf-8\")\n",
    "    return solution\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "branin-run-heading",
   "metadata": {},
   "source": [
    "## 本地运行\n",
    "\n",
    "Branin 函数不需要外部实例文件，直接调用 `main` 即可；调整 `time_limit` 可以控制求解时间。\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "branin-run",
   "metadata": {},
   "outputs": [],
   "source": [
    "solution_branin = main(time_limit=1)\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "0a3a1d58",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "2473a5f4",
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": ".venv",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.14.6"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}