---
name: "mlpack_nca_SoftmaxErrorFunction"
section: "3"
platform: "linux"
package: "mlpack-doc"
version: "1.0.10-1"
release: "Debian 8 (Jessie)"
platforms: ["linux"]
url: "https://new.carta.tech/mlpack_nca_SoftmaxErrorFunction"
---

# mlpack\_nca\_SoftmaxErrorFunction(3)

The 'softmax' stochastic neighbor assignment probability function.

## NAME

mlpack::nca::SoftmaxErrorFunction\< MetricType \> -

The 'softmax' stochastic neighbor assignment probability function.

## SYNOPSIS

### Public Member Functions

**SoftmaxErrorFunction** (const arma::mat &**dataset**, const arma::Col\< size\_t \> &**labels**, MetricType **metric**=MetricType())\
 *Initialize with the given kernel; useful when the kernel has some state to store, which is set elsewhere.*  double **Evaluate** (const arma::mat &covariance)\
 *Evaluate the softmax function for the given covariance matrix.*  double **Evaluate** (const arma::mat &covariance, const size\_t i)\
 *Evaluate the softmax objective function for the given covariance matrix on only one point of the dataset.*  const arma::mat **GetInitialPoint** () const \
 *Get the initial point.*  void **Gradient** (const arma::mat &covariance, arma::mat &gradient)\
 *Evaluate the gradient of the softmax function for the given covariance matrix.*  void **Gradient** (const arma::mat &covariance, const size\_t i, arma::mat &gradient)\
 *Evaluate the gradient of the softmax function for the given covariance matrix on only one point of the dataset.*  size\_t **NumFunctions** () const \
 *Get the number of functions the objective function can be decomposed into.*  std::string **ToString** () const \

### Private Member Functions

void **Precalculate** (const arma::mat &coordinates)\
 *Precalculate the denominators and numerators that will make up the p\_ij, but only if the coordinates matrix is different than the last coordinates the* **Precalculate()** *method was run with.*

### Private Attributes

const arma::mat & **dataset**\
 *The dataset.*  arma::vec **denominators**\
 *Holds denominators for calculation of p\_ij, for the non-separable* **Evaluate()** *and* **Gradient()***.*  const arma::Col\< size\_t \> & **labels**\
 *Labels for each point in the dataset.*  arma::mat **lastCoordinates**\
 *Last coordinates. Used for the non-separable* **Evaluate()** *and* **Gradient()***.*  MetricType **metric**\
 *The instantiated metric.*  arma::vec **p**\
 *Holds calculated p\_i, for the non-separable* **Evaluate()** *and* **Gradient()***.*  bool **precalculated**\
 *False if nothing has ever been precalculated (only at construction time).*  arma::mat **stretchedDataset**\
 *Stretched dataset. Kept internal to avoid memory reallocations.*

## Detailed Description

### template\<typename MetricType = metric::SquaredEuclideanDistance\>class mlpack::nca::SoftmaxErrorFunction\< MetricType \>

The 'softmax' stochastic neighbor assignment probability function.

The actual function is

p\_ij = (exp(-\|\| A x\_i - A x\_j \|\| ^ 2)) / (sum\_{k != i} (exp(-\|\| A x\_i - A x\_k \|\| ^ 2)))

where x\_n represents a point and A is the current scaling matrix.

This class is more flexible than the original paper, allowing an arbitrary metric function to be used in place of \|\| A x\_i - A x\_j \|\|^2, meaning that the squared Euclidean distance is not the only allowed metric for **NCA**. However, that is probably the best way to use this class.

In addition to the standard **Evaluate()** and **Gradient()** functions which MLPACK optimizers use, overloads of **Evaluate()** and **Gradient()** are given which only operate on one point in the dataset. This is useful for optimizers like stochastic gradient descent (see **mlpack::optimization::SGD**).

Definition at line 52 of file nca\_softmax\_error\_function.hpp.

## Constructor & Destructor Documentation

### template\<typename MetricType = metric::SquaredEuclideanDistance\> mlpack::nca::SoftmaxErrorFunction\< MetricType \>::SoftmaxErrorFunction (const arma::mat &dataset, const arma::Col\< size\_t \> &labels, MetricTypemetric = `MetricType()`)

Initialize with the given kernel; useful when the kernel has some state to store, which is set elsewhere. If no kernel is given, an empty kernel is used; this way, you can call the constructor with no arguments. A reference to the dataset we will be optimizing over is also required.

**Parameters:**

*dataset* Matrix containing the dataset. \
 *labels* Vector of class labels for each point in the dataset. \
 *kernel* Instantiated kernel (optional).

## Member Function Documentation

### template\<typename MetricType = metric::SquaredEuclideanDistance\> double mlpack::nca::SoftmaxErrorFunction\< MetricType \>::Evaluate (const arma::mat &covariance)

Evaluate the softmax function for the given covariance matrix. This is the non-separable implementation, where the objective function is not decomposed into the sum of several objective functions.

**Parameters:**

*covariance* Covariance matrix of Mahalanobis distance.

### template\<typename MetricType = metric::SquaredEuclideanDistance\> double mlpack::nca::SoftmaxErrorFunction\< MetricType \>::Evaluate (const arma::mat &covariance, const size\_ti)

Evaluate the softmax objective function for the given covariance matrix on only one point of the dataset. This is the separable implementation, where the objective function is decomposed into the sum of many objective functions, and here, only one of those constituent objective functions is returned.

**Parameters:**

*covariance* Covariance matrix of Mahalanobis distance. \
 *i* Index of point to use for objective function.

### template\<typename MetricType = metric::SquaredEuclideanDistance\> const arma::mat mlpack::nca::SoftmaxErrorFunction\< MetricType \>::GetInitialPoint () const

Get the initial point.

### template\<typename MetricType = metric::SquaredEuclideanDistance\> void mlpack::nca::SoftmaxErrorFunction\< MetricType \>::Gradient (const arma::mat &covariance, arma::mat &gradient)

Evaluate the gradient of the softmax function for the given covariance matrix. This is the non-separable implementation, where the objective function is not decomposed into the sum of several objective functions.

**Parameters:**

*covariance* Covariance matrix of Mahalanobis distance. \
 *gradient* Matrix to store the calculated gradient in.

### template\<typename MetricType = metric::SquaredEuclideanDistance\> void mlpack::nca::SoftmaxErrorFunction\< MetricType \>::Gradient (const arma::mat &covariance, const size\_ti, arma::mat &gradient)

Evaluate the gradient of the softmax function for the given covariance matrix on only one point of the dataset. This is the separable implementation, where the objective function is decomposed into the sum of many objective functions, and here, only one of those constituent objective functions is returned.

**Parameters:**

*covariance* Covariance matrix of Mahalanobis distance. \
 *i* Index of point to use for objective function. \
 *gradient* Matrix to store the calculated gradient in.

### template\<typename MetricType = metric::SquaredEuclideanDistance\> size\_t mlpack::nca::SoftmaxErrorFunction\< MetricType \>::NumFunctions () const` [inline]`

Get the number of functions the objective function can be decomposed into. This is just the number of points in the dataset.

Definition at line 124 of file nca\_softmax\_error\_function.hpp.

### template\<typename MetricType = metric::SquaredEuclideanDistance\> void mlpack::nca::SoftmaxErrorFunction\< MetricType \>::Precalculate (const arma::mat &coordinates)` [private]`

Precalculate the denominators and numerators that will make up the p\_ij, but only if the coordinates matrix is different than the last coordinates the **Precalculate()** method was run with. This method is only called by the non-separable **Evaluate()** and **Gradient()**.

This will update last\_coordinates\_ and stretched\_dataset\_, and also calculate the p\_i and denominators\_ which are used in the calculation of p\_i or p\_ij. The calculation will be O((n \* (n + 1)) / 2), which is not great.

**Parameters:**

*coordinates* Coordinates matrix to use for precalculation.

### template\<typename MetricType = metric::SquaredEuclideanDistance\> std::string mlpack::nca::SoftmaxErrorFunction\< MetricType \>::ToString () const

## Member Data Documentation

### template\<typename MetricType = metric::SquaredEuclideanDistance\> const arma::mat& mlpack::nca::SoftmaxErrorFunction\< MetricType \>::dataset` [private]`

The dataset.

Definition at line 131 of file nca\_softmax\_error\_function.hpp.

### template\<typename MetricType = metric::SquaredEuclideanDistance\> arma::vec mlpack::nca::SoftmaxErrorFunction\< MetricType \>::denominators` [private]`

Holds denominators for calculation of p\_ij, for the non-separable **Evaluate()** and **Gradient()**.

Definition at line 146 of file nca\_softmax\_error\_function.hpp.

### template\<typename MetricType = metric::SquaredEuclideanDistance\> const arma::Col\<size\_t\>& mlpack::nca::SoftmaxErrorFunction\< MetricType \>::labels` [private]`

Labels for each point in the dataset.

Definition at line 133 of file nca\_softmax\_error\_function.hpp.

### template\<typename MetricType = metric::SquaredEuclideanDistance\> arma::mat mlpack::nca::SoftmaxErrorFunction\< MetricType \>::lastCoordinates` [private]`

Last coordinates. Used for the non-separable **Evaluate()** and **Gradient()**.

Definition at line 139 of file nca\_softmax\_error\_function.hpp.

### template\<typename MetricType = metric::SquaredEuclideanDistance\> MetricType mlpack::nca::SoftmaxErrorFunction\< MetricType \>::metric` [private]`

The instantiated metric.

Definition at line 136 of file nca\_softmax\_error\_function.hpp.

### template\<typename MetricType = metric::SquaredEuclideanDistance\> arma::vec mlpack::nca::SoftmaxErrorFunction\< MetricType \>::p` [private]`

Holds calculated p\_i, for the non-separable **Evaluate()** and **Gradient()**.

Definition at line 143 of file nca\_softmax\_error\_function.hpp.

### template\<typename MetricType = metric::SquaredEuclideanDistance\> bool mlpack::nca::SoftmaxErrorFunction\< MetricType \>::precalculated` [private]`

False if nothing has ever been precalculated (only at construction time).

Definition at line 149 of file nca\_softmax\_error\_function.hpp.

### template\<typename MetricType = metric::SquaredEuclideanDistance\> arma::mat mlpack::nca::SoftmaxErrorFunction\< MetricType \>::stretchedDataset` [private]`

Stretched dataset. Kept internal to avoid memory reallocations.

Definition at line 141 of file nca\_softmax\_error\_function.hpp.

## Author

Generated automatically by Doxygen for MLPACK from the source code.