Actual source code: random.c
petsc-3.7.1 2016-05-15
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>                              /*I "petscsys.h" I*/

     19: /*@
     20:    PetscRandomGetValue - Generates a random number.  Call this after first calling
     21:    PetscRandomCreate().

     23:    Not Collective

     25:    Intput Parameter:
     26: .  r  - the random number generator context

     28:    Output Parameter:
     29: .  val - the value

     31:    Level: intermediate

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

     36:    When PETSc is compiled for complex numbers this returns a complex number with random real and complex parts.
     37:    Use PetscGetValueReal() to get a random real number.

     39:    To get a complex number with only a random real part, first call PetscRandomSetInterval() with a equal
     40:    low and high imaginary part. Similarly to get a complex number with only a random imaginary part call
     41:    PetscRandomSetInterval() with a equal low and high real part.

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

     52:    Concepts: random numbers^getting

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

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

     72: /*@
     73:    PetscRandomGetValueReal - Generates a purely real random number.  Call this after first calling
     74:    PetscRandomCreate().

     76:    Not Collective

     78:    Intput Parameter:
     79: .  r  - the random number generator context

     81:    Output Parameter:
     82: .  val - the value

     84:    Level: intermediate

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

     89:    Example of Usage:
     90: .vb
     91:       PetscRandomCreate(PETSC_COMM_WORLD,&r);
     92:       PetscRandomGetValueReal(r,&value1);
     93:       PetscRandomGetValueReal(r,&value2);
     94:       PetscRandomGetValueReal(r,&value3);
     95:       PetscRandomDestroy(&r);
     96: .ve

     98:    Concepts: random numbers^getting

    100: .seealso: PetscRandomCreate(), PetscRandomDestroy(), VecSetRandom(), PetscRandomGetValue()
    101: @*/
    102: PetscErrorCode  PetscRandomGetValueReal(PetscRandom r,PetscReal *val)
    103: {

    111:   (*r->ops->getvaluereal)(r,val);
    112:   PetscObjectStateIncrease((PetscObject)r);
    113:   return(0);
    114: }

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

    122:    Not collective

    124:    Input Parameters:
    125: .  r  - the random number generator context

    127:    Output Parameters:
    128: +  low - The lower bound of the interval
    129: -  high - The upper bound of the interval

    131:    Level: intermediate

    133:    Concepts: random numbers^range

    135: .seealso: PetscRandomCreate(), PetscRandomSetInterval()
    136: @*/
    137: PetscErrorCode  PetscRandomGetInterval(PetscRandom r,PetscScalar *low,PetscScalar *high)
    138: {
    141:   if (low) {
    143:     *low = r->low;
    144:   }
    145:   if (high) {
    147:     *high = r->low+r->width;
    148:   }
    149:   return(0);
    150: }

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

    158:    Not collective

    160:    Input Parameters:
    161: +  r  - the random number generator context
    162: .  low - The lower bound of the interval
    163: -  high - The upper bound of the interval

    165:    Level: intermediate

    167:    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.
    168:     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.

    170:    Concepts: random numbers^range

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