LD-SDA Documentation

[AlbertLee125]

Summary/Motivation:

This PR enhances the Pyomo Documentation by incorporating detailed instructions on utilizing the Logic-based Discrete-Steepest Descent Algorithm (LD-SDA) solver within the Generalized Disjunctive Programming optimizer (GDPopt).
It includes additional narrative content and a usage example and ensures that the LD-SDA solver class is included in the API documentation.

Changes proposed in this PR:

• Added comprehensive documentation on the usage of the LD-SDA solver within GDPopt.
• Included an executable doctest illustrating the application of LD-SDA to a small GDP problem with ordered disjuncts and logical constraints.
• Documented key solver arguments: starting_point, logical_constraint_list, and direction_norm.
• Added ~pyomo.contrib.gdpopt.ldsda.GDP_LDSDA_Solver to the autodoc list to enable API documentation rendering.

The narrative content and example were added at the bottom of gdpopt.rst.
The autodoc entry for GDP_LDSDA_Solver was appended to the list of GDPopt solver classes to ensure it appears in the API reference.

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.

[emma58]

This looks good! Could you also please edit lines 15-19 to update the number of algorithms to four and add a citation for the LDSDA paper?

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 88.70%. Comparing base (fa15cc7) to head (015a010).
Report is 17 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #3539   +/-   ##
=======================================
  Coverage   88.70%   88.70%           
=======================================
  Files         888      888           
  Lines      102024   102024           
=======================================
  Hits        90505    90505           
  Misses      11519    11519           

Flag	Coverage Δ
builders	26.56% <ø> (+0.01%)	⬆️
default	84.82% <ø> (?)
expensive	33.96% <ø> (?)
linux	86.18% <ø> (-2.28%)	⬇️
linux_other	86.18% <ø> (ø)
osx	76.09% <ø> (ø)
win	84.66% <ø> (ø)
win_other	84.66% <ø> (ø)

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.