1: /*
  2:     This file contains routines for interfacing to random number generators.
  3:     This provides more than just an interface to some system random number
  4:     generator:

  6:     Numbers can be shuffled for use as random tuples

  8:     Multiple random number generators may be used

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

 14: #include <petsc/private/randomimpl.h>

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

 20:   Not Collective

 22:   Input Parameter:
 23: . r - the random number generator context

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

 28:   Level: intermediate

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

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

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

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

 49: .seealso: `PetscRandom`, `PetscRandomCreate()`, `PetscRandomDestroy()`, `VecSetRandom()`, `PetscRandomGetValueReal()`, `PetscRandomSetInterval()`
 50: @*/
 51: PetscErrorCode PetscRandomGetValue(PetscRandom r, PetscScalar *val)
 52: {
 53:   PetscFunctionBegin;
 56:   if (!r->ops->getvalue) PetscUseTypeMethod(r, getvalues, 1, val);
 57:   else PetscUseTypeMethod(r, getvalue, val);
 58:   PetscCall(PetscObjectStateIncrease((PetscObject)r));
 59:   PetscFunctionReturn(PETSC_SUCCESS);
 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: {
 92:   PetscFunctionBegin;
 95:   if (!r->ops->getvaluereal) PetscUseTypeMethod(r, getvaluesreal, 1, val);
 96:   else PetscUseTypeMethod(r, getvaluereal, val);
 97:   PetscCall(PetscObjectStateIncrease((PetscObject)r));
 98:   PetscFunctionReturn(PETSC_SUCCESS);
 99: }

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

105:   Not Collective

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

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

114:   Level: intermediate

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

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

122: .seealso: `PetscRandom`, `PetscRandomCreate()`, `PetscRandomDestroy()`, `VecSetRandom()`, `PetscRandomGetValue()`
123: @*/
124: PetscErrorCode PetscRandomGetValues(PetscRandom r, PetscInt n, PetscScalar *val)
125: {
126:   PetscFunctionBegin;
129:   if (!r->ops->getvalues) {
130:     PetscErrorCode (*const getvalue)(PetscRandom, PetscScalar *) = r->ops->getvalue;

132:     for (PetscInt i = 0; i < n; ++i) PetscCall(getvalue(r, val + i));
133:   } else PetscUseTypeMethod(r, getvalues, n, val);
134:   PetscCall(PetscObjectStateIncrease((PetscObject)r));
135:   PetscFunctionReturn(PETSC_SUCCESS);
136: }

138: /*@
139:   PetscRandomGetValuesReal - Generates a sequence of real random numbers.  Call this after first calling
140:   `PetscRandomCreate()`.

142:   Not Collective

144:   Input Parameters:
145: + r - the random number generator context
146: - n - number of random numbers to generate

148:   Output Parameter:
149: . val - the array to hold the values

151:   Level: intermediate

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

156: .seealso: `PetscRandom`, `PetscRandomCreate()`, `PetscRandomDestroy()`, `VecSetRandom()`, `PetscRandomGetValues()`
157: @*/
158: PetscErrorCode PetscRandomGetValuesReal(PetscRandom r, PetscInt n, PetscReal *val)
159: {
160:   PetscFunctionBegin;
163:   if (!r->ops->getvaluesreal) {
164:     PetscInt i;
165:     for (i = 0; i < n; i++) PetscUseTypeMethod(r, getvaluereal, val + i);
166:   } else PetscUseTypeMethod(r, getvaluesreal, n, val);
167:   PetscCall(PetscObjectStateIncrease((PetscObject)r));
168:   PetscFunctionReturn(PETSC_SUCCESS);
169: }

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

175:   Not Collective

177:   Input Parameter:
178: . r - the random number generator context

180:   Output Parameters:
181: + low  - The lower bound of the interval
182: - high - The upper bound of the interval

184:   Level: intermediate

186: .seealso: `PetscRandom`, `PetscRandomCreate()`, `PetscRandomSetInterval()`
187: @*/
188: PetscErrorCode PetscRandomGetInterval(PetscRandom r, PetscScalar *low, PetscScalar *high)
189: {
190:   PetscFunctionBegin;
192:   if (low) {
193:     PetscAssertPointer(low, 2);
194:     *low = r->low;
195:   }
196:   if (high) {
197:     PetscAssertPointer(high, 3);
198:     *high = r->low + r->width;
199:   }
200:   PetscFunctionReturn(PETSC_SUCCESS);
201: }

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

207:   Not Collective

209:   Input Parameters:
210: + r    - the random number generator context
211: . low  - The lower bound of the interval
212: - high - The upper bound of the interval

214:   Level: intermediate

216:   Notes:
217:   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.

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

221: .seealso: `PetscRandomCreate()`, `PetscRandomGetInterval()`
222: @*/
223: PetscErrorCode PetscRandomSetInterval(PetscRandom r, PetscScalar low, PetscScalar high)
224: {
225:   PetscFunctionBegin;
227: #if defined(PETSC_USE_COMPLEX)
228:   PetscCheck(PetscRealPart(low) <= PetscRealPart(high), PETSC_COMM_SELF, PETSC_ERR_ARG_OUTOFRANGE, "only low <= high");
229:   PetscCheck(PetscImaginaryPart(low) <= PetscImaginaryPart(high), PETSC_COMM_SELF, PETSC_ERR_ARG_OUTOFRANGE, "only low <= high");
230: #else
231:   PetscCheck(low < high, PETSC_COMM_SELF, PETSC_ERR_ARG_OUTOFRANGE, "only low <= high: Instead %g %g", (double)low, (double)high);
232: #endif
233:   r->low   = low;
234:   r->width = high - low;
235:   r->iset  = PETSC_TRUE;
236:   PetscFunctionReturn(PETSC_SUCCESS);
237: }