NAG CL Interface
g03fac (multidimscal_​metric)

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

1: $\mathbf{roots}$ – Nag_Eigenvalues Input

On entry: indicates if all the eigenvalues are to be computed or just the ndim largest.

$\mathbf{roots}=\mathrm{Nag\_AllEigVals}$

All the eigenvalues are computed.

$\mathbf{roots}=\mathrm{Nag\_LargeEigVals}$

Only the largest ndim eigenvalues are computed.

Constraint: $\mathbf{roots}=\mathrm{Nag\_AllEigVals}$ or $\mathrm{Nag\_LargeEigVals}$.

2: $\mathbf{n}$ – Integer Input

On entry: the number of objects in the distance matrix, $n$.

Constraint: $\mathbf{n}>\mathbf{ndim}$.

3: $\mathbf{d}\left[\mathbf{n}\times \left(\mathbf{n}-1\right)/2\right]$ – const double Input

On entry: the lower triangle of the distance matrix $D$ stored packed by rows. That is, $\mathbf{d}\left[\left(\mathit{i}-1\right)\times \left(\mathit{i}-2\right)/2+\mathit{j}-1\right]$ must contain $d_{\mathit{i}\mathit{j}}$, for $\mathit{i}=2,3,\dots ,n$ and $\mathit{j}=1,2,\dots ,i-1$.

Constraint: $\mathbf{d}\left[\mathit{i}-1\right]\ge 0.0$, for $\mathit{i}=1,2,\dots ,n\left(n-1\right)/2$.

4: $\mathbf{ndim}$ – Integer Input

On entry: the number of dimensions used to represent the data, $k$.

Constraint: $\mathbf{ndim}\ge 1$.

5: $\mathbf{x}\left[\mathbf{n}\times \mathbf{tdx}\right]$ – double Output

Note: the $\left(i,j\right)$th element of the matrix $X$ is stored in $\mathbf{x}\left[\left(i-1\right)\times \mathbf{tdx}+j-1\right]$.

On exit: the $i$th row contains $k$ coordinates for the $i$th point, $i=1,2,\dots ,n$.

6: $\mathbf{tdx}$ – Integer Input

On entry: the stride separating matrix column elements in the array x.

Constraint: $\mathbf{tdx}\ge \mathbf{ndim}$.

7: $\mathbf{eval}\left[\mathbf{n}\right]$ – double Output

On exit: if $\mathbf{roots}=\mathrm{Nag\_AllEigVals}$, eval contains the $n$ scaled eigenvalues of the matrix $E$. If $\mathbf{roots}=\mathrm{Nag\_LargeEigVals}$, eval contains the largest $k$ scaled eigenvalues of the matrix $E$. In both cases the eigenvalues are divided by the sum of the eigenvalues (that is, the trace of $E$).

8: $\mathbf{fail}$ – NagError * Input/Output

The NAG error argument (see Section 7 in the Introduction to the NAG Library CL Interface).

6 Error Indicators and Warnings

NE_2_INT_ARG_LE

On entry, $\mathbf{n}=〈\mathit{\text{value}}〉$ while $\mathbf{ndim}=〈\mathit{\text{value}}〉$. These arguments must satisfy $\mathbf{n}>\mathbf{ndim}$.

NE_2_INT_ARG_LT

On entry, $\mathbf{tdx}=〈\mathit{\text{value}}〉$ while $\mathbf{ndim}=〈\mathit{\text{value}}〉$. These arguments must satisfy $\mathbf{tdx}\ge \mathbf{ndim}$.

NE_ALLOC_FAIL

Dynamic memory allocation failed.

NE_BAD_PARAM

On entry, argument roots had an illegal value.

NE_EIGVAL

The computation of eigenvalues or eigenvectors has failed.

NE_INT_ARG_LT

On entry, $\mathbf{ndim}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{ndim}\ge 1$.

NE_INTERNAL_ERROR

An internal error has occurred in this function. Check the function call and any array sizes. If the call is correct then please contact NAG for assistance.

NE_NEG_ELEMENT

At least one element of the array d < 0.0.
Constraint: $\mathbf{d}\left[\mathit{i}-1\right]\ge 0.0$, for $\mathit{i}=1,2,\dots ,n\times \left(n-1\right)/2$.

NE_NONZERO_EIGVALS

There are fewer than ndim eigenvalues greater than zero. Try a smaller number of dimensions (ndim) or use non-metric scaling (g03fcc).

NE_REALARR

On entry, $\mathbf{d}\left[〈\mathit{\text{value}}〉\right]=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{d}\left[\mathit{i}-1\right]\ge 0.0$, for $\mathit{i}=1,2,\dots ,n\times \left(n-1\right)/2$.

7 Accuracy

8 Parallelism and Performance

9 Further Comments

10 Example

10.1 Program Text

10.2 Program Data

10.3 Program Results