================
converter module
================

.. automodule:: gdpnum.converter
   :members:
   :undoc-members:
   :show-inheritance:

Overview
========

The ``converter`` module provides functionality for converting Privacy Loss Distributions (PLDs) to Gaussian Differential Privacy (GDP) parameters. The core of this module is the ``PLDConverter`` class, which analyzes PLDs and computes the corresponding GDP parameter μ and the approximation regret.

Classes
=======

PLDConverter
-----------

.. autoclass:: gdpnum.converter.PLDConverter
   :members:
   :undoc-members:
   :special-members: __init__

Functions
========

gaussian_fdp
-----------

.. autofunction:: gdpnum.converter.gaussian_fdp

get_worst_case_regret
-------------------

.. autofunction:: gdpnum.converter.get_worst_case_regret

Private Functions
===============

These functions are used internally by the module and are not typically needed by users:

.. autofunction:: gdpnum.converter._ensure_array

.. autofunction:: gdpnum.converter._get_plrv

.. autofunction:: gdpnum.converter._normalize_pmf

.. autofunction:: gdpnum.converter._compute_breakpoints

Technical Details
===============

The module implements the algorithms described in the paper `(ε,δ) Considered Harmful: Best Practices for Reporting Differential Privacy Guarantees <https://arxiv.org/abs/2503.10945>`_.

Key concepts include:

1. **Privacy Loss Random Variables (PLRVs)**: Represent the log-likelihood ratio between outputs on neighboring datasets.

2. **Tradeoff Function**: Maps Type I error (false positive rate) to Type II error (false negative rate) in the hypothesis testing interpretation of differential privacy.

3. **GDP Parameter (μ)**: A single parameter that characterizes the privacy guarantee in terms of the standard deviation of a Gaussian privacy loss random variable.

4. **Regret**: Measures how well the GDP approximation fits the actual privacy loss distribution.

The conversion process involves:

1. Extracting the privacy loss random variables from a PLD
2. Computing breakpoints for the tradeoff curve
3. Finding the smallest μ such that the GDP tradeoff curve dominates the actual tradeoff curve
4. Computing the regret as the worst-case gap between the curves

Example Usage
============

.. code-block:: python

    from dp_accounting.pld.privacy_loss_distribution import from_gaussian_mechanism
    from gdpnum import PLDConverter
    
    # Create a PLD for a Gaussian mechanism
    pld = from_gaussian_mechanism(standard_deviation=1.0)
    
    # Convert to GDP
    converter = PLDConverter(pld)
    mu, regret = converter.get_mu_and_regret()
    
    print(f"GDP parameter μ: {mu:.6f}")
    print(f"Regret: {regret:.6f}")