API Details
Random Integer Numbers
Copyright 2016 Scott Michael Doctor
NousMind, NousCrypt, and NousRandom are trademarks of Scott Michael Doctor
Patents Pending
NousMind, NousCrypt, and NousRandom are trademarks of Scott Michael Doctor
Patents Pending
The Random Integer Numbers API sends random integer numbers with resolutions of 8 bits to 52 bits depending on the options selected. Integer numbers are calculated by scaling the floating point random number from the generator, then rounding to the nearest integer.
A note about rounding. The most common technique for rounding is to round up if the fractional value is greater or equal to 0.5. Doing such causes a non-uniform distribution of the integers, especially the boundary numbers. This process uses a custom rounding algorithm.
An integer segment is defined as: abs(max-min) / (abs(max-min)+1)
The API rounds a scaled value by finding which segment a value is greater or equal to, but less than the next higher segment. A complete discussion of this topic is on the Theory & Statistics page.
The following are the API commands for this process:
int -- This is the process ID. Each process has an ID to tell the API what to generate. int specifies that you want random integer numbers.
min=n -- Sets the minimum value for scaling the numbers. Default: -1.0
n is any number specified by an integer, floating point decimal, or scientific notation number. min and max cannot be equal. You must set a value for max if setting a value for min.
(max-min) must be equal or greater than 1. Note that although n may be a floating point value, only its integer value is used. The number is not rounded. The fractional part is truncated. For example, if n is set to 4.9, then min will be assigned the value 4.
max=n -- Sets the maximum value for scaling the numbers. Default: 1.0
n is any number specified by an integer, floating point decimal, or scientific notation number. min and max cannot be equal.
(max-min) must be equal or greater than 1. Note that although n may be a floating point value, only its integer value is used. The number is not rounded. The fractional part is truncated. For example, if n is set to 4.9, then max will be assigned the value 4.
If you set max without setting min, the scaling will be set to +/- the value of max. For example, if max=3 without specifying a value for min, then min will be set by the API to -3.
The value of max should be the greater than the value of min. However, the API always checks both values and if it finds that max is less than min, then the API will swap their values.
cnt=d -- Sets the total count of numbers to send. Default: 1
d is a positive integer greater than zero. A negative value for d returns an error. The value of d can be a floating point number. However, only the integer value of the number is used. For example, a value of 4.9 will set the value of cnt to 4. The API does not round the value, simply truncates the fractional part. The maximum count of numbers per request is 1,048,576 which is 2^20.
Note that cnt is the Total count of numbers. For example, if you want 20 rows of numbers with 4 columns of numbers in each row, that is a total of 80 numbers, so you would set cnt=80.
Note that if using one of the hex commands, The cnt command does not represent total number of bytes, but the total count of numbers that have the selected resolution. For example, the hex32 command will use a 4 byte resolution. Assume we want 10 numbers by setting cnt=10. Since each number has 4 bytes, the total number of bytes will be 40 (10 numbers at 4 bytes each).
cols=d -- Sets the number of columns per row. Default: 1
d is a positive integer greater or equal to zero. A negative value for d returns an error. The value of d can be a floating point number. However, only the integer value of the number is used. For example, a value of 4.9 will set the value of cols to 4. The API does not round the value, simply truncates the fractional part.
If cols is set to 0, then all of the numbers will be sent in a single line.
If cols is greater than the value of cnt, then cols is set by the API to the value of cnt.
The following hex commands will return values as hexadecimal base 16 numbers instead of decimal integers. The default without using one of the hex options is to send the numbers as base 10 integers. Each two letter pair of hexadecimal text represents a byte. So a four byte resolution number is represented by eight hexadecimal letters.
hex8 -- one byte scaled 0 to 255
hex16 -- two byte scaled 0 to 65535
hex24 -- three byte scaled 0 to 16777215
hex32 -- four byte scaled 0 to 4294967295
hex40 -- five byte scaled 0 to 1099511627775
hex48 -- six byte scaled 0 to 281474976710655
Since the API sets the scaling for the hex commands, the values of min and max are ignored when one of these options are used.
The following are common formatting options. Full details are on the Results Formatting page.
nohtml -- disables sending HTML tags. The tags are used for proper display in a web browser. HTML tags are not used if the numbers are sent as a text file.
astextfile -- Send the numbers as a text file. If the total count of numbers sent exceeds 16384, then the numbers will always be sent as a file.
asbinaryfile -- Send the numbers as a flattened binary file. The API converts each number into the resolution number of binary encoded bytes as read left to right. For example, if using hex32, the first byte of the file is the left most hex pair of its text representation. Binary files do not use any formatting.
csv -- Separate columns of numbers with a single space character.
csvq -- Same as csv with each number surrounded by the double quote character.
json -- Sends the numbers as a JSON array. See the Results Formatting page for details.
jsonq -- Same as json with each number surrounded by the double quote character.
A note about rounding. The most common technique for rounding is to round up if the fractional value is greater or equal to 0.5. Doing such causes a non-uniform distribution of the integers, especially the boundary numbers. This process uses a custom rounding algorithm.
An integer segment is defined as: abs(max-min) / (abs(max-min)+1)
The API rounds a scaled value by finding which segment a value is greater or equal to, but less than the next higher segment. A complete discussion of this topic is on the Theory & Statistics page.
The following are the API commands for this process:
int -- This is the process ID. Each process has an ID to tell the API what to generate. int specifies that you want random integer numbers.
min=n -- Sets the minimum value for scaling the numbers. Default: -1.0
n is any number specified by an integer, floating point decimal, or scientific notation number. min and max cannot be equal. You must set a value for max if setting a value for min.
(max-min) must be equal or greater than 1. Note that although n may be a floating point value, only its integer value is used. The number is not rounded. The fractional part is truncated. For example, if n is set to 4.9, then min will be assigned the value 4.
max=n -- Sets the maximum value for scaling the numbers. Default: 1.0
n is any number specified by an integer, floating point decimal, or scientific notation number. min and max cannot be equal.
(max-min) must be equal or greater than 1. Note that although n may be a floating point value, only its integer value is used. The number is not rounded. The fractional part is truncated. For example, if n is set to 4.9, then max will be assigned the value 4.
If you set max without setting min, the scaling will be set to +/- the value of max. For example, if max=3 without specifying a value for min, then min will be set by the API to -3.
The value of max should be the greater than the value of min. However, the API always checks both values and if it finds that max is less than min, then the API will swap their values.
cnt=d -- Sets the total count of numbers to send. Default: 1
d is a positive integer greater than zero. A negative value for d returns an error. The value of d can be a floating point number. However, only the integer value of the number is used. For example, a value of 4.9 will set the value of cnt to 4. The API does not round the value, simply truncates the fractional part. The maximum count of numbers per request is 1,048,576 which is 2^20.
Note that cnt is the Total count of numbers. For example, if you want 20 rows of numbers with 4 columns of numbers in each row, that is a total of 80 numbers, so you would set cnt=80.
Note that if using one of the hex commands, The cnt command does not represent total number of bytes, but the total count of numbers that have the selected resolution. For example, the hex32 command will use a 4 byte resolution. Assume we want 10 numbers by setting cnt=10. Since each number has 4 bytes, the total number of bytes will be 40 (10 numbers at 4 bytes each).
cols=d -- Sets the number of columns per row. Default: 1
d is a positive integer greater or equal to zero. A negative value for d returns an error. The value of d can be a floating point number. However, only the integer value of the number is used. For example, a value of 4.9 will set the value of cols to 4. The API does not round the value, simply truncates the fractional part.
If cols is set to 0, then all of the numbers will be sent in a single line.
If cols is greater than the value of cnt, then cols is set by the API to the value of cnt.
The following hex commands will return values as hexadecimal base 16 numbers instead of decimal integers. The default without using one of the hex options is to send the numbers as base 10 integers. Each two letter pair of hexadecimal text represents a byte. So a four byte resolution number is represented by eight hexadecimal letters.
hex8 -- one byte scaled 0 to 255
hex16 -- two byte scaled 0 to 65535
hex24 -- three byte scaled 0 to 16777215
hex32 -- four byte scaled 0 to 4294967295
hex40 -- five byte scaled 0 to 1099511627775
hex48 -- six byte scaled 0 to 281474976710655
Since the API sets the scaling for the hex commands, the values of min and max are ignored when one of these options are used.
The following are common formatting options. Full details are on the Results Formatting page.
nohtml -- disables sending HTML tags. The tags are used for proper display in a web browser. HTML tags are not used if the numbers are sent as a text file.
astextfile -- Send the numbers as a text file. If the total count of numbers sent exceeds 16384, then the numbers will always be sent as a file.
asbinaryfile -- Send the numbers as a flattened binary file. The API converts each number into the resolution number of binary encoded bytes as read left to right. For example, if using hex32, the first byte of the file is the left most hex pair of its text representation. Binary files do not use any formatting.
csv -- Separate columns of numbers with a single space character.
csvq -- Same as csv with each number surrounded by the double quote character.
json -- Sends the numbers as a JSON array. See the Results Formatting page for details.
jsonq -- Same as json with each number surrounded by the double quote character.