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: .seealso: PetscRandomCreate(), PetscRandomDestroy(), VecSetRandom(), PetscRandomGetValueReal()
 51: @*/
 52: PetscErrorCode  PetscRandomGetValue(PetscRandom r,PetscScalar *val)
 53: {


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

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

 70:    Not Collective

 72:    Intput Parameter:
 73: .  r  - the random number generator context

 75:    Output Parameter:
 76: .  val - the value

 78:    Level: intermediate

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

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

 92: .seealso: PetscRandomCreate(), PetscRandomDestroy(), VecSetRandom(), PetscRandomGetValue()
 93: @*/
 94: PetscErrorCode  PetscRandomGetValueReal(PetscRandom r,PetscReal *val)
 95: {


103:   (*r->ops->getvaluereal)(r,val);
104:   PetscObjectStateIncrease((PetscObject)r);
105:   return(0);
106: }

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

112:    Not collective

114:    Input Parameters:
115: .  r  - the random number generator context

117:    Output Parameters:
118: +  low - The lower bound of the interval
119: -  high - The upper bound of the interval

121:    Level: intermediate

123: .seealso: PetscRandomCreate(), PetscRandomSetInterval()
124: @*/
125: PetscErrorCode  PetscRandomGetInterval(PetscRandom r,PetscScalar *low,PetscScalar *high)
126: {
129:   if (low) {
131:     *low = r->low;
132:   }
133:   if (high) {
135:     *high = r->low+r->width;
136:   }
137:   return(0);
138: }

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

144:    Not collective

146:    Input Parameters:
147: +  r  - the random number generator context
148: .  low - The lower bound of the interval
149: -  high - The upper bound of the interval

151:    Level: intermediate

153:    Notes:
154:     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.
155:     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.

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