class_docstr: MC-based batch acquisition function that reduces across samples and implements
  a general treatment of outcome constraints.
  
  This class's `forward` computes the - possibly constrained - acquisition value by
  (1) computing the unconstrained utility for each MC sample using `_sample_forward`,
  (2) weighing the utility values by the constraint indicator per MC sample, and
  (3) reducing (e.g. averaging) the weighted utility values over the MC dimension.
  
  NOTE: Do *NOT* override the `forward` method, unless you have thought about it well.
  
  `forward` is implemented generically to incorporate constraints in a principled way,
  and takes care of reducing over the Monte Carlo and batch dimensions via the
  `sample_reduction` and `q_reduction` arguments, which default to `torch.mean` and
  `torch.max`, respectively.
  
  In order to implement a custom SampleReducingMCAcquisitionFunction, we only need to
  implement the `_sample_forward(obj: Tensor) -> Tensor` method, which maps objective
  samples to acquisition utility values without reducing the Monte Carlo and batch
  (i.e. q) dimensions (see details in the docstring of `_sample_forward`).
  
  A note on design choices:
  
  The primary purpose of `SampleReducingMCAcquisitionFunction`is to support outcome
  constraints. On the surface, designing a wrapper `ConstrainedMCAcquisitionFunction`
  could be an elegant solution to this end, but it would still require the acquisition
  functions to implement a `_sample_forward` method to weigh acquisition utilities at
  the sample level. Further, `qNoisyExpectedImprovement` is a special case that is
  hard to encompass in this pattern, since it requires the computation of the best
  *feasible* objective, which requires access to the constraint functions. However,
  if the constraints are stored in a wrapper class, they will be inaccessible to the
  forward pass. These problems are circumvented by the design of this class.
class_docstr_tok: ["MC-based","batch","acquisition","function","that","reduces","across","samples","and","implements","a","general","treatment","of","outcome","constraints",".","This","class","'s","`","forward","`","computes","the","-","possibly","constrained","-","acquisition","value","by","(","1",")","computing","the","unconstrained","utility","for","each","MC","sample","using","`","_sample_forward","`",",","(","2",")","weighing","the","utility","values","by","the","constraint","indicator","per","MC","sample",",","and","(","3",")","reducing","(","e.g",".","averaging",")","the","weighted","utility","values","over","the","MC","dimension",".","NOTE",":","Do","*","NOT","*","override","the","`","forward","`","method",",","unless","you","have","thought","about","it","well",".","`","forward","`","is","implemented","generically","to","incorporate","constraints","in","a","principled","way",",","and","takes","care","of","reducing","over","the","Monte","Carlo","and","batch","dimensions","via","the","`","sample_reduction","`","and","`","q_reduction","`","arguments",",","which","default","to","`","torch.mean","`","and","`","torch.max","`",",","respectively",".","In","order","to","implement","a","custom","SampleReducingMCAcquisitionFunction",",","we","only","need","to","implement","the","`","_sample_forward","(","obj",":","Tensor",")","-",">","Tensor","`","method",",","which","maps","objective","samples","to","acquisition","utility","values","without","reducing","the","Monte","Carlo","and","batch","(","i.e",".","q",")","dimensions","(","see","details","in","the","docstring","of","`","_sample_forward","`",")",".","A","note","on","design","choices",":","The","primary","purpose","of","`","SampleReducingMCAcquisitionFunction","`","is","to","support","outcome","constraints",".","On","the","surface",",","designing","a","wrapper","`","ConstrainedMCAcquisitionFunction","`","could","be","an","elegant","solution","to","this","end",",","but","it","would","still","require","the","acquisition","functions","to","implement","a","`","_sample_forward","`","method","to","weigh","acquisition","utilities","at","the","sample","level",".","Further",",","`","qNoisyExpectedImprovement","`","is","a","special","case","that","is","hard","to","encompass","in","this","pattern",",","since","it","requires","the","computation","of","the","best","*","feasible","*","objective",",","which","requires","access","to","the","constraint","functions",".","However",",","if","the","constraints","are","stored","in","a","wrapper","class",",","they","will","be","inaccessible","to","the","forward","pass",".","These","problems","are","circumvented","by","the","design","of","this","class","."]
docstr: Constructor of SampleReducingMCAcquisitionFunction.
  
  Args:
      model: A fitted model.
      sampler: The sampler used to draw base samples. If not given, a
          sampler is generated on the fly within the
          `get_posterior_samples` method using
          `botorch.sampling.get_sampler`.
          NOTE: For posteriors that do not support base samples,
          a sampler compatible with intended use case must be provided.
          See `ForkedRNGSampler` and `StochasticSampler` as examples.
      objective: The MCAcquisitionObjective under which the samples are
          evaluated. Defaults to `IdentityMCObjective()`.
          NOTE: `ConstrainedMCObjective` for outcome constraints is deprecated in
          favor of passing the `constraints` directly to this constructor.
      posterior_transform: A `PosteriorTransform` (optional).
      X_pending: A `batch_shape, m x d`-dim Tensor of `m` design points
          that have points that have been submitted for function evaluation
          but have not yet been evaluated.
      sample_reduction: A callable that takes in a `sample_shape x batch_shape`
          Tensor of acquisition utility values, a keyword-argument `dim` that
          specifies the sample dimensions to reduce over, and returns a
          `batch_shape`-dim Tensor of acquisition values.
      q_reduction: A callable that takes in a `sample_shape x batch_shape x q`
          Tensor of acquisition utility values, a keyword-argument `dim` that
          specifies the q dimension to reduce over (i.e. -1), and returns a
          `sample_shape x batch_shape`-dim Tensor of acquisition values.
      constraints: A list of constraint callables which map a Tensor of posterior
          samples of dimension `sample_shape x batch-shape x q x m`-dim to a
          `sample_shape x batch-shape x q`-dim Tensor. The associated constraints
          are considered satisfied if the output is less than zero.
          NOTE: Constraint-weighting is only compatible with non-negative
          acquistion utilities, e.g. all improvement-based acquisition functions.
      eta: Temperature parameter(s) governing the smoothness of the sigmoid
          approximation to the constraint indicators. For more details, on this
          parameter, see the docs of `compute_smoothed_feasibility_indicator`.
      fat: Wether to apply a fat-tailed smooth approximation to the feasibility
          indicator or the canonical sigmoid approximation.
docstr_tok: ["Constructor","of","SampleReducingMCAcquisitionFunction",".","Args",":","model",":","A","fitted","model",".","sampler",":","The","sampler","used","to","draw","base","samples",".","If","not","given",",","a","sampler","is","generated","on","the","fly","within","the","`","get_posterior_samples","`","method","using","`","botorch.sampling.get_sampler","`",".","NOTE",":","For","posteriors","that","do","not","support","base","samples",",","a","sampler","compatible","with","intended","use","case","must","be","provided",".","See","`","ForkedRNGSampler","`","and","`","StochasticSampler","`","as","examples",".","objective",":","The","MCAcquisitionObjective","under","which","the","samples","are","evaluated",".","Defaults","to","`","IdentityMCObjective","(",")","`",".","NOTE",":","`","ConstrainedMCObjective","`","for","outcome","constraints","is","deprecated","in","favor","of","passing","the","`","constraints","`","directly","to","this","constructor",".","posterior_transform",":","A","`","PosteriorTransform","`","(","optional",")",".","X_pending",":","A","`","batch_shape",",","m","x","d","`","-dim","Tensor","of","`","m","`","design","points","that","have","points","that","have","been","submitted","for","function","evaluation","but","have","not","yet","been","evaluated",".","sample_reduction",":","A","callable","that","takes","in","a","`","sample_shape","x","batch_shape","`","Tensor","of","acquisition","utility","values",",","a","keyword-argument","`","dim","`","that","specifies","the","sample","dimensions","to","reduce","over",",","and","returns","a","`","batch_shape","`","-dim","Tensor","of","acquisition","values",".","q_reduction",":","A","callable","that","takes","in","a","`","sample_shape","x","batch_shape","x","q","`","Tensor","of","acquisition","utility","values",",","a","keyword-argument","`","dim","`","that","specifies","the","q","dimension","to","reduce","over","(","i.e",".","-1",")",",","and","returns","a","`","sample_shape","x","batch_shape","`","-dim","Tensor","of","acquisition","values",".","constraints",":","A","list","of","constraint","callables","which","map","a","Tensor","of","posterior","samples","of","dimension","`","sample_shape","x","batch-shape","x","q","x","m","`","-dim","to","a","`","sample_shape","x","batch-shape","x","q","`","-dim","Tensor",".","The","associated","constraints","are","considered","satisfied","if","the","output","is","less","than","zero",".","NOTE",":","Constraint-weighting","is","only","compatible","with","non-negative","acquistion","utilities",",","e.g",".","all","improvement-based","acquisition","functions",".","eta",":","Temperature","parameter","(","s",")","governing","the","smoothness","of","the","sigmoid","approximation","to","the","constraint","indicators",".","For","more","details",",","on","this","parameter",",","see","the","docs","of","`","compute_smoothed_feasibility_indicator","`",".","fat",":","Wether","to","apply","a","fat-tailed","smooth","approximation","to","the","feasibility","indicator","or","the","canonical","sigmoid","approximation","."]
code: def __init__(
      self,
      model: Model,
      sampler: Optional[MCSampler] = None,
      objective: Optional[MCAcquisitionObjective] = None,
      posterior_transform: Optional[PosteriorTransform] = None,
      X_pending: Optional[Tensor] = None,
      sample_reduction: SampleReductionProtocol = torch.mean,
      q_reduction: SampleReductionProtocol = torch.amax,
      constraints: Optional[List[Callable[[Tensor], Tensor]]] = None,
      eta: Union[Tensor, float] = 1e-3,
      fat: bool = False,
  ):
      r"""Constructor of SampleReducingMCAcquisitionFunction.
  
      Args:
          model: A fitted model.
          sampler: The sampler used to draw base samples. If not given, a
              sampler is generated on the fly within the
              `get_posterior_samples` method using
              `botorch.sampling.get_sampler`.
              NOTE: For posteriors that do not support base samples,
              a sampler compatible with intended use case must be provided.
              See `ForkedRNGSampler` and `StochasticSampler` as examples.
          objective: The MCAcquisitionObjective under which the samples are
              evaluated. Defaults to `IdentityMCObjective()`.
              NOTE: `ConstrainedMCObjective` for outcome constraints is deprecated in
              favor of passing the `constraints` directly to this constructor.
          posterior_transform: A `PosteriorTransform` (optional).
          X_pending: A `batch_shape, m x d`-dim Tensor of `m` design points
              that have points that have been submitted for function evaluation
              but have not yet been evaluated.
          sample_reduction: A callable that takes in a `sample_shape x batch_shape`
              Tensor of acquisition utility values, a keyword-argument `dim` that
              specifies the sample dimensions to reduce over, and returns a
              `batch_shape`-dim Tensor of acquisition values.
          q_reduction: A callable that takes in a `sample_shape x batch_shape x q`
              Tensor of acquisition utility values, a keyword-argument `dim` that
              specifies the q dimension to reduce over (i.e. -1), and returns a
              `sample_shape x batch_shape`-dim Tensor of acquisition values.
          constraints: A list of constraint callables which map a Tensor of posterior
              samples of dimension `sample_shape x batch-shape x q x m`-dim to a
              `sample_shape x batch-shape x q`-dim Tensor. The associated constraints
              are considered satisfied if the output is less than zero.
              NOTE: Constraint-weighting is only compatible with non-negative
              acquistion utilities, e.g. all improvement-based acquisition functions.
          eta: Temperature parameter(s) governing the smoothness of the sigmoid
              approximation to the constraint indicators. For more details, on this
              parameter, see the docs of `compute_smoothed_feasibility_indicator`.
          fat: Wether to apply a fat-tailed smooth approximation to the feasibility
              indicator or the canonical sigmoid approximation.
      """
      if constraints is not None and isinstance(
          objective, ConstrainedMCObjective
      ):
          raise ValueError(
              "ConstrainedMCObjective as well as constraints passed to constructor."
              "Choose one or the other, preferably the latter."
          )
      # TODO: deprecate ConstrainedMCObjective
      super().__init__(
          model=model,
          sampler=sampler,
          objective=objective,
          posterior_transform=posterior_transform,
          X_pending=X_pending,
      )
      # Shall the need arise, sample_dim could be exposed in the constructor.
      sample_dim = tuple(range(len(self.sample_shape)))
      self._sample_reduction = partial(sample_reduction, dim=sample_dim)
      self._q_reduction = partial(q_reduction, dim=-1)
      self._constraints = constraints
      self._eta = eta
      self._fat = fat
  
imports: from __future__ import annotations
  import math
  from abc import ABC, abstractmethod
  from copy import deepcopy
  from functools import partial
  from typing import Callable, List, Optional, Protocol, Tuple, Union
  import torch
  from botorch.acquisition.acquisition import AcquisitionFunction, MCSamplerMixin
  from botorch.acquisition.cached_cholesky import CachedCholeskyMCSamplerMixin
  from botorch.acquisition.objective import ConstrainedMCObjective, IdentityMCObjective, MCAcquisitionObjective, PosteriorTransform
  from botorch.acquisition.utils import compute_best_feasible_objective, prune_inferior_points, repeat_to_match_aug_dim
  from botorch.exceptions.errors import UnsupportedError
  from botorch.models.model import Model
  from botorch.sampling.base import MCSampler
  from botorch.utils.objective import compute_smoothed_feasibility_indicator
  from botorch.utils.transforms import concatenate_pending_points, match_batch_shape, t_batch_mode_transform
  from torch import Tensor
label_desc: Use image node_id 1 to create a new SampleReducingMCAcquisitionFunction object from inherited base classes: MCAcquisitionFunction with example: obj = SampleReducingMCAcquisitionFunction(model, sampler, objective, posterior_transform, X_pending, sample_reduction, q_reduction, constraints, eta, fat)