Initialization Module by michaelbynum · Pull Request #3912 · Pyomo/pyomo

michaelbynum · 2026-04-15T12:02:45Z

Fixes #3878

Summary/Motivation:

This PR adds a module to devel called initialization. The goal of the module is to provide methods to help initialize nonconvex nonlinear programming problems.

Changes proposed in this PR:

Add initialization module
Add an initialization method that uses a global optimization solver to find a feasible solution
Add an initialization method that builds a linear programming approximation using linear least squares
Add an initialization method that builds a piecewise linear approximation and iteratively refines it

Legal Acknowledgement

By contributing to this software project, I have read the contribution guide and agree to the following terms and conditions for my contribution:

I agree my contributions are submitted under the BSD license.
I represent I am authorized to make the contributions and grant the license. If my employer has rights to intellectual property that includes these contributions, I represent that I have received permission to make contributions and grant the required license on behalf of that employer.

…tion

Co-authored-by: Miranda Mundt <55767766+mrmundt@users.noreply.github.com>

…alization

Co-authored-by: Miranda Mundt <55767766+mrmundt@users.noreply.github.com>

michaelbynum · 2026-05-28T02:50:40Z

Looks like tests are failing due to a cplex release yesterday...

blnicho

@michaelbynum I have a few questions and suggestions but overall I think this looks great and I'm excited to try it out!

blnicho · 2026-05-28T23:09:36Z

      `Design of Experiments`
      `MPC`
      `AOS`
+      `NLP Initialization`


I don't think this change was necessary. I'm pretty sure this is just an old comment block we were using to track the documentation reorganization effort.

blnicho · 2026-05-28T23:59:07Z

+    # in all cases, try to solve the nlp before doing extra work
+    res = nlp_solver.solve(
+        nlp, load_solutions=False, raise_exception_on_nonoptimal_result=False
+    )
+    logger.info(f'solved NLP: {res.solution_status}, {res.termination_condition}')
+
+    if res.solution_status == SolutionStatus.optimal:
+        res.solution_loader.load_vars()
+        logger.info('NLP solved without any initialization')
+        return res


What do you think about adding an option to skip this initial NLP solve? I feel like this could add a lot of extra time for complex models and I can picture a scenario where a user has already tried and failed to solve it directly so they turn to this initialization tool and have to wait again for the NLP solver to fail (which could take a while even with the default solver settings).

blnicho · 2026-05-29T00:10:42Z

+            lb = -1e6
+        else:
+            lb = v.lb
+        if v.ub is None:
+            ub = 1e6


Should these be using the default_bound instead of being hard-coded to 1e6?

I don't think this code should exist. We set the bounds to default_bound before we ever get to this function. I'm going to delete it. Good catch.

jsiirola

This is really cool. Lots of comments / questions, but I don't think there was anything that should block merging.

jsiirola · 2026-05-28T18:15:47Z

@@ -0,0 +1 @@
+The purpose of this module is to provide methods for initializing nonlinear programming models.


Is this readme necessary? Should it just have a pointer to the documentation?

jsiirola · 2026-05-29T03:51:16Z

+    constraints in the model, m. If variable bounds cannot be obtained,
+    we use default_bound.
+    """
+    fbbt(m)


Is it worth only running FBBT on constraints that actually involve unbounded variables (instead of attempting to tighten all variables in the model)?

jsiirola · 2026-05-29T04:10:08Z

+    return opt
+
+
+def initialize_nlp(


Design question: would it better to make this a context manager instead of a "global gateway for all initialization routines"? The problem with the "gateway function" is that:

it has to be updated every time we add a new strategy/method

the API must be the superset of all the options / arguments that any method takes (and then there is the question about warning about arguments that the user provided, but are ignored by the chosen method)

Instead, if you made this a context manager, it might look like:

with initialization_context(m): res = initialize_with_piecewise_linear_approximation( nlp=m, mip_solver="xpress", max_iter=5, )

And InitializationContext could be as simple as

@context_manager def initialization_context(nlp): # get all variable bounds, domains, etc. to restore them later orig_var_data = [ (v, v.lower, v.upper, v.domain, v.fixed, v.value) for v in get_vars(nlp) ] yield for v, lb, ub, domain, fixed, value in orig_var_data: v.setlb(lb) v.setub(ub) v.domain = domain if fixed: assert v.value == value assert v.fixed else: v.unfix()

I don't know how to ensure users use the context manager. However, I agree. I'm going to just put this code into helper functions and ensure all the initialization functions call them.

jsiirola · 2026-05-29T04:10:32Z

+
+    # get all variable bounds, domains, etc. to restore them later
+    orig_vars = get_vars(nlp)
+    orig_var_data = ComponentMap(


This doesn't need to be a ComponentMap; a list is sufficient

jsiirola · 2026-05-29T05:20:32Z

+        elif lb is None:
+            ps = m.slacks.add()
+            ps.setlb(0)
+            con.set_value(body - ub - ps <= 0)
+        elif ub is None:
+            ns = m.slacks.add()
+            ns.setlb(0)
+            con.set_value(body - lb + ns >= 0)


Will you get an exception if the constraint is unbounded? Maybe catch that case above with

if lb == ub: if lb is not None: ps = m.slacks.add() # ... else: # trivial constraint; no slacks needed pass

jsiirola · 2026-05-29T05:24:55Z

+logger = logging.getLogger(__name__)
+
+
+def _minimize_infeasibility(m):


This is basically a reimplementation of the core.add_slack_variables transformation. Why not just use it?

jsiirola · 2026-05-29T05:35:43Z

+    _handlers[t] = _handle_node
+
+
+class _PWLRefinementVisitor(StreamBasedExpressionVisitor):


I lost the thread on the logic here, but this seems to do way more expression manipulation than I would think is necessary. I would have thought this could have been done in one pass through the model where you substituted the nonlinear expressions with a new variable. If you kept a list of all the "new" constraints, you would have only had to rebuild the refined piecewise linearization of those expressions (no walker needed)?

jsiirola · 2026-05-29T05:36:35Z

+                if val <= v.lb + 1e-6 + 1e-6 * abs(v.lb):
+                    val += 1e-5
+                if val >= v.ub - 1e-6 - 1e-6 * abs(v.ub):
+                    val -= 1e-5


Should these embedded constants be moved to either an argument or a global named constant?

jsiirola · 2026-05-29T05:37:14Z

+
+    if len(violations) == 0:
+        raise RuntimeError(
+            'Did not find any piecewise linear functions with variable values'


I do not understand this exception message. Can you clarify it?

blnicho · 2026-05-29T16:21:02Z

+    TerminationCondition,
+)
+from pyomo.contrib.solver.common.base import Availability, SolverBase
+import pytest


Suggested change

import pytest

from pyomo.common.unittest import pytest

…tialization.rst Co-authored-by: Bethany Nicholson <blnicho@users.noreply.github.com>

Co-authored-by: Bethany Nicholson <blnicho@users.noreply.github.com>

michaelbynum · 2026-05-30T00:11:04Z

Thanks for all the feedback! Working on this now.

michaelbynum added 30 commits January 29, 2026 15:19

merge observer_fix into intialization

00b3c27

Merge branch 'pwl_approx' into initialization

d2aae9f

Merge branch 'pwl_factorable_aggressive_substitution' into initializa…

b2fa0a5

…tion

Merge branch 'observer_gurobi_refactor' into initialization

fd06964

starting a module for initialization

d29a2cf

starting a module for initialization

8914a63

initialization

5ebfdd4

pwl initialization is almost working

488a539

debugging

e993623

initialization

aa450e1

Merge branch 'scip_port' into initialization

4945388

Merge branch 'pwl_approx' into initialization

ab9a46c

Merge branch 'pwl_factorable' into initialization

6f30fac

some updates to initialization module

043f8c8

Merge branch 'scip_port' into initialization

83c5e72

Merge branch 'pwl_factorable' into initialization

8bf25d1

Merge branch 'scip_port' into initialization

4e3d913

initialize with global solvers

c8a0730

initialization work

e019bff

lp init should bound all variables

9568bb0

move initialization module from contrib to devel

387a646

update imports

24dbd64

initialization example

2616502

initialization: starting tests

54d354e

initialization: add copyright statements

056cc99

docstring

d70e677

initialization: docs

823641d

Merge branch 'pwl_approx' into initialization

6a29fba

Merge branch 'scip_port' into initialization

5eb638f

Merge branch 'pwl_factorable' into initialization

3ddc25d

mrmundt requested changes May 20, 2026

View reviewed changes

michaelbynum and others added 19 commits May 25, 2026 05:33

devel.initialization: make LP approximation deterministic

784804d

devel.initialization: make LP approximation deterministic

cc6b78f

run black

9aaa84c

Merge remote-tracking branch 'origin/main' into initialization

f56e4b6

Update pyomo/devel/initialization/global_init.py

d3e79ac

Co-authored-by: Miranda Mundt <55767766+mrmundt@users.noreply.github.com>

Update pyomo/devel/initialization/lp_approx_init.py

021f968

Co-authored-by: Miranda Mundt <55767766+mrmundt@users.noreply.github.com>

initialization cleanup

f4f71aa

merge

f1e6467

Update pyomo/devel/initialization/utils.py

bd4f5ae

Co-authored-by: Miranda Mundt <55767766+mrmundt@users.noreply.github.com>

initialization cleanup

fa557b3

Merge remote-tracking branch 'michaelbynum/initialization' into initi…

75436ea

…alization

Update pyomo/devel/initialization/pwl_init.py

e80b737

Co-authored-by: Miranda Mundt <55767766+mrmundt@users.noreply.github.com>

run black

9ba42c6

use pyo instead of pe

c7cb2f9

run black

ba1a999

fix tests

6d8d072

devel.initializaton: more tests

4a895b2

run black

d90d2be

fix tests

4cc1659

blnicho requested a review from mrmundt May 27, 2026 17:28

Merge branch 'main' into initialization

ac60807

Merge branch 'main' into initialization

8668d8e

blnicho reviewed May 29, 2026

View reviewed changes

jsiirola reviewed May 29, 2026

View reviewed changes

blnicho reviewed May 29, 2026

View reviewed changes

michaelbynum and others added 2 commits May 29, 2026 18:02

Update doc/OnlineDocs/explanation/analysis/nlp_initialization/nlp_ini…

7a182bf

…tialization.rst Co-authored-by: Bethany Nicholson <blnicho@users.noreply.github.com>

Update pyomo/devel/initialization/initialize.py

53c0073

Co-authored-by: Bethany Nicholson <blnicho@users.noreply.github.com>

		@@ -0,0 +1 @@
		The purpose of this module is to provide methods for initializing nonlinear programming models. No newline at end of file

		logger = logging.getLogger(__name__)


		def _minimize_infeasibility(m):

		_handlers[t] = _handle_node


		class _PWLRefinementVisitor(StreamBasedExpressionVisitor):

Conversation

michaelbynum commented Apr 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Fixes #3878

Summary/Motivation:

Changes proposed in this PR:

Legal Acknowledgement

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

michaelbynum commented May 28, 2026

Uh oh!

blnicho left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jsiirola left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

michaelbynum commented May 30, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

michaelbynum commented Apr 15, 2026 •

edited

Loading