DpEvent

A DpEvent is a representation of the application of a differentially private mechanism. Just as a differentially private mechanism can be build from simpler building blocks, a DpEvent representing such a mechanism can be built from simpler DpEvents.

Base Event Class

class dp_accounting.dp_event.DpEvent[source]

Bases: object

Represents application of a private mechanism.

A DpEvent describes a differentially private mechanism sufficiently for computing the associated privacy losses, both in isolation and in combination with other DpEvents.

to_named_tuple()[source]

Converts DpEvent to a NamedTuple representation.

This can be useful for passing around DpEvents in contexts where it is undesirable to take dp_accounting as a dependency, or for serialization.

Return type:: DpEventNamedTuple
Returns:: NamedTuple representing the DpEvent.
Raises:: ValueError – This type of DpEvent is not convertable to NamedTuple. This could happen for example if the DpEvent has private fields or has a field with init = False.

classmethod from_named_tuple(obj)[source]

Converts NamedTuple representation to corresponding DpEvent.

This can be useful for passing around DpEvents in contexts where it is undesirable to take dp_accounting as a dependency, or for serialization.

Parameters:: obj (DpEventNamedTuple) – The NamedTuple to convert to a DpEvent.
Return type:: DpEvent
Returns:: The DpEvent corresponding to the NamedTuple.
Raises:: ValueError – This type of DpEvent is not convertable to NamedTuple. This could happen for example if the DpEvent has private fields or has a field with init = False.

Self-Contained Events

These represent mechanisms that can be fully described by the parameters of the class, without relying on another DpEvent. These typically correspond to the “basic building blocks” of differentially private mechanisms, such as the Gaussian, Laplace, and Exponential mechanisms.

class dp_accounting.dp_event.GaussianDpEvent(noise_multiplier)[source]

Bases: DpEvent

Represents an application of the Gaussian mechanism.

For values v_i and noise z ~ N(0, s^2I), this mechanism returns sum_i v_i + z. If the norms of the values are bounded ||v_i|| <= C, the noise_multiplier is defined as s / C.

noise_multiplier: float

class dp_accounting.dp_event.DiscreteGaussianDpEvent(sigma, sensitivity=1.0, dimension=None)[source]

Bases: DpEvent

Represents an application of the discrete Gaussian mechanism.

For an integer-valued function f with sensitivity sensitivity, the discrete Gaussian mechanism outputs f(x) + z where z is drawn from the discrete Gaussian distribution with scale parameter sigma. The (centered) discrete Gaussian distribution with scale parameter sigma has probability mass function proportional to exp(-z@z / 2 / sigma**2) at z for any integer vector z. This is roughly equivalent to GaussianDpEvent with noise_multiplier = sigma / sensitivity

Unlike for the continuous Gaussian, the univariate and multivariate cases are not equivalent for the discrete Gaussian. The dimension parameter specifies the dimensionality of the output:

dimension=1: Univariate.
dimension>1: Multivariate.
dimension=None: Unknown. (Default.) Accountants should be conservative.

See https://arxiv.org/abs/2004.00010 for details.

sigma: float

sensitivity: float

dimension: Optional[int]

class dp_accounting.dp_event.TruncatedSubsampledGaussianDpEvent(dataset_size, sampling_probability, truncated_batch_size, noise_multiplier)[source]

Bases: DpEvent

Represents the Gaussian mechanism with truncated Poisson sampling.

In this event, we sample from a dataset of size dataset_size using Poisson sampling with probability sampling_probability, truncate the resulting sample to size truncated_batch_size by sampling a random subset, and then apply a Gaussian mechanism with standard deviation noise_multiplier to the truncated sample. See https://arxiv.org/abs/2508.15089 for more details.

Variables:

dataset_size – The size of the dataset.
sampling_probability – The probability of sampling a given record.
truncated_batch_size – The maximum number of records to sample in a batch.
noise_multiplier – The noise multiplier of the Gaussian distribution.

dataset_size: int

sampling_probability: float

truncated_batch_size: int

noise_multiplier: float

class dp_accounting.dp_event.LaplaceDpEvent(noise_multiplier)[source]

Bases: DpEvent

Represents an application of the Laplace mechanism.

For values v_i and noise z sampled coordinate-wise from the Laplace distribution L(0, s), this mechanism returns sum_i v_i + z. The probability density function of the Laplace distribution L(0, s) with parameter s is given as exp(-|x|/s) * (0.5/s) at x for any real value x. If the L_1 norm of the values are bounded ||v_i||_1 <= C, the noise_multiplier is defined as s / C.

noise_multiplier: float

class dp_accounting.dp_event.DiscreteLaplaceDpEvent(noise_parameter, sensitivity)[source]

Bases: DpEvent

Represents an application of the discrete Laplace mechanism.

For integer values v_i and noise z sampled coordinate-wise from the discrete Laplace distribution DLap(a), this mechanism returns sum_i v_i + z. The probability mass function of the discrete Laplace distribution DLap(a) with noise parameter a is given as exp(-a|x|) * tanh(a/2) at x for any integer value x. If the L_1 norm of the values are bounded ||v_i||_1 <= C, the sensitivity is C.

noise_parameter: float

sensitivity: int

class dp_accounting.dp_event.MixtureOfGaussiansDpEvent(standard_deviation, sensitivities, sampling_probs)[source]

Bases: DpEvent

Represents an application of the Mixture of Gaussians mechanism.

For sigma, sensitivities c_i and probabilities p_i, given D this mechanism outputs a sample from N(0, sigma^2) and given D’ this mechanism outputs a sample from sum_i p_i N(c_i, sigma^2).

See https://arxiv.org/abs/2310.15526 for details.

Variables:

standard_deviation – The standard deviation of the Gaussian noise.
sensitivities – The support of the sensitivity random variable. Should be the same length as sampling_probs.
sampling_probs – The probabilities associated with the sensitivities.

standard_deviation: float

sensitivities: Sequence[float]

sampling_probs: Sequence[float]

class dp_accounting.dp_event.ExponentialMechanismDpEvent(epsilon)[source]

Bases: DpEvent

Represents an application of the epsilon-DP exponential mechanism.

For RDP accounting, we use the fact that the exponential mechanism is epsilon-bounded range, i.e. for some t the privacy loss is always in the interval [t, t+epsilon]. See https://arxiv.org/abs/1905.04273 for details. For PLD accounting, we just treat it as a black-box epsilon-DP mechanism.

Variables:: epsilon – The epsilon parameter of the exponential mechanism.

epsilon: float

class dp_accounting.dp_event.PermuteAndFlipDpEvent(epsilon)[source]

Bases: DpEvent

Represents an application of the permute-and-flip mechanism.

See https://arxiv.org/abs/2010.12603 (McKenna & Sheldon, 2020) for details.

Unlike the exponential mechanism which is epsilon-bounded range, the permute-and-flip mechanism satisfies standard epsilon-DP. Its privacy loss distribution is identical to that of the Laplace mechanism with parameter 1/epsilon. A dedicated event type is provided for API clarity and to allow future tighter analyses.

For RDP accounting, we use the tight Laplace RDP formula (Mironov, 2017). For PLD accounting, we use the Laplace privacy loss distribution.

Variables:: epsilon – The epsilon parameter of the permute-and-flip mechanism.

epsilon: float

class dp_accounting.dp_event.RandomizedResponseDpEvent(noise_parameter, num_buckets)[source]

Bases: DpEvent

Represents application of the randomized response mechanism.

The Randomized Response over k buckets with noise parameter p takes in an input which is one of the k buckets. With probability 1 - p, it simply outputs the input bucket. Otherwise, with probability p, it outputs a bucket drawn uniformly at random from the k buckets.

The noise parameter p can be any value in [0, 1], with p=0 corresponding to the case where the mechanism always outputs the input bucket, and p=1 corresponding to the case where the mechanism outputs a bucket drawn uniformly at random from the k buckets regardless of the input bucket.

noise_parameter: float

num_buckets: int

class dp_accounting.dp_event.EpsilonDeltaDpEvent(epsilon, delta)[source]

Bases: DpEvent

Represents application of a mechanism which satisfies (epsilon, delta)-DP.

Note that for many mechanisms, a single (epsilon, delta)-DP does not fully characterize the privacy loss. If a more specific DpEvent that characterizes a mechanism is available, it should be preferred over this one.

epsilon: float

delta: float

class dp_accounting.dp_event.ZCDpEvent(rho, xi=0.0)[source]

Bases: DpEvent

Represents an application of a mechanism satisfying (xi, rho)-zCDP.

Specifically, this event satisfies (alpha, xi + rho * alpha)-RDP for all alpha > 0. The case where xi = 0 is referred to as rho-zCDP. See https://arxiv.org/pdf/1605.02065 for details.

Variables:

rho – The multiplicative constant in the RDP bound.
xi – The additive constant in the RDP bound.

rho: float

xi: float

class dp_accounting.dp_event.SingleEpochTreeAggregationDpEvent(noise_multiplier, step_counts)[source]

Bases: DpEvent

Represents aggregation for a single epoch using one or more trees.

Multiple tree-aggregation steps can occur, but it is required that each record occurs at most once across all trees. See appendix D of “Practical and Private (Deep) Learning without Sampling or Shuffling” https://arxiv.org/abs/2103.00039.

To represent the common case where the same record can occur in multiple trees (but still at most once per tree), wrap this with SelfComposedDpEvent or ComposedDpEvent and use a scalar for step_counts.

Variables:

noise_multiplier – The ratio of the noise per node to the sensitivity.
step_counts – The number of steps in each tree. May be a scalar for a single tree.

noise_multiplier: float

step_counts: Union[int, List[int]]

Events Wrapping Other Events

These represent mechanisms that are defined in terms of other DpEvents. These can be used to describe more complex mechanisms in terms of simpler ones. For example, DP-SGD with Poisson sampling can be represented as a SelfComposedDpEvent (corresponding to the composition of many iterations) of a PoissonSampledDpEvent containing a GaussianDpEvent (corresponding to the subsampled Gaussian mechanism used in a single iteration).

class dp_accounting.dp_event.PoissonSampledDpEvent(sampling_probability, event)[source]

Bases: DpEvent

Represents an application of Poisson subsampling.

Each record in the dataset is included in the sample independently with probability sampling_probability. Then the DpEvent event is applied to the sample of records.

sampling_probability: float

event: DpEvent

class dp_accounting.dp_event.SampledWithReplacementDpEvent(source_dataset_size, sample_size, event)[source]

Bases: DpEvent

Represents sampling a fixed sized batch of records with replacement.

A sample of sample_size (possibly repeated) records is drawn uniformly at random from the set of possible samples of a source dataset of size source_dataset_size. Then the DpEvent event is applied to the sample of records.

source_dataset_size: int

sample_size: int

event: DpEvent

class dp_accounting.dp_event.SampledWithoutReplacementDpEvent(source_dataset_size, sample_size, event)[source]

Bases: DpEvent

Represents sampling a fixed sized batch of records without replacement.

A sample of sample_size unique records is drawn uniformly at random from the set of possible samples of a source dataset of size source_dataset_size. Then the DpEvent event is applied to the sample of records.

source_dataset_size: int

sample_size: int

event: DpEvent

class dp_accounting.dp_event.ComposedDpEvent(events)[source]

Bases: DpEvent

Represents application of a series of composed mechanisms.

The composition may be adaptive, where the query producing each event depends on the results of prior queries.

events: List[DpEvent]

class dp_accounting.dp_event.SelfComposedDpEvent(event, count)[source]

Bases: DpEvent

Represents repeated application of a mechanism.

The repeated applications may be adaptive, where the query producing each event depends on the results of prior queries.

This is equivalent to ComposedDpEvent that contains a list of length count of identical copies of event.

event: DpEvent

count: int

class dp_accounting.dp_event.RepeatAndSelectDpEvent(event, mean, shape)[source]

Bases: DpEvent

Represents repeatedly running the mechanism and selecting the best output.

The total number of runs is randomized and drawn from a distribution with the given parameters: Poisson (shape=infinity), Geometric (shape=1), Logarithmic (shape=0), or Truncated Negative binomial (0<shape<infinity).

See https://arxiv.org/abs/2110.03620 for details.

Variables:

event – The DpEvent that is being repeated.
mean – The mean number of repetitions.
shape – The shape of the distribution of the number of repetitions.

event: DpEvent

mean: float

shape: float

Non-Standard Events

These represent extreme mechanisms, or unsupported mechanisms, provided mostly for completeness of the API or for testing purposes. Most users will not need to interact with these DpEvents.

class dp_accounting.dp_event.NoOpDpEvent[source]

Bases: DpEvent

Represents appplication of an operation with no privacy impact.

A NoOpDpEvent is generally never required, but it can be useful as a placeholder where a DpEvent is expected, such as in tests or some live accounting pipelines.

class dp_accounting.dp_event.NonPrivateDpEvent[source]

Bases: DpEvent

Represents application of a non-private operation.

This DpEvent should be used when an operation is performed that does not satisfy (epsilon, delta)-DP. All PrivacyAccountant`s should return infinite epsilon/delta when encountering a `NonPrivateDpEvent.

class dp_accounting.dp_event.UnsupportedDpEvent[source]

Bases: DpEvent

Represents application of an as-yet unsupported operation.

This DpEvent should be used when an operation is performed that does not yet have any associated DP description, or if the description is temporarily inaccessible, for example, during development. All PrivacyAccountant`s should return `supports(event) == False for UnsupportedDpEvent.