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?

[emma58]

It might be worth noting that in its current implementation is requires an explicit LogicalConstraint, not just the fact that the Disjunction is declared with xor=True, since that's a deviation from anything else in GDP-land right now.

[AlbertLee125]

I added the note on the documentation of the current LD-SDA requires the explicit LogicalConstraint.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 88.69%. Comparing base (a9d673d) to head (41edf80).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3539      +/-   ##
==========================================
- Coverage   88.69%   88.69%   -0.01%     
==========================================
  Files         888      888              
  Lines      101886   101886              
==========================================
- Hits        90365    90364       -1     
- Misses      11521    11522       +1     

Flag	Coverage Δ
builders	26.54% <ø> (+<0.01%)	⬆️
default	84.80% <ø> (?)
expensive	33.94% <ø> (?)
linux	86.15% <ø> (-2.29%)	⬇️
linux_other	86.15% <ø> (-0.01%)	⬇️
osx	76.05% <ø> (ø)
win	84.63% <ø> (-0.01%)	⬇️
win_other	84.63% <ø> (-0.01%)	⬇️

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.