Class RandomComplex

java.lang.Object
java.util.Random
org.flag4j.rng.RandomComplex
All Implemented Interfaces:
Serializable, RandomGenerator
public class RandomComplex extends Random

The RandomComplex class provides methods to generate pseudorandom complex numbers under a variety of distributions and constraints. This class supports both Complex128 and Complex64.

Distributions supported by this class include:

  • Uniformly distributed random complex numbers on the unit disk, within annular regions, or rectangular regions of the complex plane.
  • Gaussian distributed random complex numbers, including standard circular, elliptical, and bivariate Gaussian distributions.

Example Usage:


 RandomComplex randomComplex = new RandomComplex();

 // Generate a random complex number with a magnitude between 0 and 1.
 Complex128 randomOnDisk = randomComplex.randomComplex128();

 // Generate a random complex number with a magnitude between 1 and 2.
 Complex128 randomInAnnulus = randomComplex.randomComplex128(1, 2);

 // Generate a Gaussian-distributed random complex number centered at (0, 0)
 //   with standard distributions of 1 along both real and imaginary axis and
 //   a correlation coefficient between real and imaginary values of 0.5.
 Complex64 gaussianComplex = randomComplex.randnComplex64(0, 1, 0, 1, 0.5f);

Note: This class extends Random. As such instances of RandomComplex are threadsafe. However, the concurrent use of the same RandomComplex instance across threads may encounter contention and consequent poor performance.

See Also:

  • Constructor Details

    • RandomComplex

      public RandomComplex()
      Constructs a complex value random number generator. The seed of this random number generator is very likely to be distinct from any other invocation of this constructor.

    • RandomComplex

      public RandomComplex(long seed)
      Constructs a complex value random number generator. Use this constructor with a seed value for reproducible results.
      Parameters:
      seed - Seed for this random number generator.

  • Method Details

    • randomComplex128

      public Complex128 randomComplex128()
      Generates a pseudorandom complex number which is uniformly distributed on the unit disk within the complex plane.
      Returns:
      A pseudorandom complex number uniformly distributed on the unit disk within the complex plane.

    • randomComplex128

      public Complex128 randomComplex128(double mag)
      Generates pseudorandom complex number with specified magnitude which is uniformly distributed around the origin. That is, a pseudorandom complex number which is uniformly distributed around the circle in the complex plane with radius equal to the specified magnitude.
      Parameters:
      mag - Magnitude of the pseudorandom complex number to generate. Must be non-negative.
      Returns:
      pseudorandom complex number uniformly distributed around the origin with the specified magnitude.
      Throws:
      IllegalArgumentException - If the magnitude is negative.

    • randomComplex128

      public Complex128 randomComplex128(double min, double max)
      Generates a pseudorandom complex number with magnitude in [min, max) which is uniformly distributed in the annulus (i.e. washer) with minimum and maximum radii equal to min and max respectively.
      Parameters:
      min - Minimum value for random number. Must be non-negative.
      max - Maximum value for random number. Must be larger than or equal to min.
      Returns:
      A pseudorandom complex number with magnitude uniformly distributed in [min, max).
      Throws:
      IllegalArgumentException - If min is not positive or if max is less than min.

    • randomRectComplex128

      public Complex128 randomRectComplex128()
      Generates a pseudorandom complex number distributed uniformly in the unit square on the complex plane centered at (0.0, 0.0).
      Returns:
      A pseudorandom complex number distributed uniformly in the unit square on the complex plane centered at (0.0, 0.0).
      See Also:

    • randomRectComplex128

      public Complex128 randomRectComplex128(double minRe, double maxRe, double minIm, double maxIm)

      Generates a pseudorandom complex number distributed uniformly in a rectangle on the complex plane. The bounds of the rectangle along each axis are specified by minRe, maxRe, minIm, and maxIm.

      Parameters:
      minRe - Minimum value along the real axis (inclusive).
      maxRe - Maximum value along the real axis (exclusive).
      minIm - Minimum value along the imaginary axis (inclusive).
      maxIm - Maximum value along the imaginary axis (exclusive).
      Returns:
      A pseudorandom complex number distributed uniformly in a rectangle on the complex plane.

    • randnComplex128

      public Complex128 randnComplex128()

      Generates a pseudorandom complex number sampled from a 2D circular standard Gaussian (normal) distribution on the complex plain. The distribution is centered at (0.0, 0.0) with standard deviation 1.0 along both the real and imaginary axes of the complex plane.

      The 2D circular standard Gaussian distribution centered at (x0, x0) with standard deviations along each axis, σ, is defined as: 

           f(x, y) = 1/(2π) exp[ -1/2 (x2 + y2) ]
      Parameters:
      mean - Mean of distribution.
      std - Standard deviation of distribution. Must be greater than zero.
      Returns:
      A pseudorandom complex number sampled from a 2D circular standard Gaussian (normal) distribution on the complex plain.
      See Also:

    • randnComplex128

      public Complex128 randnComplex128(double mean, double std)

      Generates a pseudorandom complex number sampled from a 2D circular Gaussian (normal) distribution on the complex plain. The distribution is centered at (mean, mean) with standard deviation std along both the real and imaginary axes of the complex plane.

      The 2D circular Gaussian distribution centered at (x0, x0) with standard deviations along each axis, σ, is defined as: 

           f(x, y) = 1/(2πσ2) exp[ -1/(2σ2) ((x - x0)2 + (y - x0)2) ]
      Parameters:
      mean - Mean of distribution.
      std - Standard deviation of distribution. Must be greater than zero.
      Returns:
      A pseudorandom complex number sampled from a 2D circular Gaussian (normal) distribution on the complex plain.
      See Also:

    • randnComplex128

      public Complex128 randnComplex128(double meanRe, double stdRe, double meanIm, double stdIm)

      Generates a pseudorandom complex number sampled from a 2D elliptical Gaussian (normal) distribution on the complex plain. The distribution is centered at (meanRe, meanIm) with standard deviations stdRe and stdIm along the real and imaginary axes of the complex plane respectively.

      The 2D Gaussian distribution centered at (x0, y0) with standard deviations along each axis, σX and σY, is defined as: 

           f(x, y) = 1/(2πσXσY) * exp[ -(x - x0)2/2σX2 - (y - y0)2/2σY2]
      Parameters:
      meanRe - Mean of distribution along real axis.
      stdRe - Standard deviation of distributions along real axis. Must be greater than zero.
      meanIm - Mean of distribution along imaginary axis.
      stdIm - Standard deviation of distributions along imaginary axis. Must be greater than zero.
      Returns:
      A pseudorandom complex number sampled from a 2D elliptical Gaussian (normal) distribution on the complex plain.
      See Also:

    • randnComplex128

      public Complex128 randnComplex128(double meanRe, double stdRe, double meanIm, double stdIm, double corrCoeff)

      Generates a pseudorandom complex number sampled from a bivariate Gaussian (normal) distribution on the complex plain. The distribution is centered at (meanRe, meanIm) with standard deviations stdRe and stdIm along the real and imaginary axes of the complex plane respectively. Further, corrCoeff is the correlation coefficient between the real and imaginary values.

      The covariance matrix, Σ, of such a distribution is expressed as: 

         Σ = [      stdRe*stdRe        corrCoeff*stdRe*stdIm ]
       [ corrCoeff*stdRe*stdIm        stdIm*stdIm      ]
      Let μ = [x0 y0]T be the mean column vector and z = [x y]T also be a column vector. Then, the bivariate Gaussian distribution may be expressed as: 
           f(z) = 1/(2 π det(Σ)1/2) exp[-1/2 (z - μ)T Σ-1 (z - μ)]
      Parameters:
      meanRe - Mean of distribution along real axis.
      stdRe - Standard deviation of distributions along real axis. Must be greater than zero.
      meanIm - Mean of distribution along imaginary axis.
      stdIm - Standard deviation of distributions along imaginary axis. Must be greater than zero.
      corrCoeff - Correlation coefficient between real and imaginary values in the distribution. Must satisfy corrCoeff > -1 && corrCoeff < 1
      Returns:
      A pseudorandom complex number sampled from a bivariate Gaussian (normal) distribution on the complex plain.
      Throws:
      IllegalArgumentException - If corrCoeff <= -1 || corrCoeff >= 1 or stdRe < 0.0 || stdIm < 0.0.
      See Also:

    • randomComplex64

      public Complex64 randomComplex64()
      Generates a pseudorandom complex number which is uniformly distributed on the unit disk within the complex plane.
      Returns:
      A pseudorandom complex number uniformly distributed on the unit disk within the complex plane.

    • randomComplex64

      public Complex64 randomComplex64(float mag)
      Generates pseudorandom complex number with specified magnitude which is uniformly distributed around the origin. That is, a pseudorandom complex number which is uniformly distributed around the circle in the complex plane with radius equal to the specified magnitude.
      Parameters:
      mag - Magnitude of the pseudorandom complex number to generate. Must be non-negative.
      Returns:
      pseudorandom complex number uniformly distributed around the origin with the specified magnitude.
      Throws:
      IllegalArgumentException - If the magnitude is negative.

    • randomComplex64

      public Complex64 randomComplex64(float min, float max)
      Generates a pseudorandom complex number with magnitude in [min, max) which is uniformly distributed in the annulus (i.e. washer) with minimum and maximum radii equal to min and max respectively.
      Parameters:
      min - Minimum value for random number. Must be non-negative.
      max - Maximum value for random number. Must be larger than or equal to min.
      Returns:
      A pseudorandom complex number with magnitude uniformly distributed in [min, max).
      Throws:
      IllegalArgumentException - If min is not positive or if max is less than min.

    • randomCartComplex64

      public Complex64 randomCartComplex64()
      Generates a pseudorandom complex number distributed uniformly in the unit square on the complex plane centered at (0.0, 0.0).
      Returns:
      A pseudorandom complex number distributed uniformly in the unit square on the complex plane centered at (0.0, 0.0).
      See Also:
      • invalid reference 
        #randomCartComplex64(double, double, double, double)

    • randomCartComplex64

      public Complex64 randomCartComplex64(float minRe, float maxRe, float minIm, float maxIm)

      Generates a pseudorandom complex number distributed uniformly in a rectangle on the complex plane. The bounds of the rectangle along each axis are specified by minRe, maxRe, minIm, and maxIm.

      Parameters:
      minRe - Minimum value along the real axis (inclusive).
      maxRe - Maximum value along the real axis (exclusive).
      minIm - Minimum value along the imaginary axis (inclusive).
      maxIm - Maximum value along the imaginary axis (exclusive).
      Returns:
      A pseudorandom complex number distributed uniformly in a rectangle on the complex plane.

    • randnComplex64

      public Complex64 randnComplex64()

      Generates a pseudorandom complex number sampled from a 2D circular standard Gaussian (normal) distribution on the complex plain. The distribution is centered at (0.0, 0.0) with standard deviation 1.0 along both the real and imaginary axes of the complex plane.

      The 2D circular standard Gaussian distribution centered at (x0, x0) with standard deviations along each axis, σ, is defined as: 

           f(x, y) = 1/(2π) exp[ -1/2 (x2 + y2) ]
      Parameters:
      mean - Mean of distribution.
      std - Standard deviation of distribution. Must be greater than zero.
      Returns:
      A pseudorandom complex number sampled from a 2D circular standard Gaussian (normal) distribution on the complex plain.
      See Also:
      • invalid reference 
        #randnComplex64(double, double)
      • invalid reference 
        #randnComplex64(double, double, double, double)
      • invalid reference 
        #randnComplex64(double, double, double, double, double)

    • randnComplex64

      public Complex64 randnComplex64(float mean, float std)

      Generates a pseudorandom complex number sampled from a 2D circular Gaussian (normal) distribution on the complex plain. The distribution is centered at (mean, mean) with standard deviation std along both the real and imaginary axes of the complex plane.

      The 2D circular Gaussian distribution centered at (x0, x0) with standard deviations along each axis, σ, is defined as: 

           f(x, y) = 1/(2πσ2) exp[ -1/(2σ2) ((x - x0)2 + (y - x0)2) ]
      Parameters:
      mean - Mean of distribution.
      std - Standard deviation of distribution. Must be greater than zero.
      Returns:
      A pseudorandom complex number sampled from a 2D circular Gaussian (normal) distribution on the complex plain.
      See Also:
      • randnComplex64()
      • invalid reference 
        #randnComplex64(double, double, double, double)
      • invalid reference 
        #randnComplex64(double, double, double, double, double)

    • randnComplex64

      public Complex64 randnComplex64(float meanRe, float stdRe, float meanIm, float stdIm)

      Generates a pseudorandom complex number sampled from a 2D elliptical Gaussian (normal) distribution on the complex plain. The distribution is centered at (meanRe, meanIm) with standard deviations stdRe and stdIm along the real and imaginary axes of the complex plane respectively.

      The 2D Gaussian distribution centered at (x0, y0) with standard deviations along each axis, σX and σY, is defined as: 

           f(x, y) = 1/(2πσXσY) * exp[ -(x - x0)2/2σX2 - (y - y0)2/2σY2]
      Parameters:
      meanRe - Mean of distribution along real axis.
      stdRe - Standard deviation of distributions along real axis. Must be greater than zero.
      meanIm - Mean of distribution along imaginary axis.
      stdIm - Standard deviation of distributions along imaginary axis. Must be greater than zero.
      Returns:
      A pseudorandom complex number sampled from a 2D elliptical Gaussian (normal) distribution on the complex plain.
      See Also:
      • invalid reference 
        #randnComplex64(double, double)
      • randnComplex64()
      • invalid reference 
        #randnComplex64(double, double, double, double, double)

    • randnComplex64

      public Complex64 randnComplex64(float meanRe, float stdRe, float meanIm, float stdIm, float corrCoeff)

      Generates a pseudorandom complex number sampled from a bivariate Gaussian (normal) distribution on the complex plain. The distribution is centered at (meanRe, meanIm) with standard deviations stdRe and stdIm along the real and imaginary axes of the complex plane respectively. Further, corrCoeff is the correlation coefficient between the real and imaginary values.

      The covariance matrix, Σ, of such a distribution is expressed as: 

         Σ = [      stdRe*stdRe        corrCoeff*stdRe*stdIm ]
       [ corrCoeff*stdRe*stdIm        stdIm*stdIm      ]
      Let μ = [x0 y0]T be the mean column vector and z = [x y]T also be a column vector. Then, the bivariate Gaussian distribution may be expressed as: 
           f(z) = 1/(2 π det(Σ)1/2) exp[-1/2 (z - μ)T Σ-1 (z - μ)]
      Parameters:
      meanRe - Mean of distribution along real axis.
      stdRe - Standard deviation of distributions along real axis. Must be greater than zero.
      meanIm - Mean of distribution along imaginary axis.
      stdIm - Standard deviation of distributions along imaginary axis. Must be greater than zero.
      corrCoeff - Correlation coefficient between real and imaginary values in the distribution. Must satisfy corrCoeff > -1 && corrCoeff < 1
      Returns:
      A pseudorandom complex number sampled from a bivariate Gaussian (normal) distribution on the complex plain.
      Throws:
      IllegalArgumentException - If corrCoeff <= -1 || corrCoeff >= 1 or stdRe < 0.0 || stdIm < 0.0.
      See Also:
      • invalid reference 
        #randnComplex64(double, double)
      • invalid reference 
        #randnComplex64(double, double, double, double)
      • randnComplex64()