Actual source code: random.c

petsc-3.3-p7 2013-05-11
  2: /*
  3:     This file contains routines for interfacing to random number generators.
  4:     This provides more than just an interface to some system random number
  5:     generator:

  7:     Numbers can be shuffled for use as random tuples

  9:     Multiple random number generators may be used

 11:     We are still not sure what interface we want here.  There should be
 12:     one to reinitialize and set the seed.
 13:  */

 15: #include <../src/sys/random/randomimpl.h>                              /*I "petscsys.h" I*/
 16: #if defined (PETSC_HAVE_STDLIB_H)
 17: #include <stdlib.h>
 18: #endif

 22: /*@
 23:    PetscRandomGetValue - Generates a random number.  Call this after first calling
 24:    PetscRandomCreate().

 26:    Not Collective

 28:    Intput Parameter:
 29: .  r  - the random number generator context

 31:    Output Parameter:
 32: .  val - the value

 34:    Level: intermediate

 36:    Notes:
 37:    Use VecSetRandom() to set the elements of a vector to random numbers.

 39:    When PETSc is compiled for complex numbers this returns a complex number with random real and complex parts.
 40:    Use PetscGetValueReal() to get a random real number.

 42:    To get a complex number with only a random real part, first call PetscRandomSetInterval() with a equal 
 43:    low and high imaginary part. Similarly to get a complex number with only a random imaginary part call 
 44:    PetscRandomSetInterval() with a equal low and high real part.

 46:    Example of Usage:
 47: .vb
 48:       PetscRandomCreate(PETSC_COMM_WORLD,&r);
 49:       PetscRandomGetValue(r,&value1);
 50:       PetscRandomGetValue(r,&value2);
 51:       PetscRandomGetValue(r,&value3);
 52:       PetscRandomDestroy(&r);
 53: .ve

 55:    Concepts: random numbers^getting

 57: .seealso: PetscRandomCreate(), PetscRandomDestroy(), VecSetRandom(), PetscRandomGetValueReal()
 58: @*/
 59: PetscErrorCode  PetscRandomGetValue(PetscRandom r,PetscScalar *val)
 60: {


 68:   (*r->ops->getvalue)(r,val);
 69:   PetscObjectStateIncrease((PetscObject)r);
 70:   return(0);
 71: }

 75: /*@
 76:    PetscRandomGetValueReal - Generates a purely real random number.  Call this after first calling
 77:    PetscRandomCreate().

 79:    Not Collective

 81:    Intput Parameter:
 82: .  r  - the random number generator context

 84:    Output Parameter:
 85: .  val - the value

 87:    Level: intermediate

 89:    Notes:
 90:    Use VecSetRandom() to set the elements of a vector to random numbers.

 92:    Example of Usage:
 93: .vb
 94:       PetscRandomCreate(PETSC_COMM_WORLD,&r);
 95:       PetscRandomGetValueReal(r,&value1);
 96:       PetscRandomGetValueReal(r,&value2);
 97:       PetscRandomGetValueReal(r,&value3);
 98:       PetscRandomDestroy(&r);
 99: .ve

101:    Concepts: random numbers^getting

103: .seealso: PetscRandomCreate(), PetscRandomDestroy(), VecSetRandom(), PetscRandomGetValue()
104: @*/
105: PetscErrorCode  PetscRandomGetValueReal(PetscRandom r,PetscReal *val)
106: {


114:   (*r->ops->getvaluereal)(r,val);
115:   PetscObjectStateIncrease((PetscObject)r);
116:   return(0);
117: }

121: /*@
122:    PetscRandomGetInterval - Gets the interval over which the random numbers
123:    will be randomly distributed.  By default, this interval is [0,1).

125:    Not collective

127:    Input Parameters:
128: .  r  - the random number generator context

130:    Output Parameters:
131: +  low - The lower bound of the interval
132: -  high - The upper bound of the interval

134:    Level: intermediate

136:    Concepts: random numbers^range

138: .seealso: PetscRandomCreate(), PetscRandomSetInterval()
139: @*/
140: PetscErrorCode  PetscRandomGetInterval(PetscRandom r,PetscScalar *low,PetscScalar *high)
141: {
144:   if (low) {
146:     *low = r->low;
147:   }
148:   if (high) {
150:     *high = r->low+r->width;
151:   }
152:   return(0);
153: }

157: /*@
158:    PetscRandomSetInterval - Sets the interval over which the random numbers
159:    will be randomly distributed.  By default, this interval is [0,1).

161:    Not collective

163:    Input Parameters:
164: +  r  - the random number generator context
165: .  low - The lower bound of the interval
166: -  high - The upper bound of the interval

168:    Level: intermediate

170:    Notes: for complex numbers either the real part or the imaginary part of high must be greater than its low part; or both of them can be greater.
171:     If the real or imaginary part of low and high are the same then that value is always returned in the real or imaginary part.

173:    Concepts: random numbers^range

175: .seealso: PetscRandomCreate(), PetscRandomGetInterval()
176: @*/
177: PetscErrorCode  PetscRandomSetInterval(PetscRandom r,PetscScalar low,PetscScalar high)
178: {
181: #if defined(PETSC_USE_COMPLEX)
182:   if (PetscRealPart(low) > PetscRealPart(high))           SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"only low < high");
183:   if (PetscImaginaryPart(low) > PetscImaginaryPart(high)) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"only low < high");
184: #else
185:   if (low >= high) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"only low < high: Instead %G %G",low,high);
186: #endif
187:   r->low   = low;
188:   r->width = high-low;
189:   r->iset  = PETSC_TRUE;
190:   return(0);
191: }