<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/experimental/mcmc/with_reductions.py#L41-L176) |

Applies `Reducer`s to stream over MCMC samples.

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

    tfp.experimental.mcmc.WithReductions(
        inner_kernel, reducer, adjust_kr_fn=(lambda x: x), name=None
    )

### Used in the notebooks

| Used in the tutorials |
|---|
| - [TFP Release Notes notebook (0.12.1)](https://www.tensorflow.org/probability/examples/TFP_Release_Notebook_0_12_1) |

`WithReductions` augments an inner MCMC kernel with
side-computations that can read the stream of samples as they
are generated. This is relevant for streaming uses of MCMC,
where materializing the entire Markov chain history is undesirable,
e.g. due to memory limits.

One `WithReductions` instance can attach an arbitrary collection
of side-computations, each of which must be packaged as a
`Reducer`. `WithReductions` operates by generating a
sample with its `inner_kernel`'s `one_step`, then invoking each
`Reducer`'s `one_step` method on that sample. The updated reducer
states are stored in the `reduction_results` field of
`WithReductions`' kernel results.

<br />

<br />

<br />

| ## Args ||
|---|---|
| `inner_kernel` | `TransitionKernel` whose `one_step` will generate MCMC sample(s). |
| `reducer` | A (possibly nested) structure of `Reducer`s to be evaluated on the `inner_kernel`'s samples. |
| `adjust_kr_fn` | Optional function to adjust the kernel_results structure of `inner_kernel` before presenting it to `reducer`. Useful for drivers (like `sample_fold`) that construct their own kernel onions, but accept `Reducer`s as arguments. |
| `name` | Python `str` name prefixed to Ops created by this function. Default value: `None` (i.e., "reduced_kernel"). |

<br />

<br />

<br />

<br />

| ## Attributes ||
|---|---|
| `adjust_kr_fn` | <br /> <br /> |
| `experimental_shard_axis_names` | The shard axis names for members of the state. |
| `inner_kernel` | <br /> <br /> |
| `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`. |
| `name` | <br /> <br /> |
| `parameters` | <br /> <br /> |
| `reducer` | <br /> <br /> |

<br />

## Methods

### `bootstrap_results`

[View source](https://github.com/tensorflow/probability/blob/v0.25.0/tensorflow_probability/python/experimental/mcmc/with_reductions.py#L122-L152)

    bootstrap_results(
        init_state, inner_results=None, previous_reducer_state=None
    )

Instantiates reducer states with identical structure to the `init_state`.

<br />

<br />

<br />

| Args ||
|---|---|
| `init_state` | `Tensor` or Python `list` of `Tensor`s representing the state(s) of the Markov chain(s). For consistency across sampling procedures (i.e. [`tfp.mcmc.sample_chain`](https://www.tensorflow.org/probability/api_docs/python/tfp/mcmc/sample_chain) follows similar semantics), the initial state does not count as a "sample". Hence, all reducer states will reflect empty streams. |
| `inner_results` | Optional results tuple for the inner kernel. Will be re-bootstrapped if omitted. |
| `previous_reducer_state` | Optional results structure for the reducers. Will be re-initialized if omitted. |

<br />

<br />

<br />

<br />

| Returns ||
|---|---|
| `kernel_results` | `WithReductionsKernelResults` representing updated kernel results. Reducer states are stored in the `reduction_results` field. The state structure is identical to `self.reducer`. |

<br />

### `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/kernel.py#L136-L146)

    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 />

### `one_step`

[View source](https://github.com/tensorflow/probability/blob/v0.25.0/tensorflow_probability/python/experimental/mcmc/with_reductions.py#L82-L120)

    one_step(
        current_state, previous_kernel_results, seed=None
    )

Updates all `Reducer`s with a new sample from the `inner_kernel`.

<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` | `WithReductionsKernelResults` named tuple. `WithReductionsKernelResults` contain the state of `reduction_results` and a reference to kernel results of nested `TransitionKernel`s. |
| `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 ||
|---|---|
| `new_state` | Newest MCMC state drawn from the `inner_kernel`. |
| `kernel_results` | `WithReductionsKernelResults` representing updated kernel results. Reducer states are stored in the `reduction_results` field. The state structure is identical to `self.reducer`. |

<br />