Logo AND Algorithmique Numérique Distribuée

Public GIT Repository
b1b0c9d2e4ec39749b9831e1237a417d307c2603
[simgrid.git] / org / simgrid / msg / RngStream.java
1 /*
2  * JNI interface to C RngStream code
3  * 
4  * Copyright 2006,2007,2010,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         public 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                 nativeInit();
117         }
118 }