===========
Basic Usage
===========

The ``gdpnum`` library provides tools to compute the Gaussian Differential Privacy (GDP) parameter μ for privacy mechanisms. GDP offers a more interpretable and composable way to think about privacy guarantees compared to traditional (ε, δ) formulations.

Core Concepts
=============

Privacy Loss Distribution (PLD)
-------------------------------

The library builds upon the Privacy Loss Distribution (PLD) framework from the ``dp_accounting`` package. PLD is a way to represent the privacy loss random variable for a mechanism, which captures the distribution of log-likelihood ratios between outputs on neighboring datasets.

GDP Parameter (μ)
-----------------

The GDP parameter μ represents the "standard deviation" of the privacy loss random variable. A smaller μ indicates stronger privacy guarantees. The GDP parameter can be directly related to traditional (ε, δ) parameters but offers better composition properties and interpretability.

Regret
------

When converting from PLD to GDP, we compute a "regret" value that quantifies how closely the GDP approximation fits the actual privacy loss distribution. A lower regret value indicates a better fit.

Basic Workflow
==============

A typical workflow with ``gdpnum`` involves:

1. Creating a Privacy Loss Distribution (PLD) object from a mechanism
2. Converting the PLD to GDP parameters using the ``PLDConverter``
3. Analyzing the GDP parameter and regret value

Example
=======

Here's a simple example using a Gaussian mechanism:

.. code-block:: python

    import gdpnum
    from dp_accounting.pld.privacy_loss_distribution import from_gaussian_mechanism

    # Create a PLD for a Gaussian mechanism with standard deviation 1.0
    pld = from_gaussian_mechanism(standard_deviation=1.0)

    # Convert to GDP
    converter = gdpnum.PLDConverter(pld)
    mu, regret = converter.get_mu_and_regret()

    print(f"GDP parameter μ: {mu:.6f}")
    print(f"Regret: {regret:.6f}")

For pure DP mechanisms (like the Gaussian mechanism), the regret is effectively zero, indicating that the GDP representation is exact.

Getting the Tradeoff Curve
==========================

You can also get the tradeoff curve (Type I vs Type II error rates) at recommended values of alpha:

.. code-block:: python

    # Get beta values at recommended alpha points
    beta_values = converter.get_beta()
    
    # Or at custom alpha values
    alpha_values = [0.001, 0.01, 0.1, 0.2, 0.3, 0.4, 0.5]
    beta_values = converter.get_beta(alpha_values)