class_docstr: Batch Hypervolume Knowledge Gradient using one-shot optimization.
  
  The hypervolume knowledge gradient seeks to maximize the difference in
  hypervolume of the hypervolume-maximizing set of a fixed size after
  conditioning the unknown observation(s) that would be recevied if X where
  evalauted. See [Daulton2023hvkg]_ for details.
  
  This computes the batch Hypervolume Knowledge Gradient using fantasies for
  the outer expectation and MC-sampling for the inner expectation.
  
  In addition to the design variables, the input `X` also includes variables
  for the optimal designs for each of the fantasy models (Note this is
  `N x N_pareto` optimal designs). For a fixed number of fantasies, all points
  in `X` can be optimized in a "one-shot" fashion.
class_docstr_tok: ["Batch","Hypervolume","Knowledge","Gradient","using","one-shot","optimization",".","The","hypervolume","knowledge","gradient","seeks","to","maximize","the","difference","in","hypervolume","of","the","hypervolume-maximizing","set","of","a","fixed","size","after","conditioning","the","unknown","observation","(","s",")","that","would","be","recevied","if","X","where","evalauted",".","See","[","Daulton2023hvkg","]","_","for","details",".","This","computes","the","batch","Hypervolume","Knowledge","Gradient","using","fantasies","for","the","outer","expectation","and","MC-sampling","for","the","inner","expectation",".","In","addition","to","the","design","variables",",","the","input","`","X","`","also","includes","variables","for","the","optimal","designs","for","each","of","the","fantasy","models","(","Note","this","is","`","N","x","N_pareto","`","optimal","designs",")",".","For","a","fixed","number","of","fantasies",",","all","points","in","`","X","`","can","be","optimized","in","a","``","one-shot","''","fashion","."]
docstr: q-Hypervolume Knowledge Gradient.
  
  Args:
      model: A fitted model. Must support fantasizing.
      ref_point: A `m`-dim tensor containing the reference point.
      num_fantasies: The number of fantasy points to use. More fantasy
          points result in a better approximation, at the expense of
          memory and wall time. Unused if `sampler` is specified.
      num_pareto: The number of pareto optimal designs to consider.
      sampler: The sampler used to sample fantasy observations. Optional
          if `num_fantasies` is specified. The optimization performance
          does not seem particularly sensitive to the number of fantasies.
          As the number of fantasies increases, the estimation of the
          expectation over fantasies becomes more accurate, but the one-
          shot optimization problem gets harder as there are more "fantasy"
          designs that need to be optimized.
      objective: The objective under which the samples are evaluated. If
          `None`, then the analytic posterior mean is used. Otherwise, the
          objective is MC-evaluated (using inner_sampler).
      inner_sampler: The sampler used for inner sampling. Ignored if the
          objective is `None`.
      X_evaluation_mask: A `q x m`-dim tensor of booleans indicating which
          objective(s) each of the `q` points should be evaluated on.
      X_pending: A `n' x d`-dim Tensor of `m` design points that have
          points that have been submitted for function evaluation
          but have not yet been evaluated.
      X_pending_evaluation_mask: A `n' x m`-dim tensor of booleans indicating
          which objective(s) each of the `n'` pending points are being
          evaluated on.
      current_value: The current value, i.e. the expected best objective
          given the observed points `D`. If omitted, forward will not
          return the actual KG value, but the expected best objective
          given the data set `D u X`. If pending points are used,
          this should be the current value under the fantasy model
          conditioned on the pending points so that the incremental KG value
          from the new candidates (not pending points) is used.
      use_posterior_mean: If true, optimize the hypervolume of the posterior
          mean, otherwise optimize the expected hypervolume. See
          [Daulton2023hvkg]_ for details.
      cost_aware_utility: A CostAwareUtility specifying the cost function for
          evaluating the `X` on the objectives indicated by `evaluation_mask`.
docstr_tok: ["q-Hypervolume","Knowledge","Gradient",".","Args",":","model",":","A","fitted","model",".","Must","support","fantasizing",".","ref_point",":","A","`","m","`","-dim","tensor","containing","the","reference","point",".","num_fantasies",":","The","number","of","fantasy","points","to","use",".","More","fantasy","points","result","in","a","better","approximation",",","at","the","expense","of","memory","and","wall","time",".","Unused","if","`","sampler","`","is","specified",".","num_pareto",":","The","number","of","pareto","optimal","designs","to","consider",".","sampler",":","The","sampler","used","to","sample","fantasy","observations",".","Optional","if","`","num_fantasies","`","is","specified",".","The","optimization","performance","does","not","seem","particularly","sensitive","to","the","number","of","fantasies",".","As","the","number","of","fantasies","increases",",","the","estimation","of","the","expectation","over","fantasies","becomes","more","accurate",",","but","the","one-","shot","optimization","problem","gets","harder","as","there","are","more","``","fantasy","''","designs","that","need","to","be","optimized",".","objective",":","The","objective","under","which","the","samples","are","evaluated",".","If","`","None","`",",","then","the","analytic","posterior","mean","is","used",".","Otherwise",",","the","objective","is","MC-evaluated","(","using","inner_sampler",")",".","inner_sampler",":","The","sampler","used","for","inner","sampling",".","Ignored","if","the","objective","is","`","None","`",".","X_evaluation_mask",":","A","`","q","x","m","`","-dim","tensor","of","booleans","indicating","which","objective","(","s",")","each","of","the","`","q","`","points","should","be","evaluated","on",".","X_pending",":","A","`","n","'","x","d","`","-dim","Tensor","of","`","m","`","design","points","that","have","points","that","have","been","submitted","for","function","evaluation","but","have","not","yet","been","evaluated",".","X_pending_evaluation_mask",":","A","`","n","'","x","m","`","-dim","tensor","of","booleans","indicating","which","objective","(","s",")","each","of","the","`","n","'","`","pending","points","are","being","evaluated","on",".","current_value",":","The","current","value",",","i.e",".","the","expected","best","objective","given","the","observed","points","`","D","`",".","If","omitted",",","forward","will","not","return","the","actual","KG","value",",","but","the","expected","best","objective","given","the","data","set","`","D","u","X","`",".","If","pending","points","are","used",",","this","should","be","the","current","value","under","the","fantasy","model","conditioned","on","the","pending","points","so","that","the","incremental","KG","value","from","the","new","candidates","(","not","pending","points",")","is","used",".","use_posterior_mean",":","If","true",",","optimize","the","hypervolume","of","the","posterior","mean",",","otherwise","optimize","the","expected","hypervolume",".","See","[","Daulton2023hvkg","]","_","for","details",".","cost_aware_utility",":","A","CostAwareUtility","specifying","the","cost","function","for","evaluating","the","`","X","`","on","the","objectives","indicated","by","`","evaluation_mask","`","."]
code: def __init__(
      self,
      model: Model,
      ref_point: Tensor,
      num_fantasies: int = 8,
      num_pareto: int = 10,
      sampler: Optional[ListSampler] = None,
      objective: Optional[MCMultiOutputObjective] = None,
      inner_sampler: Optional[MCSampler] = None,
      X_evaluation_mask: Optional[List[Tensor]] = None,
      X_pending: Optional[Tensor] = None,
      X_pending_evaluation_mask: Optional[Tensor] = None,
      current_value: Optional[Tensor] = None,
      use_posterior_mean: bool = True,
      cost_aware_utility: Optional[CostAwareUtility] = None,
      **kwargs: Any,
  ) -> None:
      r"""q-Hypervolume Knowledge Gradient.
  
      Args:
          model: A fitted model. Must support fantasizing.
          ref_point: A `m`-dim tensor containing the reference point.
          num_fantasies: The number of fantasy points to use. More fantasy
              points result in a better approximation, at the expense of
              memory and wall time. Unused if `sampler` is specified.
          num_pareto: The number of pareto optimal designs to consider.
          sampler: The sampler used to sample fantasy observations. Optional
              if `num_fantasies` is specified. The optimization performance
              does not seem particularly sensitive to the number of fantasies.
              As the number of fantasies increases, the estimation of the
              expectation over fantasies becomes more accurate, but the one-
              shot optimization problem gets harder as there are more "fantasy"
              designs that need to be optimized.
          objective: The objective under which the samples are evaluated. If
              `None`, then the analytic posterior mean is used. Otherwise, the
              objective is MC-evaluated (using inner_sampler).
          inner_sampler: The sampler used for inner sampling. Ignored if the
              objective is `None`.
          X_evaluation_mask: A `q x m`-dim tensor of booleans indicating which
              objective(s) each of the `q` points should be evaluated on.
          X_pending: A `n' x d`-dim Tensor of `m` design points that have
              points that have been submitted for function evaluation
              but have not yet been evaluated.
          X_pending_evaluation_mask: A `n' x m`-dim tensor of booleans indicating
              which objective(s) each of the `n'` pending points are being
              evaluated on.
          current_value: The current value, i.e. the expected best objective
              given the observed points `D`. If omitted, forward will not
              return the actual KG value, but the expected best objective
              given the data set `D u X`. If pending points are used,
              this should be the current value under the fantasy model
              conditioned on the pending points so that the incremental KG value
              from the new candidates (not pending points) is used.
          use_posterior_mean: If true, optimize the hypervolume of the posterior
              mean, otherwise optimize the expected hypervolume. See
              [Daulton2023hvkg]_ for details.
          cost_aware_utility: A CostAwareUtility specifying the cost function for
              evaluating the `X` on the objectives indicated by `evaluation_mask`.
      """
      if sampler is None:
          # base samples should be fixed for joint optimization over X, X_fantasies
          samplers = [
              SobolQMCNormalSampler(
                  sample_shape=torch.Size([num_fantasies])
              )
              for _ in range(model.num_outputs)
          ]
          sampler = ListSampler(*samplers)
      else:
          sample_shape = sampler.samplers[0].sample_shape
          if sample_shape != torch.Size([num_fantasies]):
              raise ValueError(
                  f"The sampler shape must match num_fantasies={num_fantasies}."
              )
      super().__init__(model=model, X_evaluation_mask=X_evaluation_mask)
  
      if inner_sampler is None:
          inner_sampler = SobolQMCNormalSampler(
              sample_shape=torch.Size([32])
          )
      if current_value is None and cost_aware_utility is not None:
          raise UnsupportedError(
              "Cost-aware HVKG requires current_value to be specified."
          )
      self.register_buffer("ref_point", ref_point)
      self.sampler = sampler
      self.objective = objective
      self.set_X_pending(
          X_pending=X_pending,
          X_pending_evaluation_mask=X_pending_evaluation_mask,
      )
      self.inner_sampler = inner_sampler
      self.num_fantasies = num_fantasies
      self.num_pareto = num_pareto
      self.num_pseudo_points = num_fantasies * num_pareto
      self.current_value = current_value
      self.use_posterior_mean = use_posterior_mean
      self.cost_aware_utility = cost_aware_utility
      self._cost_sampler = None
  
imports: from copy import deepcopy
  from typing import Any, Callable, Dict, List, Optional, Tuple, Type
  import torch
  from botorch import settings
  from botorch.acquisition.acquisition import AcquisitionFunction, OneShotAcquisitionFunction
  from botorch.acquisition.cost_aware import CostAwareUtility
  from botorch.acquisition.decoupled import DecoupledAcquisitionFunction
  from botorch.acquisition.knowledge_gradient import ProjectedAcquisitionFunction
  from botorch.acquisition.multi_objective.monte_carlo import MultiObjectiveMCAcquisitionFunction, qExpectedHypervolumeImprovement
  from botorch.acquisition.multi_objective.objective import MCMultiOutputObjective
  from botorch.exceptions.errors import UnsupportedError
  from botorch.models.deterministic import PosteriorMeanModel
  from botorch.models.model import Model
  from botorch.sampling.base import MCSampler
  from botorch.sampling.list_sampler import ListSampler
  from botorch.sampling.normal import SobolQMCNormalSampler
  from botorch.sampling.stochastic_samplers import StochasticSampler
  from botorch.utils.multi_objective.box_decompositions.non_dominated import FastNondominatedPartitioning
  from botorch.utils.transforms import match_batch_shape, t_batch_mode_transform
  from torch import Tensor
label_desc: Use image node_id 1 to create a new qHypervolumeKnowledgeGradient object from inherited base classes: DecoupledAcquisitionFunction, MultiObjectiveMCAcquisitionFunction, OneShotAcquisitionFunction with example: obj = qHypervolumeKnowledgeGradient(model, ref_point, num_fantasies, num_pareto, sampler, objective, inner_sampler, X_evaluation_mask, X_pending, X_pending_evaluation_mask, current_value, use_posterior_mean, cost_aware_utility)