Exact hull reformulation for quadratic constraints

[sergey-gusev94]

Fixes # .

Summary/Motivation:

This PR adds support for the exact hull reformulation for quadratic constraints in Generalized Disjunctive Programming (GDP).

The current gdp.hull transformation applies perspective-function based relaxations for nonlinear constraints. While effective for many nonlinear expressions, this approach can produce weaker relaxations for quadratically constrained disjunctions.

This PR implements the exact hull reformulation for quadratic constraints described in:

Gusev, S., & Bernal Neira, D. E. (2025).
Exact Hull Reformulation for Quadratically Constrained Generalized Disjunctive Programs.
https://arxiv.org/abs/2508.16093

The implementation extends the existing hull transformation with an optional configuration flag (which is False by default) that detects quadratic constraints and applies the exact hull formulation when appropriate.

For convex quadratic constraints, the reformulation is expressed as a rotated second-order cone (SOC) representable constraint. For nonconvex quadratics and equality constraints, the general exact hull formulation is used.

Convexity is determined automatically through eigenvalue analysis of the Hessian matrix.

This provides a tighter relaxation for quadratic GDP models and maintains the quadratic structure of constraints in hull reformulation.

Changes proposed in this PR:

• Extend the gdp.hull transformation with a new configuration option:

  • exact_hull_quadratic (default: False)

• When enabled, quadratic constraints inside disjuncts are reformulated using the exact hull formulation instead of the standard perspective function.

• Implement automatic convexity detection via eigenvalue decomposition of the quadratic Hessian matrix.

• Apply different reformulations depending on structure:

  • Convex quadratic inequalities
    Reformulated using a rotated second-order cone representation.

  • Nonconvex quadratics or equalities
    Reformulated using the general exact hull formulation.

• Add a configuration parameter:

  • eigenvalue_tolerance
    Controls numerical tolerance when checking positive or negative semidefiniteness of the Hessian.

• Extend the implementation in pyomo.gdp.plugins.hull to support these reformulations.

• Add unit tests verifying:

  • correctness of the generated constraints
  • compatibility with existing hull behavior
  • correctness of variable disaggregation and mappings.

The default behavior of gdp.hull is unchanged unless the new option is enabled.

Example usage:

TransformationFactory("gdp.hull").apply_to(
    model,
    exact_hull_quadratic=True
)

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:

1. I agree my contributions are submitted under the BSD license.
2. 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.

[codecov]

Codecov Report

❌ Patch coverage is 99.37107% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 89.70%. Comparing base (200746e) to head (aa9e6d7).
⚠️ Report is 86 commits behind head on main.

Files with missing lines	Patch %	Lines
pyomo/gdp/plugins/hull.py	99.37%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3874      +/-   ##
==========================================
+ Coverage   89.68%   89.70%   +0.01%     
==========================================
  Files         908      908              
  Lines      106753   106906     +153     
==========================================
+ Hits        95740    95895     +155     
+ Misses      11013    11011       -2     

Flag	Coverage Δ
builders	29.04% <4.40%> (-0.04%)	⬇️
default	85.99% <99.37%> (?)
expensive	35.46% <4.40%> (?)
linux	87.16% <99.37%> (-2.01%)	⬇️
linux_other	87.16% <99.37%> (+0.02%)	⬆️
oldsolvers	27.96% <4.40%> (-0.04%)	⬇️
osx	82.50% <99.37%> (+0.02%)	⬆️
win	85.58% <99.37%> (+0.02%)	⬆️
win_other	85.58% <99.37%> (+0.02%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[emma58]

This looks pretty good, but I'm submitting a partial review because there's one major revision: See my notes below, but can you please rewrite this to use the QuadraticRepnVisitor rather than generate_standard_repn? You'll be able to get all the same data, though it will come in a slightly different structure. But it is much more robust to edge cases--I think generate_standard_repn is not long for this world, actually.

[emma58]

Sorry, this isn't documented yet, but we are gradually replacing generate_standard_repn with more robust expression visitors. For your purposes, you should use the QuadraticRepnVisitor from pyomo.repn.quadratic.

You will also want to account for the assume_fixed_vars_permanent option when you do this. Right now, the easiest way to do that when you are not assuming they are permanent (the default) is to actually unfix them before you walk the expression and then fix them back to their old values after the fact. The same Hessian issue would happen if they are treated as params (the True option) but in this case it's actually okay because setting that option to True is promising to not unfix them or change their values in any way.

[emma58]

Thanks for the docstring!!

[emma58]

There are some known issues with polynomial_degree... I think that, since we're going to need it anyway, it probably makes sense to use the QuadraticRepnVisitor here to determine the nature of the Constraint body. That will be more robust to some strange edge cases.

[emma58]

I would lean towards putting this fact in the documentation rather than logging a warning, since there's nothing a user can do to prevent this warning other than actually going through and replacing mutable params with immutable ones. But we should definitely make this loud in the docs: It's a departure from the usual behavior of GDP transformations.

[emma58]

It looks like you're building several data structures you don't need here. You never use all_vars for anything, and the keys of var_to_index are the var_ids_seen set. So I propose replacing these lines with:

var_to_idx = {}
for quad_vars in repn.quadratic_vars:
    for var_i in quad_vars:
        if id(var_i) not in var_to_idx:
            var_to_idx[id(var_i)] = len(var_to_idx)
n_vars = len(var_to_idx)