0
# Random Number Generators
1

2
Pure Rand provides four high-quality pseudorandom number generators, each with different performance characteristics and statistical properties. All generators implement the `RandomGenerator` interface and support both pure (immutable) and unsafe (mutable) operations.
3

4
## Capabilities
5

6
### Xoroshiro128+
7

8
The recommended high-quality, very fast generator with excellent statistical properties. Supports jump functionality for independent subsequences.
9

10
```typescript { .api }
11
/**
12
 * Create a Xoroshiro128+ pseudorandom number generator
13
 * @param seed - 32-bit seed value for initialization
14
 * @returns RandomGenerator instance
15
 */
16
function xoroshiro128plus(seed: number): RandomGenerator;
17

18
/** 
19
 * Create a Xoroshiro128+ generator from existing state
20
 * @param state - Previously exported state array
21
 * @returns RandomGenerator instance
22
 */
23
xoroshiro128plus.fromState(state: readonly number[]): RandomGenerator;
24
```
25

26
**Usage Examples:**
27

28
```typescript
29
import { xoroshiro128plus } from 'pure-rand';
30

31
// Create generator with seed
32
const rng = xoroshiro128plus(42);
33

34
// Generate value (pure)
35
const [value, nextRng] = rng.next();
36

37
// Generate value (unsafe)
38
const value2 = rng.unsafeNext();
39

40
// Jump for independent subsequence (2^64 generations ahead)
41
const independentRng = rng.jump();
42

43
// Export and restore state
44
const state = rng.getState();
45
const restoredRng = xoroshiro128plus.fromState(state);
46
```
47

48
### XorShift128+
49

50
Fast generator with good statistical properties and jump functionality for independent subsequences.
51

52
```typescript { .api }
53
/**
54
 * Create a XorShift128+ pseudorandom number generator with parameters a=23, b=18, c=5
55
 * @param seed - 32-bit seed value for initialization
56
 * @returns RandomGenerator instance
57
 */
58
function xorshift128plus(seed: number): RandomGenerator;
59

60
/** 
61
 * Create a XorShift128+ generator from existing state
62
 * @param state - Previously exported state array
63
 * @returns RandomGenerator instance
64
 */
65
xorshift128plus.fromState(state: readonly number[]): RandomGenerator;
66
```
67

68
**Usage Examples:**
69

70
```typescript
71
import { xorshift128plus } from 'pure-rand';
72

73
// Create generator with seed
74
const rng = xorshift128plus(12345);
75

76
// Generate multiple values
77
const [values, finalRng] = generateN(rng, 5);
78

79
// Jump for parallel simulations
80
const parallelRng = rng.jump();
81
```
82

83
### Mersenne Twister
84

85
Well-known, extensively tested generator with a very long period (2^19937-1). Suitable when statistical quality is paramount.
86

87
```typescript { .api }
88
/**
89
 * Create a Mersenne Twister MT19937 pseudorandom number generator
90
 * @param seed - 32-bit seed value for initialization
91
 * @returns RandomGenerator instance
92
 */
93
function mersenne(seed: number): RandomGenerator;
94

95
/** 
96
 * Create a Mersenne Twister generator from existing state
97
 * @param state - Previously exported state array
98
 * @returns RandomGenerator instance
99
 */
100
mersenne.fromState(state: readonly number[]): RandomGenerator;
101
```
102

103
**Usage Examples:**
104

105
```typescript
106
import { mersenne } from 'pure-rand';
107

108
// Create generator with seed
109
const rng = mersenne(98765);
110

111
// Clone for separate usage
112
const clonedRng = rng.clone();
113

114
// Access internal state
115
const state = rng.getState();
116
const reconstructed = mersenne.fromState(state);
117
```
118

119
### Linear Congruential Generator
120

121
Simple, fast generator based on Java's implementation. Suitable for applications where speed is more important than statistical quality.
122

123
```typescript { .api }
124
/**
125
 * Create a Linear Congruential Generator based on Java's implementation
126
 * @param seed - 32-bit seed value for initialization
127
 * @returns RandomGenerator instance
128
 */
129
function congruential32(seed: number): RandomGenerator;
130

131
/** 
132
 * Create a Linear Congruential generator from existing state
133
 * @param state - Previously exported state array
134
 * @returns RandomGenerator instance
135
 */
136
congruential32.fromState(state: readonly number[]): RandomGenerator;
137
```
138

139
**Usage Examples:**
140

141
```typescript
142
import { congruential32 } from 'pure-rand';
143

144
// Create generator with seed
145
const rng = congruential32(1);
146

147
// Simple value generation
148
const value = rng.unsafeNext();
149

150
// State management
151
const state = rng.getState();
152
const newRng = congruential32.fromState(state);
153
```
154

155
## Generator Selection Guide
156

157
- **Xoroshiro128+**: Best overall choice for most applications - high quality, very fast, supports jumps
158
- **XorShift128+**: Good alternative with jump support, slightly different statistical properties
159
- **Mersenne Twister**: When maximum statistical quality is required, traditional choice for simulations
160
- **Linear Congruential**: When maximum speed is needed and statistical quality is less critical
161

162
## Jump Functionality
163

164
Only Xoroshiro128+ and XorShift128+ support jump operations, which move the generator 2^64 positions ahead in the sequence. This enables creation of independent subsequences for parallel simulations.
165

166
```typescript
167
// Create independent generators for parallel work
168
const mainRng = xoroshiro128plus(42);
169
const worker1Rng = mainRng.jump();
170
const worker2Rng = worker1Rng.jump();
171
const worker3Rng = worker2Rng.jump();
172

173
// Each worker can generate values independently
174
// without overlap in their sequences
175
```
176

177
## State Management
178

179
All generators support state export and reconstruction:
180

181
```typescript
182
// Export state
183
const currentState = rng.getState();
184

185
// Later, reconstruct exact same generator
186
const restoredRng = xoroshiro128plus.fromState(currentState);
187

188
// Restored generator will produce identical sequences
189
```
190

191
This enables:
192
- Saving/loading generator state for reproducibility
193
- Checkpointing in long-running simulations
194
- Distributed computing with synchronized randomness