docs: Clarify scalar PLD scope for correlated multi-output Gaussian releases

[Gaijin-01]

docs + fix: Clarify scalar PLD scope for correlated multi-output Gaussian releases + numerical hardening

Summary

This PR improves both usability and numerical robustness in Google's dp_accounting library:

1. Documentation Clarification (python/dp_accounting)

• Clearly documents when and how to use scalar from_gaussian_mechanism for jointly observed correlated multi-output releases.
• Introduces the Effective Sensitivity pattern: when outputs are linearly coupled (f_j = c_j · f_1) with independent noise, the exact ε-hockey-stick divergence equals the scalar case computed at Delta_eff = Delta × ||c_vec||₂.
• Includes a practical Federated Learning example (2-client with coupling c=0.5).

This pattern is mathematically valid but was not explicitly documented, leading to potential privacy underestimation when users naively apply scalar PLD to multi-output scenarios.

2. Numerical Hardening (C++)

• Added stable LogErfc(x) and LogNormalCdf(z) helpers using asymptotic expansions.
• Switched to log-space arithmetic in CalculateDeltaForGaussianStddev to prevent NaN/overflow for large ε (ε ≳ 709).
• Improved input validation and precision near boundary cases using expm1-based log1mexp.

These changes follow best practices from JAX, TensorFlow Privacy, and high-precision libraries, and are particularly valuable for extreme privacy parameters.

Comparison with other libraries

• OpenDP: Stronger on formal composition, but less emphasis on scalar PLD optimizations for structured releases.
• TensorFlow Privacy / Opacus: Primarily RDP-based; the effective sensitivity reduction is valid but not prominently documented.
• This PR: Makes an advanced, efficient pattern explicit and safe to use inside Google's PLD tooling.

Related

• Addresses discussion in [API Gap] Marginal scalar accounting yields optimistic estimates for jointly observed correlated Gaussian releases #428
• Includes new tests for large-ε and invalid input cases

See also: https://doi.org/10.5281/zenodo.20078486

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.