Privacy Engine

class opacus.privacy_engine.PrivacyEngine(*, accountant='prv', secure_mode=False)[source]

Main entry point to the Opacus API - use PrivacyEngine to enable differential privacy for your model training.

PrivacyEngine object encapsulates current privacy state (privacy budget + method it’s been calculated) and exposes make_private method to wrap your PyTorch training objects with their private counterparts.

Example

>>> dataloader = demo_dataloader
>>> model = MyCustomModel()
>>> optimizer = torch.optim.SGD(model.parameters(), lr=0.05)
>>> privacy_engine = PrivacyEngine()
>>>
>>> model, optimizer, dataloader = privacy_engine.make_private(
...    module=model,
...    optimizer=optimizer,
...    data_loader=dataloader,
...    noise_multiplier=1.0,
...    max_grad_norm=1.0,
... )
>>> # continue training as normal
Parameters:

  • accountant (str) – Accounting mechanism. Currently supported: - rdp (RDPAccountant) - gdp (GaussianAccountant) - prv (:class`~opacus.accountants.PRVAccountant`)

  • secure_mode (bool) – Set to True if cryptographically strong DP guarantee is required. secure_mode=True uses secure random number generator for noise and shuffling (as opposed to pseudo-rng in vanilla PyTorch) and prevents certain floating-point arithmetic-based attacks. See _generate_noise() for details. When set to True requires torchcsprng to be installed

classmethod get_compatible_module(module)[source]

Return a privacy engine compatible module. Also validates the module after running registered fixes.

Parameters:

module (Module) – module to be modified

Return type:

Module

Returns:

Module with some submodules replaced for their deep copies or close equivalents. See ModuleValidator for more details

get_epsilon(delta)[source]

Computes the (epsilon, delta) privacy budget spent so far.

Parameters:

delta – The target delta.

Returns:

Privacy budget (epsilon) expended so far.

is_compatible(*, module, optimizer, data_loader)[source]

Check if task components are compatible with DP.

Parameters:
Return type:

bool

Returns:

True if compatible, False otherwise

make_private(*, module, optimizer, criterion=CrossEntropyLoss(), data_loader, noise_multiplier, max_grad_norm, batch_first=True, loss_reduction='mean', poisson_sampling=True, clipping='flat', noise_generator=None, grad_sample_mode='hooks', **kwargs)[source]

Add privacy-related responsibilities to the main PyTorch training objects: model, optimizer, and the data loader.

All of the returned objects act just like their non-private counterparts passed as arguments, but with added DP tasks.

  • Model is wrapped to also compute per sample gradients.

  • Optimizer is now responsible for gradient clipping and adding noise to the gradients.

  • Criterion is a wrapper around the original criterion that packages the two backward passes for fast gradient clipping.

  • DataLoader is updated to perform Poisson sampling.

Notes

Using any other models, optimizers, or data sources during training will invalidate stated privacy guarantees.

Parameters:

  • module (Module) – PyTorch module to be used for training

  • optimizer (Optimizer) – Optimizer to be used for training

  • data_loader (DataLoader) – DataLoader to be used for training

  • noise_multiplier (float) – The ratio of the standard deviation of the Gaussian noise to the L2-sensitivity of the function to which the noise is added (How much noise to add)

  • max_grad_norm (Union[float, List[float]]) – The maximum norm of the per-sample gradients. Any gradient with norm higher than this will be clipped to this value.

  • batch_first (bool) – Flag to indicate if the input tensor to the corresponding module has the first dimension representing the batch. If set to True, dimensions on input tensor are expected be [batch_size, ...], otherwise [K, batch_size, ...]

  • loss_reduction (str) – Indicates if the loss reduction (for aggregating the gradients) is a sum or a mean operation. Can take values “sum” or “mean”

  • poisson_sampling (bool) – True if you want to use standard sampling required for DP guarantees. Setting False will leave provided data_loader unchanged. Technically this doesn’t fit the assumptions made by privacy accounting mechanism, but it can be a good approximation when using Poisson sampling is unfeasible.

  • clipping (str) – Per sample gradient clipping mechanism (“flat” or “per_layer” or “adaptive”). Flat clipping calculates the norm of the entire gradient over all parameters, per layer clipping sets individual norms for every parameter tensor, and adaptive clipping updates clipping bound per iteration. Flat clipping is usually preferred, but using per layer clipping in combination with distributed training can provide notable performance gains.

  • noise_generator – torch.Generator() object used as a source of randomness for the noise

  • grad_sample_mode (str) – mode for computing per sample gradients. Determines the implementation class for the wrapped module. See AbstractGradSampleModule for more details

Return type:

Union[Tuple[GradSampleModule, DPOptimizer, DataLoader], Tuple[GradSampleModule, DPOptimizer, DPLossFastGradientClipping, DataLoader]]

Returns:

Tuple of (model, optimizer, data_loader) or (model, optimizer, criterion, data_loader).

Model is a wrapper around the original model that also computes per sample

gradients

Optimizer is a wrapper around the original optimizer that also does

gradient clipping and noise addition to the gradients

Criterion is a wrapper around the original criterion that packages the two backward passes for fast gradient clipping.

Only returned when grad_sample_mode is “ghost”.

DataLoader is a brand new DataLoader object, constructed to behave as

equivalent to the original data loader, possibly with updated sampling mechanism. Points to the same dataset object.

make_private_with_epsilon(*, module, optimizer, criterion=CrossEntropyLoss(), data_loader, target_epsilon, target_delta, epochs, max_grad_norm, batch_first=True, loss_reduction='mean', poisson_sampling=True, clipping='flat', noise_generator=None, grad_sample_mode='hooks', **kwargs)[source]

Version of make_private(), that calculates privacy parameters based on a given privacy budget.

For the full documentation see make_private()

Parameters:

  • module (Module) – PyTorch module to be used for training

  • optimizer (Optimizer) – Optimizer to be used for training

  • data_loader (DataLoader) – DataLoader to be used for training

  • target_epsilon (float) – Target epsilon to be achieved, a metric of privacy loss at differential changes in data.

  • target_delta (float) – Target delta to be achieved. Probability of information being leaked.

  • epochs (int) – Number of training epochs you intend to perform; noise_multiplier relies on this to calculate an appropriate sigma to ensure privacy budget of (target_epsilon, target_delta) at the end of epochs.

  • max_grad_norm (Union[float, List[float]]) – The maximum norm of the per-sample gradients. Any gradient with norm higher than this will be clipped to this value.

  • batch_first (bool) – Flag to indicate if the input tensor to the corresponding module has the first dimension representing the batch. If set to True, dimensions on input tensor are expected be [batch_size, ...], otherwise [K, batch_size, ...]

  • loss_reduction (str) – Indicates if the loss reduction (for aggregating the gradients) is a sum or a mean operation. Can take values “sum” or “mean”

  • poisson_sampling (bool) – True if you want to use standard sampling required for DP guarantees. Setting False will leave provided data_loader unchanged. Technically this doesn’t fit the assumptions made by privacy accounting mechanism, but it can be a good approximation when using Poisson sampling is unfeasible.

  • clipping (str) – Per sample gradient clipping mechanism (“flat” or “per_layer” or “adaptive”). Flat clipping calculates the norm of the entire gradient over all parameters, per layer clipping sets individual norms for every parameter tensor, and adaptive clipping updates clipping bound per iteration. Flat clipping is usually preferred, but using per layer clipping in combination with distributed training can provide notable performance gains.

  • noise_generator – torch.Generator() object used as a source of randomness for the noise

  • grad_sample_mode (str) – mode for computing per sample gradients. Determines the implementation class for the wrapped module. See AbstractGradSampleModule for more details

Return type:

Union[Tuple[GradSampleModule, DPOptimizer, DataLoader], Tuple[GradSampleModule, DPOptimizer, DPLossFastGradientClipping, DataLoader]]

Returns:

Tuple of (model, optimizer, data_loader) or (model, optimizer, criterion, data_loader).

Model is a wrapper around the original model that also computes per sample

gradients

Optimizer is a wrapper around the original optimizer that also does

gradient clipping and noise addition to the gradients

Criterion is a wrapper around the original criterion that packages the two backward passes for fast gradient clipping.

Only returned when grad_sample_mode is “ghost”.

DataLoader is a brand new DataLoader object, constructed to behave as

equivalent to the original data loader, possibly with updated sampling mechanism. Points to the same dataset object.

save_checkpoint(*, path, module, optimizer=None, noise_scheduler=None, grad_clip_scheduler=None, checkpoint_dict=None, module_state_dict_kwargs=None, torch_save_kwargs=None)[source]

Saves the state_dict of module, optimizer, and accountant at path. :type path: Union[str, PathLike, BinaryIO, IO[bytes]] :param path: Path to save the state dict objects. :type module: GradSampleModule :param module: GradSampleModule to save; wrapped module’s state_dict is saved. :type optimizer: Optional[DPOptimizer] :param optimizer: DPOptimizer to save; wrapped optimizer’s state_dict is saved. :type noise_scheduler: Optional[_NoiseScheduler] :param noise_scheduler: _NoiseScheduler whose state we should save. :type grad_clip_scheduler: Optional[_GradClipScheduler] :param grad_clip_scheduler: _GradClipScheduler whose state we should save. :type checkpoint_dict: Optional[Dict[str, Any]] :param checkpoint_dict: Dict[str, Any]; an already-filled checkpoint dict. :type module_state_dict_kwargs: Optional[Dict[str, Any]] :param module_state_dict_kwargs: dict of kwargs to pass to module.state_dict() :type torch_save_kwargs: Optional[Dict[str, Any]] :param torch_save_kwargs: dict of kwargs to pass to torch.save()

validate(*, module, optimizer, data_loader)[source]

Validate that task components are compatible with DP. Same as is_compatible(), but raises error instead of returning bool.

Parameters:
Raises:

UnsupportedModuleError – If one or more modules found to be incompatible