# tf_agents.bandits.multi_objective.multi_objective_scalarizer.HyperVolumeScalarizer

<br />

|---|
| [![](https://www.tensorflow.org/images/GitHub-Mark-32px.png) View source on GitHub](https://github.com/tensorflow/agents/blob/v0.19.0/tf_agents/bandits/multi_objective/multi_objective_scalarizer.py#L333-L488) |

Implement the hypervolume scalarization.

Inherits From: [`Scalarizer`](https://www.tensorflow.org/agents/api_docs/python/tf_agents/bandits/multi_objective/multi_objective_scalarizer/Scalarizer)

    tf_agents.bandits.multi_objective.multi_objective_scalarizer.HyperVolumeScalarizer(
        direction: Sequence[https://www.tensorflow.org/agents/api_docs/python/tf_agents/bandits/multi_objective/multi_objective_scalarizer/ScalarFloat],
        transform_params: Sequence[https://www.tensorflow.org/agents/api_docs/python/tf_agents/bandits/multi_objective/multi_objective_scalarizer/HyperVolumeScalarizer/PARAMS],
        multi_objective_transform: Optional[Callable[[tf.Tensor, Sequence[ScalarFloat], Sequence[ScalarFloat]],
            tf.Tensor]] = None
    )

Given a vector of (at least two) objectives M, a unit-length vector V with
non-negative coordinates, a slope vector A, and an offset vector B, all having
the same dimension, the hypervolume scalarization of M is defined as:

`min_{i: V_i > 0} max(A_i * M_i + B_i, 0) / V_i.`

See <https://arxiv.org/abs/2006.04655> for more details.
Note that it is recommended for the user to set A_i and B_i in such a way to
ensure non-negativity of the transformed objectives.

<br />

<br />

<br />

| ## Args ||
|---|---|
| `direction` | A `Sequence` representing a directional vector, which will be normalized to have unit length. Coordinates of the normalized direction whose absolute values are less than [`HyperVolumeScalarizer.ALMOST_ZERO`](https://www.tensorflow.org/agents/api_docs/python/tf_agents/bandits/multi_objective/multi_objective_scalarizer/HyperVolumeScalarizer#ALMOST_ZERO) will be considered zeros. |
| `transform_params` | A `Sequence` of namedtuples [`HyperVolumeScalarizer.PARAMS`](https://www.tensorflow.org/agents/api_docs/python/tf_agents/bandits/multi_objective/multi_objective_scalarizer/HyperVolumeScalarizer/PARAMS), each containing a slope and an offset for transforming an objective to be non-negative. |
| `multi_objective_transform` | A `Optional` `Callable` that takes in a [`tf.Tensor`](https://www.tensorflow.org/api_docs/python/tf/Tensor) of multiple objective values, a `Sequence` of slopes, and a `Sequence` of offsets, and returns a [`tf.Tensor`](https://www.tensorflow.org/api_docs/python/tf/Tensor) of transformed multiple objectives. If unset, the transform is defaulted to the standard transform multiple_objectives \* slopes + offsets. |

<br />

<br />

<br />

<br />

| ## Raises ||
|---|---|
| `ValueError` | if `any([x < 0 for x in direction])`. |
| `ValueError` | if the 2-norm of `direction` is less than [`HyperVolumeScalarizer.ALMOST_ZERO`](https://www.tensorflow.org/agents/api_docs/python/tf_agents/bandits/multi_objective/multi_objective_scalarizer/HyperVolumeScalarizer#ALMOST_ZERO). |
| `ValueError` | if `len(transform_params) != len(self._direction)`. |

<br />

## Child Classes

[`class PARAMS`](https://www.tensorflow.org/agents/api_docs/python/tf_agents/bandits/multi_objective/multi_objective_scalarizer/HyperVolumeScalarizer/PARAMS)

## Methods

### `set_parameters`

[View source](https://github.com/tensorflow/agents/blob/v0.19.0/tf_agents/bandits/multi_objective/multi_objective_scalarizer.py#L451-L488)

    set_parameters(
        direction: tf.Tensor, transform_params: Dict[str, tf.Tensor]
    )

Set the scalarization parameters for the HyperVolumeScalarizer.

<br />

<br />

<br />

| Args ||
|---|---|
| `direction` | A [`tf.Tensor`](https://www.tensorflow.org/api_docs/python/tf/Tensor) representing a directional vector, which will be normalized to have unit length. Coordinates of the normalized direction whose absolute values are less than [`HyperVolumeScalarizer.ALMOST_ZERO`](https://www.tensorflow.org/agents/api_docs/python/tf_agents/bandits/multi_objective/multi_objective_scalarizer/HyperVolumeScalarizer#ALMOST_ZERO) will be considered zeros. It must be rank-2 and shaped as \[batch_size, self._num_of_objectives\], where `batch_size` should match the batch size of the multi objectives passed to the scalarizer call. |
| `transform_params` | A dictionary mapping `self.SLOPE_KEY` and/or `self.OFFSET_KEY` to [`tf.Tensor`](https://www.tensorflow.org/api_docs/python/tf/Tensor), representing the slope and the offset parameters for transforming an objective to be non-negative. These tensors must satisfy the same rank and shape requirements as `direction`. |

<br />

<br />

<br />

<br />

| Raises ||
|---|---|
| `ValueError` | if any input scalarization parameter tensor is not rank-2, or has a last dimension size that does not match `self._num_of_objectives`. |

<br />

### `__call__`

[View source](https://github.com/tensorflow/agents/blob/v0.19.0/tf_agents/bandits/multi_objective/multi_objective_scalarizer.py#L135-L161)

    __call__(
        multi_objectives: tf.Tensor
    ) -> tf.Tensor

Returns a single reward by scalarizing multiple objectives.

<br />

<br />

<br />

| Args ||
|---|---|
| `multi_objectives` | A `Tensor` of shape \[batch_size, number_of_objectives\], where each column represents an objective. |

<br />

Returns: A `Tensor` of shape \[batch_size\] representing scalarized rewards.

<br />

<br />

<br />

| Raises ||
|---|---|
| `ValueError` | if `multi_objectives.shape.rank != 2`. |
| `ValueError` | if `multi_objectives.shape.dims[1] != self._num_of_objectives`. |

<br />

<br />

<br />

<br />

| ## Class Variables ||
|---|---|
| ALMOST_ZERO | `1e-16` |
| DIRECTION_KEY | `'direction'` |
| OFFSET_KEY | `'offset'` |
| SLOPE_KEY | `'slope'` |

<br />