{ "cells": [ { "cell_type": "code", "execution_count": 1, "id": "ee6769f6", "metadata": { "execution": { "iopub.execute_input": "2026-10-02T14:42:19.477258Z", "iopub.status.busy": "2026-10-02T14:42:19.476906Z", "iopub.status.idle": "2026-10-02T14:42:19.481774Z", "shell.execute_reply": "2026-10-02T14:42:19.481113Z" }, "papermill": { "duration": 0.008964, "end_time": "2026-10-02T14:42:19.482448+00:00", "exception": false, "start_time": "2026-10-02T14:42:19.473484+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": "568835aa", "metadata": { "papermill": { "duration": 0.04314, "end_time": "2026-10-02T14:42:19.527134+00:00", "exception": false, "start_time": "2026-10-02T14:42:19.483994+00:00", "status": "completed" }, "tags": [] }, "source": [ "# BoundsEnforceLS\n", "\n", "The BoundsEnforceLS only backtracks until variables violate their upper and lower bounds.\n", "\n", "Here is a simple example where BoundsEnforceLS 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": "a13c2cbd", "metadata": { "execution": { "iopub.execute_input": "2026-10-02T14:42:19.530524Z", "iopub.status.busy": "2026-10-02T14:42:19.530325Z", "iopub.status.idle": "2026-10-02T14:42:22.165588Z", "shell.execute_reply": "2026-10-02T14:42:22.164927Z" }, "papermill": { "duration": 2.637783, "end_time": "2026-10-02T14:42:22.166167+00:00", "exception": false, "start_time": "2026-10-02T14:42:19.528384+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_src20" } }, "output_type": "display_data" } ], "source": [ "from openmdao.utils.notebook_utils import get_code\n", "from myst_nb import glue\n", "glue(\"code_src20\", get_code(\"openmdao.test_suite.components.implicit_newton_linesearch.ImplCompTwoStatesArrays\"), display=False)" ] }, { "cell_type": "markdown", "id": "05453939", "metadata": { "papermill": { "duration": 0.001105, "end_time": "2026-10-02T14:42:22.168650+00:00", "exception": false, "start_time": "2026-10-02T14:42:22.167545+00:00", "status": "completed" }, "tags": [] }, "source": [ ":::{dropdown} `ImplCompTwoStatesArrays` class definition \n", "\n", "{glue:}`code_src20`\n", ":::" ] }, { "cell_type": "code", "execution_count": 3, "id": "aad91883", "metadata": { "execution": { "iopub.execute_input": "2026-10-02T14:42:22.171864Z", "iopub.status.busy": "2026-10-02T14:42:22.171661Z", "iopub.status.idle": "2026-10-02T14:42:23.390934Z", "shell.execute_reply": "2026-10-02T14:42:23.390044Z" }, "papermill": { "duration": 1.222264, "end_time": "2026-10-02T14:42:23.392062+00:00", "exception": false, "start_time": "2026-10-02T14:42:22.169798+00:00", "status": "completed" }, "tags": [] }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "[1790952143.374906] [runnervm8df0l:7077 :0] ib_iface.c:1269 UCX ERROR mana_0: iface 0x55862d26b600 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", "[1790952143.375183] [runnervm8df0l:7077 :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:07077] pml_ucx.c:313 Error: Failed to create UCP worker\n" ] } ], "source": [ "import numpy as np\n", "\n", "import openmdao.api as om\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.BoundsEnforceLS()\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": 4, "id": "51065d3c", "metadata": { "execution": { "iopub.execute_input": "2026-10-02T14:42:23.397341Z", "iopub.status.busy": "2026-10-02T14:42:23.397120Z", "iopub.status.idle": "2026-10-02T14:42:23.400888Z", "shell.execute_reply": "2026-10-02T14:42:23.400344Z" }, "papermill": { "duration": 0.007162, "end_time": "2026-10-02T14:42:23.401652+00:00", "exception": false, "start_time": "2026-10-02T14:42:23.394490+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": "804140de", "metadata": { "papermill": { "duration": 0.001548, "end_time": "2026-10-02T14:42:23.404809+00:00", "exception": false, "start_time": "2026-10-02T14:42:23.403261+00:00", "status": "completed" }, "tags": [] }, "source": [ "## BoundsEnforceLS Options" ] }, { "cell_type": "code", "execution_count": 5, "id": "3df92ffe", "metadata": { "execution": { "iopub.execute_input": "2026-10-02T14:42:23.412038Z", "iopub.status.busy": "2026-10-02T14:42:23.411822Z", "iopub.status.idle": "2026-10-02T14:42:23.416346Z", "shell.execute_reply": "2026-10-02T14:42:23.415727Z" }, "papermill": { "duration": 0.010368, "end_time": "2026-10-02T14:42:23.416787+00:00", "exception": false, "start_time": "2026-10-02T14:42:23.406419+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", "
OptionDefaultAcceptable ValuesAcceptable TypesDescription
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.
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.
iprint1N/A['int']whether to print output
print_bound_enforceFalseN/AN/ASet to True to print out names and values of variables that are pulled back to their bounds.
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.BoundsEnforceLS\")" ] }, { "cell_type": "markdown", "id": "fe6625a7", "metadata": { "papermill": { "duration": 0.001757, "end_time": "2026-10-02T14:42:23.420270+00:00", "exception": false, "start_time": "2026-10-02T14:42:23.418513+00:00", "status": "completed" }, "tags": [] }, "source": [ "## BoundsEnforceLS Constructor\n", "\n", "The call signature for the `BoundsEnforceLS` constructor is:\n", "\n", "```{eval-rst}\n", " .. automethod:: openmdao.solvers.linesearch.backtracking.BoundsEnforceLS.__init__\n", " :noindex:\n", "```\n", "\n", "## BoundsEnforceLS Option Examples\n", "\n", "**bound_enforcement**\n", "\n", "BoundsEnforceLS 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 difference 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. This is the default bounds enforcement for `BoundsEnforceLS`.\n", "\n", "![BT2](images/BT2.jpg)\n", "\n", "With \"vector\" bounds enforcement, the solution in the output vector is pulled back in unison 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 remaining values are kept at the Newton-stepped point. Further backtracking only occurs in the direction of the non-violating variables, so that it will move along the wall.\n", "\n", "```{Note}\n", "When using BoundsEnforceLS linesearch, the `scalar` and `wall` methods are exactly the same because no further\n", "backtracking is performed.\n", "```\n", "\n", "![BT3](images/BT3.jpg)\n", "\n", "Here are a few examples of this 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." ] }, { "cell_type": "code", "execution_count": 6, "id": "b814ff07", "metadata": { "execution": { "iopub.execute_input": "2026-10-02T14:42:23.424873Z", "iopub.status.busy": "2026-10-02T14:42:23.424686Z", "iopub.status.idle": "2026-10-02T14:42:23.438303Z", "shell.execute_reply": "2026-10-02T14:42:23.437618Z" }, "papermill": { "duration": 0.016846, "end_time": "2026-10-02T14:42:23.438976+00:00", "exception": false, "start_time": "2026-10-02T14:42:23.422130+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.BoundsEnforceLS(bound_enforcement='vector')\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": 7, "id": "7d70f5db", "metadata": { "execution": { "iopub.execute_input": "2026-10-02T14:42:23.443258Z", "iopub.status.busy": "2026-10-02T14:42:23.443091Z", "iopub.status.idle": "2026-10-02T14:42:23.446283Z", "shell.execute_reply": "2026-10-02T14:42:23.445664Z" }, "papermill": { "duration": 0.00634, "end_time": "2026-10-02T14:42:23.447016+00:00", "exception": false, "start_time": "2026-10-02T14:42:23.440676+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": "fc58b908", "metadata": { "papermill": { "duration": 0.001796, "end_time": "2026-10-02T14:42:23.450323+00:00", "exception": false, "start_time": "2026-10-02T14:42:23.448527+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": "f393be12", "metadata": { "execution": { "iopub.execute_input": "2026-10-02T14:42:23.454608Z", "iopub.status.busy": "2026-10-02T14:42:23.454449Z", "iopub.status.idle": "2026-10-02T14:42:23.465473Z", "shell.execute_reply": "2026-10-02T14:42:23.464881Z" }, "papermill": { "duration": 0.014121, "end_time": "2026-10-02T14:42:23.466187+00:00", "exception": false, "start_time": "2026-10-02T14:42:23.452066+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", "top.model.nonlinear_solver.linesearch = om.BoundsEnforceLS(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": "4623cfa8", "metadata": { "execution": { "iopub.execute_input": "2026-10-02T14:42:23.470429Z", "iopub.status.busy": "2026-10-02T14:42:23.470308Z", "iopub.status.idle": "2026-10-02T14:42:23.479792Z", "shell.execute_reply": "2026-10-02T14:42:23.478973Z" }, "papermill": { "duration": 0.012268, "end_time": "2026-10-02T14:42:23.480320+00:00", "exception": false, "start_time": "2026-10-02T14:42:23.468052+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": "bdd55e67", "metadata": { "papermill": { "duration": 0.001772, "end_time": "2026-10-02T14:42:23.483650+00:00", "exception": false, "start_time": "2026-10-02T14:42:23.481878+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": "01789615", "metadata": { "execution": { "iopub.execute_input": "2026-10-02T14:42:23.488006Z", "iopub.status.busy": "2026-10-02T14:42:23.487888Z", "iopub.status.idle": "2026-10-02T14:42:23.501466Z", "shell.execute_reply": "2026-10-02T14:42:23.500741Z" }, "papermill": { "duration": 0.016685, "end_time": "2026-10-02T14:42:23.502110+00:00", "exception": false, "start_time": "2026-10-02T14:42:23.485425+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.BoundsEnforceLS(bound_enforcement='wall')\n", "\n", "top.setup()\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": "2d17a00b", "metadata": { "execution": { "iopub.execute_input": "2026-10-02T14:42:23.506670Z", "iopub.status.busy": "2026-10-02T14:42:23.506476Z", "iopub.status.idle": "2026-10-02T14:42:23.511368Z", "shell.execute_reply": "2026-10-02T14:42:23.510867Z" }, "papermill": { "duration": 0.007852, "end_time": "2026-10-02T14:42:23.511829+00:00", "exception": false, "start_time": "2026-10-02T14:42:23.503977+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)" ] } ], "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": 8.20267, "end_time": "2026-10-02T14:42:26.894454+00:00", "environment_variables": {}, "exception": null, "input_path": "/home/runner/work/OpenMDAO/OpenMDAO/openmdao/docs/openmdao_book/features/building_blocks/solvers/bounds_enforce.ipynb", "output_path": "/home/runner/work/OpenMDAO/OpenMDAO/openmdao/docs/_executed_book/features/building_blocks/solvers/bounds_enforce.ipynb", "parameters": {}, "start_time": "2026-10-02T14:42:18.691784+00:00", "version": "2.7.0" } }, "nbformat": 4, "nbformat_minor": 5 }