/// <summary>Overrides the stream state data of a specific stream object with the data of the current object.
/// </summary>
/// <param name="destinationStream">The destination random number stream.</param>
/// <exception cref="ArgumentException">Thrown, if the stream of the current instance and the stream represented by <paramref name="destinationStream"/> are not compatible.</exception>
/// <remarks>Stream state data are for example the dimension etc.</remarks>
public void CopyStreamStateTo(IRandomNumberStream destinationStream)
{
AcmlRandomNumberStream acmlStream = (AcmlRandomNumberStream)destinationStream;
if (acmlStream == null)
{
throw new ArgumentException(nameof(destinationStream));
}
acmlStream.m_State = m_State.ToArray();
}
/// <summary>Creates a copy of the current <see cref="IRandomNumberStream"/> object and apply Block-splitting approach to it.
/// </summary>
/// <param name="numberOfSkippedElements">The number of skipped elements.</param>
/// <returns>A (deep) copy of the current instance which applies the Block-splitting approach.
/// </returns>
/// <exception cref="ArgumentException">Thrown, if the current object does not support the Block-split approach or the arguments are invalid.</exception>
/// <remarks>This method skips a specified number of elements in a random stream. This feature is particularly useful in distributing random numbers from
/// original random stream across different computational nodes.
/// If the largest number of random numbers used by a computational node is <paramref name="numberOfSkippedElements"/>, then the original random sequence
/// may be split into non-overlapping blocks of <paramref name="numberOfSkippedElements"/> size so that each block corresponds to the respective computational node.
/// The number of computational nodes is unlimited.
/// <para>
/// Note that for Quasi-Random Number Generators the Skip-ahead method works with components of Quasi-Random Vectors rather than with whole Quasi-Random Vectors.
/// Therefore, to skip <c>n</c> Quasi-Random Vectors, set <paramref name="numberOfSkippedElements"/> to <c>n</c> * <see cref="IRandomNumberStream.Dimension"/>.
/// If this operation results in exceeding the period of the Quasi-Random Number Generator, an exception will be thrown.
/// </para>
/// </remarks>
public IRandomNumberStream CreateSkipAheadStream(int numberOfSkippedElements)
{
AcmlRandomNumberStream randomStream = new AcmlRandomNumberStream(m_Generator, m_State.ToArray());
int errorCode = 0;
_acml_DRandomSkipAhead(ref numberOfSkippedElements, randomStream.m_State, ref errorCode);
if (errorCode != 0) // execution is not successful
{
throw new InvalidOperationException(String.Format("ACML: Return value {0} in DRANDSKIPAHEAD.", errorCode));
}
return(randomStream);
}
/// <summary>Creates a copy of the current <see cref="IRandomNumberStream"/> object and apply Leapfrog approach to it.
/// </summary>
/// <param name="streamIndex">The null-based index of the computational node (stream index), 0 <= <paramref name="streamIndex"/> < <paramref name="numberOfStreams"/>.</param>
/// <param name="numberOfStreams">The number of streams, i.e. largest number of computational nodes, or stride. In the case of a Quasi-Random Number Generator this parameter should be equal to the dimension.</param>
/// <returns>A (deep) copy of the current instance which applies the Leapfrog approach.
/// </returns>
/// <exception cref="ArgumentException">Thrown, if the current object does not support the Leapfrog method or the arguments are invalid.</exception>
/// <remarks>This feature is particularly useful in distributing random numbers from the original stream across the <paramref name="numberOfStreams"/> buffers. One of the important applications
/// of the Leapfrog method is splitting the original sequence into non-overlapping subsequences across <paramref name="numberOfStreams"/> computational nodes.
/// For Quasi-Random Number Generators, the Leapfrog method allows generating individual components of Quasi-Random Vectors instead of whole
/// Quasi-Random Vectors. In this case <paramref name="numberOfStreams"/> should be equal to the dimension of the Quasi-Random Vector.
/// </remarks>
public IRandomNumberStream CreateLeapfrogStream(int streamIndex, int numberOfStreams)
{
AcmlRandomNumberStream randomStream = new AcmlRandomNumberStream(m_Generator, m_State.ToArray());
streamIndex += 1; // This parameter is one-base in the API of ACML!
int errorCode = 0;
_acml_DRandomLeapFrog(ref numberOfStreams, ref streamIndex, randomStream.m_State, ref errorCode);
if (errorCode != 0) // execution is not successful
{
throw new InvalidOperationException(String.Format("ACML: Return value {0} in DRANDLEAPFROG.", errorCode));
}
return(randomStream);
}
/// <summary>Initializes a new instance of the <see cref="Distribution"/> class.
/// </summary>
/// <param name="randomNumberStream">The random number stream.</param>
internal Distribution(AcmlRandomNumberStream randomNumberStream)
{
m_RandomNumberStream = randomNumberStream;
}