RNGDS
Sets up table to generate pseudorandom numbers from a general discrete distribution.
Required Arguments
PRF — User‑supplied FUNCTION to compute the probability associated with each mass point of the distribution. The form is PRF(IX), where
IX – Point at which the probability function is to be evaluated. (Input)
IX can range from IMIN to the value at which the cumulative probability is greater than or equal to 1.0 – DEL.
PRF – Value of the probability function at IX. (Output)
PRF must be declared EXTERNAL in the calling program.
DEL — Maximum absolute error allowed in computing the cumulative probability. (Input)
Probabilities smaller than DEL are ignored; hence, DEL should be a small positive number. If DEL is too small, however, CUMPR(NMASS) must be exactly 1.0 since that value is compared to 1.0 ‑ DEL.
NNDX — The number of elements of CUMPR available to be used as indexes. (Input)
NNDX must be greater than or equal to 1. In general, the larger NNDX is, to within sixty or seventy percent of NMASS, the more efficient the generation of random numbers using RNGDS will be.
IMIN — Smallest value the random deviate can assume. (Input/Output)
IMIN is not used if IOPT = 1. If IOPT = 0, PRF is evaluated at IMIN. If this value is less than DEL, IMIN is incremented by 1 and again PRF is evaluated at IMIN. This process is continued until PRF(IMIN) ≥ DEL. IMIN is output as this value and CUMPR(1) is output as PRF(IMIN).
NMASS — The number of mass points in the distribution. (Input, if IOPT = 1; Output, if IOPT = 0)
If IOPT = 0, NMASS is the smallest integer such that PRF(IMIN + NMASS ‑ 1) > 1.0 ‑ DEL. NMASS does include the points IMIN(in) + j for which PRF(IMIN(in) + j) < DEL, for j = 0, 1, …, IMIN(out) ‑ IMIN(in), where IMIN(in) denotes the input value of IMIN and IMIN(out) denotes its output value.
CUMPR — Vector of length NMASS + NNDX containing in the first NMASS positions, the cumulative probabilities and in some of the remaining positions, indexes to speed access to the probabilities. (Output, if IOPT = 0; Input/Output, otherwise)
CUMPR(NMASS + 1) + 1 is the actual number of index positions used.
Optional Arguments
IOPT — Indicator of the extent to which CUMPR is initialized prior to calling RNGDS. (Input)
Default: IOPT = 0.
IOPT | Action |
|---|
0 | RNGDS fills all of CUMPR, using PRF. |
1 | RNGDS fills only the index portion of CUMPR, using the values in the first NMASS positions. PRF is not used and may be a dummy function; also, IMIN and DEL are not used. |
LCUMPR — Dimension of CUMPR exactly as specified in the dimension statement in the calling program. (Input)
Since the logical length of CUMPR is determined in RNGDS, LCUMPR is used for error checking.
Default : LCUMPR = size (CUMPR,1).
FORTRAN 90 Interface
Generic: CALL RNGDS (PRF, DEL, NNDX, IMIN, NMASS, CUMPR [, …])
Specific: The specific interface names are S_RNGDS and D_RNGDS.
FORTRAN 77 Interface
Single: CALL RNGDS (PRF, IOPT, DEL, NNDX, IMIN, NMASS, CUMPR, LCUMPR)
Double: The double precision name is DRNGDS.
Description
Routine
RNGDS sets up a table that routine
RNGDT uses to generate pseudorandom deviates from a discrete distribution. The distribution can be specified either by its probability function
PRF or by a vector of values of the cumulative probability function. Note that
PRF is
not the cumulative probability distribution function. If the cumulative probabilities are already available in
CUMPR, the only reason to call
RNGDS is to form an index vector in the upper portion of
CUMPR so as to speed up the generation of random deviates by the routine
RNGDT.
Comments
1. Informational error
Type | Code | Description |
|---|
3 | 1 | For some I, CUMPR(I) is computed to be less than 1.0 ‑ DEL, and yet CUMPR(I + 1) ‑ 1.0 is greater than 1.0 ‑ CUMPR(I + 1). In this case, the maximum value that the random variable is allowed to take on is I; that is, CUMPR(I) is set to 1.0. |
2. The routine
RNGDT uses the table set up by
RNGDS to generate random numbers from the distribution with
CDF represented in
CUMPR.
Examples
Example 1
In this example, RNGDS is used to set up a table to generate pseudorandom variates from the discrete distribution:
Pr(X = 1) = .05
Pr(X = 2) = .45
Pr(X = 3) = .31
Pr(X = 4) = .04
Pr(X = 5) = .15
In this simple example, we input the cumulative probabilities directly in CUMPR and request 3 indexes to be computed (NNDX = 4). Since the number of mass points is so small, the indexes would not have much effect on the speed of the generation of the random variates.
USE RNGDS_INT
USE UMACH_INT
IMPLICIT NONE
INTEGER LCUMPR
PARAMETER (LCUMPR=9)
!
INTEGER IMIN, IOPT, NMASS, NNDX, NOUT
REAL CUMPR(LCUMPR), DEL, PRF
EXTERNAL PRF
!
CALL UMACH (2, NOUT)
NMASS = 5
CUMPR(1) = 0.05
CUMPR(2) = 0.50
CUMPR(3) = 0.81
CUMPR(4) = 0.85
CUMPR(5) = 1.00
IOPT = 1
NNDX = 4
DEL = 0.00001
CALL RNGDS (PRF, DEL, NNDX, IMIN, NMASS, CUMPR, IOPT=IOPT)
WRITE (NOUT,99999) CUMPR
99999 FORMAT (' Cumulative probabilities and indexes: ', /, 9F6.2)
END
!
! Dummy function
REAL FUNCTION PRF (IX)
INTEGER IX
!
PRF = 0.0
RETURN
END
Output
Cumulative probabilities and indexes:
0.05 0.50 0.81 0.85 1.00 3.00 1.00 2.00 5.00
Example 2
In this example,
RNGDS is used to set up a table to generate binomial variates with parameters 20 and 0.5. The routine
BINPR (see
Chapter 17, “Probability Distribution Functions and Inverses”) is used to compute the probabilities.
USE RNGDS_INT
USE UMACH_INT
IMPLICIT NONE
INTEGER LCUMPR
PARAMETER (LCUMPR=33)
!
INTEGER I, IMIN, N, NMASS, NNDX, NOUT
REAL CUMPR(LCUMPR), DEL, P, PRF
COMMON /BINCOM/ N, P
EXTERNAL PRF
!
CALL UMACH (2, NOUT)
N = 20
P = 0.5
IMIN = 0
NNDX = 12
DEL = 0.00001
CALL RNGDS (PRF, DEL, NNDX, IMIN, NMASS, CUMPR)
WRITE (NOUT,99998) IMIN, NMASS
99998 FORMAT (' The smallest point with positive probability using ', &
/, ' the given DEL is ', I1, ' and all points after ', /, &
' point number ', I2, ' (counting from the input value ', &
/, ' of IMIN) have zero probability.')
WRITE (NOUT,99999) (CUMPR(I),I=1,NMASS+NNDX)
99999 FORMAT (' Cumulative probabilities and indexes: ', /, (5X,8F8.4))
END
!
! Compute binomial probabilities
REAL FUNCTION PRF (IX)
INTEGER IX
!
INTEGER N
REAL BINPR, P
COMMON /BINCOM/ N, P
EXTERNAL BINPR
!
PRF = BINPR(IX,N,P)
RETURN
END
Output
The smallest point with positive probability using
the given DEL is 1 and all points after
point number 19 (counting from the input value
of IMIN) have zero probability.
Cumulative probabilities and indexes:
0.0000 0.0002 0.0013 0.0059 0.0207 0.0577 0.1316 0.2517
0.4119 0.5881 0.7483 0.8684 0.9423 0.9793 0.9941 0.9987
0.9998 1.0000 1.0000 11.0000 1.0000 7.0000 8.0000 9.0000
9.0000 10.0000 11.0000 11.0000 12.0000 13.0000 19.0000
