Actual source code: random.c


  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 <petsc/private/randomimpl.h>

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

 21:    Not Collective

 23:    Input 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 `PetscRandomGetValueReal()` 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: `PetscRandom`, `PetscRandomCreate()`, `PetscRandomDestroy()`, `VecSetRandom()`, `PetscRandomGetValueReal()`, `PetscRandomSetInterval()`
 51: @*/
 52: PetscErrorCode PetscRandomGetValue(PetscRandom r, PetscScalar *val)
 53: {
 56:   if (!r->ops->getvalue) PetscUseTypeMethod(r, getvalues, 1, val);
 57:   else PetscUseTypeMethod(r, getvalue, val);
 58:   PetscObjectStateIncrease((PetscObject)r);
 59:   return 0;
 60: }

 62: /*@
 63:    PetscRandomGetValueReal - Generates a real random number.  Call this after first calling
 64:    `PetscRandomCreate()`.

 66:    Not Collective

 68:    Input Parameter:
 69: .  r  - the random number generator context

 71:    Output Parameter:
 72: .  val - the value

 74:    Level: intermediate

 76:    Note:
 77:    Use `VecSetRandom()` to set the elements of a vector to random numbers.

 79:    Example of Usage:
 80: .vb
 81:       PetscRandomCreate(PETSC_COMM_WORLD,&r);
 82:       PetscRandomGetValueReal(r,&value1);
 83:       PetscRandomGetValueReal(r,&value2);
 84:       PetscRandomGetValueReal(r,&value3);
 85:       PetscRandomDestroy(&r);
 86: .ve

 88: .seealso: `PetscRandom`, `PetscRandomCreate()`, `PetscRandomDestroy()`, `VecSetRandom()`, `PetscRandomGetValue()`
 89: @*/
 90: PetscErrorCode PetscRandomGetValueReal(PetscRandom r, PetscReal *val)
 91: {
 94:   if (!r->ops->getvaluereal) PetscUseTypeMethod(r, getvaluesreal, 1, val);
 95:   else PetscUseTypeMethod(r, getvaluereal, val);
 96:   PetscObjectStateIncrease((PetscObject)r);
 97:   return 0;
 98: }

100: /*@
101:    PetscRandomGetValues - Generates a sequence of random numbers.  Call this after first calling
102:    `PetscRandomCreate()`.

104:    Not Collective

106:    Input Parameters:
107: +  r  - the random number generator context
108: -  n  - number of random numbers to generate

110:    Output Parameter:
111: .  val - the array to hold the values

113:    Level: intermediate

115:    Notes:
116:    Use `VecSetRandom()` to set the elements of a vector to random numbers.

118:    When PETSc is compiled for complex numbers this returns an array of complex numbers with random real and complex parts.
119:    Use `PetscRandomGetValuesReal()` to get an array of random real numbers.

121: .seealso: `PetscRandom`, `PetscRandomCreate()`, `PetscRandomDestroy()`, `VecSetRandom()`, `PetscRandomGetValue()`
122: @*/
123: PetscErrorCode PetscRandomGetValues(PetscRandom r, PetscInt n, PetscScalar *val)
124: {
127:   if (!r->ops->getvalues) {
128:     PetscInt i;
129:     for (i = 0; i < n; i++) (*r->ops->getvalue)(r, val + i);
130:   } else PetscUseTypeMethod(r, getvalues, n, val);
131:   PetscObjectStateIncrease((PetscObject)r);
132:   return 0;
133: }

135: /*@
136:    PetscRandomGetValuesReal - Generates a sequence of real random numbers.  Call this after first calling
137:    `PetscRandomCreate()`.

139:    Not Collective

141:    Input Parameters:
142: +  r  - the random number generator context
143: -  n  - number of random numbers to generate

145:    Output Parameter:
146: .  val - the array to hold the values

148:    Level: intermediate

150:    Note:
151:    Use `VecSetRandom()` to set the elements of a vector to random numbers.

153: .seealso: `PetscRandom`, `PetscRandomCreate()`, `PetscRandomDestroy()`, `VecSetRandom()`, `PetscRandomGetValues()`
154: @*/
155: PetscErrorCode PetscRandomGetValuesReal(PetscRandom r, PetscInt n, PetscReal *val)
156: {
159:   if (!r->ops->getvaluesreal) {
160:     PetscInt i;
161:     for (i = 0; i < n; i++) (*r->ops->getvaluereal)(r, val + i);
162:   } else PetscUseTypeMethod(r, getvaluesreal, n, val);
163:   PetscObjectStateIncrease((PetscObject)r);
164:   return 0;
165: }

167: /*@
168:    PetscRandomGetInterval - Gets the interval over which the random numbers
169:    will be distributed.  By default, this interval is [0,1).

171:    Not collective

173:    Input Parameter:
174: .  r  - the random number generator context

176:    Output Parameters:
177: +  low - The lower bound of the interval
178: -  high - The upper bound of the interval

180:    Level: intermediate

182: .seealso: `PetscRandom`, `PetscRandomCreate()`, `PetscRandomSetInterval()`
183: @*/
184: PetscErrorCode PetscRandomGetInterval(PetscRandom r, PetscScalar *low, PetscScalar *high)
185: {
187:   if (low) {
189:     *low = r->low;
190:   }
191:   if (high) {
193:     *high = r->low + r->width;
194:   }
195:   return 0;
196: }

198: /*@
199:    PetscRandomSetInterval - Sets the interval over which the random numbers
200:    will be distributed.  By default, this interval is [0,1).

202:    Not collective

204:    Input Parameters:
205: +  r  - the random number generator context
206: .  low - The lower bound of the interval
207: -  high - The upper bound of the interval

209:    Level: intermediate

211:    Notes:
212:     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.

214:     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.

216: .seealso: `PetscRandomCreate()`, `PetscRandomGetInterval()`
217: @*/
218: PetscErrorCode PetscRandomSetInterval(PetscRandom r, PetscScalar low, PetscScalar high)
219: {
221: #if defined(PETSC_USE_COMPLEX)
224: #else
226: #endif
227:   r->low   = low;
228:   r->width = high - low;
229:   r->iset  = PETSC_TRUE;
230:   return 0;
231: }