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>

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

 21:    Not Collective

 23:    Intput Parameter:
 24: .  r  - the random number generator context

 26:    Output Parameter:
 27: .  val - the value

 29:    Level: intermediate

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

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

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

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

 50:    Concepts: random numbers^getting

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


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

 68: /*@
 69:    PetscRandomGetValueReal - Generates a purely real random number.  Call this after first calling
 70:    PetscRandomCreate().

 72:    Not Collective

 74:    Intput Parameter:
 75: .  r  - the random number generator context

 77:    Output Parameter:
 78: .  val - the value

 80:    Level: intermediate

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

 85:    Example of Usage:
 86: .vb
 87:       PetscRandomCreate(PETSC_COMM_WORLD,&r);
 88:       PetscRandomGetValueReal(r,&value1);
 89:       PetscRandomGetValueReal(r,&value2);
 90:       PetscRandomGetValueReal(r,&value3);
 91:       PetscRandomDestroy(&r);
 92: .ve

 94:    Concepts: random numbers^getting

 96: .seealso: PetscRandomCreate(), PetscRandomDestroy(), VecSetRandom(), PetscRandomGetValue()
 97: @*/
 98: PetscErrorCode  PetscRandomGetValueReal(PetscRandom r,PetscReal *val)
 99: {


107:   (*r->ops->getvaluereal)(r,val);
108:   PetscObjectStateIncrease((PetscObject)r);
109:   return(0);
110: }

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

116:    Not collective

118:    Input Parameters:
119: .  r  - the random number generator context

121:    Output Parameters:
122: +  low - The lower bound of the interval
123: -  high - The upper bound of the interval

125:    Level: intermediate

127:    Concepts: random numbers^range

129: .seealso: PetscRandomCreate(), PetscRandomSetInterval()
130: @*/
131: PetscErrorCode  PetscRandomGetInterval(PetscRandom r,PetscScalar *low,PetscScalar *high)
132: {
135:   if (low) {
137:     *low = r->low;
138:   }
139:   if (high) {
141:     *high = r->low+r->width;
142:   }
143:   return(0);
144: }

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

150:    Not collective

152:    Input Parameters:
153: +  r  - the random number generator context
154: .  low - The lower bound of the interval
155: -  high - The upper bound of the interval

157:    Level: intermediate

159:    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.
160:     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.

162:    Concepts: random numbers^range

164: .seealso: PetscRandomCreate(), PetscRandomGetInterval()
165: @*/
166: PetscErrorCode  PetscRandomSetInterval(PetscRandom r,PetscScalar low,PetscScalar high)
167: {
170: #if defined(PETSC_USE_COMPLEX)
171:   if (PetscRealPart(low) > PetscRealPart(high))           SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"only low <= high");
172:   if (PetscImaginaryPart(low) > PetscImaginaryPart(high)) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"only low <= high");
173: #else
174:   if (low >= high) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"only low <= high: Instead %g %g",(double)low,(double)high);
175: #endif
176:   r->low   = low;
177:   r->width = high-low;
178:   r->iset  = PETSC_TRUE;
179:   return(0);
180: }