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