Actual source code: random.c
petsc-3.3-p7 2013-05-11
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/random/randomimpl.h> /*I "petscsys.h" I*/
16: #if defined (PETSC_HAVE_STDLIB_H)
17: #include <stdlib.h>
18: #endif
22: /*@
23: PetscRandomGetValue - Generates a random number. Call this after first calling
24: PetscRandomCreate().
26: Not Collective
28: Intput Parameter:
29: . r - the random number generator context
31: Output Parameter:
32: . val - the value
34: Level: intermediate
36: Notes:
37: Use VecSetRandom() to set the elements of a vector to random numbers.
39: When PETSc is compiled for complex numbers this returns a complex number with random real and complex parts.
40: Use PetscGetValueReal() to get a random real number.
42: To get a complex number with only a random real part, first call PetscRandomSetInterval() with a equal
43: low and high imaginary part. Similarly to get a complex number with only a random imaginary part call
44: PetscRandomSetInterval() with a equal low and high real part.
46: Example of Usage:
47: .vb
48: PetscRandomCreate(PETSC_COMM_WORLD,&r);
49: PetscRandomGetValue(r,&value1);
50: PetscRandomGetValue(r,&value2);
51: PetscRandomGetValue(r,&value3);
52: PetscRandomDestroy(&r);
53: .ve
55: Concepts: random numbers^getting
57: .seealso: PetscRandomCreate(), PetscRandomDestroy(), VecSetRandom(), PetscRandomGetValueReal()
58: @*/
59: PetscErrorCode PetscRandomGetValue(PetscRandom r,PetscScalar *val)
60: {
68: (*r->ops->getvalue)(r,val);
69: PetscObjectStateIncrease((PetscObject)r);
70: return(0);
71: }
75: /*@
76: PetscRandomGetValueReal - Generates a purely real random number. Call this after first calling
77: PetscRandomCreate().
79: Not Collective
81: Intput Parameter:
82: . r - the random number generator context
84: Output Parameter:
85: . val - the value
87: Level: intermediate
89: Notes:
90: Use VecSetRandom() to set the elements of a vector to random numbers.
92: Example of Usage:
93: .vb
94: PetscRandomCreate(PETSC_COMM_WORLD,&r);
95: PetscRandomGetValueReal(r,&value1);
96: PetscRandomGetValueReal(r,&value2);
97: PetscRandomGetValueReal(r,&value3);
98: PetscRandomDestroy(&r);
99: .ve
101: Concepts: random numbers^getting
103: .seealso: PetscRandomCreate(), PetscRandomDestroy(), VecSetRandom(), PetscRandomGetValue()
104: @*/
105: PetscErrorCode PetscRandomGetValueReal(PetscRandom r,PetscReal *val)
106: {
114: (*r->ops->getvaluereal)(r,val);
115: PetscObjectStateIncrease((PetscObject)r);
116: return(0);
117: }
121: /*@
122: PetscRandomGetInterval - Gets the interval over which the random numbers
123: will be randomly distributed. By default, this interval is [0,1).
125: Not collective
127: Input Parameters:
128: . r - the random number generator context
130: Output Parameters:
131: + low - The lower bound of the interval
132: - high - The upper bound of the interval
134: Level: intermediate
136: Concepts: random numbers^range
138: .seealso: PetscRandomCreate(), PetscRandomSetInterval()
139: @*/
140: PetscErrorCode PetscRandomGetInterval(PetscRandom r,PetscScalar *low,PetscScalar *high)
141: {
144: if (low) {
146: *low = r->low;
147: }
148: if (high) {
150: *high = r->low+r->width;
151: }
152: return(0);
153: }
157: /*@
158: PetscRandomSetInterval - Sets the interval over which the random numbers
159: will be randomly distributed. By default, this interval is [0,1).
161: Not collective
163: Input Parameters:
164: + r - the random number generator context
165: . low - The lower bound of the interval
166: - high - The upper bound of the interval
168: Level: intermediate
170: 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.
171: 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.
173: Concepts: random numbers^range
175: .seealso: PetscRandomCreate(), PetscRandomGetInterval()
176: @*/
177: PetscErrorCode PetscRandomSetInterval(PetscRandom r,PetscScalar low,PetscScalar high)
178: {
181: #if defined(PETSC_USE_COMPLEX)
182: if (PetscRealPart(low) > PetscRealPart(high)) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"only low < high");
183: if (PetscImaginaryPart(low) > PetscImaginaryPart(high)) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"only low < high");
184: #else
185: if (low >= high) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"only low < high: Instead %G %G",low,high);
186: #endif
187: r->low = low;
188: r->width = high-low;
189: r->iset = PETSC_TRUE;
190: return(0);
191: }