characterization

Functions

chi2_sampler([n, generator, device, dtype])

Sample from chi-squared distribution with 2 degrees of freedom.

Classes

qMultiRandomizedStraddle(model, threshold[, ...])	Multi-target randomized straddle with smooth plateau masking.
qMultiStraddle(model, threshold[, weights, ...])	Multi-target straddle acquisition using smooth masking for level set estimation.
qRandomizedStraddle(model, threshold[, ...])	qRandomizedStraddle implements the randomized straddle acquisition for level set estimation (LSE), replacing the fixed confidence parameter with a chi-squared random draw and clipping the score at zero.
qStraddle(model, threshold[, beta, sampler, ...])	qStraddle implements the classic "straddle" acquisition function for level set estimation (LSE) with Monte Carlo sampling in BoTorch style.

obsidian.acquisition.characterization.chi2_sampler(n: int = 1, generator: Generator | None = None, device: device | str = device(type='cpu'), dtype=torch.float64) → Tensor

Sample from chi-squared distribution with 2 degrees of freedom.

Parameters:

• n – Number of samples to draw

• generator – Random number generator for reproducibility

• device – Device to create tensor on

• dtype – Data type of output tensor

Returns:

Tensor of shape (n,) if n > 1, scalar if n == 1

class obsidian.acquisition.characterization.qMultiRandomizedStraddle(model: Model, threshold: Tensor | list[float], weights: list[float] | ndarray | Tensor | None = None, beta: Tensor | list[float] | None = None, batch_size: int = 1, sync_objective_beta: bool = False, k_decay: float = 2.0, tau: float = 0.5, kernel_reduction: str = 'softmin', sampler: MCSampler = SobolQMCNormalSampler(), objective=None, posterior_transform=None, X_pending=None, generator: Generator | None = None, n_obs: int | None = None, device: device | str = device(type='cpu'))

Bases: qMultiStraddle

Multi-target randomized straddle with smooth plateau masking.

Extends qMultiStraddle by sampling beta independently per target from a chi-squared distribution, following the randomized straddle algorithm. Following GP-UCB convention, beta is the squared confidence parameter; the σ-multiplier used by the kernel is √β.

Parameters:

• threshold – 1D tensor or list of thresholds, one per target.

• beta –

  Squared confidence parameter(s). When sampled automatically, β ~ χ²₂. Can be: - None: For m_batch=1, samples independently per-target (legacy behavior). - Scalar: Use single β for all q points and all targets. - 1D tensor of shape (q,): Per-q-point β, same across all targets.

  This is the default when m_batch > 1 (sampled by parser).

  • 1D tensor of shape (num_targets,): Per-target β (legacy mode).

  • 2D tensor of shape (q, num_targets): Full specification.

• generator – Random generator for reproducible sampling.

• tau – Temperature for softmin reduction (scalar, must be > 0). Lower tau enforces balanced criticality across targets (soft-AND); higher tau tolerates candidates critical on only one target (approaches the mean). Default 0.5.

• weights – Per-target weights. For “softmin” reduction, acts as focus multiplier.

class obsidian.acquisition.characterization.qMultiStraddle(model: Model, threshold: list[float] | ndarray | Tensor, weights: list[float] | ndarray | Tensor | None = None, beta: Tensor | float | None = None, k_decay: float = 2.0, tau: float = 0.5, kernel_reduction: str = 'softmin', sampler: MCSampler = SobolQMCNormalSampler(), objective=None, posterior_transform=None, X_pending=None, device: device | str = device(type='cpu'))

Bases: MCAcquisitionFunction

Multi-target straddle acquisition using smooth masking for level set estimation.

Parameters:

• threshold – 1D tensor or list of thresholds, one per target

• beta – Confidence parameter(s) for UCB computation

• k_decay – Decay rate for the smooth plateau (default: 2.0)

• kernel_reduction – How to combine kernel values across targets (“sum”, “max”, or “softmin”)

• tau – Temperature for softmin reduction (scalar, must be > 0). Lower tau enforces balanced criticality across targets (soft-AND); higher tau tolerates candidates critical on only one target (approaches the mean). Default 0.5.

• weights – Per-target weights. For “sum” reduction, these are direct multipliers. For “softmin” reduction, these act as focus multipliers (higher = more attention to that target). Default is uniform weights.

forward(X: Tensor) → Tensor

Takes in a batch_shape x q x d X Tensor of t-batches with q d-dim design points each, and returns a Tensor with shape batch_shape’, where batch_shape’ is the broadcasted batch shape of model and input X. Should utilize the result of set_X_pending as needed to account for pending function evaluations.

class obsidian.acquisition.characterization.qRandomizedStraddle(model, threshold: float, batch_size: int = 1, sampler: MCSampler = SobolQMCNormalSampler(), objective=None, posterior_transform=None, X_pending=None, generator: Generator | None = None, beta: Tensor | float | None = None, n_obs: int | None = None, device: device | str = device(type='cpu'))

Bases: qStraddle

qRandomizedStraddle implements the randomized straddle acquisition for level set estimation (LSE), replacing the fixed confidence parameter with a chi-squared random draw and clipping the score at zero.

Following the UCB/LSE convention, beta is the squared confidence parameter; the multiplier used by the kernel is √β.

Parameters:

• model – A fitted single-output GP model.

• threshold – The target threshold value for level set estimation.

• beta –

  Optional squared confidence parameter(s). Can be: - None: Sample β ~ χ²₂ (default; the multiplier √β is then ~ √χ²₂) - Scalar: Use single β for all q points - 1D tensor of shape (q,): Per-q-point β for batch optimization

  (typically pre-sampled by the parser when m_batch > 1)

• generator – Random number generator for reproducibility when sampling beta.

• device – Device to create tensors on.

References

Inatsu, R., Abe, K., & Nishikawa, M. (2024). “Active Learning for Level Set Estimation Using Randomized Straddle Algorithms.”

class obsidian.acquisition.characterization.qStraddle(model, threshold: float, beta: Tensor | float | None = None, sampler: MCSampler = SobolQMCNormalSampler(), objective=None, posterior_transform=None, X_pending=None, device: device | str = device(type='cpu'))

Bases: MCAcquisitionFunction

qStraddle implements the classic “straddle” acquisition function for level set estimation (LSE) with Monte Carlo sampling in BoTorch style.

References Bryan, B., Nichol, R. C., Genovese, C. R., Schneider, J., Miller, C. J., & Wasserman, L. (2005). “Active Learning For Identifying Function Threshold Boundaries.”

forward(X: Tensor) → Tensor

Takes in a batch_shape x q x d X Tensor of t-batches with q d-dim design points each, and returns a Tensor with shape batch_shape’, where batch_shape’ is the broadcasted batch shape of model and input X. Should utilize the result of set_X_pending as needed to account for pending function evaluations.