<br />

|---|
| [![](https://www.tensorflow.org/images/GitHub-Mark-32px.png) View source on GitHub](https://github.com/tensorflow/neural-structured-learning/blob/v1.4.0/neural_structured_learning/lib/distances.py#L222-L331) |

A wrapper to compute the pairwise distance between `sources` and `targets`.

    nsl.lib.pairwise_distance_wrapper(
        sources, targets, weights=1.0, distance_config=None
    )

`distances = weights * distance_config.distance_type(sources, targets)`

This wrapper calculates the weighted distance between `(sources, targets)`
pairs, and provides an option to return the distance as the sum over the
difference along the given axis, when vector based distance is needed.

For the usage of `weights` and `reduction`, please refer to `tf.losses`. For
the usage of `sum_over_axis`, see the following examples:

Given target tensors with shape `[batch_size, features]`, the reduction set to
[`tf.compat.v1.losses.Reduction.MEAN`](https://www.tensorflow.org/api_docs/python/tf/compat/v1/losses/Reduction#MEAN), and `sum_over_axis` set to the last
dimension, the weighted average distance of sample pairs will be returned.
For example: With a distance_config('L2', sum_over_axis=-1), the distance
between \[\[1, 1\], \[2, 2\], \[0, 2\], \[5, 5\]\] and \[\[1, 1\], \[0, 2\], \[4, 4\], \[1, 4\]\]
will be {(0+0) + (4+0) + (16+4) + (16+1)}/4 = 10.25

If `sum_over_axis` is `None`, the weighted average distance of feature pairs
(instead of sample pairs) will be returned. For example: With a
distance_config('L2'), the distance between
\[\[1, 1\], \[2, 2\], \[0, 2\], \[5, 5\]\] and \[\[1, 1\], \[0, 2\], \[4, 4\], \[1, 4\]\] will be
{(0+0) + (4+0) + (16+4) + (16+1)}/8 = 5.125

If `transform_fn` is not `None`, the transform function is applied to both
`sources` and `targets` before computing the distance. For example:
`distance_config('KL_DIVERGENCE', sum_over_axis=-1, transform_fn='SOFTMAX')`
treats `sources` and `targets` as logits, and computes the KL-divergence
between the two probability distributions.

<br />

<br />

<br />

| ## Args ||
|---|---|
| `sources` | `Tensor` of type `float32` or `float64`. |
| `targets` | `Tensor` of the same type and shape as `sources`. |
| `weights` | (optional) `Tensor` whose rank is either 0, or the same as that of `targets`, and must be broadcastable to `targets` (i.e., all dimensions must be either `1`, or the same as the corresponding distance dimension). |
| `distance_config` | An instance of [`nsl.configs.DistanceConfig`](https://www.tensorflow.org/neural_structured_learning/api_docs/python/nsl/configs/DistanceConfig) that contains the following configuration (or hyperparameters) for computing distances: (a) `distance_type`: Type of distance function to apply. (b) `reduction`: Type of distance reduction. See `tf.losses.Reduction`. (c) `sum_over_axis`: (optional) The distance is the sum over the difference along the specified axis. Note that if `sum_over_axis` is not `None` and the rank of `weights` is non-zero, then the size of `weights` along `sum_over_axis` must be 1. (d) `transform_fn`: (optional) If set, both `sources` and `targets` will be transformed before calculating the distance. If set to 'SOFTMAX', it will be performed on the axis specified by 'sum_over_axis', or -1 if the axis is not specified. If `None`, the default distance config will be used. |

<br />

<br />

<br />

<br />

| ## Returns ||
|---|---|
| Weighted distance scalar `Tensor`. If `reduction` is [`tf.compat.v1.losses.Reduction.MEAN`](https://www.tensorflow.org/api_docs/python/tf/compat/v1/losses/Reduction#MEAN), this has the same shape as `targets`. ||

<br />

<br />

<br />

<br />

| ## Raises ||
|---|---|
| `ValueError` | If the shape of targets doesn't match that of sources, or if the shape of weights is invalid. |
| `TypeError` | If the distance function gets an unexpected keyword argument. |

<br />