RandomNumber wrapper in Lua

Question

This is a wrapper I wrote for math.random(). I have a larger program that will create a JSON file to 'load' from when I want to resume. However my program heavily used math.random() which made it hard to debug and test the program because different results would occur depending on if the program was started fresh, or from a load file.

This wrapper lets you "resume" from a random seed.

RandomNumber.lua

--[[
    RandomNumber - Lua Class for Generating and Managing Random Numbers

    The RandomNumber class is designed to facilitate the generation of random numbers
    using Lua's built-in math.random function. It includes features for tracking the
    number of generated random numbers and the ability to 'jump' to a specific iteration.
    This functionality is particularly useful for debugging and testing. Example if
    a program is to save its state and 'resume' and we want numbers generated to not
    reset,

    Usage:
    local rng = RandomNumber:new(seed)       -- Instantiate class, 'seed' is optional but suggested
    rng:jumpToIteration(10)                  -- Jump to the 10th iteration. Next generate() method will be the 11th
    rng:generate()                           -- generate a random number
--]]
---@class RandomNumber
local RandomNumber = {}

-- Wrapper for math.random() in case we want to change in the future
local function generateRandomNumber(a, b)
    if a and b then
        return math.random(a, b)
    elseif a then
        return math.random(a)
    end

    return math.random()
end

---@return RandomNumber
function RandomNumber:new(seed)
    ---@type RandomNumber
    local randomNumber = {}
    self = self or randomNumber
    self.__index = self
    setmetatable(randomNumber, self)

    randomNumber.count = 0

    if seed then
        math.randomseed(seed)
        randomNumber.seed = seed
    end

    return randomNumber
end

-- Reset the RandomNumber object with a new seed.
---@param seed number
function RandomNumber:reset(seed)
    math.randomseed(seed)
    self.count = 0
    self.seed = seed
end

function RandomNumber:generate(a, b)
    self.count = self.count + 1
    return generateRandomNumber(a, b)
end

-- Jumps to a point in the random number sequence.
-- Warning: Will produce new random seed if no seed was ever given
---@param iteration number
function RandomNumber:jumpToIteration(iteration)
    if type(iteration) ~= "number" or iteration < 0 then
        error("Invalid argument, expected a number 0 or greater: " .. iteration)
    end
    local difference = iteration - self.count

    if difference > 0 then
        for _ = 1, difference do
            generateRandomNumber()
        end
    elseif difference < 0 then
        self = RandomNumber:new(self.seed)
        self:jumpToIteration(iteration)
    end

    self.count = iteration
end

return RandomNumber

RandomNumberTest.lua:

-- Import LuaUnit module
local lu = require('luaunit')

-- Import the RandomNumber class
local RandomNumber = require('RandomNumber')

-- Test the RandomNumber class
TestRandomNumber = {}

---@class RandomNumber
local rng
local firstNumberInSeq = '0.23145237586596'
local secondNumberInSeq = '0.58485671559801'
local hundredthNumberInSeq = '0.43037202063051'

function TestRandomNumber:setUp()
    -- Set a fixed seed value for reproducibility in tests
    rng = RandomNumber:new(12345)
end

-- Function to round a number to a specified decimal place
local function round(num, numDecimalPlaces)
    local mult = 10^(numDecimalPlaces or 0)
    return math.floor(num * mult + 0.5) / mult
end

function TestRandomNumber:testGenerate()
    -- use tostring method, otherwise the comparison fails between floats
    -- Numbers are based on math.random(), given seed 12345
    lu.assertEquals(tostring(rng:generate()), firstNumberInSeq)
    lu.assertEquals(tostring(rng:generate()), secondNumberInSeq)
end

function TestRandomNumber:testJump()
    rng:jumpToIteration(99)

    lu.assertEquals(tostring(rng:generate()), hundredthNumberInSeq)
end

function TestRandomNumber:testGenerateAndJump()
    for _=1, 50 do
        rng:generate()
    end

    rng:jumpToIteration(99)

    lu.assertEquals(tostring(rng:generate()), hundredthNumberInSeq)
end

function TestRandomNumber:testJumpBackwards()
    for _=1, 50 do
        rng:generate()
    end

    rng:jumpToIteration(1)

    lu.assertEquals(tostring(rng:generate()), secondNumberInSeq)
end

function TestRandomNumber:testJumpZero()
    for _=1, 99 do
        rng:generate()
    end

    -- jump to the iteration 0
    rng:jumpToIteration(0)

    -- Should be 1st
    lu.assertEquals(tostring(rng:generate()), firstNumberInSeq)
end

function TestRandomNumber:testJumpToSameSpot()
    for _=1, 99 do
        rng:generate()
    end

    rng:jumpToIteration(99)

    lu.assertEquals(tostring(rng:generate()), hundredthNumberInSeq)
end

function TestRandomNumber:testReset()
    rng:generate()
    rng:jumpToIteration(105)
    rng:reset(12345)

    lu.assertEquals(tostring(rng:generate()), firstNumberInSeq)
    lu.assertEquals(tostring(rng:generate()), secondNumberInSeq)
end

function TestRandomNumber:testJumpToIterationInvalidArgumentNegative()
    -- Use pcall to catch the error
    local success, errorMessage = pcall(function()
        rng:jumpToIteration(-1)
    end)

    -- Check that pcall was not successful (error was thrown)
    lu.assertFalse(success)

    -- Check that the error message is as expected
    lu.assertStrContains(errorMessage, "Invalid argument")
end

function TestRandomNumber:testJumpToIterationInvalidArgumentNaN()
    -- Use pcall to catch the error
    local success, errorMessage = pcall(function()
        rng:jumpToIteration('11')
    end)

    -- Check that pcall was not successful (error was thrown)
    lu.assertFalse(success)

    -- Check that the error message is as expected
    lu.assertStrContains(errorMessage, "Invalid argument")
end

function TestRandomNumber:testJumpToIterationNilSeed()
    local rngTarget = RandomNumber:new()
    lu.assertNil(rngTarget.seed)

    rngTarget:generate()
    rngTarget:generate()

    rngTarget:jumpToIteration(0)
    lu.assertNil(rngTarget.seed)

    rngTarget:generate()
    rngTarget:generate()
end

function TestRandomNumber:testJumpToIterationWithSeed()
    local rngTarget = RandomNumber:new(1550)
    lu.assertEquals(1550, rngTarget.seed)

    local firstValue = rngTarget:generate()
    local secondValue = rngTarget:generate()

    rngTarget:jumpToIteration(0)
    lu.assertEquals(1550, rngTarget.seed)

    local newValue1 = rngTarget:generate()
    local newValue2 = rngTarget:generate()

    lu.assertEquals(firstValue, newValue1)
    lu.assertEquals(secondValue, newValue2)
end

-- Run the tests
os.exit(lu.LuaUnit.run())

random-number-1.0.0-2.rockspec (Included in case suggestions can be made to it)

package = "random-number"
version = "1.0.0-2"
source = {
   url = "git://github.com/LionelBergen/RandomNumber",
   tag = "master",
}
description = {
   summary = "RandomNumber generator and manager.",
   detailed = [[
      This is a wrapper for Lua's builtin math.random. Purpose is for debugging & testing applications
      that use random numbers. Having numbers be reproduced the same way makes for easier testing & debugging
   ]],
   homepage = "https://github.com/LionelBergen/RandomNumber",
}
dependencies = {
    "lua >= 5.1",
}
build = {
    ["type"] = "builtin",
    modules = {
        randomnumber = "RandomNumber.lua"
    }
}

Answer 1

The main issue: side effects

The main issue is that you are using a random which there is only a single seed, shared between any code running on the platform. This is a questionable design by Lua (and many other runtimes) to start with, but it does mean that the state of your program may be influenced by calls to math.random() or math.randomseed(x) that simply skip your wrapper.

Moreover, the calls to randomseed(x) may influence other parts that rely on the random number generator, leading to weird interactions between code that does use the wrapper and code that doesn't. In other words, your code has significant side effects on the state of the runtime.

One way would be to implement a RNG yourself, preferably the same one that Lua uses at the moment. In that case the results from your RandomNumber and math.random() are decoupled.

Implementation code

RandomNumber - Lua Class for Generating and Managing Random Numbers

Just the name RandomNumber nor the first line clearly shows what the class can be used for. A more clear name should be considered, such as RepeatableRandomNumber.

---

function RandomNumber:jumpToIteration(iteration)

It is unclear how the user would be able to know the iteration, as calls to any code may increase the iteration. Furthermore, this code may skip your interesting wrapper entirely.

It would be a good idea to at least to be able to retrieve the count that is kept so that the user can retrieve the iteration before or after retrieving a random at a specific point.

---

function RandomNumber:generate(a, b)
local function generateRandomNumber(a, b)

I'm wondering why the parameter names are called a and b while they are called m and n in the Lua documentation of math.random. That just makes things harder to understand.

Similarly, I'm not sure why there would be a count which counts the iterations. It might as well be called iteration in my opinion, so that there is just one term to deal with.

---

Missing documentation of:

function RandomNumber:generate(a, b)

The documentation of this method is missing. It should indicate that the iteration count is increased, and it should both summarize and reference the documentation for math.random. This is the main function of the library and although it may be clear to you what the function does, it should at least greet any other user with easy to understand documentation.

Test code

Beware that the Lua documentation doesn't seem to explicitly indicate a specific RNG implementation, just saying that "This function is an interface to the underling pseudo-random generator function provided by C." which is extremely loose. That also means that storing expected values within floating point in the test code is dangerous, as any change in the underlying implementation will result in different values being generated.

In general these kind of pseudo number generators will produce specific ranges of random numbers as long as the runtime implementation implements the same algorithms.

---

local function round(num, numDecimalPlaces)

This is an unused function. I'm not sure why it would be in the test code. There is no need to test the correctness of the random numbers if this is just a wrapper; I'd just test if the minimum and maximum values can indeed be returned (obviously from a small range).

---

lu.assertEquals(firstValue, newValue1)

Yes, that trap was setup by yourself :). If you'd just named it this way firstvalue -> a1 and secondValue -> b1 then you could have named the second run a2 and b2.

General remarks

Naming and code style seems OK, other than the remarks that have already been made.

Tests seem to take boundary values into account and cover most if not all of the code, which is generally a good idea.