class_docstr: MC-based batch Multi-Step Look-Ahead (one-shot optimization).
docstr: q-Multi-Step Look-Ahead (one-shot optimization).
  
  Performs a `k`-step lookahead by means of repeated fantasizing.
  
  Allows to specify the stage value functions by passing the respective class
  objects via the `valfunc_cls` list. Optionally, `valfunc_argfacs` takes a list
  of callables that generate additional kwargs for these constructors. By default,
  `valfunc_cls` will be chosen as `[None, ..., None, PosteriorMean]`, which
  corresponds to the (parallel) multi-step KnowledgeGradient. If, in addition,
  `k=1` and `q_1 = 1`, this reduces to the classic Knowledge Gradient.
  
  WARNING: The complexity of evaluating this function is exponential in the number
  of lookahead steps!
  
  Args:
      model: A fitted model.
      batch_sizes: A list `[q_1, ..., q_k]` containing the batch sizes for the
          `k` look-ahead steps.
      num_fantasies: A list `[f_1, ..., f_k]` containing the number of fantasy
          points to use for the `k` look-ahead steps.
      samplers: A list of MCSampler objects to be used for sampling fantasies in
          each stage.
      valfunc_cls: A list of `k + 1` acquisition function classes to be used as
          the (stage + terminal) value functions. Each element (except for the
          last one) can be `None`, in which case a zero stage value is assumed for
          the respective stage. If `None`, this defaults to
          `[None, ..., None, PosteriorMean]`
      valfunc_argfacs: A list of `k + 1` "argument factories", i.e. callables that
          map a `Model` and input tensor `X` to a dictionary of kwargs for the
          respective stage value function constructor (e.g. `best_f` for
          `ExpectedImprovement`). If None, only the standard (`model`, `sampler`
          and `objective`) kwargs will be used.
      objective: The objective under which the output is evaluated. If `None`, use
          the model output (requires a single-output model or a posterior
          transform). Otherwise the objective is MC-evaluated
          (using `inner_sampler`).
      posterior_transform: An optional PosteriorTransform. If given, this
          transforms the posterior before evaluation. If `objective is None`,
          then the output of the transformed posterior is used. If `objective` is
          given, the `inner_sampler` is used to draw samples from the transformed
          posterior, which are then evaluated under the `objective`.
      inner_mc_samples: A list `[n_0, ..., n_k]` containing the number of MC
          samples to be used for evaluating the stage value function. Ignored if
          the objective is `None`.
      X_pending: A `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. Concatenated into `X` upon forward call. Copied and set to
          have no gradient.
      collapse_fantasy_base_samples: If True, collapse_batch_dims of the Samplers
          will be applied on fantasy batch dimensions as well, meaning that base
          samples are the same in all subtrees starting from the same level.
code: def __init__(
      self,
      model: Model,
      batch_sizes: List[int],
      num_fantasies: Optional[List[int]] = None,
      samplers: Optional[List[MCSampler]] = None,
      valfunc_cls: Optional[
          List[Optional[Type[AcquisitionFunction]]]
      ] = None,
      valfunc_argfacs: Optional[
          List[Optional[TAcqfArgConstructor]]
      ] = None,
      objective: Optional[MCAcquisitionObjective] = None,
      posterior_transform: Optional[PosteriorTransform] = None,
      inner_mc_samples: Optional[List[int]] = None,
      X_pending: Optional[Tensor] = None,
      collapse_fantasy_base_samples: bool = True,
  ) -> None:
      r"""q-Multi-Step Look-Ahead (one-shot optimization).
  
      Performs a `k`-step lookahead by means of repeated fantasizing.
  
      Allows to specify the stage value functions by passing the respective class
      objects via the `valfunc_cls` list. Optionally, `valfunc_argfacs` takes a list
      of callables that generate additional kwargs for these constructors. By default,
      `valfunc_cls` will be chosen as `[None, ..., None, PosteriorMean]`, which
      corresponds to the (parallel) multi-step KnowledgeGradient. If, in addition,
      `k=1` and `q_1 = 1`, this reduces to the classic Knowledge Gradient.
  
      WARNING: The complexity of evaluating this function is exponential in the number
      of lookahead steps!
  
      Args:
          model: A fitted model.
          batch_sizes: A list `[q_1, ..., q_k]` containing the batch sizes for the
              `k` look-ahead steps.
          num_fantasies: A list `[f_1, ..., f_k]` containing the number of fantasy
              points to use for the `k` look-ahead steps.
          samplers: A list of MCSampler objects to be used for sampling fantasies in
              each stage.
          valfunc_cls: A list of `k + 1` acquisition function classes to be used as
              the (stage + terminal) value functions. Each element (except for the
              last one) can be `None`, in which case a zero stage value is assumed for
              the respective stage. If `None`, this defaults to
              `[None, ..., None, PosteriorMean]`
          valfunc_argfacs: A list of `k + 1` "argument factories", i.e. callables that
              map a `Model` and input tensor `X` to a dictionary of kwargs for the
              respective stage value function constructor (e.g. `best_f` for
              `ExpectedImprovement`). If None, only the standard (`model`, `sampler`
              and `objective`) kwargs will be used.
          objective: The objective under which the output is evaluated. If `None`, use
              the model output (requires a single-output model or a posterior
              transform). Otherwise the objective is MC-evaluated
              (using `inner_sampler`).
          posterior_transform: An optional PosteriorTransform. If given, this
              transforms the posterior before evaluation. If `objective is None`,
              then the output of the transformed posterior is used. If `objective` is
              given, the `inner_sampler` is used to draw samples from the transformed
              posterior, which are then evaluated under the `objective`.
          inner_mc_samples: A list `[n_0, ..., n_k]` containing the number of MC
              samples to be used for evaluating the stage value function. Ignored if
              the objective is `None`.
          X_pending: A `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. Concatenated into `X` upon forward call. Copied and set to
              have no gradient.
          collapse_fantasy_base_samples: If True, collapse_batch_dims of the Samplers
              will be applied on fantasy batch dimensions as well, meaning that base
              samples are the same in all subtrees starting from the same level.
      """
      if objective is not None and not isinstance(
          objective, MCAcquisitionObjective
      ):
          raise UnsupportedError(
              "`qMultiStepLookahead` got a non-MC `objective`. This is not supported."
              " Use `posterior_transform` and `objective=None` instead."
          )
  
      super(MCAcquisitionFunction, self).__init__(model=model)
      self.batch_sizes = batch_sizes
      if not ((num_fantasies is None) ^ (samplers is None)):
          raise UnsupportedError(
              "qMultiStepLookahead requires exactly one of `num_fantasies` or "
              "`samplers` as arguments."
          )
      if samplers is None:
          # If collapse_fantasy_base_samples is False, the `batch_range_override`
          # is set on the samplers during the forward call.
          samplers: List[MCSampler] = [
              SobolQMCNormalSampler(sample_shape=torch.Size([nf]))
              for nf in num_fantasies
          ]
      else:
          num_fantasies = [
              sampler.sample_shape[0] for sampler in samplers
          ]
      self.num_fantasies = num_fantasies
      # By default do not use stage values and use PosteriorMean as terminal value
      # function (= multi-step KG)
      if valfunc_cls is None:
          valfunc_cls = [None for _ in num_fantasies] + [PosteriorMean]
      if inner_mc_samples is None:
          inner_mc_samples = [None] * (1 + len(num_fantasies))
      # TODO: Allow passing in inner samplers directly
      inner_samplers = _construct_inner_samplers(
          batch_sizes=batch_sizes,
          valfunc_cls=valfunc_cls,
          objective=objective,
          inner_mc_samples=inner_mc_samples,
      )
      if valfunc_argfacs is None:
          valfunc_argfacs = [None] * (1 + len(batch_sizes))
  
      self.objective = objective
      self.posterior_transform = posterior_transform
      self.set_X_pending(X_pending)
      self.samplers = ModuleList(samplers)
      self.inner_samplers = ModuleList(inner_samplers)
      self._valfunc_cls = valfunc_cls
      self._valfunc_argfacs = valfunc_argfacs
      self._collapse_fantasy_base_samples = (
          collapse_fantasy_base_samples
      )
  
imports: from __future__ import annotations
  import math
  import warnings
  from typing import Any, Callable, Dict, List, Optional, Tuple, Type
  import numpy
  import torch
  from botorch.acquisition import AcquisitionFunction, OneShotAcquisitionFunction
  from botorch.acquisition.analytic import AnalyticAcquisitionFunction, PosteriorMean
  from botorch.acquisition.monte_carlo import MCAcquisitionFunction
  from botorch.acquisition.objective import MCAcquisitionObjective, PosteriorTransform
  from botorch.exceptions.errors import UnsupportedError
  from botorch.exceptions.warnings import BotorchWarning
  from botorch.models.model import Model
  from botorch.optim.initializers import initialize_q_batch
  from botorch.sampling.base import MCSampler
  from botorch.sampling.normal import SobolQMCNormalSampler
  from botorch.utils.transforms import match_batch_shape, t_batch_mode_transform, unnormalize
  from torch import Size, Tensor
  from torch.distributions import Beta
  from torch.nn import ModuleList
label_desc: Use image node_id 1 to create a new qMultiStepLookahead object from inherited base classes: MCAcquisitionFunction, OneShotAcquisitionFunction with example: obj = qMultiStepLookahead(model, batch_sizes, num_fantasies, samplers, valfunc_cls, valfunc_argfacs, objective, posterior_transform, inner_mc_samples, X_pending, collapse_fantasy_base_samples)