class_docstr: 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
class_docstr_tok: ["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"]
docstr: Version of :meth:`~opacus.privacy_engine.PrivacyEngine.make_private`,
  that calculates privacy parameters based on a given privacy budget.
  
  For the full documentation see
  :meth:`~opacus.privacy_engine.PrivacyEngine.make_private`
  
  Args:
      module: PyTorch module to be used for training
      optimizer: Optimizer to be used for training
      data_loader: DataLoader to be used for training
      target_epsilon: Target epsilon to be achieved, a metric of privacy loss at differential changes in data.
      target_delta: Target delta to be achieved. Probability of information being leaked.
      epochs: 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: The maximum norm of the per-sample gradients. Any gradient with norm
          higher than this will be clipped to this value.
      batch_first: 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: Indicates if the loss reduction (for aggregating the gradients)
          is a sum or a mean operation. Can take values "sum" or "mean"
      poisson_sampling: ``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: 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: mode for computing per sample gradients. Determines the
          implementation class for the wrapped ``module``. See
          :class:`~opacus.grad_sample.gsm_base.AbstractGradSampleModule` for more
          details
  
  Returns:
      Tuple of (model, optimizer, 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
      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.
docstr_tok: ["Version","of",":","meth",":","`","~opacus.privacy_engine.PrivacyEngine.make_private","`",",","that","calculates","privacy","parameters","based","on","a","given","privacy","budget",".","For","the","full","documentation","see",":","meth",":","`","~opacus.privacy_engine.PrivacyEngine.make_private","`","Args",":","module",":","PyTorch","module","to","be","used","for","training","optimizer",":","Optimizer","to","be","used","for","training","data_loader",":","DataLoader","to","be","used","for","training","target_epsilon",":","Target","epsilon","to","be","achieved",",","a","metric","of","privacy","loss","at","differential","changes","in","data",".","target_delta",":","Target","delta","to","be","achieved",".","Probability","of","information","being","leaked",".","epochs",":","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",":","The","maximum","norm","of","the","per-sample","gradients",".","Any","gradient","with","norm","higher","than","this","will","be","clipped","to","this","value",".","batch_first",":","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",":","Indicates","if","the","loss","reduction","(","for","aggregating","the","gradients",")","is","a","sum","or","a","mean","operation",".","Can","take","values","``","sum","''","or","``","mean","''","poisson_sampling",":","``","True","``","if","you","want","to","use","standard","sampling","required","for","DP","guarantees",".","Setting","``","False","``","will","leave","provided","data_loader","unchanged",".","Technically","this","does","n't","fit","the","assumptions","made","by","privacy","accounting","mechanism",",","but","it","can","be","a","good","approximation","when","using","Poisson","sampling","is","unfeasible",".","clipping",":","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",":","mode","for","computing","per","sample","gradients",".","Determines","the","implementation","class","for","the","wrapped","``","module","``",".","See",":","class",":","`","~opacus.grad_sample.gsm_base.AbstractGradSampleModule","`","for","more","details","Returns",":","Tuple","of","(","model",",","optimizer",",","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","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","."]
code: def make_private_with_epsilon(
      self,
      *,
      module: nn.Module,
      optimizer: optim.Optimizer,
      data_loader: DataLoader,
      target_epsilon: float,
      target_delta: float,
      epochs: int,
      max_grad_norm: Union[float, List[float]],
      batch_first: bool = True,
      loss_reduction: str = "mean",
      poisson_sampling: bool = True,
      clipping: str = "flat",
      noise_generator=None,
      grad_sample_mode: str = "hooks",
      **kwargs,
  ):
      """
      Version of :meth:`~opacus.privacy_engine.PrivacyEngine.make_private`,
      that calculates privacy parameters based on a given privacy budget.
  
      For the full documentation see
      :meth:`~opacus.privacy_engine.PrivacyEngine.make_private`
  
      Args:
          module: PyTorch module to be used for training
          optimizer: Optimizer to be used for training
          data_loader: DataLoader to be used for training
          target_epsilon: Target epsilon to be achieved, a metric of privacy loss at differential changes in data.
          target_delta: Target delta to be achieved. Probability of information being leaked.
          epochs: 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: The maximum norm of the per-sample gradients. Any gradient with norm
              higher than this will be clipped to this value.
          batch_first: 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: Indicates if the loss reduction (for aggregating the gradients)
              is a sum or a mean operation. Can take values "sum" or "mean"
          poisson_sampling: ``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: 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: mode for computing per sample gradients. Determines the
              implementation class for the wrapped ``module``. See
              :class:`~opacus.grad_sample.gsm_base.AbstractGradSampleModule` for more
              details
  
      Returns:
          Tuple of (model, optimizer, 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
          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.
      """
      sample_rate = 1 / len(data_loader)
  
      if len(self.accountant) > 0:
          warnings.warn(
              "You're calling make_private_with_epsilon with non-zero privacy budget "
              "already spent. Returned noise_multiplier assumes zero starting point, "
              "so your overall privacy budget will be higher."
          )
  
      return self.make_private(
          module=module,
          optimizer=optimizer,
          data_loader=data_loader,
          noise_multiplier=get_noise_multiplier(
              target_epsilon=target_epsilon,
              target_delta=target_delta,
              sample_rate=sample_rate,
              epochs=epochs,
              accountant=self.accountant.mechanism(),
              **kwargs,
          ),
          max_grad_norm=max_grad_norm,
          batch_first=batch_first,
          loss_reduction=loss_reduction,
          noise_generator=noise_generator,
          grad_sample_mode=grad_sample_mode,
          poisson_sampling=poisson_sampling,
          clipping=clipping,
      )
  
imports: import os
  import warnings
  from itertools import chain
  from typing import IO, Any, BinaryIO, Dict, List, Optional, Tuple, Union
  import torch
  from opacus.accountants import create_accountant
  from opacus.accountants.utils import get_noise_multiplier
  from opacus.data_loader import DPDataLoader, switch_generator
  from opacus.distributed import DifferentiallyPrivateDistributedDataParallel
  from opacus.grad_sample import AbstractGradSampleModule, GradSampleModule, get_gsm_class, wrap_model
  from opacus.optimizers import DPOptimizer, get_optimizer_class
  from opacus.schedulers import _GradClipScheduler, _NoiseScheduler
  from opacus.validators.module_validator import ModuleValidator
  from torch import nn, optim
  from torch.nn.parallel import DistributedDataParallel
  from torch.utils.data import DataLoader
label_desc: Use image node_id 9 for calling the PrivacyEngine obj's underlying member method code with example usage: obj.make_private_with_epsilon() and returns: self