Actual source code: random.c
petsc-3.10.5 2019-03-28
Report Typos and Errors

      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:    Concepts: random numbers^getting

     52: .seealso: PetscRandomCreate(), PetscRandomDestroy(), VecSetRandom(), PetscRandomGetValueReal()
     53: @*/
     54: PetscErrorCode  PetscRandomGetValue(PetscRandom r,PetscScalar *val)
     55: {

     63:   (*r->ops->getvalue)(r,val);
     64:   PetscObjectStateIncrease((PetscObject)r);
     65:   return(0);
     66: }

     68: /*@
     69:    PetscRandomGetValueReal - Generates a purely real random number.  Call this after first calling
     70:    PetscRandomCreate().

     72:    Not Collective

     74:    Intput Parameter:
     75: .  r  - the random number generator context

     77:    Output Parameter:
     78: .  val - the value

     80:    Level: intermediate

     82:    Notes:
     83:    Use VecSetRandom() to set the elements of a vector to random numbers.

     85:    Example of Usage:
     86: .vb
     87:       PetscRandomCreate(PETSC_COMM_WORLD,&r);
     88:       PetscRandomGetValueReal(r,&value1);
     89:       PetscRandomGetValueReal(r,&value2);
     90:       PetscRandomGetValueReal(r,&value3);
     91:       PetscRandomDestroy(&r);
     92: .ve

     94:    Concepts: random numbers^getting

     96: .seealso: PetscRandomCreate(), PetscRandomDestroy(), VecSetRandom(), PetscRandomGetValue()
     97: @*/
     98: PetscErrorCode  PetscRandomGetValueReal(PetscRandom r,PetscReal *val)
     99: {

    107:   (*r->ops->getvaluereal)(r,val);
    108:   PetscObjectStateIncrease((PetscObject)r);
    109:   return(0);
    110: }

    112: /*@
    113:    PetscRandomGetInterval - Gets the interval over which the random numbers
    114:    will be randomly distributed.  By default, this interval is [0,1).

    116:    Not collective

    118:    Input Parameters:
    119: .  r  - the random number generator context

    121:    Output Parameters:
    122: +  low - The lower bound of the interval
    123: -  high - The upper bound of the interval

    125:    Level: intermediate

    127:    Concepts: random numbers^range

    129: .seealso: PetscRandomCreate(), PetscRandomSetInterval()
    130: @*/
    131: PetscErrorCode  PetscRandomGetInterval(PetscRandom r,PetscScalar *low,PetscScalar *high)
    132: {
    135:   if (low) {
    137:     *low = r->low;
    138:   }
    139:   if (high) {
    141:     *high = r->low+r->width;
    142:   }
    143:   return(0);
    144: }

    146: /*@
    147:    PetscRandomSetInterval - Sets the interval over which the random numbers
    148:    will be randomly distributed.  By default, this interval is [0,1).

    150:    Not collective

    152:    Input Parameters:
    153: +  r  - the random number generator context
    154: .  low - The lower bound of the interval
    155: -  high - The upper bound of the interval

    157:    Level: intermediate

    159:    Notes:
    160:     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.
    161:     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.

    163:    Concepts: random numbers^range

    165: .seealso: PetscRandomCreate(), PetscRandomGetInterval()
    166: @*/
    167: PetscErrorCode  PetscRandomSetInterval(PetscRandom r,PetscScalar low,PetscScalar high)
    168: {
    171: #if defined(PETSC_USE_COMPLEX)
    172:   if (PetscRealPart(low) > PetscRealPart(high))           SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"only low <= high");
    173:   if (PetscImaginaryPart(low) > PetscImaginaryPart(high)) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"only low <= high");
    174: #else
    175:   if (low >= high) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"only low <= high: Instead %g %g",(double)low,(double)high);
    176: #endif
    177:   r->low   = low;
    178:   r->width = high-low;
    179:   r->iset  = PETSC_TRUE;
    180:   return(0);
    181: }