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 (\mathbf{n}-1)/2\right]$ – const double Input

On entry: the lower triangle of the distance matrix $D$ stored packed by rows. That is, $\mathbf{d}\left[(\mathit{i}-1)\times (\mathit{i}-2)/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(n-1)/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 $(i,j)$th element of the matrix $X$ is stored in $\mathbf{x}\left[(i-1)\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 (n-1)/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 (n-1)/2$.

7 Accuracy

8 Parallelism and Performance

9 Further Comments

10 Example

10.1 Program Text

10.2 Program Data

10.3 Program Results