Dotnet/FastRng
Dotnet/FastRng
1
0
Fork 0
Code Issues 2 Pull Requests Actions Packages Projects Releases 5 Wiki Activity

Added documentation

Browse Source
This commit is contained in:
Thorsten Sommer 2020-11-08 16:22:40 +01:00
parent afcd2f3dc8
commit 37e846233d
8 changed files with 190 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
FastRng/Double/IRandom.cs
View File

@ -5,8 +5,20 @@ using FastRng.Double.Distributions;
namespace FastRng.Double
{
/// <summary>
/// Interface for random number generators.
/// </summary>
public interface IRandom : IDisposable
{
/// <summary>
/// Returns a uniform distributed pseudo-random number from the interval (0,1].
/// This means, the result 0 is impossible, whereas 1 is possible.
/// </summary>
/// <remarks>
/// This method is thread-safe. You can consume numbers from the same generator
/// by using multiple threads at the same time.
/// </remarks>
/// <param name="cancel">An optional cancellation token.</param>
public ValueTask<double> GetUniform(CancellationToken cancel = default);
}
}

22
FastRng/Double/MathTools.cs
View File

@ -2,11 +2,18 @@ using System;
namespace FastRng.Double
{
/// <summary>
/// Provides some mathematical function, which are not available within in the .NET framework.
/// </summary>
public static class MathTools
{
private static readonly double SQRT_2 = Math.Sqrt(2.0);
private static readonly double SQRT_PI = Math.Sqrt(Math.PI);
/// <summary>
/// The mathematical gamma function.
/// </summary>
/// <param name="z">The value for which you want calculate gamma.</param>
public static double Gamma(double z)
{
// Source: http://rosettacode.org/wiki/Gamma_function#Go
@ -36,8 +43,17 @@ namespace FastRng.Double
return MathTools.SQRT_2 * MathTools.SQRT_PI * Math.Pow(t, z - 0.5) * Math.Exp(-t) * x;
}
/// <summary>
/// The mathematical factorial function for floating-point numbers.
/// </summary>
/// <param name="x">The value, for which you want to know the factorial.</param>
public static double Factorial(double x) => MathTools.Gamma(x + 1.0);
/// <summary>
/// The mathematical factorial function for integer numbers.
/// </summary>
/// <param name="x">The value, for which you want to know the factorial.</param>
/// <exception cref="ArgumentOutOfRangeException">Throws, when x is greater than 20. Due to limitations of 64bit ulong type.</exception>
public static ulong Factorial(uint x)
{
if (x > 20)
@ -50,6 +66,12 @@ namespace FastRng.Double
return accumulator;
}
/// <summary>
/// The mathematical factorial function for integer numbers.
/// </summary>
/// <param name="x">The value, for which you want to know the factorial.</param>
/// <exception cref="ArgumentOutOfRangeException">Throws, when x is greater than 20. Due to limitations
/// of 64bit ulong type. Throws also, when x is less than 0.</exception>
public static ulong Factorial(int x)
{
if(x < 0)

50
FastRng/Double/MultiThreadedRng.cs
View File

@ -68,6 +68,15 @@ namespace FastRng.Double
#region Constructors
/// <summary>
/// Creates a multi-threaded random number generator.
/// </summary>
/// <remarks>
/// This constructor uses the user's current local time
/// to derive necessary parameters for the generator.
/// Thus, the results are depending on the time, where
/// the generator was created.
/// </remarks>
public MultiThreadedRng()
{
//
@ -81,6 +90,19 @@ namespace FastRng.Double
this.StartProducerThreads();
}
/// <summary>
/// Creates a multi-threaded random number generator.
/// </summary>
/// <remarks>
/// A multi-threaded random number generator created by this constructor is
/// deterministic. It's behaviour is not depending on the time of its creation.<br/><br/>
///
/// <b>Please note:</b> Although the number generator and all distributions are deterministic,
/// the behavior of the consuming application might be non-deterministic. This is possible if
/// the application with multiple threads consumes the numbers. The scheduling of the threads
/// is up to the operating system and might not be predictable.
/// </remarks>
/// <param name="seedU">A seed value to generate a deterministic generator.</param>
public MultiThreadedRng(uint seedU)
{
this.mW = seedU;
@ -88,6 +110,20 @@ namespace FastRng.Double
this.StartProducerThreads();
}
/// <summary>
/// Creates a multi-threaded random number generator.
/// </summary>
/// <remarks>
/// A multi-threaded random number generator created by this constructor is
/// deterministic. It's behaviour is not depending on the time of its creation.<br/><br/>
///
/// <b>Please note:</b> Although the number generator and all distributions are deterministic,
/// the behavior of the consuming application might be non-deterministic. This is possible if
/// the application with multiple threads consumes the numbers. The scheduling of the threads
/// is up to the operating system and might not be predictable.
/// </remarks>
/// <param name="seedU">The first seed value.</param>
/// <param name="seedV">The second seed value.</param>
public MultiThreadedRng(uint seedU, uint seedV)
{
this.mW = seedU;
@ -209,6 +245,15 @@ namespace FastRng.Double
#region Implementing interface
/// <summary>
/// Returns a uniform distributed pseudo-random number from the interval (0,1].
/// This means, the result 0 is impossible, whereas 1 is possible.
/// </summary>
/// <remarks>
/// This method is thread-safe. You can consume numbers from the same generator
/// by using multiple threads at the same time.
/// </remarks>
/// <param name="cancel">An optional cancellation token.</param>
public async ValueTask<double> GetUniform(CancellationToken cancel = default)
{
while (!cancel.IsCancellationRequested)
@ -301,6 +346,11 @@ namespace FastRng.Double
private void StopProducer() => this.producerTokenSource.Cancel();
/// <summary>
/// Disposes this generator. It is important to dispose a generator,
/// when it is no longer needed. Otherwise, the background threads
/// are still running.
/// </summary>
public void Dispose() => this.StopProducer();
#endregion

11
FastRng/Double/ShapeFitter.cs
View File

@ -17,6 +17,12 @@ namespace FastRng.Double
private readonly double sampleSize;
private readonly IDistribution uniform;
/// <summary>
/// Creates a shape fitter instance.
/// </summary>
/// <param name="shapeFunction">The function which describes the desired shape.</param>
/// <param name="rng">The random number generator instance to use.</param>
/// <param name="sampleSize">The number of sampling steps to sample the given function.</param>
public ShapeFitter(Func<double, double> shapeFunction, IRandom rng, ushort sampleSize = 50)
{
this.rng = rng;
@ -39,6 +45,11 @@ namespace FastRng.Double
this.max = maxValue;
}
/// <summary>
/// Returns a random number regarding the given shape.
/// </summary>
/// <param name="token">An optional cancellation token.</param>
/// <returns>The next value regarding the given shape.</returns>
public async ValueTask<double> NextNumber(CancellationToken token = default)
{
while (!token.IsCancellationRequested)

12
FastRng/Float/IRandom.cs
View File

@ -5,8 +5,20 @@ using FastRng.Float.Distributions;
namespace FastRng.Float
{
/// <summary>
/// Interface for random number generators.
/// </summary>
public interface IRandom : IDisposable
{
/// <summary>
/// Returns a uniform distributed pseudo-random number from the interval (0,1].
/// This means, the result 0 is impossible, whereas 1 is possible.
/// </summary>
/// <remarks>
/// This method is thread-safe. You can consume numbers from the same generator
/// by using multiple threads at the same time.
/// </remarks>
/// <param name="cancel">An optional cancellation token.</param>
public ValueTask<float> GetUniform(CancellationToken cancel = default);
}
}

22
FastRng/Float/MathTools.cs
View File

@ -2,11 +2,18 @@ using System;
namespace FastRng.Float
{
/// <summary>
/// Provides some mathematical function, which are not available within in the .NET framework.
/// </summary>
public static class MathTools
{
private static readonly float SQRT_2 = MathF.Sqrt(2.0f);
private static readonly float SQRT_PI = MathF.Sqrt(MathF.PI);
/// <summary>
/// The mathematical gamma function.
/// </summary>
/// <param name="z">The value for which you want calculate gamma.</param>
public static float Gamma(float z)
{
// Source: http://rosettacode.org/wiki/Gamma_function#Go
@ -36,8 +43,17 @@ namespace FastRng.Float
return MathTools.SQRT_2 * MathTools.SQRT_PI * MathF.Pow(t, z - 0.5f) * MathF.Exp(-t) * x;
}
/// <summary>
/// The mathematical factorial function for floating-point numbers.
/// </summary>
/// <param name="x">The value, for which you want to know the factorial.</param>
public static float Factorial(float x) => MathTools.Gamma(x + 1.0f);
/// <summary>
/// The mathematical factorial function for integer numbers.
/// </summary>
/// <param name="x">The value, for which you want to know the factorial.</param>
/// <exception cref="ArgumentOutOfRangeException">Throws, when x is greater than 20. Due to limitations of 64bit ulong type.</exception>
public static ulong Factorial(uint x)
{
if (x > 20)
@ -50,6 +66,12 @@ namespace FastRng.Float
return accumulator;
}
/// <summary>
/// The mathematical factorial function for integer numbers.
/// </summary>
/// <param name="x">The value, for which you want to know the factorial.</param>
/// <exception cref="ArgumentOutOfRangeException">Throws, when x is greater than 20. Due to limitations
/// of 64bit ulong type. Throws also, when x is less than 0.</exception>
public static ulong Factorial(int x)
{
if(x < 0)

50
FastRng/Float/MultiThreadedRng.cs
View File

@ -68,6 +68,15 @@ namespace FastRng.Float
#region Constructors
/// <summary>
/// Creates a multi-threaded random number generator.
/// </summary>
/// <remarks>
/// This constructor uses the user's current local time
/// to derive necessary parameters for the generator.
/// Thus, the results are depending on the time, where
/// the generator was created.
/// </remarks>
public MultiThreadedRng()
{
//
@ -81,6 +90,19 @@ namespace FastRng.Float
this.StartProducerThreads();
}
/// <summary>
/// Creates a multi-threaded random number generator.
/// </summary>
/// <remarks>
/// A multi-threaded random number generator created by this constructor is
/// deterministic. It's behaviour is not depending on the time of its creation.<br/><br/>
///
/// <b>Please note:</b> Although the number generator and all distributions are deterministic,
/// the behavior of the consuming application might be non-deterministic. This is possible if
/// the application with multiple threads consumes the numbers. The scheduling of the threads
/// is up to the operating system and might not be predictable.
/// </remarks>
/// <param name="seedU">A seed value to generate a deterministic generator.</param>
public MultiThreadedRng(uint seedU)
{
this.mW = seedU;
@ -88,6 +110,20 @@ namespace FastRng.Float
this.StartProducerThreads();
}
/// <summary>
/// Creates a multi-threaded random number generator.
/// </summary>
/// <remarks>
/// A multi-threaded random number generator created by this constructor is
/// deterministic. It's behaviour is not depending on the time of its creation.<br/><br/>
///
/// <b>Please note:</b> Although the number generator and all distributions are deterministic,
/// the behavior of the consuming application might be non-deterministic. This is possible if
/// the application with multiple threads consumes the numbers. The scheduling of the threads
/// is up to the operating system and might not be predictable.
/// </remarks>
/// <param name="seedU">The first seed value.</param>
/// <param name="seedV">The second seed value.</param>
public MultiThreadedRng(uint seedU, uint seedV)
{
this.mW = seedU;
@ -209,6 +245,15 @@ namespace FastRng.Float
#region Implementing interface
/// <summary>
/// Returns a uniform distributed pseudo-random number from the interval (0,1].
/// This means, the result 0 is impossible, whereas 1 is possible.
/// </summary>
/// <remarks>
/// This method is thread-safe. You can consume numbers from the same generator
/// by using multiple threads at the same time.
/// </remarks>
/// <param name="cancel">An optional cancellation token.</param>
public async ValueTask<float> GetUniform(CancellationToken cancel = default)
{
while (!cancel.IsCancellationRequested)
@ -301,6 +346,11 @@ namespace FastRng.Float
private void StopProducer() => this.producerTokenSource.Cancel();
/// <summary>
/// Disposes this generator. It is important to dispose a generator,
/// when it is no longer needed. Otherwise, the background threads
/// are still running.
/// </summary>
public void Dispose() => this.StopProducer();
#endregion

11
FastRng/Float/ShapeFitter.cs
View File

@ -16,6 +16,12 @@ namespace FastRng.Float
private readonly float sampleSize;
private readonly IDistribution uniform;
/// <summary>
/// Creates a shape fitter instance.
/// </summary>
/// <param name="shapeFunction">The function which describes the desired shape.</param>
/// <param name="rng">The random number generator instance to use.</param>
/// <param name="sampleSize">The number of sampling steps to sample the given function.</param>
public ShapeFitter(Func<float, float> shapeFunction, IRandom rng, ushort sampleSize = 50)
{
this.rng = rng;
@ -38,6 +44,11 @@ namespace FastRng.Float
this.max = maxValue;
}
/// <summary>
/// Returns a random number regarding the given shape.
/// </summary>
/// <param name="token">An optional cancellation token.</param>
/// <returns>The next value regarding the given shape.</returns>
public async ValueTask<float> NextNumber(CancellationToken token = default)
{
while (!token.IsCancellationRequested)