added readme

1 files changed, 57 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..4c402d8
--- /dev/null
+++ b/README.md
@@ -0,0 +1,57 @@
+SyncRNG
+=======
+A synchronized Tausworthe RNG usable in R and Python.
+
+
+Why?
+----
+
+This program was created because it was desired to have the same random 
+numbers in both R and Python programs. Although both languages implement a 
+Mersenne-Twister RNG, the implementations are so different that it is not 
+possible to get the same random numbers with the same seed.
+
+SyncRNG is a Tausworthe RNG implemented in `syncrng.c`, and linked to both R 
+and Python. Since both use the same underlying C code, the random numbers will 
+be the same in both languages, provided the same seed is used.
+
+How
+---
+
+In Python, the interface SyncRNG.py can be used as an importable module. In R, 
+it is adviced to simply source the 'SyncRNG.R' file. Before use, make sure to 
+build both shared libraries using:
+
+    make
+
+Then, in a Python script located in the same directory as `syncrng.so` and 
+`pysyncrng.py`, you can do:
+
+    from pysyncrng import SyncRNG
+    
+    s = SyncRNG(seed=123456)
+    for i in range(10):
+	print(s.randi())
+
+Similarly, in an R script located in the same directory as `Rsyncrng.so` and 
+`Rsyncrng.R`, you can do:
+
+    source('./Rsyncrng.R')
+    
+    s = SyncRNG(seed=123456)
+    for (i in 1:10) {
+	cat(s$randi(), '\n')
+    }
+
+You'll notice that the random numbers are indeed the same.
+
+Notes
+-----
+
+Since R is not capable of reliable handling integers larger than `2^32 - 1`, 
+the random numbers are internally capped at this value (using a bitwise and 
+with `0x7FFFFFF`), this influences the quality of the random numbers. The 
+random numbers are no longer uniformly distributed on `[0, 2^32 -1]`. For the 
+intended use of SyncRNG this is not a problem, but it is a compromise worth 
+considering when using SyncRNG. SyncRNG should definitely not be used for any 
+cryptographic purposes.