1 package nl.tudelft.simulation.jstats.streams;
2
3 import java.io.Serializable;
4
5 /**
6 * The StreamInterface defines the streams to be used within the JSTATS package. Potential implementations include the pseudo
7 * random stream, the fully one-time random stream, etc.
8 * <p>
9 * Copyright (c) 2002-2024 Delft University of Technology, Jaffalaan 5, 2628 BX Delft, the Netherlands. All rights reserved. See
10 * for project information <a href="https://simulation.tudelft.nl/" target="_blank"> https://simulation.tudelft.nl</a>. The DSOL
11 * project is distributed under a three-clause BSD-style license, which can be found at
12 * <a href="https://https://simulation.tudelft.nl/dsol/docs/latest/license.html" target="_blank">
13 * https://https://simulation.tudelft.nl/dsol/docs/latest/license.html</a>.
14 * </p>
15 * @author <a href="https://www.tudelft.nl/averbraeck" target="_blank"> Alexander Verbraeck</a>
16 * @author <a href="https://www.linkedin.com/in/peterhmjacobs">Peter Jacobs </a>
17 */
18 public interface StreamInterface extends Serializable
19 {
20 /**
21 * Return the next pseudo-random, uniformly distributed boolean value.
22 * @return boolean; a pseudo-random boolean with 50/50 chance for true or false
23 */
24 boolean nextBoolean();
25
26 /**
27 * Return a pseudo-random number from the stream over the interval (0,1) using this stream, after advancing its
28 * state by one step.
29 * @return double; the pseudo-random number
30 */
31 double nextDouble();
32
33 /**
34 * Return a pseudo-random number from the stream over the interval (0,1) using this stream, after advancing its
35 * state by one step.
36 * @return float; the pseudo-random number
37 */
38 float nextFloat();
39
40 /**
41 * Return a pseudo-random number from the stream over using this stream, after advancing its state by one step.
42 * @return int; the pseudo-random number
43 */
44 int nextInt();
45
46 /**
47 * Return pseudo-random number from the stream between the integers i (inclusive) and j (inclusive).
48 * @param i int; the minimal value
49 * @param j int; the maximum value
50 * @return int; a value between i and j
51 */
52 int nextInt(int i, int j);
53
54 /**
55 * Return a pseudo-random number from the stream over using this stream, after advancing its state by one step.
56 * @return long; the pseudo-random number
57 */
58 long nextLong();
59
60 /**
61 * Return the seed of the generator.
62 * @return long; the seed
63 */
64 long getSeed();
65
66 /**
67 * Return the original seed of the generator with which it has been first initialized.
68 * @return long; the original seed of the generator when it was first initialized
69 */
70 long getOriginalSeed();
71
72 /**
73 * Set the seed of the generator.
74 * @param seed long; the new seed
75 */
76 void setSeed(long seed);
77
78 /**
79 * Reset the stream to use the original seed with which it was initialized.
80 */
81 void reset();
82
83 /**
84 * Save the state of the RNG into an object, e.g. to roll it back to this state.
85 * @return the state as an object specific to the RNG.
86 * @throws StreamException when getting the state fails.
87 */
88 byte[] saveState() throws StreamException;
89
90 /**
91 * Restore the state to an earlier saved state object.
92 * @param state Object; the earlier saved state to which the RNG rolls back.
93 * @throws StreamException when resetting the state fails.
94 */
95 void restoreState(byte[] state) throws StreamException;
96 }