Feature/add funnel globalization mechanism to trf

[gulhameed361]

Fixes # .

Summary/Motivation:

This PR introduces the Funnel globalization strategy to the Trust Region Framework (TRF) solver in Pyomo. The Funnel method is an alternative to the existing Filter globalization mechanism.
The solver functionality remains unchanged by default and will continue to work as it has in previous versions unless the user explicitly selects the Funnel strategy in solver's options (globalization_strategy=1). This ensures backward compatibility.
The Funnel strategy is based on the methodology introduced in the paper "A Trust-region Funnel Algorithm for Grey-Box Optimisation" (https://arxiv.org/abs/2511.18998), which is accepted in AIChE Journal and will be live in the upcoming days.

Changes proposed in this PR:

1. Added funnel.py to implement the Funnel globalization strategy.
2. Updated TRF.py to integrate the Funnel strategy into the Trust Region Framework solver.
3. Added unit tests:
   • test_funnel.py: Tests for the Funnel class.
   • test_TRF_w_Funnel.py: Tests for the integration of Funnel with TRF.
   • 'test_TRFw_Filter.py': Tests for the integration of Filter with TRF (it works even after adding funnel method as it used to in current/previous versions)
4. Ensured backward compatibility:
   • The solver defaults to the existing Filter globalization strategy unless the Funnel strategy is explicitly selected by the user by using "globalization_strategy=1" in options of the solver.

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.

[gulhameed361]

Thank you for reviewing this PR! Please let me know if there are any changes or clarifications needed. I have tested the feature locally, and all tests passed successfully.

[mrmundt]

Some initial requests for changes that will be stoppers on this PR.

[mrmundt]

Also, please install the most recent version of black and run it on your changes. I can already tell that at least one file is going to cause our CI check for formatting to fail.

[gulhameed361]

Many thanks for the quick feedback. I have addressed the requested changes:

• Added copyright headers to funnel.py and test_funnel.py.
• Consolidated Funnel and Filter tests into test_TRF.py and removed duplicate test files (test_TRF_w_Funnel.py and test_TRF_w_Filter.py).
• Formatted the updated files using black.
• Verified functionality with pytest, and all tests passed successfully.
  Please let me know if further changes are required. Thank you!

[gulhameed361]

All the requested changes have been addressed. Made a few additional changes as well to the code to make it concise/efficient.

[codecov]

Codecov Report

❌ Patch coverage is 88.63636% with 10 lines in your changes missing coverage. Please review.
✅ Project coverage is 89.47%. Comparing base (f2d23a5) to head (fd5e661).
⚠️ Report is 165 commits behind head on main.

Files with missing lines	Patch %	Lines
pyomo/contrib/trustregion/TRF.py	83.33%	9 Missing ⚠️
pyomo/contrib/trustregion/funnel.py	97.05%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3832      +/-   ##
==========================================
- Coverage   89.48%   89.47%   -0.02%     
==========================================
  Files         904      905       +1     
  Lines      105385   105454      +69     
==========================================
+ Hits        94299    94350      +51     
- Misses      11086    11104      +18     

Flag	Coverage Δ
builders	29.04% <21.59%> (+<0.01%)	⬆️
default	83.57% <88.63%> (?)
expensive	35.52% <21.59%> (?)
linux	86.77% <88.63%> (-2.44%)	⬇️
linux_other	86.77% <88.63%> (+0.01%)	⬆️
oldsolvers	29.69% <21.59%> (+<0.01%)	⬆️
osx	82.91% <88.63%> (+<0.01%)	⬆️
win	84.98% <88.63%> (-0.02%)	⬇️
win_other	84.98% <88.63%> (-0.02%)	⬇️
xpress95	?

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.

[gulhameed361]

I have added a test for lines which were not tested as per the codecov report, and updated both the main and feature branches.

[gulhameed361]

I haven't updated the branch, because it may require the PR to go through all checks again! I can do it whenever required.

[gulhameed361]

Rebased onto the latest main, this should fix the CI failures.

[mrmundt]

Thanks for doing the updates! Sorry, we messed with you a bit here on the copyright. We updated them everywhere while this PR was open.

Additionally, there is existing online documentation for TRF: https://pyomo.readthedocs.io/en/stable/explanation/solvers/trustregion.html

It would be good for you to go edit those files with updates about your changes: https://github.com/Pyomo/pyomo/blob/main/doc/OnlineDocs/explanation/solvers/trustregion.rst

[mrmundt]

Sorry sorry, little bit of a nitpick here.

[gulhameed361]

Sorry sorry, little bit of a nitpick here.

I think it was a great catch as it wasn't step 4, it was just an alternative.

[gulhameed361]

I just noticed it was at pre-test inspected status. Apologies for re-requesting review!