API:IRandom

From Wiketomica
Jump to: navigation, search
API Home Participants API Discussion Demos Downloads Documentation Contact Us Acknowledgements

IRandom

Reason for existence

Random number generators (RNGs) are used within a simulation, typically for Monte Carlo moves. Random numbers might also be used for a randomized initial configuration or a thermostat. Although most languages have native RNGs and each component could use its own RNG, each software component in a multi-codebase simulation would not be able to properly initialize the RNG. Furthermore, the Etomica plugin for Eclipse runs multiple simulations in-process, so use of a static RNG would fail to behave properly in that context.

Proposed Interface

We propose an IRandom interface containing methods for generating a random double precision number, a random integer and a random Gaussian. The random gaussian is mostly a specialized convenience method and might be more appropriate elsewhere.

interface IRandom {

    /**
     * Returns a pseudorandom double, uniformly distributed between 
     * 0.0 (inclusive) and 1.0 (exclusive).
     */
    double nextDouble();

    /**
     * Returns a pseudorandom integer, uniformly distributed between 
     * 0 (inclusive) and maxInt (exclusive).
     */
    int nextInt(in int maxInt);

    /**
     * Returns a pseudorandom double, Gaussian ("normally") distributed
     * value with mean 0.0 and standard deviation 1.0.
     */
    double nextGaussian();

}

Rationale

By having a single object in the simulation (perhaps held by the simulation object itself) that implements the IRandom interface, all software components can use the same random number generator, yielding consistent results.

Use

We expect that the ISimulation object would own the IRandom object. The RNG can be initialized (with a random seed) when it is created. The Monte Carlo integrator and moves could be given the IRandom object when they are created and used whenever they propose and accept or reject trials.

Notes

There several other methods (mostly for convenience) that might also live in an IRandom interface, including nextLong (64bit integer), nextFloat (32bit floating point number) or setSeed.