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: }