<br />

|---|
| [![](https://www.tensorflow.org/images/GitHub-Mark-32px.png) View source on GitHub](https://github.com/tensorflow/probability/blob/v0.25.0/tensorflow_probability/python/mcmc/nuts.py#L165-L946) |

Runs one step of the No U-Turn Sampler.

Inherits From: [`TransitionKernel`](https://www.tensorflow.org/probability/api_docs/python/tfp/mcmc/TransitionKernel)

    tfp.mcmc.NoUTurnSampler(
        target_log_prob_fn,
        step_size,
        max_tree_depth=10,
        max_energy_diff=1000.0,
        unrolled_leapfrog_steps=1,
        parallel_iterations=10,
        experimental_shard_axis_names=None,
        name=None
    )

### Used in the notebooks

| Used in the tutorials |
|---|
| - [Gaussian Process Regression in TensorFlow Probability](https://www.tensorflow.org/probability/examples/Gaussian_Process_Regression_In_TFP) - [Bayesian Modeling with Joint Distribution](https://www.tensorflow.org/probability/examples/Modeling_with_JointDistribution) - [Approximate inference for STS models with non-Gaussian observations](https://www.tensorflow.org/probability/examples/STS_approximate_inference_for_models_with_non_Gaussian_observations) |

The No U-Turn Sampler (NUTS) is an adaptive variant of the Hamiltonian Monte
Carlo (HMC) method for MCMC. NUTS adapts the distance traveled in response to
the curvature of the target density. Conceptually, one proposal consists of
reversibly evolving a trajectory through the sample space, continuing until
that trajectory turns back on itself (hence the name, 'No U-Turn'). This class
implements one random NUTS step from a given `current_state`.
Mathematical details and derivations can be found in
\[Hoffman, Gelman (2011)\]\[1\] and \[Betancourt (2018)\]\[2\].

The `one_step` function can update multiple chains in parallel. It assumes
that a prefix of leftmost dimensions of `current_state` index independent
chain states (and are therefore updated independently). The output of
`target_log_prob_fn(*current_state)` should sum log-probabilities across all
event dimensions. Slices along the rightmost dimensions may have different
target distributions; for example, `current_state[0][0, ...]` could have a
different target distribution from `current_state[0][1, ...]`. These
semantics are governed by `target_log_prob_fn(*current_state)`. (The number of
independent chains is `tf.size(target_log_prob_fn(*current_state))`.)

#### References

\[1\]: Matthew D. Hoffman, Andrew Gelman. The No-U-Turn Sampler: Adaptively
Setting Path Lengths in Hamiltonian Monte Carlo. 2011.
<https://arxiv.org/pdf/1111.4246.pdf>

\[2\]: Michael Betancourt. A Conceptual Introduction to Hamiltonian Monte Carlo.
*arXiv preprint arXiv:1701.02434* , 2018. <https://arxiv.org/abs/1701.02434>

<br />

<br />

<br />

| ## Args ||
|---|---|
| `target_log_prob_fn` | Python callable which takes an argument like `current_state` (or `*current_state` if it's a list) and returns its (possibly unnormalized) log-density under the target distribution. |
| `step_size` | `Tensor` or Python `list` of `Tensor`s representing the step size for the leapfrog integrator. Must broadcast with the shape of `current_state`. Larger step sizes lead to faster progress, but too-large step sizes make rejection exponentially more likely. When possible, it's often helpful to match per-variable step sizes to the standard deviations of the target distribution in each variable. |
| `max_tree_depth` | Maximum depth of the tree implicitly built by NUTS. The maximum number of leapfrog steps is bounded by `2**max_tree_depth` i.e. the number of nodes in a binary tree `max_tree_depth` nodes deep. The default setting of 10 takes up to 1024 leapfrog steps. |
| `max_energy_diff` | Scaler threshold of energy differences at each leapfrog, divergence samples are defined as leapfrog steps that exceed this threshold. Default to 1000. |
| `unrolled_leapfrog_steps` | The number of leapfrogs to unroll per tree expansion step. Applies a direct linear multipler to the maximum trajectory length implied by max_tree_depth. Defaults to 1. |
| `parallel_iterations` | The number of iterations allowed to run in parallel. It must be a positive integer. See [`tf.while_loop`](https://www.tensorflow.org/api_docs/python/tf/while_loop) for more details. |
| `experimental_shard_axis_names` | A structure of string names indicating how members of the state are sharded. |
| `name` | Python `str` name prefixed to Ops created by this function. Default value: `None` (i.e., 'NoUTurnSampler'). |

<br />

<br />

<br />

<br />

| ## Attributes ||
|---|---|
| `experimental_shard_axis_names` | The shard axis names for members of the state. |
| `is_calibrated` | Returns `True` if Markov chain converges to specified distribution. <br /> `TransitionKernel`s which are "uncalibrated" are often calibrated by composing them with the [`tfp.mcmc.MetropolisHastings`](https://www.tensorflow.org/probability/api_docs/python/tfp/mcmc/MetropolisHastings) `TransitionKernel`. |
| `max_energy_diff` | <br /> <br /> |
| `max_tree_depth` | <br /> <br /> |
| `name` | <br /> <br /> |
| `parallel_iterations` | <br /> <br /> |
| `parameters` | <br /> <br /> |
| `read_instruction` | <br /> <br /> |
| `step_size` | <br /> <br /> |
| `target_log_prob_fn` | <br /> <br /> |
| `unrolled_leapfrog_steps` | <br /> <br /> |
| `write_instruction` | <br /> <br /> |

<br />

## Methods

### `bootstrap_results`

[View source](https://github.com/tensorflow/probability/blob/v0.25.0/tensorflow_probability/python/mcmc/nuts.py#L456-L503)

    bootstrap_results(
        init_state
    )

Creates initial `previous_kernel_results` using a supplied `state`.

### `copy`

[View source](https://github.com/tensorflow/probability/blob/v0.25.0/tensorflow_probability/python/mcmc/kernel.py#L148-L164)

    copy(
        **override_parameter_kwargs
    )

Non-destructively creates a deep copy of the kernel.

<br />

<br />

<br />

| Args ||
|---|---|
| `**override_parameter_kwargs` | Python String/value `dictionary` of initialization arguments to override with new values. |

<br />

<br />

<br />

<br />

| Returns ||
|---|---|
| `new_kernel` | `TransitionKernel` object of same type as `self`, initialized with the union of self.parameters and override_parameter_kwargs, with any shared keys overridden by the value of override_parameter_kwargs, i.e., `dict(self.parameters, **override_parameters_kwargs)`. |

<br />

### `experimental_with_shard_axes`

[View source](https://github.com/tensorflow/probability/blob/v0.25.0/tensorflow_probability/python/mcmc/nuts.py#L509-L510)

    experimental_with_shard_axes(
        shard_axis_names
    )

Returns a copy of the kernel with the provided shard axis names.

<br />

<br />

<br />

| Args ||
|---|---|
| `shard_axis_names` | a structure of strings indicating the shard axis names for each component of this kernel's state. |

<br />

<br />

<br />

<br />

| Returns ||
|---|---|
| A copy of the current kernel with the shard axis information. ||

<br />

### `init_momentum_state_memory`

[View source](https://github.com/tensorflow/probability/blob/v0.25.0/tensorflow_probability/python/mcmc/nuts.py#L447-L454)

    init_momentum_state_memory(
        input_tensors
    )

Allocate TensorArray for storing state and momentum.

### `one_step`

[View source](https://github.com/tensorflow/probability/blob/v0.25.0/tensorflow_probability/python/mcmc/nuts.py#L321-L445)

    one_step(
        current_state, previous_kernel_results, seed=None
    )

Takes one step of the TransitionKernel.

Must be overridden by subclasses.

<br />

<br />

<br />

| Args ||
|---|---|
| `current_state` | `Tensor` or Python `list` of `Tensor`s representing the current state(s) of the Markov chain(s). |
| `previous_kernel_results` | A (possibly nested) `tuple`, `namedtuple` or `list` of `Tensor`s representing internal calculations made within the previous call to this function (or as returned by `bootstrap_results`). |
| `seed` | PRNG seed; see [`tfp.random.sanitize_seed`](https://www.tensorflow.org/probability/api_docs/python/tfp/random/sanitize_seed) for details. |

<br />

<br />

<br />

<br />

| Returns ||
|---|---|
| `next_state` | `Tensor` or Python `list` of `Tensor`s representing the next state(s) of the Markov chain(s). |
| `kernel_results` | A (possibly nested) `tuple`, `namedtuple` or `list` of `Tensor`s representing internal calculations made within this function. |

<br />