# tff.learning.models.VariableModel

<br />

|---|
| [![](https://www.tensorflow.org/images/GitHub-Mark-32px.png) View source on GitHub](https://github.com/tensorflow/federated/blob/v0.87.0 Version 2.0, January 2004 Licensed under the Apache License, Version 2.0 (the) |

Represents a variable-based model for use in TensorFlow Federated.

### Used in the notebooks

| Used in the tutorials |
|---|
| - [Federated Learning for Image Classification](https://www.tensorflow.org/federated/tutorials/federated_learning_for_image_classification) |

Each `VariableModel` will work on a set of `tf.Variables`, and each method
should be a computation that can be implemented as a [`tf.function`](https://www.tensorflow.org/api_docs/python/tf/function); this
implies the class should essentially be stateless from a Python perspective,
as each method will generally only be traced once (per set of arguments) to
create the corresponding TensorFlow graph functions. Thus, `VariableModel`
instances should behave as expected in both eager and graph (TF 1.0) usage.

In general, `tf.Variables` may be either:

- Weights, the variables needed to make predictions with the model.
- Local variables, e.g. to accumulate aggregated metrics across calls to forward_pass.

The weights can be broken down into trainable variables (variables
that can and should be trained using gradient-based methods), and
non-trainable variables (which could include fixed pre-trained layers,
or static model data). These variables are provided via the
`trainable_variables`, `non_trainable_variables`, and `local_variables`
properties, and must be initialized by the user of the `VariableModel`.

In federated learning, model weights will generally be provided by the
server, and updates to trainable model variables will be sent back to the
server. Local variables are not transmitted, and are instead initialized
locally on the device, and then used to produce `aggregated_outputs` which
are sent to the server.

All `tf.Variables` should be introduced in `__init__`; this could move to a
`build` method more inline with Keras (see
<https://www.tensorflow.org/api_docs/python/tf/keras/layers/Layer>) in
the future.

<br />

<br />

<br />

| ## Attributes ||
|---|---|
| `input_spec` | <br /> <br /> |
| `local_variables` | An iterable of [`tf.Variable`](https://www.tensorflow.org/api_docs/python/tf/Variable) objects, see class comment for details. |
| `non_trainable_variables` | An iterable of [`tf.Variable`](https://www.tensorflow.org/api_docs/python/tf/Variable) objects, see class comment for details. |
| `trainable_variables` | An iterable of [`tf.Variable`](https://www.tensorflow.org/api_docs/python/tf/Variable) objects, see class comment for details. |

<br />

## Methods

### `forward_pass`

[View source](https://github.com/tensorflow/federated/blob/v0.87.0
Version 2.0, January 2004
Licensed under the Apache License, Version 2.0 (the)

    @abc.abstractmethod
    forward_pass(
        batch_input, training=True
    ) -> https://www.tensorflow.org/federated/api_docs/python/tff/learning/models/BatchOutput

Runs the forward pass and returns results.

This method must be serializable in a [`tff.tensorflow.computation`](https://www.tensorflow.org/federated/api_docs/python/tff/tensorflow/computation) or other
backend decorator. Any pure-Python or unserializable logic will not be
runnable in the federated system.

This method should not modify any variables that are part of the model
parameters, that is, variables that influence the predictions (exceptions
being updated, rather than learned, parameters such as BatchNorm means and
variances). Rather, this is done by the training loop. However, this method
may update aggregated metrics computed across calls to `forward_pass`; the
final values of such metrics can be accessed via `aggregated_outputs`.

<br />

<br />

| Uses in TFF ||
|---|---|
| <br /> - To implement model evaluation. - To implement federated gradient descent and other non-Federated-Averaging algorithms, where we want the model to run the forward pass and update metrics, but there is no optimizer (we might only compute gradients on the returned loss). - To implement Federated Averaging. ||

<br />

<br />

<br />

<br />

| Args ||
|---|---|
| `batch_input` | A nested structure that matches the structure of [`VariableModel.input_spec`](https://www.tensorflow.org/federated/api_docs/python/tff/learning/models/VariableModel#input_spec) and each tensor in `batch_input` satisfies [`tf.TensorSpec.is_compatible_with()`](https://www.tensorflow.org/api_docs/python/tf/TensorSpec#is_compatible_with) for the corresponding [`tf.TensorSpec`](https://www.tensorflow.org/api_docs/python/tf/TensorSpec) in [`VariableModel.input_spec`](https://www.tensorflow.org/federated/api_docs/python/tff/learning/models/VariableModel#input_spec). |
| `training` | If `True`, run the training forward pass, otherwise, run in evaluation mode. The semantics are generally the same as the `training` argument to `keras.Model.call`; this might e.g. influence how dropout or batch normalization is handled. |

<br />

<br />

<br />

<br />

| Returns ||
|---|---|
| A `BatchOutput` object. The object must include the `loss` tensor if the model will be trained via a gradient-based algorithm. ||

<br />

### `metric_finalizers`

[View source](https://github.com/tensorflow/federated/blob/v0.87.0
Version 2.0, January 2004
Licensed under the Apache License, Version 2.0 (the)

    @abc.abstractmethod
    metric_finalizers() -> https://www.tensorflow.org/federated/api_docs/python/tff/learning/metrics/MetricFinalizersType

Creates an `collections.OrderedDict` of metric names to finalizers.

This method and the `report_local_unfinalized_metrics()` method should have
the same keys (i.e., metric names). A finalizer returned by this method is a
function (typically a [`tf.function`](https://www.tensorflow.org/api_docs/python/tf/function) decorated callable or a
[`tff.tensorflow.computation`](https://www.tensorflow.org/federated/api_docs/python/tff/tensorflow/computation) decorated TFF Computation) that takes in a
metric's unfinalized values (returned by
`report_local_unfinalized_metrics()`), and returns the finalized metric
values.

This method and the `report_local_unfinalized_metrics()` method will be used
together to build a cross-client metrics aggregator. See the documentation
of `report_local_unfinalized_metrics()` for more information.

<br />

<br />

<br />

| Returns ||
|---|---|
| An `collections.OrderedDict` of metric names to finalizers. The metric names must be the same as those from the `report_local_unfinalized_metrics()` method. A finalizer is a [`tf.function`](https://www.tensorflow.org/api_docs/python/tf/function) (or [`tff.tensorflow.computation`](https://www.tensorflow.org/federated/api_docs/python/tff/tensorflow/computation)) decorated callable that takes in a metric's unfinalized values, and returns the finalized values. This method and the `report_local_unfinalized_metrics()` method will be used together to build a cross-client metrics aggregator in federated training processes or evaluation computations. ||

<br />

### `predict_on_batch`

[View source](https://github.com/tensorflow/federated/blob/v0.87.0
Version 2.0, January 2004
Licensed under the Apache License, Version 2.0 (the)

    @abc.abstractmethod
    predict_on_batch(
        batch_input, training=True
    )

### `report_local_unfinalized_metrics`

[View source](https://github.com/tensorflow/federated/blob/v0.87.0
Version 2.0, January 2004
Licensed under the Apache License, Version 2.0 (the)

    @abc.abstractmethod
    report_local_unfinalized_metrics() -> collections.OrderedDict[str, Any]

Creates an `collections.OrderedDict` of metric names to unfinalized values.

For a metric, its unfinalized values are given as a structure (typically a
list) of tensors representing values from aggregating over *all* previous
`forward_pass` calls, unless the `reset_metrics` is called. Each time the
`reset_metrics` is called, the local metric variables will be reset, and
`report_local_unfinalized_metrics` only reports metrics aggregated from the
`forward_pass` calls since the *last* `reset_metrics` call. For a Keras
metric, its unfinalized values are typically the tensor values of its state
variables. In general, the tensors can be an arbitrary function of all the
[`tf.Variable`](https://www.tensorflow.org/api_docs/python/tf/Variable)s of this model.

The metric names returned by this method should be the same as those
expected by the `metric_finalizers()`; one should be able to use the
unfinalized values as input to the finalizers to get the finalized values.
Taking [`tf.keras.metrics.CategoricalAccuracy`](https://www.tensorflow.org/api_docs/python/tf/keras/metrics/CategoricalAccuracy) as an example, its unfinalized
values can be a list of two tensors (from its state variables): `total` and
`count`, and the finalizer function performs a [`tf.math.divide_no_nan`](https://www.tensorflow.org/api_docs/python/tf/math/divide_no_nan).

In federated learning, this method returns the local results from clients,
which will typically be further aggregated across clients and made available
on the server. This method and the `metric_finalizers()` method will be used
together to build a cross-client metrics aggregator. For example, a simple
"sum_then_finalize" aggregator will first sum the unfinalized metric values
from clients, and then call the finalizer functions at the server.

Because both of this method and the `metric_finalizers()` method are defined
in a per-metric manner, users have the flexiblity to call finalizer at the
clients or at the server for different metrics. Users also have the freedom
to defined a cross-client metrics aggregator that aggregates a single metric
in multiple ways.

<br />

<br />

<br />

| Returns ||
|---|---|
| An `collections.OrderedDict` of metric names to unfinalized values. The metric names must be the same as those expected by the `metric_finalizers()` method. One should be able to use the unfinalized metric values (returned by this method) as the input to the finalizers (returned by `metric_finalizers()`) to get the finalized metrics. This method and the `metric_finalizers()` method will be used together to build a cross-client metrics aggregator when defining the federated training processes or evaluation computations. ||

<br />

### `reset_metrics`

[View source](https://github.com/tensorflow/federated/blob/v0.87.0
Version 2.0, January 2004
Licensed under the Apache License, Version 2.0 (the)

    @abc.abstractmethod
    reset_metrics() -> None

Resets metrics variables to initial value.

This method is a [`tf.function`](https://www.tensorflow.org/api_docs/python/tf/function). It is used to reset the metrics variables
between different stages in client's *local* computation. Each time the
`reset_metrics` is called, the *local* metric variables will be reset, and
`report_local_unfinalized_metrics` only reports metrics aggregated from the
`forward_pass` calls since the *last* `reset_metrics` call. If the
`reset_metrics` is never called, `report_local_unfinalized_metrics` will
report metrics aggregated over *all* previous `forward_pass` calls.