> ## Documentation Index
> Fetch the complete documentation index at: https://docs.priorlabs.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> TabPFN-3 and later versions support up to 1,000,000 rows, subject to feature count and checkpoint/API limits.
> For large datasets, use per-estimator subsampling, e.g. inference_config={"SUBSAMPLE_SAMPLES": 100_000}, in TabPFNClassifier or TabPFNRegressor from tabpfn or tabpfn_client.
> Pass raw pandas DataFrames to fit and predict. Categorical strings/categories, raw text, and missing feature values are handled automatically; no manual integer/one-hot encoding, imputation, scaling, or outlier removal is needed.

# Bayesian optimization

> EI over ``best_f`` for a batch of points, differentiable w.r.t. ``x``.

## Installation

```bash theme={null}
pip install "tabpfn-extensions[bayesian_optimization]"
```

<div className="python-reference-heading">
  <h2 id="bayesian-optimization-bo-expected-improvement">
    `expected_improvement`
  </h2>

  <a className="python-reference-source" href="https://github.com/PriorLabs/tabpfn-extensions/blob/840c15a1848a986b39c85bc17efc61e0e377f983/src/tabpfn_extensions/bayesian_optimization/bo.py#L34" aria-label="View source for expected_improvement"><span aria-hidden="true">\</></span> View source <span aria-hidden="true">↗</span></a>
</div>

EI over `best_f` for a batch of points, differentiable w\.r.t. `x`.

`forward` returns bar-distribution logits as \[N\_borders, N\_samples];
after transposing, `raw_space_bardist_.ei` integrates the improvement
over the predicted distribution in closed form. Because the raw-space
borders are an affine rescaling of the z-normalized ones, the logits can
be used with the raw-space criterion directly and `best_f` is passed in
the original (unnormalized) target space.

```python theme={null}
expected_improvement(
    reg: TabPFNRegressor,
    x: torch.Tensor,
    best_f: float,
) -> torch.Tensor
```

**Parameters**

<div className="python-reference-table">
  | Parameter | Type | Default | Description |
  | - | - | - | - |
  | <span id="bayesian-optimization-bo-expected-improvement--reg" /><code className="python-reference-parameter">reg</code> | <code className="python-reference-type"><a href="/api-reference/python/tabpfn/regressor/configuration#constructor">Tab<wbr />PFN<wbr />Regressor</a></code> | Required | A fitted [`TabPFNRegressor`](/api-reference/python/tabpfn/regressor/configuration#constructor) with `differentiable_input=True`. |
  | <span id="bayesian-optimization-bo-expected-improvement--x" /><code className="python-reference-parameter">x</code> | <code className="python-reference-type">torch.Tensor</code> | Required | Candidate points of shape `(n, d)`. |
  | <span id="bayesian-optimization-bo-expected-improvement--best-f" /><code className="python-reference-parameter">best\_<wbr />f</code> | <code className="python-reference-type">float</code> | Required | Best objective value observed so far, in the original (unnormalized) target space. |
</div>

**Returns**

<div className="python-reference-table python-reference-returns">
  | Type | Description |
  | - | - |
  | <code className="python-reference-type">torch.Tensor</code> | EI values of shape `(n,)`. |
</div>

***

<div className="python-reference-heading">
  <h2 id="bayesian-optimization-bo-propose-next-point">
    `propose_next_point`
  </h2>

  <a className="python-reference-source" href="https://github.com/PriorLabs/tabpfn-extensions/blob/840c15a1848a986b39c85bc17efc61e0e377f983/src/tabpfn_extensions/bayesian_optimization/bo.py#L67" aria-label="View source for propose_next_point"><span aria-hidden="true">\</></span> View source <span aria-hidden="true">↗</span></a>
</div>

One acquisition round: screen random candidates, refine the best by EI ascent.

Fits `reg` on the observations via `fit_with_differentiable_input`,
screens `n_candidates` uniform random points in `[0, 1]^d` with EI in
a single forward pass, then refines the `top_k` most promising ones by
gradient ascent on EI w\.r.t. the candidate coordinates.

```python theme={null}
propose_next_point(
    reg: TabPFNRegressor,
    train_x: torch.Tensor,
    train_y: torch.Tensor,
    *,
    n_candidates: int = 512,
    top_k: int = 4,
    n_refine_steps: int = 8,
    refine_lr: float = 0.05,
) -> torch.Tensor
```

**Parameters**

<div className="python-reference-table">
  | Parameter | Type | Default | Description |
  | - | - | - | - |
  | <span id="bayesian-optimization-bo-propose-next-point--reg" /><code className="python-reference-parameter">reg</code> | <code className="python-reference-type"><a href="/api-reference/python/tabpfn/regressor/configuration#constructor">Tab<wbr />PFN<wbr />Regressor</a></code> | Required | A [`TabPFNRegressor`](/api-reference/python/tabpfn/regressor/configuration#constructor) constructed with `differentiable_input=True`. |
  | <span id="bayesian-optimization-bo-propose-next-point--train-x" /><code className="python-reference-parameter">train\_<wbr />x</code> | <code className="python-reference-type">torch.Tensor</code> | Required | Observed inputs of shape `(n, d)`, scaled to `[0, 1]^d`. |
  | <span id="bayesian-optimization-bo-propose-next-point--train-y" /><code className="python-reference-parameter">train\_<wbr />y</code> | <code className="python-reference-type">torch.Tensor</code> | Required | Observed objective values of shape `(n,)`. |
  | <span id="bayesian-optimization-bo-propose-next-point--n-candidates" /><code className="python-reference-parameter">n\_<wbr />candidates</code> | <code className="python-reference-type">int</code> | `512` | Number of random candidates screened per round. |
  | <span id="bayesian-optimization-bo-propose-next-point--top-k" /><code className="python-reference-parameter">top\_<wbr />k</code> | <code className="python-reference-type">int</code> | `4` | Number of candidates refined by gradient ascent on EI. |
  | <span id="bayesian-optimization-bo-propose-next-point--n-refine-steps" /><code className="python-reference-parameter">n\_<wbr />refine\_<wbr />steps</code> | <code className="python-reference-type">int</code> | `8` | Gradient steps on the candidate coordinates. |
  | <span id="bayesian-optimization-bo-propose-next-point--refine-lr" /><code className="python-reference-parameter">refine\_<wbr />lr</code> | <code className="python-reference-type">float</code> | `0.05` | Learning rate for the refinement steps. |
</div>

**Returns**

<div className="python-reference-table python-reference-returns">
  | Type | Description |
  | - | - |
  | <code className="python-reference-type">torch.Tensor</code> | The proposed next point of shape `(d,)`, detached. |
</div>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.