{ "cells": [ { "cell_type": "code", "execution_count": 1, "id": "2ef3a8ca", "metadata": { "execution": { "iopub.execute_input": "2026-10-02T14:42:12.695007Z", "iopub.status.busy": "2026-10-02T14:42:12.694785Z", "iopub.status.idle": "2026-10-02T14:42:12.700935Z", "shell.execute_reply": "2026-10-02T14:42:12.699742Z" }, "papermill": { "duration": 0.009906, "end_time": "2026-10-02T14:42:12.701538+00:00", "exception": false, "start_time": "2026-10-02T14:42:12.691632+00:00", "status": "completed" }, "tags": [ "remove-input", "active-ipynb", "remove-output" ] }, "outputs": [], "source": [ "try:\n", " from openmdao.utils.notebook_utils import notebook_mode # noqa: F401\n", "except ImportError:\n", " !python -m pip install openmdao[notebooks]" ] }, { "cell_type": "markdown", "id": "c99bcd0e", "metadata": { "papermill": { "duration": 0.001791, "end_time": "2026-10-02T14:42:12.717450+00:00", "exception": false, "start_time": "2026-10-02T14:42:12.715659+00:00", "status": "completed" }, "tags": [] }, "source": [ "# ArmijoGoldsteinLS\n", "\n", "ArmijoGoldsteinLS checks bounds and backtracks to a point that satisfies them. From there,\n", "further backtracking is performed, until the termination criteria are satisfied.\n", "The main termination criteria is the Armijo-Goldstein condition, which checks for a sufficient\n", "decrease from the initial point by measuring the slope. There is also an iteration maximum.\n", "\n", "Here is a simple example where ArmijoGoldsteinLS is used to backtrack during the Newton solver's iteration on\n", "a system that contains an implicit component with 3 states that are confined to a small range of values." ] }, { "cell_type": "code", "execution_count": 2, "id": "3b3ce287", "metadata": { "execution": { "iopub.execute_input": "2026-10-02T14:42:12.721859Z", "iopub.status.busy": "2026-10-02T14:42:12.721661Z", "iopub.status.idle": "2026-10-02T14:42:15.179499Z", "shell.execute_reply": "2026-10-02T14:42:15.178180Z" }, "papermill": { "duration": 2.460887, "end_time": "2026-10-02T14:42:15.180076+00:00", "exception": false, "start_time": "2026-10-02T14:42:12.719189+00:00", "status": "completed" }, "tags": [ "remove-input", "remove-output" ] }, "outputs": [ { "data": { "application/papermill.record/text/html": "
class ImplCompTwoStatesArrays(om.ImplicitComponent):\n    """\n    A Simple Implicit Component with an additional output equation.\n\n    f(x,z) = xz + z - 4\n    y = x + 2z\n\n    Sol : when x = 0.5, z = 2.666\n    Sol : when x = 2.0, z = 1.333\n\n    Coupled derivs:\n\n    y = x + 8/(x+1)\n    dy_dx = 1 - 8/(x+1)**2 = -2.5555555555555554\n\n    z = 4/(x+1)\n    dz_dx = -4/(x+1)**2 = -1.7777777777777777\n    """\n\n    def setup(self):\n        self.add_input('x', np.zeros((3, 1)))\n        self.add_output('y', np.zeros((3, 1)))\n        self.add_output('z', 2.0*np.ones((3, 1)), lower=1.5,\n            upper=np.array([2.6, 2.5, 2.65]).reshape((3,1)))\n\n        self.maxiter = 10\n        self.atol = 1.0e-12\n\n    def setup_partials(self):\n        self.declare_partials(of='*', wrt='*')\n\n    def apply_nonlinear(self, inputs, outputs, residuals):\n        """\n        Don't solve; just calculate the residual.\n        """\n\n        x = inputs['x']\n        y = outputs['y']\n        z = outputs['z']\n\n        residuals['y'] = y - x - 2.0*z\n        residuals['z'] = x*z + z - 4.0\n\n    def linearize(self, inputs, outputs, jac):\n        """\n        Analytical derivatives.\n        """\n\n        # Output equation\n        jac[('y', 'x')] = -np.diag(np.array([1.0, 1.0, 1.0]))\n        jac[('y', 'y')] = np.diag(np.array([1.0, 1.0, 1.0]))\n        jac[('y', 'z')] = -np.diag(np.array([2.0, 2.0, 2.0]))\n\n        # State equation\n        jac[('z', 'z')] = (inputs['x'] + 1.0) * np.eye(3)\n        jac[('z', 'x')] = outputs['z'] * np.eye(3)\n
\n", "application/papermill.record/text/latex": "\\begin{Verbatim}[commandchars=\\\\\\{\\}]\n\\PY{k}{class}\\PY{+w}{ }\\PY{n+nc}{ImplCompTwoStatesArrays}\\PY{p}{(}\\PY{n}{om}\\PY{o}{.}\\PY{n}{ImplicitComponent}\\PY{p}{)}\\PY{p}{:}\n\\PY{+w}{ }\\PY{l+s+sd}{\\PYZdq{}\\PYZdq{}\\PYZdq{}}\n\\PY{l+s+sd}{ A Simple Implicit Component with an additional output equation.}\n\n\\PY{l+s+sd}{ f(x,z) = xz + z \\PYZhy{} 4}\n\\PY{l+s+sd}{ y = x + 2z}\n\n\\PY{l+s+sd}{ Sol : when x = 0.5, z = 2.666}\n\\PY{l+s+sd}{ Sol : when x = 2.0, z = 1.333}\n\n\\PY{l+s+sd}{ Coupled derivs:}\n\n\\PY{l+s+sd}{ y = x + 8/(x+1)}\n\\PY{l+s+sd}{ dy\\PYZus{}dx = 1 \\PYZhy{} 8/(x+1)**2 = \\PYZhy{}2.5555555555555554}\n\n\\PY{l+s+sd}{ z = 4/(x+1)}\n\\PY{l+s+sd}{ dz\\PYZus{}dx = \\PYZhy{}4/(x+1)**2 = \\PYZhy{}1.7777777777777777}\n\\PY{l+s+sd}{ \\PYZdq{}\\PYZdq{}\\PYZdq{}}\n\n \\PY{k}{def}\\PY{+w}{ }\\PY{n+nf}{setup}\\PY{p}{(}\\PY{n+nb+bp}{self}\\PY{p}{)}\\PY{p}{:}\n \\PY{n+nb+bp}{self}\\PY{o}{.}\\PY{n}{add\\PYZus{}input}\\PY{p}{(}\\PY{l+s+s1}{\\PYZsq{}}\\PY{l+s+s1}{x}\\PY{l+s+s1}{\\PYZsq{}}\\PY{p}{,} \\PY{n}{np}\\PY{o}{.}\\PY{n}{zeros}\\PY{p}{(}\\PY{p}{(}\\PY{l+m+mi}{3}\\PY{p}{,} \\PY{l+m+mi}{1}\\PY{p}{)}\\PY{p}{)}\\PY{p}{)}\n \\PY{n+nb+bp}{self}\\PY{o}{.}\\PY{n}{add\\PYZus{}output}\\PY{p}{(}\\PY{l+s+s1}{\\PYZsq{}}\\PY{l+s+s1}{y}\\PY{l+s+s1}{\\PYZsq{}}\\PY{p}{,} \\PY{n}{np}\\PY{o}{.}\\PY{n}{zeros}\\PY{p}{(}\\PY{p}{(}\\PY{l+m+mi}{3}\\PY{p}{,} \\PY{l+m+mi}{1}\\PY{p}{)}\\PY{p}{)}\\PY{p}{)}\n \\PY{n+nb+bp}{self}\\PY{o}{.}\\PY{n}{add\\PYZus{}output}\\PY{p}{(}\\PY{l+s+s1}{\\PYZsq{}}\\PY{l+s+s1}{z}\\PY{l+s+s1}{\\PYZsq{}}\\PY{p}{,} \\PY{l+m+mf}{2.0}\\PY{o}{*}\\PY{n}{np}\\PY{o}{.}\\PY{n}{ones}\\PY{p}{(}\\PY{p}{(}\\PY{l+m+mi}{3}\\PY{p}{,} \\PY{l+m+mi}{1}\\PY{p}{)}\\PY{p}{)}\\PY{p}{,} \\PY{n}{lower}\\PY{o}{=}\\PY{l+m+mf}{1.5}\\PY{p}{,}\n \\PY{n}{upper}\\PY{o}{=}\\PY{n}{np}\\PY{o}{.}\\PY{n}{array}\\PY{p}{(}\\PY{p}{[}\\PY{l+m+mf}{2.6}\\PY{p}{,} \\PY{l+m+mf}{2.5}\\PY{p}{,} \\PY{l+m+mf}{2.65}\\PY{p}{]}\\PY{p}{)}\\PY{o}{.}\\PY{n}{reshape}\\PY{p}{(}\\PY{p}{(}\\PY{l+m+mi}{3}\\PY{p}{,}\\PY{l+m+mi}{1}\\PY{p}{)}\\PY{p}{)}\\PY{p}{)}\n\n \\PY{n+nb+bp}{self}\\PY{o}{.}\\PY{n}{maxiter} \\PY{o}{=} \\PY{l+m+mi}{10}\n \\PY{n+nb+bp}{self}\\PY{o}{.}\\PY{n}{atol} \\PY{o}{=} \\PY{l+m+mf}{1.0e\\PYZhy{}12}\n\n \\PY{k}{def}\\PY{+w}{ }\\PY{n+nf}{setup\\PYZus{}partials}\\PY{p}{(}\\PY{n+nb+bp}{self}\\PY{p}{)}\\PY{p}{:}\n \\PY{n+nb+bp}{self}\\PY{o}{.}\\PY{n}{declare\\PYZus{}partials}\\PY{p}{(}\\PY{n}{of}\\PY{o}{=}\\PY{l+s+s1}{\\PYZsq{}}\\PY{l+s+s1}{*}\\PY{l+s+s1}{\\PYZsq{}}\\PY{p}{,} \\PY{n}{wrt}\\PY{o}{=}\\PY{l+s+s1}{\\PYZsq{}}\\PY{l+s+s1}{*}\\PY{l+s+s1}{\\PYZsq{}}\\PY{p}{)}\n\n \\PY{k}{def}\\PY{+w}{ }\\PY{n+nf}{apply\\PYZus{}nonlinear}\\PY{p}{(}\\PY{n+nb+bp}{self}\\PY{p}{,} \\PY{n}{inputs}\\PY{p}{,} \\PY{n}{outputs}\\PY{p}{,} \\PY{n}{residuals}\\PY{p}{)}\\PY{p}{:}\n\\PY{+w}{ }\\PY{l+s+sd}{\\PYZdq{}\\PYZdq{}\\PYZdq{}}\n\\PY{l+s+sd}{ Don\\PYZsq{}t solve; just calculate the residual.}\n\\PY{l+s+sd}{ \\PYZdq{}\\PYZdq{}\\PYZdq{}}\n\n \\PY{n}{x} \\PY{o}{=} \\PY{n}{inputs}\\PY{p}{[}\\PY{l+s+s1}{\\PYZsq{}}\\PY{l+s+s1}{x}\\PY{l+s+s1}{\\PYZsq{}}\\PY{p}{]}\n \\PY{n}{y} \\PY{o}{=} \\PY{n}{outputs}\\PY{p}{[}\\PY{l+s+s1}{\\PYZsq{}}\\PY{l+s+s1}{y}\\PY{l+s+s1}{\\PYZsq{}}\\PY{p}{]}\n \\PY{n}{z} \\PY{o}{=} \\PY{n}{outputs}\\PY{p}{[}\\PY{l+s+s1}{\\PYZsq{}}\\PY{l+s+s1}{z}\\PY{l+s+s1}{\\PYZsq{}}\\PY{p}{]}\n\n \\PY{n}{residuals}\\PY{p}{[}\\PY{l+s+s1}{\\PYZsq{}}\\PY{l+s+s1}{y}\\PY{l+s+s1}{\\PYZsq{}}\\PY{p}{]} \\PY{o}{=} \\PY{n}{y} \\PY{o}{\\PYZhy{}} \\PY{n}{x} \\PY{o}{\\PYZhy{}} \\PY{l+m+mf}{2.0}\\PY{o}{*}\\PY{n}{z}\n \\PY{n}{residuals}\\PY{p}{[}\\PY{l+s+s1}{\\PYZsq{}}\\PY{l+s+s1}{z}\\PY{l+s+s1}{\\PYZsq{}}\\PY{p}{]} \\PY{o}{=} \\PY{n}{x}\\PY{o}{*}\\PY{n}{z} \\PY{o}{+} \\PY{n}{z} \\PY{o}{\\PYZhy{}} \\PY{l+m+mf}{4.0}\n\n \\PY{k}{def}\\PY{+w}{ }\\PY{n+nf}{linearize}\\PY{p}{(}\\PY{n+nb+bp}{self}\\PY{p}{,} \\PY{n}{inputs}\\PY{p}{,} \\PY{n}{outputs}\\PY{p}{,} \\PY{n}{jac}\\PY{p}{)}\\PY{p}{:}\n\\PY{+w}{ }\\PY{l+s+sd}{\\PYZdq{}\\PYZdq{}\\PYZdq{}}\n\\PY{l+s+sd}{ Analytical derivatives.}\n\\PY{l+s+sd}{ \\PYZdq{}\\PYZdq{}\\PYZdq{}}\n\n \\PY{c+c1}{\\PYZsh{} Output equation}\n \\PY{n}{jac}\\PY{p}{[}\\PY{p}{(}\\PY{l+s+s1}{\\PYZsq{}}\\PY{l+s+s1}{y}\\PY{l+s+s1}{\\PYZsq{}}\\PY{p}{,} \\PY{l+s+s1}{\\PYZsq{}}\\PY{l+s+s1}{x}\\PY{l+s+s1}{\\PYZsq{}}\\PY{p}{)}\\PY{p}{]} \\PY{o}{=} \\PY{o}{\\PYZhy{}}\\PY{n}{np}\\PY{o}{.}\\PY{n}{diag}\\PY{p}{(}\\PY{n}{np}\\PY{o}{.}\\PY{n}{array}\\PY{p}{(}\\PY{p}{[}\\PY{l+m+mf}{1.0}\\PY{p}{,} \\PY{l+m+mf}{1.0}\\PY{p}{,} \\PY{l+m+mf}{1.0}\\PY{p}{]}\\PY{p}{)}\\PY{p}{)}\n \\PY{n}{jac}\\PY{p}{[}\\PY{p}{(}\\PY{l+s+s1}{\\PYZsq{}}\\PY{l+s+s1}{y}\\PY{l+s+s1}{\\PYZsq{}}\\PY{p}{,} \\PY{l+s+s1}{\\PYZsq{}}\\PY{l+s+s1}{y}\\PY{l+s+s1}{\\PYZsq{}}\\PY{p}{)}\\PY{p}{]} \\PY{o}{=} \\PY{n}{np}\\PY{o}{.}\\PY{n}{diag}\\PY{p}{(}\\PY{n}{np}\\PY{o}{.}\\PY{n}{array}\\PY{p}{(}\\PY{p}{[}\\PY{l+m+mf}{1.0}\\PY{p}{,} \\PY{l+m+mf}{1.0}\\PY{p}{,} \\PY{l+m+mf}{1.0}\\PY{p}{]}\\PY{p}{)}\\PY{p}{)}\n \\PY{n}{jac}\\PY{p}{[}\\PY{p}{(}\\PY{l+s+s1}{\\PYZsq{}}\\PY{l+s+s1}{y}\\PY{l+s+s1}{\\PYZsq{}}\\PY{p}{,} \\PY{l+s+s1}{\\PYZsq{}}\\PY{l+s+s1}{z}\\PY{l+s+s1}{\\PYZsq{}}\\PY{p}{)}\\PY{p}{]} \\PY{o}{=} \\PY{o}{\\PYZhy{}}\\PY{n}{np}\\PY{o}{.}\\PY{n}{diag}\\PY{p}{(}\\PY{n}{np}\\PY{o}{.}\\PY{n}{array}\\PY{p}{(}\\PY{p}{[}\\PY{l+m+mf}{2.0}\\PY{p}{,} \\PY{l+m+mf}{2.0}\\PY{p}{,} \\PY{l+m+mf}{2.0}\\PY{p}{]}\\PY{p}{)}\\PY{p}{)}\n\n \\PY{c+c1}{\\PYZsh{} State equation}\n \\PY{n}{jac}\\PY{p}{[}\\PY{p}{(}\\PY{l+s+s1}{\\PYZsq{}}\\PY{l+s+s1}{z}\\PY{l+s+s1}{\\PYZsq{}}\\PY{p}{,} \\PY{l+s+s1}{\\PYZsq{}}\\PY{l+s+s1}{z}\\PY{l+s+s1}{\\PYZsq{}}\\PY{p}{)}\\PY{p}{]} \\PY{o}{=} \\PY{p}{(}\\PY{n}{inputs}\\PY{p}{[}\\PY{l+s+s1}{\\PYZsq{}}\\PY{l+s+s1}{x}\\PY{l+s+s1}{\\PYZsq{}}\\PY{p}{]} \\PY{o}{+} \\PY{l+m+mf}{1.0}\\PY{p}{)} \\PY{o}{*} \\PY{n}{np}\\PY{o}{.}\\PY{n}{eye}\\PY{p}{(}\\PY{l+m+mi}{3}\\PY{p}{)}\n \\PY{n}{jac}\\PY{p}{[}\\PY{p}{(}\\PY{l+s+s1}{\\PYZsq{}}\\PY{l+s+s1}{z}\\PY{l+s+s1}{\\PYZsq{}}\\PY{p}{,} \\PY{l+s+s1}{\\PYZsq{}}\\PY{l+s+s1}{x}\\PY{l+s+s1}{\\PYZsq{}}\\PY{p}{)}\\PY{p}{]} \\PY{o}{=} \\PY{n}{outputs}\\PY{p}{[}\\PY{l+s+s1}{\\PYZsq{}}\\PY{l+s+s1}{z}\\PY{l+s+s1}{\\PYZsq{}}\\PY{p}{]} \\PY{o}{*} \\PY{n}{np}\\PY{o}{.}\\PY{n}{eye}\\PY{p}{(}\\PY{l+m+mi}{3}\\PY{p}{)}\n\\end{Verbatim}\n", "application/papermill.record/text/plain": "class ImplCompTwoStatesArrays(om.ImplicitComponent):\n \"\"\"\n A Simple Implicit Component with an additional output equation.\n\n f(x,z) = xz + z - 4\n y = x + 2z\n\n Sol : when x = 0.5, z = 2.666\n Sol : when x = 2.0, z = 1.333\n\n Coupled derivs:\n\n y = x + 8/(x+1)\n dy_dx = 1 - 8/(x+1)**2 = -2.5555555555555554\n\n z = 4/(x+1)\n dz_dx = -4/(x+1)**2 = -1.7777777777777777\n \"\"\"\n\n def setup(self):\n self.add_input('x', np.zeros((3, 1)))\n self.add_output('y', np.zeros((3, 1)))\n self.add_output('z', 2.0*np.ones((3, 1)), lower=1.5,\n upper=np.array([2.6, 2.5, 2.65]).reshape((3,1)))\n\n self.maxiter = 10\n self.atol = 1.0e-12\n\n def setup_partials(self):\n self.declare_partials(of='*', wrt='*')\n\n def apply_nonlinear(self, inputs, outputs, residuals):\n \"\"\"\n Don't solve; just calculate the residual.\n \"\"\"\n\n x = inputs['x']\n y = outputs['y']\n z = outputs['z']\n\n residuals['y'] = y - x - 2.0*z\n residuals['z'] = x*z + z - 4.0\n\n def linearize(self, inputs, outputs, jac):\n \"\"\"\n Analytical derivatives.\n \"\"\"\n\n # Output equation\n jac[('y', 'x')] = -np.diag(np.array([1.0, 1.0, 1.0]))\n jac[('y', 'y')] = np.diag(np.array([1.0, 1.0, 1.0]))\n jac[('y', 'z')] = -np.diag(np.array([2.0, 2.0, 2.0]))\n\n # State equation\n jac[('z', 'z')] = (inputs['x'] + 1.0) * np.eye(3)\n jac[('z', 'x')] = outputs['z'] * np.eye(3)" }, "metadata": { "scrapbook": { "mime_prefix": "application/papermill.record/", "name": "code_src19" } }, "output_type": "display_data" } ], "source": [ "from openmdao.utils.notebook_utils import get_code\n", "from myst_nb import glue\n", "glue(\"code_src19\", get_code(\"openmdao.test_suite.components.implicit_newton_linesearch.ImplCompTwoStatesArrays\"), display=False)" ] }, { "cell_type": "markdown", "id": "058757be", "metadata": { "papermill": { "duration": 0.001677, "end_time": "2026-10-02T14:42:15.183481+00:00", "exception": false, "start_time": "2026-10-02T14:42:15.181804+00:00", "status": "completed" }, "tags": [] }, "source": [ ":::{dropdown} `ImplCompTwoStatesArrays` class definition \n", "\n", "{glue:}`code_src19`\n", ":::" ] }, { "cell_type": "code", "execution_count": 3, "id": "f29eea07", "metadata": { "execution": { "iopub.execute_input": "2026-10-02T14:42:15.186987Z", "iopub.status.busy": "2026-10-02T14:42:15.186808Z", "iopub.status.idle": "2026-10-02T14:42:16.422446Z", "shell.execute_reply": "2026-10-02T14:42:16.421753Z" }, "papermill": { "duration": 1.238628, "end_time": "2026-10-02T14:42:16.423488+00:00", "exception": false, "start_time": "2026-10-02T14:42:15.184860+00:00", "status": "completed" }, "tags": [] }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "[1790952136.398976] [runnervm8df0l:7030 :0] ib_iface.c:1269 UCX ERROR mana_0: iface 0x55b5fec69280 failed to create UD QP TX wr:256 sge:6 inl:64 resp:0 RX wr:4096 sge:1 resp:0 failed: Operation not supported\n", "[1790952136.399263] [runnervm8df0l:7030 :0] ucp_worker.c:1412 UCX ERROR uct_iface_open(ud_verbs/mana_0:1) failed: Input/output error\n", "NL: NewtonSolver 'NL: Newton' on system '' failed to converge in 10 iterations.\n", "[1.5]\n", "[1.5]\n", "[1.5]\n" ] }, { "name": "stderr", "output_type": "stream", "text": [ "[runnervm8df0l:07030] pml_ucx.c:313 Error: Failed to create UCP worker\n" ] } ], "source": [ "import numpy as np\n", "import openmdao.api as om\n", "\n", "from openmdao.test_suite.components.implicit_newton_linesearch import ImplCompTwoStatesArrays\n", "\n", "top = om.Problem()\n", "top.model.add_subsystem('comp', ImplCompTwoStatesArrays(), promotes_inputs=['x'])\n", "\n", "top.model.nonlinear_solver = om.NewtonSolver(solve_subsystems=False)\n", "top.model.nonlinear_solver.options['maxiter'] = 10\n", "top.model.linear_solver = om.ScipyKrylov()\n", "\n", "top.model.nonlinear_solver.linesearch = om.ArmijoGoldsteinLS()\n", "\n", "top.setup()\n", "top.set_val('x', np.array([2., 2, 2]).reshape(3, 1))\n", "# Test lower bounds: should go to the lower bound and stall\n", "top.set_val('comp.y', 0.)\n", "top.set_val('comp.z', 1.6)\n", "top.run_model()\n", "\n", "for ind in range(3):\n", " print(top.get_val('comp.z', indices=ind))" ] }, { "cell_type": "code", "execution_count": 4, "id": "24887749", "metadata": { "execution": { "iopub.execute_input": "2026-10-02T14:42:16.428995Z", "iopub.status.busy": "2026-10-02T14:42:16.428787Z", "iopub.status.idle": "2026-10-02T14:42:16.432760Z", "shell.execute_reply": "2026-10-02T14:42:16.432037Z" }, "papermill": { "duration": 0.00737, "end_time": "2026-10-02T14:42:16.433303+00:00", "exception": false, "start_time": "2026-10-02T14:42:16.425933+00:00", "status": "completed" }, "tags": [ "remove-input", "remove-output" ] }, "outputs": [], "source": [ "from openmdao.utils.assert_utils import assert_near_equal\n", "\n", "for ind in range(3):\n", " assert_near_equal(top.get_val('comp.z', indices=ind), [1.5], 1e-8)" ] }, { "cell_type": "markdown", "id": "79c67189", "metadata": { "papermill": { "duration": 0.001595, "end_time": "2026-10-02T14:42:16.436611+00:00", "exception": false, "start_time": "2026-10-02T14:42:16.435016+00:00", "status": "completed" }, "tags": [] }, "source": [ "## ArmijoGoldsteinLS Options" ] }, { "cell_type": "code", "execution_count": 5, "id": "0ef55791", "metadata": { "execution": { "iopub.execute_input": "2026-10-02T14:42:16.440768Z", "iopub.status.busy": "2026-10-02T14:42:16.440572Z", "iopub.status.idle": "2026-10-02T14:42:16.445640Z", "shell.execute_reply": "2026-10-02T14:42:16.444778Z" }, "papermill": { "duration": 0.007972, "end_time": "2026-10-02T14:42:16.446189+00:00", "exception": false, "start_time": "2026-10-02T14:42:16.438217+00:00", "status": "completed" }, "tags": [ "remove-input" ] }, "outputs": [ { "data": { "text/html": [ "\n", "\n", "\n", "\n", " \n", "\n", "\n", "

\n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", "
OptionDefaultAcceptable ValuesAcceptable TypesDescription
alpha1.0N/AN/AInitial line search step.
atol1e-10N/AN/Aabsolute error tolerance
bound_enforcementscalar['vector', 'scalar', 'wall']N/AIf this is set to 'vector', the entire vector is backtracked together when a bound is violated. If this is set to 'scalar', only the violating entries are set to the bound and then the backtracking occurs on the vector as a whole. If this is set to 'wall', only the violating entries are set to the bound, and then the backtracking follows the wall - i.e., the violating entries do not change during the line search.
c0.1N/AN/ASlope parameter for line of sufficient decrease. The larger the step, the more decrease is required to terminate the line search.
debug_printFalse[True, False]['bool']If True, the values of input and output variables at the start of iteration are printed and written to a file after a failure to converge or when encountering aninvalid value in the residual.
err_on_non_convergeFalse[True, False]['bool']When True, AnalysisError will be raised if we don't converge.
iprint1N/A['int']whether to print output
maxiter5N/A['int']maximum number of iterations
methodArmijo['Armijo', 'Goldstein']N/AMethod to calculate stopping condition.
print_bound_enforceFalseN/AN/ASet to True to print out names and values of variables that are pulled back to their bounds.
restart_from_successfulFalse[True, False]['bool']If True, the states are cached after a successful solve and used to restart the solver in the case of a failed solve.
retry_on_analysis_errorTrueN/AN/ABacktrack and retry if an AnalysisError is raised.
rho0.5N/AN/AContraction factor.
rtol1e-10N/AN/Arelative error tolerance
stall_limit0N/AN/ANumber of iterations after which, if the residual norms are identical within the stall_tol, then terminate as if max iterations were reached. Default is 0, which disables this feature.
stall_tol1e-12N/AN/AWhen stall checking is enabled, the threshold below which the residual norm is considered unchanged.
stall_tol_typerel['abs', 'rel']N/ASpecifies whether the absolute or relative norm of the residual is used for stall detection.
\n", "\n", "\n" ], "text/plain": [ "" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "om.show_options_table(\"openmdao.solvers.linesearch.backtracking.ArmijoGoldsteinLS\")" ] }, { "cell_type": "markdown", "id": "840c51ca", "metadata": { "papermill": { "duration": 0.001578, "end_time": "2026-10-02T14:42:16.449924+00:00", "exception": false, "start_time": "2026-10-02T14:42:16.448346+00:00", "status": "completed" }, "tags": [] }, "source": [ "## ArmijoGoldsteinLS Constructor\n", "\n", "The call signature for the `ArmijoGoldsteinLS` constructor is:\n", "\n", "```{eval-rst}\n", " .. automethod:: openmdao.solvers.linesearch.backtracking.ArmijoGoldsteinLS.__init__\n", " :noindex:\n", "```\n", "\n", "## ArmijoGoldsteinLS Option Examples\n", "\n", "**bound_enforcement**\n", "\n", "ArmijoGoldsteinLS includes the `bound_enforcement` option in its options dictionary. This option has a dual role:\n", "\n", "1. Behavior of the non-bounded variables when the bounded ones are capped.\n", "2. Direction of the further backtracking.\n", "\n", "There are three different acceptable values for bounds-enforcement schemes available in this option.\n", "\n", "With \"scalar\" bounds enforcement, only the variables that violate their bounds are pulled back to feasible values; the\n", "remaining values are kept at the Newton-stepped point. This changes the direction of the backtracking vector so that\n", "it still moves in the direction of the initial point.\n", "\n", "![BT2](images/BT2.jpg)\n", "\n", "With \"vector\" bounds enforcement, the solution in the output vector is pulled back to a point where none of the\n", "variables violate any upper or lower bounds. Further backtracking continues along the Newton gradient direction vector back towards the\n", "initial point.\n", "\n", "![BT1](images/BT1.jpg)\n", "\n", "With \"wall\" bounds enforcement, only the variables that violate their bounds are pulled back to feasible values; the\n", "remaining values are kept at the Newton-stepped point. Further backtracking only occurs in the direction of the non-violating\n", "variables, so that it will move along the wall.\n", "\n", "![BT3](images/BT3.jpg)\n", "\n", "Here are examples of each acceptable value for the **bound_enforcement** option:\n", "\n", "- bound_enforcement: vector\n", "\n", " The `bound_enforcement` option in the options dictionary is used to specify how the output bounds\n", " are enforced. When this is set to \"vector\", the output vector is rolled back along the computed gradient until\n", " it reaches a point where the earliest bound violation occurred. The backtracking continues along the original\n", " computed gradient.\n" ] }, { "cell_type": "code", "execution_count": 6, "id": "5a1a9eb1", "metadata": { "execution": { "iopub.execute_input": "2026-10-02T14:42:16.453691Z", "iopub.status.busy": "2026-10-02T14:42:16.453550Z", "iopub.status.idle": "2026-10-02T14:42:16.469803Z", "shell.execute_reply": "2026-10-02T14:42:16.469155Z" }, "papermill": { "duration": 0.018879, "end_time": "2026-10-02T14:42:16.470275+00:00", "exception": false, "start_time": "2026-10-02T14:42:16.451396+00:00", "status": "completed" }, "tags": [] }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "NL: NewtonSolver 'NL: Newton' on system '' failed to converge in 10 iterations.\n", "[1.5]\n", "[1.5]\n", "[1.5]\n" ] } ], "source": [ "from openmdao.test_suite.components.implicit_newton_linesearch import ImplCompTwoStatesArrays\n", "\n", "top = om.Problem()\n", "top.model.add_subsystem('comp', ImplCompTwoStatesArrays(), promotes_inputs=['x'])\n", "\n", "top.model.nonlinear_solver = om.NewtonSolver(solve_subsystems=False)\n", "top.model.nonlinear_solver.options['maxiter'] = 10\n", "top.model.linear_solver = om.ScipyKrylov()\n", "\n", "top.model.nonlinear_solver.linesearch = om.ArmijoGoldsteinLS(bound_enforcement='vector')\n", "\n", "top.setup()\n", "\n", "top.set_val('x', np.array([2., 2, 2]).reshape(3, 1))\n", "\n", "# Test lower bounds: should go to the lower bound and stall\n", "top.set_val('comp.y', 0.)\n", "top.set_val('comp.z', 1.6)\n", "top.run_model()\n", "\n", "for ind in range(3):\n", " print(top.get_val('comp.z', indices=ind))" ] }, { "cell_type": "code", "execution_count": 7, "id": "25c6f2f6", "metadata": { "execution": { "iopub.execute_input": "2026-10-02T14:42:16.475522Z", "iopub.status.busy": "2026-10-02T14:42:16.475331Z", "iopub.status.idle": "2026-10-02T14:42:16.478394Z", "shell.execute_reply": "2026-10-02T14:42:16.477664Z" }, "papermill": { "duration": 0.006397, "end_time": "2026-10-02T14:42:16.478875+00:00", "exception": false, "start_time": "2026-10-02T14:42:16.472478+00:00", "status": "completed" }, "tags": [ "remove-input", "remove-output" ] }, "outputs": [], "source": [ "for ind in range(3):\n", " assert_near_equal(top.get_val('comp.z', indices=ind), [1.5], 1e-8)" ] }, { "cell_type": "markdown", "id": "0781d0aa", "metadata": { "papermill": { "duration": 0.0015, "end_time": "2026-10-02T14:42:16.481954+00:00", "exception": false, "start_time": "2026-10-02T14:42:16.480454+00:00", "status": "completed" }, "tags": [] }, "source": [ "- bound_enforcement: scalar\n", "\n", " The `bound_enforcement` option in the options dictionary is used to specify how the output bounds\n", " are enforced. When this is set to \"scaler\", then the only indices in the output vector that are rolled back\n", " are the ones that violate their upper or lower bounds. The backtracking continues along the modified gradient." ] }, { "cell_type": "code", "execution_count": 8, "id": "58028ba4", "metadata": { "execution": { "iopub.execute_input": "2026-10-02T14:42:16.494171Z", "iopub.status.busy": "2026-10-02T14:42:16.493980Z", "iopub.status.idle": "2026-10-02T14:42:16.505396Z", "shell.execute_reply": "2026-10-02T14:42:16.504713Z" }, "papermill": { "duration": 0.022452, "end_time": "2026-10-02T14:42:16.505942+00:00", "exception": false, "start_time": "2026-10-02T14:42:16.483490+00:00", "status": "completed" }, "tags": [] }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "NL: NewtonSolver 'NL: Newton' on system '' failed to converge in 10 iterations.\n" ] } ], "source": [ "from openmdao.test_suite.components.implicit_newton_linesearch import ImplCompTwoStatesArrays\n", "\n", "top = om.Problem()\n", "top.model.add_subsystem('comp', ImplCompTwoStatesArrays(), promotes_inputs=['x'])\n", "\n", "top.model.nonlinear_solver = om.NewtonSolver(solve_subsystems=False)\n", "top.model.nonlinear_solver.options['maxiter'] = 10\n", "top.model.linear_solver = om.ScipyKrylov()\n", "\n", "ls = top.model.nonlinear_solver.linesearch = om.ArmijoGoldsteinLS(bound_enforcement='scalar')\n", "\n", "top.setup()\n", "top.set_val('x', np.array([2., 2, 2]).reshape(3, 1))\n", "top.run_model()" ] }, { "cell_type": "code", "execution_count": 9, "id": "d92c39c4", "metadata": { "execution": { "iopub.execute_input": "2026-10-02T14:42:16.511131Z", "iopub.status.busy": "2026-10-02T14:42:16.510941Z", "iopub.status.idle": "2026-10-02T14:42:16.522292Z", "shell.execute_reply": "2026-10-02T14:42:16.521535Z" }, "papermill": { "duration": 0.014966, "end_time": "2026-10-02T14:42:16.522865+00:00", "exception": false, "start_time": "2026-10-02T14:42:16.507899+00:00", "status": "completed" }, "tags": [] }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "NL: NewtonSolver 'NL: Newton' on system '' failed to converge in 10 iterations.\n" ] } ], "source": [ "# Test lower bounds: should stop just short of the lower bound\n", "top.set_val('comp.y', 0.)\n", "top.set_val('comp.z', 1.6)\n", "top.run_model()" ] }, { "cell_type": "markdown", "id": "01013678", "metadata": { "papermill": { "duration": 0.002727, "end_time": "2026-10-02T14:42:16.527996+00:00", "exception": false, "start_time": "2026-10-02T14:42:16.525269+00:00", "status": "completed" }, "tags": [] }, "source": [ "- bound_enforcement: wall\n", "\n", " The `bound_enforcement` option in the options dictionary is used to specify how the output bounds\n", " are enforced. When this is set to \"wall\", then the only indices in the output vector that are rolled back\n", " are the ones that violate their upper or lower bounds. The backtracking continues along a modified gradient\n", " direction that follows the boundary of the violated output bounds." ] }, { "cell_type": "code", "execution_count": 10, "id": "568fb564", "metadata": { "execution": { "iopub.execute_input": "2026-10-02T14:42:16.546125Z", "iopub.status.busy": "2026-10-02T14:42:16.545989Z", "iopub.status.idle": "2026-10-02T14:42:16.561811Z", "shell.execute_reply": "2026-10-02T14:42:16.561172Z" }, "papermill": { "duration": 0.026522, "end_time": "2026-10-02T14:42:16.562428+00:00", "exception": false, "start_time": "2026-10-02T14:42:16.535906+00:00", "status": "completed" }, "tags": [] }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "NL: NewtonSolver 'NL: Newton' on system '' failed to converge in 10 iterations.\n", "[2.6]\n", "[2.5]\n", "[2.65]\n" ] } ], "source": [ "from openmdao.test_suite.components.implicit_newton_linesearch import ImplCompTwoStatesArrays\n", "\n", "top = om.Problem()\n", "top.model.add_subsystem('comp', ImplCompTwoStatesArrays(), promotes_inputs=['x'])\n", "\n", "top.model.nonlinear_solver = om.NewtonSolver(solve_subsystems=False)\n", "top.model.nonlinear_solver.options['maxiter'] = 10\n", "top.model.linear_solver = om.ScipyKrylov()\n", "\n", "top.model.nonlinear_solver.linesearch = om.ArmijoGoldsteinLS(bound_enforcement='wall')\n", "\n", "top.setup()\n", "\n", "top.set_val('x', np.array([0.5, 0.5, 0.5]).reshape(3, 1))\n", "\n", "# Test upper bounds: should go to the upper bound and stall\n", "top.set_val('comp.y', 0.)\n", "top.set_val('comp.z', 2.4)\n", "top.run_model()\n", "\n", "print(top.get_val('comp.z', indices=0))\n", "print(top.get_val('comp.z', indices=1))\n", "print(top.get_val('comp.z', indices=2))" ] }, { "cell_type": "code", "execution_count": 11, "id": "2bb60b0b", "metadata": { "execution": { "iopub.execute_input": "2026-10-02T14:42:16.567185Z", "iopub.status.busy": "2026-10-02T14:42:16.567009Z", "iopub.status.idle": "2026-10-02T14:42:16.571047Z", "shell.execute_reply": "2026-10-02T14:42:16.570331Z" }, "papermill": { "duration": 0.007126, "end_time": "2026-10-02T14:42:16.571502+00:00", "exception": false, "start_time": "2026-10-02T14:42:16.564376+00:00", "status": "completed" }, "tags": [ "remove-input", "remove-output" ] }, "outputs": [ { "data": { "text/plain": [ "np.float64(0.0)" ] }, "execution_count": 11, "metadata": {}, "output_type": "execute_result" } ], "source": [ "assert_near_equal(top.get_val('comp.z', indices=0), [2.6], 1e-8)\n", "assert_near_equal(top.get_val('comp.z', indices=1), [2.5], 1e-8)\n", "assert_near_equal(top.get_val('comp.z', indices=2), [2.65], 1e-8)" ] }, { "cell_type": "markdown", "id": "351c5d47", "metadata": { "papermill": { "duration": 0.001599, "end_time": "2026-10-02T14:42:16.574808+00:00", "exception": false, "start_time": "2026-10-02T14:42:16.573209+00:00", "status": "completed" }, "tags": [] }, "source": [ "**maxiter**\n", "\n", " The \"maxiter\" option is a termination criteria that specifies the maximum number of backtracking steps to allow.\n", "\n", "**alpha**\n", "\n", " The \"alpha\" option is used to specify the initial length of the Newton step. Since NewtonSolver assumes a\n", " step size of 1.0, this value usually shouldn't be changed.\n", "\n", "**rho**\n", "\n", " The \"rho\" option controls how far to backtrack in each successive backtracking step. It is applied as a multiplier to\n", " the step, so a higher value (approaching 1.0) is a very small step, while a low value takes you close to the initial\n", " point. The default value is 0.5.\n", "\n", "**c**\n", "\n", " In the `ArmijoGoldsteinLS`, the \"c\" option is a multiplier on the slope check. Setting it to a smaller value means a more\n", " gentle slope will satisfy the condition and terminate.\n", "\n", "**print_bound_enforce**\n", "\n", " When the \"print_bound_enforce\" option is set to True, the line-search will print the name and values of any variables\n", " that exceeded their lower or upper bounds and were drawn back during bounds enforcement." ] }, { "cell_type": "code", "execution_count": 12, "id": "01c6ac35", "metadata": { "execution": { "iopub.execute_input": "2026-10-02T14:42:16.579178Z", "iopub.status.busy": "2026-10-02T14:42:16.578986Z", "iopub.status.idle": "2026-10-02T14:42:16.588719Z", "shell.execute_reply": "2026-10-02T14:42:16.588002Z" }, "papermill": { "duration": 0.012642, "end_time": "2026-10-02T14:42:16.589324+00:00", "exception": false, "start_time": "2026-10-02T14:42:16.576682+00:00", "status": "completed" }, "tags": [] }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "NL: Newton 0 ; 9.1126286 1\n", "| LN: SCIPY 0 ; 0.18556153 1\n", "| LN: SCIPY 1 ; 5.87797659e-16 3.16766982e-15\n", "| LS: BCHK 0 ; 5.69539287 0.625\n", "NL: Newton 1 ; 5.69539287 0.625\n", "| LN: SCIPY 0 ; 0.0742246119 1\n", "| LN: SCIPY 1 ; 2.20006239e-16 2.96406048e-15\n", "| LS: BCHK 0 ; 5.69539287 1\n", "NL: Newton 2 ; 5.69539287 0.625\n", "NL: NewtonSolver 'NL: Newton' on system '' failed to converge in 2 iterations.\n", "[1.5]\n", "[1.5]\n", "[1.5]\n" ] }, { "name": "stderr", "output_type": "stream", "text": [ "/home/runner/work/OpenMDAO/OpenMDAO/.pixi/envs/dev/lib/python3.13/site-packages/openmdao/solvers/linesearch/backtracking.py:39: SolverWarning:'comp.z' exceeds lower bounds\n", " Val: [1.33333333 1.33333333 1.33333333]\n", " Lower: [1.5 1.5 1.5]\n", "\n", "/home/runner/work/OpenMDAO/OpenMDAO/.pixi/envs/dev/lib/python3.13/site-packages/openmdao/solvers/linesearch/backtracking.py:39: SolverWarning:'comp.z' exceeds lower bounds\n", " Val: [1.33333333 1.33333333 1.33333333]\n", " Lower: [1.5 1.5 1.5]\n", "\n" ] } ], "source": [ "from openmdao.test_suite.components.implicit_newton_linesearch import ImplCompTwoStatesArrays\n", "\n", "top = om.Problem()\n", "top.model.add_subsystem('comp', ImplCompTwoStatesArrays(), promotes_inputs=['x'])\n", "\n", "newt = top.model.nonlinear_solver = om.NewtonSolver(solve_subsystems=False)\n", "top.model.nonlinear_solver.options['maxiter'] = 2\n", "top.model.linear_solver = om.ScipyKrylov()\n", "\n", "ls = newt.linesearch = om.BoundsEnforceLS(bound_enforcement='vector')\n", "ls.options['print_bound_enforce'] = True\n", "\n", "top.set_solver_print(level=2)\n", "\n", "\n", "top.setup()\n", "top.set_val('x', np.array([2., 2, 2]).reshape(3, 1))\n", "\n", "# Test lower bounds: should go to the lower bound and stall\n", "top.set_val('comp.y', 0.)\n", "top.set_val('comp.z', 1.6)\n", "top.run_model()\n", "\n", "for ind in range(3):\n", " print(top.get_val('comp.z', indices=ind))" ] }, { "cell_type": "code", "execution_count": 13, "id": "cafe1686", "metadata": { "execution": { "iopub.execute_input": "2026-10-02T14:42:16.593888Z", "iopub.status.busy": "2026-10-02T14:42:16.593747Z", "iopub.status.idle": "2026-10-02T14:42:16.596839Z", "shell.execute_reply": "2026-10-02T14:42:16.596039Z" }, "papermill": { "duration": 0.006279, "end_time": "2026-10-02T14:42:16.597428+00:00", "exception": false, "start_time": "2026-10-02T14:42:16.591149+00:00", "status": "completed" }, "tags": [ "remove-input", "remove-output" ] }, "outputs": [], "source": [ "for ind in range(3):\n", " assert_near_equal(top.get_val('comp.z', indices=ind), [1.5], 1e-8)" ] }, { "cell_type": "markdown", "id": "6d6f9ef9", "metadata": { "papermill": { "duration": 0.002499, "end_time": "2026-10-02T14:42:16.602423+00:00", "exception": false, "start_time": "2026-10-02T14:42:16.599924+00:00", "status": "completed" }, "tags": [] }, "source": [ "- retry_on_analysis_error\n", "\n", " By default, the ArmijoGoldsteinLS linesearch will backtrack if the model raises an AnalysisError, which can happen if the component explicitly raises it, or a subsolver hits its iteration limit with the 'err_on_non_converge' option set to True. If you would rather terminate on an AnalysisError, you can set this option to False.\n" ] } ], "metadata": { "celltoolbar": "Tags", "kernelspec": { "display_name": "Python 3", "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.13.14" }, "orphan": true, "papermill": { "default_parameters": {}, "duration": 5.440013, "end_time": "2026-10-02T14:42:17.323046+00:00", "environment_variables": {}, "exception": null, "input_path": "/home/runner/work/OpenMDAO/OpenMDAO/openmdao/docs/openmdao_book/features/building_blocks/solvers/armijo_goldstein.ipynb", "output_path": "/home/runner/work/OpenMDAO/OpenMDAO/openmdao/docs/_executed_book/features/building_blocks/solvers/armijo_goldstein.ipynb", "parameters": {}, "start_time": "2026-10-02T14:42:11.883033+00:00", "version": "2.7.0" } }, "nbformat": 4, "nbformat_minor": 5 }