src/bindings/java/org/simgrid/msg/RngStream.java

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