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/classes/random/randomimpl.h>                              /*I "petscsys.h" I*/

 19: /*@
 20:    PetscRandomGetValue - Generates a random number.  Call this after first calling
 21:    PetscRandomCreate().

 23:    Not Collective

 25:    Intput Parameter:
 26: .  r  - the random number generator context

 28:    Output Parameter:
 29: .  val - the value

 31:    Level: intermediate

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

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

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

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

 52:    Concepts: random numbers^getting

 54: .seealso: PetscRandomCreate(), PetscRandomDestroy(), VecSetRandom(), PetscRandomGetValueReal()
 55: @*/
 56: PetscErrorCode  PetscRandomGetValue(PetscRandom r,PetscScalar *val)
 57: {


 65:   (*r->ops->getvalue)(r,val);
 66:   PetscObjectStateIncrease((PetscObject)r);
 67:   return(0);
 68: }

 72: /*@
 73:    PetscRandomGetValueReal - Generates a purely real random number.  Call this after first calling
 74:    PetscRandomCreate().

 76:    Not Collective

 78:    Intput Parameter:
 79: .  r  - the random number generator context

 81:    Output Parameter:
 82: .  val - the value

 84:    Level: intermediate

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

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

 98:    Concepts: random numbers^getting

100: .seealso: PetscRandomCreate(), PetscRandomDestroy(), VecSetRandom(), PetscRandomGetValue()
101: @*/
102: PetscErrorCode  PetscRandomGetValueReal(PetscRandom r,PetscReal *val)
103: {


111:   (*r->ops->getvaluereal)(r,val);
112:   PetscObjectStateIncrease((PetscObject)r);
113:   return(0);
114: }

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

122:    Not collective

124:    Input Parameters:
125: .  r  - the random number generator context

127:    Output Parameters:
128: +  low - The lower bound of the interval
129: -  high - The upper bound of the interval

131:    Level: intermediate

133:    Concepts: random numbers^range

135: .seealso: PetscRandomCreate(), PetscRandomSetInterval()
136: @*/
137: PetscErrorCode  PetscRandomGetInterval(PetscRandom r,PetscScalar *low,PetscScalar *high)
138: {
141:   if (low) {
143:     *low = r->low;
144:   }
145:   if (high) {
147:     *high = r->low+r->width;
148:   }
149:   return(0);
150: }

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

158:    Not collective

160:    Input Parameters:
161: +  r  - the random number generator context
162: .  low - The lower bound of the interval
163: -  high - The upper bound of the interval

165:    Level: intermediate

167:    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.
168:     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.

170:    Concepts: random numbers^range

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