NAG Library Function Document

nag_rngs_2_way_table (g05qdc)

1  Purpose

2  Specification

3  Description

4  References

5  Arguments

1:     order – Nag_OrderTypeInput

On entry: the order argument specifies the two-dimensional storage scheme being used, i.e., row-major ordering or column-major ordering. C language defined storage is specified by $\mathbf{order}=\mathrm{Nag\_RowMajor}$. See Section 3.2.1.3 in the Essential Introduction for a more detailed explanation of the use of this argument.

Constraint: $\mathbf{order}=\mathrm{Nag\_RowMajor}$ or Nag_ColMajor.

2:     mode – IntegerInput

On entry: a code for selecting the operation to be performed by the function.

$\mathbf{mode}=0$

Set up reference vector only.

$\mathbf{mode}=1$

Generate two-way table using reference vector set up in a prior call to nag_rngs_2_way_table (g05qdc).

$\mathbf{mode}=2$

Set up reference vector and generate two-way table.

Constraint: $\mathbf{mode}=0$, $1$ or $2$.

3:     nrow – IntegerInput

On entry: $m$, the number of rows in the table.

Constraint: $\mathbf{nrow}\ge 2$.

4:     ncol – IntegerInput

On entry: $n$, the number of columns in the table.

Constraint: $\mathbf{ncol}\ge 2$.

5:     totr[nrow] – const IntegerInput

On entry: the $m$ row totals, $R_{\mathit{i}}$, for $\mathit{i}=1,2,\dots ,m$.

Constraints:

• $\mathbf{totr}\left[\mathit{i}-1\right]\ge 0$, for $\mathit{i}=1,2,\dots ,m$;
• ${\displaystyle \sum _{i=1}^m}\mathbf{totr}\left[i-1\right]={\displaystyle \sum _{j=1}^n}\mathbf{totc}\left[j-1\right]$.

6:     totc[ncol] – const IntegerInput

On entry: the $n$ column totals, $C_{\mathit{j}}$, for $\mathit{j}=1,2,\dots ,n$.

Constraints:

• $\mathbf{totc}\left[\mathit{j}-1\right]\ge 0$, for $\mathit{j}=1,2,\dots ,n$;
• ${\displaystyle \sum _{j=1}^n}\mathbf{totc}\left[j-1\right]={\displaystyle \sum _{i=1}^m}\mathbf{totr}\left[i-1\right]$.

7:     x[$\mathit{dim}$] – IntegerOutput

Note: the dimension, dim, of the array x must be at least

• $\max \left(1,\mathbf{pdx}\times \mathbf{ncol}\right)$ when $\mathbf{order}=\mathrm{Nag\_ColMajor}$;
• $\max \left(1,\mathbf{nrow}\times \mathbf{pdx}\right)$ when $\mathbf{order}=\mathrm{Nag\_RowMajor}$.

Where $\mathbf{X}\left(i,j\right)$ appears in this document, it refers to the array element

• $\mathbf{x}\left[\left(j-1\right)\times \mathbf{pdx}+i-1\right]$ when $\mathbf{order}=\mathrm{Nag\_ColMajor}$;
• $\mathbf{x}\left[\left(i-1\right)\times \mathbf{pdx}+j-1\right]$ when $\mathbf{order}=\mathrm{Nag\_RowMajor}$.

On exit: if $\mathbf{mode}=1$ or $2$, a pseudorandom two-way $m$ by $n$ table, $X$, with element $\mathbf{X}\left(i,j\right)$ containing the $\left(i,j\right)$th entry in the table such that ${\displaystyle \sum _{i=1}^{\mathbf{nrow}}}\mathbf{X}\left(i,j\right)=\mathbf{totc}\left[j-1\right]$ and ${\displaystyle \sum _{j=1}^{\mathbf{ncol}}}\mathbf{X}\left(i,j\right)=\mathbf{totr}\left[i-1\right]$

8:     pdx – IntegerInput

On entry: the stride separating row or column elements (depending on the value of order) in the array x.

Constraints:

• if $\mathbf{order}=\mathrm{Nag\_ColMajor}$, $\mathbf{pdx}\ge \mathbf{nrow}$;
• if $\mathbf{order}=\mathrm{Nag\_RowMajor}$, $\mathbf{pdx}\ge \mathbf{ncol}$.

9:     igen – IntegerInput

On entry: must contain the identification number for the generator to be used to return a pseudorandom number and should remain unchanged following initialization by a prior call to nag_rngs_init_repeatable (g05kbc) or nag_rngs_init_nonrepeatable (g05kcc).

10:   iseed[$4$] – IntegerCommunication Array

On entry: contains values which define the current state of the selected generator.

On exit: contains updated values defining the new state of the selected generator.

11:   r[nr] – doubleCommunication Array

On entry: if $\mathbf{mode}=1$, the reference vector from the previous call to nag_rngs_2_way_table (g05qdc).

On exit: the reference vector.

12:   nr – IntegerInput

On entry: the dimension of the array r.

Constraint: $\mathbf{nr}\ge {\displaystyle \sum _{i=1}^{\mathbf{nrow}}}\mathbf{totr}\left[i-1\right]+4$.

13:   fail – NagError *Input/Output

The NAG error argument (see Section 3.6 in the Essential Introduction).

6  Error Indicators and Warnings

NE_ALLOC_FAIL

Dynamic memory allocation failed.

NE_BAD_PARAM

On entry, argument $〈\mathit{\text{value}}〉$ had an illegal value.

NE_INT

On entry, $\mathbf{mode}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{mode}=0$, $1$ or $2$.

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

On entry, nr not large enough, $\mathbf{nr}=〈\mathit{\text{value}}〉$. Minimum length required $=〈\mathit{\text{value}}〉$.

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

On entry, $\mathbf{pdx}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{pdx}>0$.

NE_INT_2

On entry, $\mathbf{nrow}<2$ or $\mathbf{ncol}<2$: $\mathbf{nrow}=〈\mathit{\text{value}}〉$ and $\mathbf{ncol}=〈\mathit{\text{value}}〉$.

On entry, $\mathbf{pdx}=〈\mathit{\text{value}}〉$ and $\mathbf{ncol}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{pdx}\ge \mathbf{ncol}$.

On entry, $\mathbf{pdx}=〈\mathit{\text{value}}〉$ and $\mathbf{nrow}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{pdx}\ge \mathbf{nrow}$.

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_PREV_CALL

nrow or ncol is not the same as when r was set up in a previous call. Previous value of $\mathbf{nrow}=〈\mathit{\text{value}}〉$, current value of $\mathbf{nrow}=〈\mathit{\text{value}}〉$. Previous value of $\mathbf{ncol}=〈\mathit{\text{value}}〉$, current value of $\mathbf{ncol}=〈\mathit{\text{value}}〉$.

NE_REAL_ARRAY_ELEM_CONS

On entry, totc has at least one negative element.

On entry, totr has at least one negative element.

NE_REAL_ARRAYS_SUM

On entry, the arrays totr and totc do not sum to the same total: totr array total is $〈\mathit{\text{value}}〉$, totc array total is $〈\mathit{\text{value}}〉$.

7  Accuracy

8  Further Comments

9  Example

9.1  Program Text

Program Text (g05qdce.c)

9.2  Program Data

9.3  Program Results

Program Results (g05qdce.r)