# tff.program.FederatedContext

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

An abstract interface representing a federated context.

Inherits From: [`SyncContext`](https://www.tensorflow.org/federated/api_docs/python/tff/framework/SyncContext)

A federated context supports invoking a limited set of [`tff.Computation`](https://www.tensorflow.org/federated/api_docs/python/tff/Computation)s,
making guarantees about what a [`tff.Computation`](https://www.tensorflow.org/federated/api_docs/python/tff/Computation) can accept as an argument and
what it returns when invoked.

## Restrictions on the TensorFlow Federated Type

Arguments can be nested structures of values corresponding to the TensorFlow
Federated type signature of the [`tff.Computation`](https://www.tensorflow.org/federated/api_docs/python/tff/Computation):

- Server-placed values must be represented by [`tff.program.MaterializableStructure`](https://www.tensorflow.org/federated/api_docs/python/tff/program/MaterializableStructure).
- Client-placed values must be represented by structures of values returned by a [`tff.program.FederatedDataSourceIterator`](https://www.tensorflow.org/federated/api_docs/python/tff/program/FederatedDataSourceIterator).

Return values can be structures of [`tff.program.MaterializableValueReference`](https://www.tensorflow.org/federated/api_docs/python/tff/program/MaterializableValueReference)s
or a single [`tff.program.MaterializableValueReference`](https://www.tensorflow.org/federated/api_docs/python/tff/program/MaterializableValueReference), where a reference
corresponds to the tensor-type of the TensorFlow Federated type signature in
the return value of the invoked [`tff.Computation`](https://www.tensorflow.org/federated/api_docs/python/tff/Computation).

## TensorFlow Federated Type to Python Representation

In order to interact with the value returned by a [`tff.Computation`](https://www.tensorflow.org/federated/api_docs/python/tff/Computation), it is
helpful to be able to reason about the Python type of this value. In some way
this Python type must depend on the TensorFlow Federated type signature of the
associated value. To provide uniformity of experience and ease of reasoning,
we specify the Python representation of values in a manner that can be stated
entirely in the TensorFlow Federated typesystem.

We have chosen to limit the TensorFlow Federated type signatures of invoked
[`tff.Computation`](https://www.tensorflow.org/federated/api_docs/python/tff/Computation)s to disallow the returning of client-placed values,
`tff.SequenceTypes`, and `tff.FunctionTypes`, in order to reduced the area
which needs to be supported by federated programs. Below we describe the
mapping between TensorFlow Federated type signatures and Python
representations of values that can be passed as arguments to or returned as
results from [`tff.Computation`](https://www.tensorflow.org/federated/api_docs/python/tff/Computation)s.

Python representations of values that can be *accepted as an arguments to* or
*returned as a value from* a [`tff.Computation`](https://www.tensorflow.org/federated/api_docs/python/tff/Computation):

| TensorFlow Federated Type | Python Representation |
|---|---|
| [`tff.TensorType`](https://www.tensorflow.org/federated/api_docs/python/tff/types/TensorType) | [`tff.program.MaterializableValueReference`](https://www.tensorflow.org/federated/api_docs/python/tff/program/MaterializableValueReference) |
| [`tff.SequenceType`](https://www.tensorflow.org/federated/api_docs/python/tff/types/SequenceType) | [`tff.program.MaterializableValueReference`](https://www.tensorflow.org/federated/api_docs/python/tff/program/MaterializableValueReference) |
| [`tff.FederatedType`](https://www.tensorflow.org/federated/api_docs/python/tff/types/FederatedType) (server-placed) | Python representation of the `member` of the [`tff.FederatedType`](https://www.tensorflow.org/federated/api_docs/python/tff/types/FederatedType) |
| [`tff.StructWithPythonType`](https://www.tensorflow.org/federated/api_docs/python/tff/types/StructWithPythonType) | Python container of the [`tff.StructWithPythonType`](https://www.tensorflow.org/federated/api_docs/python/tff/types/StructWithPythonType) |
| [`tff.StructType`](https://www.tensorflow.org/federated/api_docs/python/tff/types/StructType) (with no Python type, all fields named) | `collections.OrderedDict` |
| [`tff.StructType`](https://www.tensorflow.org/federated/api_docs/python/tff/types/StructType) (with no Python type, no fields named) | `tuple` |

Python representations of values that can be only be *accepted as an arguments
to* a [`tff.Computation`](https://www.tensorflow.org/federated/api_docs/python/tff/Computation):

| TFF Type | Python Representation |
|---|---|
| [`tff.FederatedType`](https://www.tensorflow.org/federated/api_docs/python/tff/types/FederatedType) (client-placed) | Opaque object returned by `tff.program.DataSourceIterator.select` |
| [`tff.FunctionType`](https://www.tensorflow.org/federated/api_docs/python/tff/types/FunctionType) | [`tff.Computation`](https://www.tensorflow.org/federated/api_docs/python/tff/Computation) |

## Methods

### `invoke`

[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
    invoke(
        comp: https://www.tensorflow.org/federated/api_docs/python/tff/Computation,
        arg: Optional[ComputationArgValue]
    ) -> structure_utils.Structure[value_reference.MaterializableValueReference]

Invokes the `comp` with the argument `arg`.

<br />

<br />

<br />

| Args ||
|---|---|
| `comp` | The [`tff.Computation`](https://www.tensorflow.org/federated/api_docs/python/tff/Computation) being invoked. |
| `arg` | The optional argument of `comp`; server-placed values must be represented by [`tff.program.MaterializableStructure`](https://www.tensorflow.org/federated/api_docs/python/tff/program/MaterializableStructure), and client-placed values must be represented by structures of values returned by a [`tff.program.FederatedDataSourceIterator`](https://www.tensorflow.org/federated/api_docs/python/tff/program/FederatedDataSourceIterator). |

<br />

<br />

<br />

<br />

| Returns ||
|---|---|
| The result of invocation; a structure of [`tff.program.MaterializableValueReference`](https://www.tensorflow.org/federated/api_docs/python/tff/program/MaterializableValueReference). ||

<br />

<br />

<br />

<br />

| Raises ||
|---|---|
| `ValueError` | If the result type of `comp` does not contain only structures, server-placed values, or tensors. |

<br />