simgrid-java/org/simgrid/msg/RngStream.java

   1 /*
   2  * JNI interface to C RngStream code
   3  *
   4  * Copyright 2006-2012 The SimGrid Team.
   5  * All right reserved.
   6  *
   7  * This program is free software; you can redistribute
   8  * it and/or modify it under the terms of the license
   9  * (GNU LGPL) which comes with this package.
  10  */
  11 package org.simgrid.msg;
  12 /**
  13  * Export of RngStreams for Java
  14  */
  15 public class RngStream {
  16         /**
  17          * Represents the bind between the RngStream java object and the C object.
  18          */
  19         private long bind;
  20         /**
  21          * Creates and returns a new stream without identifier.
  22          * This procedure reserves space to keep the information relative to
  23          * the RngStream, initializes its seed Ig , sets Bg and Cg equal to Ig , sets its antithetic and
  24          * precision switches to 0. The seed Ig is equal to the initial seed of the package given by
  25          * setPackageSeed if this is the first stream created, otherwise it is Z steps ahead
  26          * of that of the most recently created stream.
  27          */
  28         public RngStream() {
  29                 create("");
  30         }
  31         /**
  32          * Creates and returns a new stream with identifier "name".
  33          * This procedure reserves space to keep the information relative to
  34          * the RngStream, initializes its seed Ig , sets Bg and Cg equal to Ig , sets its antithetic and
  35          * precision switches to 0. The seed Ig is equal to the initial seed of the package given by
  36          * setPackageSeed if this is the first stream created, otherwise it is Z steps ahead
  37          * of that of the most recently created stream.
  38          */
  39         public RngStream(String name) {
  40                 create(name);
  41         }
  42         /**
  43          * The natively implemented method to create a C RngStream object.
  44          */
  45         private native void create(String name);
  46         /**
  47          * Destructor
  48          */
  49         protected void finalize() {
  50                 destroy();
  51         }
  52         /**
  53          * Release the C RngStream object
  54          */
  55         private native void destroy();
  56
  57         /**
  58          * Sets the initial seed of the package RngStreams to the six integers in the vector seed. This will
  59          * be the seed (initial state) of the first stream. If this procedure is not called, the default initial
  60          * seed is (12345, 12345, 12345, 12345, 12345, 12345). If it is called, the first 3 values of the seed
  61          * must all be less than m1 = 4294967087, and not all 0; and the last 3 values must all be less
  62          * than m2 = 4294944443, and not all 0. Returns false for invalid seeds, and true otherwise.
  63          */
  64         public static native boolean setPackageSeed(int seed[]);
  65         /**
  66          * Reinitializes the stream g to its initial state: Cg and Bg are set to Ig .
  67          */
  68         public native void resetStart();
  69         /**
  70          * Reinitializes the stream g to the beginning of its current substream: Cg is set to Bg .
  71          */
  72         public native void restartStartSubstream();
  73         /**
  74          * Reinitializes the stream g to the beginning of its next substream: Ng is computed, and Cg and
  75          * Bg are set to Ng .
  76          */
  77         public native void resetNextSubstream();
  78         /**
  79          * If a = true the stream g will start generating antithetic variates, i.e., 1 - U instead of U , until
  80          *  this method is called again with a = false.
  81          */
  82         public native void setAntithetic(boolean a);
  83         /**
  84           * Sets the initial seed Ig of stream g to the vector seed. This vector must satisfy the same
  85           * conditions as in setPackageSeed. The stream is then reset to this initial seed. The
  86           * states and seeds of the other streams are not modified. As a result, after calling this procedure,
  87           * the initial seeds of the streams are no longer spaced Z values apart. We discourage the use of
  88           * this procedure. Returns false for invalid seeds, and true otherwise.
  89          */
  90         public native boolean setSeed(int seed[]);
  91         /**
  92           * Advances the state of the stream by k values, without modifying the states of other streams (as
  93           * in RngStream_SetSeed), nor the values of Bg and Ig associated with this stream. If e > 0, then
  94           * k = 2e + c; if e < 0, then k = -2-e + c; and if e = 0, then k = c. Note: c is allowed to take
  95           * negative values. We discourage the use of this procedure.
  96           */
  97         public native void advanceState(int e, int g);
  98
  99         /**
 100          * Returns a (pseudo)random number from the uniform distribution over the interval (0, 1), after advancing the state by one step. The returned number has 32 bits of precision
 101          * in the sense that it is always a multiple of 1/(232 - 208), unless RngStream_IncreasedPrecis
 102          * has been called for this stream.
 103          */
 104         public native double randU01();
 105         /**
 106          * Returns a (pseudo)random number from the discrete uniform distribution over the integers
 107          * {i, i + 1, . . . , j}
 108          */
 109         public native int randInt(int i, int j);
 110
 111         /**
 112          * Class initializer, to initialize various JNI stuff
 113          */
 114         public static native void nativeInit();
 115         static {
 116                 Msg.nativeInit();
 117                 nativeInit();
 118         }
 119 }