docs: add runnable integral relative entropy example

[Artamta]

Description

Adds a runnable example for evaluate_relative_entropy_integral as part of #1886.

Changes

• Demonstrate the function using two diagonal density matrices.
• Print a concise, reproducible relative-entropy estimate.

Checklist

• Use ruff for errors related to code style and formatting.
• Verify all previous and newly added unit tests pass in pytest.
• Check the documentation build does not lead to any failures.

Testing performed

• New example runs successfully and prints 0.1194.
• 19 targeted tests passed.
• ruff check passed.
• ruff format --check passed.
• git diff --check passed.
• Full docs build progressed through generation but was stopped during an unrelated, long-running existing CVXPY example.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[vprusso]

Thanks @Artamta. The example is well-formed and runs, but reviewing it surfaced an accuracy problem in the function itself that I don't want to put front-and-center in the rendered docs.

For X = diag(0.75, 0.25), Y = diag(0.5, 0.5):

• The exact relative entropy is 0.13081 nats.
• Evaluating the function's own stated integral formula, $D(X|Y) = \int_\mu^\lambda \frac{ds}{s},\mathrm{tr}^+[Ys - X] + \log\lambda + 1 - \lambda$, with fine quadrature also gives 0.13081.
• But evaluate_relative_entropy_integral returns 0.11940, and the lower and upper bounds both collapse to 0.11940 (zero gap, so they don't bracket the true value). Refining the grid (epsilon_dec from 1e-1 down to 1e-4) doesn't move it.

So this isn't a coarse-approximation artifact; the estimate converges to the wrong number on a trivial diagonal case. A docstring example is the first thing a user runs, so I'd rather not ship one whose printed value is visibly ~9% off from a result the reader can compute by hand.

Holding this until the underlying accuracy issue is resolved (that's a separate fix, not something to paper over here). Once the function returns a faithful value, this example is a good addition. Nothing wrong with your PR mechanically.

[simsaidan]

@vprusso I came across this PR, and I took a look into the integral relative entropy implementation. I think the issue is in the mu/lambda generator. It was setting the lower bound mu to 1/lambda, which for small lambda was overestimating the grid lower bound, leading to too small values. Opened a fix in #1904, let me know what you think

[vprusso]

The underlying accuracy bug is now fixed on master (#1904, thanks to @simsaidan): _sandwich_parameters was truncating the integration range at 1/lam. On current master your example prints 0.1308, matching the exact relative entropy, so it's a faithful demonstration now. Thanks for the patience, @Artamta. Merging.