Actual source code: random.c
petsc-3.13.6 2020-09-29
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: }