Skip to content

Latest commit

 

History

History

doc

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
README.md
README.md
 
 

README.md

  • All variables of struct mt19937_32_t (32-bit MT19937) and struct mt19937_64_t (64-bit MT19937) objects should be considered private.
  • The last argument of each of the below functions is mt, which denotes the 32- or 64-bit MT19937 object to use.
    • If it is NULL, the internal 32- or 64-bit MT19937 object is used.
    • For instance, mt19937_rand32(NULL) and mt19937_rand32(foo) are both valid invocations of mt19937_rand32—the former generates a pseudorandom number using the internal 32-bit MT19937 object, and the latter does so using foo.
    • The internal 32- and 64-bit MT19937 objects are initialised by default as if they were seeded with 5489. As a result, the sequences of numbers generated by them (when not seeded manually) are identical to those generated by default-constructed std::mt19937 and std::mt19937_64 objects of the C++ standard library.
  • Whenever a function has a C++ API, an objected-oriented interface is also available.
    • Default-constructed 32- and 64-bit MT19937 objects in C++ are also seeded with 5489.
  • Whenever a function has a Python API, there is no option to specify the mt argument. In other words, all Python functions use the internal MT19937 objects. The CPython implementation has a global interpreter lock, and (looking at the Python bytecode disassembly) a C function call corresponds to a single Python bytecode instruction. Hence, there are no race conditions to worry about, and the provided functions are thread-safe.
    • The Python API functions are given names similar to those below. Nevertheless, you can see a summary by entering import mt19937 and then help(mt19937) at the Python REPL.
    • It is possible for a Python integer to not be exactly representable as a C integer. To mitigate this, appropriate range checks are automatically done on all Python integers.
uint32_t mt19937_seed32(uint32_t seed, struct mt19937_32_t *mt);

Seed 32-bit MT19937.

  • seed 32-bit number.
  • mt MT19937 object to seed. If NULL, the internal 32-bit MT19937 object is seeded.
  • → The value used for seeding (seed).
C C++ Equivalent Python Equivalent
mt19937_seed32(seed, NULL) mt19937::seed32(seed) mt19937.seed32(seed)
mt19937_seed32(seed, &bar) bar.seed32(seed)

In C++, you can also seed an MT19937 object in this manner by passing the value to its constructor: mt19937_32_t bar(seed). As mentioned earlier, the default value of seed is 5489.

uint64_t mt19937_seed64(uint64_t seed, struct mt19937_64_t *mt);

Seed 64-bit MT19937.

  • seed 64-bit number.
  • mt MT19937 object to seed. If NULL, the internal 64-bit MT19937 object is seeded.
  • → The value used for seeding (seed).
C C++ Equivalent Python Equivalent
mt19937_seed64(seed, NULL) mt19937::seed64(seed) mt19937.seed64(seed)
mt19937_seed64(seed, &bar) bar.seed64(seed)

In C++, you can also seed an MT19937 object in this manner by passing the value to its constructor: mt19937_64_t bar(seed). As mentioned earlier, the default value of seed is 5489.

uint32_t mt19937_init32(struct mt19937_32_t *mt);

Seed 32-bit MT19937 with a value generated in an unspecified manner at run-time.

  • mt MT19937 object to seed. If NULL, the internal 32-bit MT19937 object is seeded.
  • → The value used for seeding.
C C++ Equivalent Python Equivalent
mt19937_init32(NULL) mt19937::init32() mt19937.init32()
mt19937_init32(&bar) bar.init32()

In C++, you can also seed an MT19937 object in this manner by passing nullptr to its constructor: mt19937_32_t bar(nullptr).

uint64_t mt19937_init64(struct mt19937_64_t *mt);

Seed 64-bit MT19937 with a value generated in an unspecified manner at run-time.

  • mt MT19937 object to seed. If NULL, the internal 64-bit MT19937 object is seeded.
  • → The value used for seeding.
C C++ Equivalent Python Equivalent
mt19937_init64(NULL) mt19937::init64() mt19937.init64()
mt19937_init64(&bar) bar.init64()

In C++, you can also seed an MT19937 object in this manner by passing nullptr to its constructor: mt19937_64_t bar(nullptr).

Implementation Details

If the C compiler you are using supports threads (both GCC and Clang do), calling mt19937_init32 in different threads of the same process will likely generate different seeds provided that those threads were simultaneously alive at some point in time. However, with most POSIX-conforming compilers, calling mt19937_init32 twice in the same thread in the space of one second will probably generate the same seed. Likewise for mt19937_init64.

uint32_t mt19937_rand32(struct mt19937_32_t *mt);

Generate a pseudorandom number.

  • mt MT19937 object to use. If NULL, the internal 32-bit MT19937 object is used.
  • → Uniform pseudorandom 32-bit number.
C C++ Equivalent Python Equivalent
mt19937_rand32(NULL) mt19937::rand32() mt19937.rand32()
mt19937_rand32(&bar) bar.rand32() 
uint64_t mt19937_rand64(struct mt19937_64_t *mt);

Generate a pseudorandom number.

  • mt MT19937 object to use. If NULL, the internal 64-bit MT19937 object is used.
  • → Uniform pseudorandom 64-bit number.
C C++ Equivalent Python Equivalent
mt19937_rand64(NULL) mt19937::rand64() mt19937.rand64()
mt19937_rand64(&bar) bar.rand64() 
uint32_t mt19937_uint32(uint32_t modulus, struct mt19937_32_t *mt);

Generate a pseudorandom residue.

  • modulus 32-bit number. Must not be 0.
  • mt MT19937 object to use. If NULL, the internal 32-bit MT19937 object is used.
  • → Uniform pseudorandom 32-bit number from 0 (inclusive) to modulus (exclusive).
C C++ Equivalent Python Equivalent
mt19937_uint32(modulus, NULL) mt19937::uint32(modulus) mt19937.uint32(modulus)
mt19937_uint32(modulus, &bar) bar.uint32(modulus) 
uint64_t mt19937_uint64(uint64_t modulus, struct mt19937_64_t *mt);

Generate a pseudorandom residue.

  • modulus 64-bit number. Must not be 0.
  • mt MT19937 object to use. If NULL, the internal 64-bit MT19937 object is used.
  • → Uniform pseudorandom 64-bit number from 0 (inclusive) to modulus (exclusive).
C C++ Equivalent Python Equivalent
mt19937_uint64(modulus, NULL) mt19937::uint64(modulus) mt19937.uint64(modulus)
mt19937_uint64(modulus, &bar) bar.uint64(modulus) 
int32_t mt19937_span32(int32_t left, int32_t right, struct mt19937_32_t *mt);

Generate a pseudorandom residue offset.

  • left 32-bit number.
  • right 32-bit number. Must be greater than left.
  • mt MT19937 object to use. If NULL, the internal 32-bit MT19937 object is used.
  • → Uniform pseudorandom 32-bit number from left (inclusive) to right (exclusive).
C C++ Equivalent Python Equivalent
mt19937_span32(left, right, NULL) mt19937::span32(left, right) mt19937.span32(left, right)
mt19937_span32(left, right, &bar) bar.span32(left, right) 
int64_t mt19937_span64(int64_t left, int64_t right, struct mt19937_64_t *mt);

Generate a pseudorandom residue offset.

  • left 64-bit number.
  • right 64-bit number. Must be greater than left.
  • mt MT19937 object to use. If NULL, the internal 64-bit MT19937 object is used.
  • → Uniform pseudorandom 64-bit number from left (inclusive) to right (exclusive).
C C++ Equivalent Python Equivalent
mt19937_span64(left, right, NULL) mt19937::span64(left, right) mt19937.span64(left, right)
mt19937_span64(left, right, &bar) bar.span64(left, right) 
double mt19937_real32(struct mt19937_32_t *mt);

Generate a pseudorandom fraction.

  • mt MT19937 object to use. If NULL, the internal 32-bit MT19937 object is used.
  • → Uniform pseudorandom number from 0 (inclusive) to 1 (inclusive).
C C++ Equivalent Python Equivalent
mt19937_real32(NULL) mt19937::real32() mt19937.real32()
mt19937_real32(&bar) bar.real32() 
double long mt19937_real64(struct mt19937_64_t *mt);

Generate a pseudorandom fraction.

  • mt MT19937 object to use. If NULL, the internal 64-bit MT19937 object is used.
  • → Uniform pseudorandom number from 0 (inclusive) to 1 (inclusive).
C C++ Equivalent Python Equivalent
mt19937_real64(NULL) mt19937::real64() mt19937.real64()
mt19937_real64(&bar) bar.real64() 
void mt19937_shuf32(void *items, uint32_t num_of_items, size_t size_of_item, struct mt19937_32_t *mt);

Pseudorandomly shuffle an array in place.

  • items Array to shuffle.
  • num_of_items Number of elements in the array. Must not be 0.
  • size_of_item Size of each element of the array in bytes.
  • mt MT19937 object to use. If NULL, the internal 32-bit MT19937 object is used.
C C++ Equivalent Python Equivalent
mt19937_shuf32(items, num_of_items, size_of_item, NULL) mt19937::shuf32(items, num_of_items, size_of_item)
mt19937_shuf32(items, num_of_items, size_of_item, &bar) bar.shuf32(items, num_of_items, size_of_item) 
void mt19937_shuf64(void *items, uint64_t num_of_items, size_t size_of_item, struct mt19937_64_t *mt);

Pseudorandomly shuffle an array in place. This function is provided only for completeness. In almost all cases, the previous function should be used.

  • items Array to shuffle.
  • num_of_items Number of elements in the array. Must not be 0.
  • size_of_item Size of each element of the array in bytes.
  • mt MT19937 object to use. If NULL, the internal 64-bit MT19937 object is used.
C C++ Equivalent Python Equivalent
mt19937_shuf64(items, num_of_items, size_of_item, NULL) mt19937::shuf64(items, num_of_items, size_of_item)
mt19937_shuf64(items, num_of_items, size_of_item, &bar) bar.shuf64(items, num_of_items, size_of_item) 
void mt19937_drop32(int long long count, struct mt19937_32_t *mt);

Mutate 32-bit MT19937 by advancing its internal state. Equivalent to running mt19937_rand32(mt) count times and discarding the results.

  • count Number of steps to advance the state by. If not positive, this function has no effect.
  • mt MT19937 object to mutate. If NULL, the internal 32-bit MT19937 object is mutated.
C C++ Equivalent Python Equivalent
mt19937_drop32(count, NULL) mt19937::drop32(count) mt19937.drop32(count)
mt19937_drop32(count, &bar) bar.drop32(count) 
void mt19937_drop64(int long long count, struct mt19937_64_t *mt);

Mutate 64-bit MT19937 by advancing its internal state. Equivalent to running mt19937_rand64(mt) count times and discarding the results.

  • count Number of steps to advance the state by. If not positive, this function has no effect.
  • mt MT19937 object to mutate. If NULL, the internal 64-bit MT19937 object is mutated.
C C++ Equivalent Python Equivalent
mt19937_drop64(count, NULL) mt19937::drop64(count) mt19937.drop64(count)
mt19937_drop64(count, &bar) bar.drop64(count)