Class RandomSparseTensor

java.lang.Object
org.flag4j.rng.RandomSparseTensor
public class RandomSparseTensor extends Object
A utility class for generating random sparse tensors and matrices with customizable sparsity and distributions.

Features:

  • Generate sparse matrices and tensors with specified sparsity levels.
  • Support for uniform and annular (complex valued) distributions for non-zero values.
  • Create symmetric sparse matrices.

Example Usage:


     RandomSparseTensor generator = new RandomSparseTensor(12345L);
     CooMatrix sparseMatrix = generator.randomCooMatrix(100, 100, 0, 10, 0.95);
     CsrMatrix csrMatrix = generator.randomCsrMatrix(new Shape(50, 50), 0, 1, 0.9);
See Also:

  • Constructor Summary

    Constructors
    Constructor
    Description
    RandomSparseTensor()
    Constructs a new pseudorandom tensor generator with seed set to RandomState.getGlobalSeed().
    RandomSparseTensor(long seed)
    Constructs a pseudorandom tensor generator with a specified seed.

  • Method Summary

    Modifier and Type
    Method
    Description
    CooCMatrix
    randomCooCMatrix(int rows, int cols, double min, double max, double sparsity)
    Generates a random sparse matrix with the specified sparsity.
    CooCMatrix
    randomCooCMatrix(int rows, int cols, double min, double max, int nnz)
    Generates a random sparse matrix with the specified number of non-zero data.
    CooCMatrix
    randomCooCMatrix(Shape shape, double min, double max, double sparsity)
    Generates a random sparse matrix with the specified sparsity.
    CooCMatrix
    randomCooCMatrix(Shape shape, double min, double max, int nnz)
    Generates a random sparse matrix with the specified number of non-zero data.
    CooCTensor
    randomCooCTensor(Shape shape, double min, double max, double sparsity)
    Constructs a complex COO tensor with the specified shape and sparsity filled with pseudo-random values uniformly distributed in an annulus centered on the origin of the complex plane.
    CooCTensor
    randomCooCTensor(Shape shape, double min, double max, int nnz)
    Constructs a complex COO tensor with the specified shape and number of non-zero entries filled with pseudo-random values uniformly distributed in an annulus centered on the origin of the complex plane.
    CooCVector
    randomCooCVector(int size, double min, double max, double sparsity)
    Constructs a COO vector with the specified sparsity entries filled with pseudo-random values uniformly distributed in an annulus centered on the complex plane.
    CooCVector
    randomCooCVector(int size, double min, double max, int nnz)
    Constructs a COO vector with the specified number of non-zero entries filled with pseudo-random values uniformly distributed in an annulus centered on the complex plane.
    CooMatrix
    randomCooMatrix(int rows, int cols, double min, double max, double sparsity)
    Generates a random sparse matrix with the specified sparsity.
    CooMatrix
    randomCooMatrix(int rows, int cols, double min, double max, int nnz)
    Generates a random sparse matrix with the specified number of non-zero data.
    CooMatrix
    randomCooMatrix(Shape shape, double min, double max, double sparsity)
    Generates a random sparse matrix with the specified sparsity.
    CooMatrix
    randomCooMatrix(Shape shape, double min, double max, int nnz)
    Generates a random sparse matrix with the specified number of non-zero data.
    CooTensor
    randomCooTensor(Shape shape, double min, double max, double sparsity)
    Constructs a COO tensor with the specified shape and sparsity filled with pseudo-random values from a uniform distribution in [min, max).
    CooTensor
    randomCooTensor(Shape shape, double min, double max, int nnz)
    Constructs a COO tensor with the specified shape and number of non-zero entries filled with pseudo-random values from a uniform distribution in [min, max).
    CooVector
    randomCooVector(int size, double min, double max, double sparsity)
    Constructs a COO vector with the specified sparsity filled with pseudo-random values from a uniform distribution in [min, max).
    CooVector
    randomCooVector(int size, double min, double max, int nnz)
    Constructs a COO vector with the specified number of non-zero entries filled with pseudo-random values from a uniform distribution in [min, max).
    CsrMatrix
    randomCsrMatrix(int rows, int cols, double min, double max, double sparsity)
    Generates a random sparse matrix with the specified sparsity.
    CsrMatrix
    randomCsrMatrix(int rows, int cols, double min, double max, int nnz)
    Generates a random sparse matrix with the specified number of non-zero data.
    CsrMatrix
    randomCsrMatrix(Shape shape, double min, double max, double sparsity)
    Generates a random sparse matrix with the specified sparsity.
    CsrMatrix
    randomCsrMatrix(Shape shape, double min, double max, int nnz)
    Generates a random sparse matrix with the specified number of non-zero data.
    CooCMatrix
    randomHermitianCooMatrix(int size, int min, int max, double sparsity)
    Generates a Hermitian complex COO matrix filled with pseudorandom values uniformly distributed in an annulus centered on the complex plane.
    CsrCMatrix
    randomHermitianCsrMatrix(int size, int min, int max, double sparsity)
    Generates a Hermitian complex CSR matrix filled with pseudorandom values uniformly distributed in an annulus centered on the complex plane.
    CooMatrix
    randomSymmetricCooMatrix(int size, int min, int max, double sparsity)
    Generates a symmetric COO matrix filled with pseudorandom values uniformly distributed in [min, max).
    CsrMatrix
    randomSymmetricCsrMatrix(int size, int min, int max, double sparsity)
    Generates a symmetric CSR matrix filled with pseudorandom values uniformly distributed in [min, max).

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • RandomSparseTensor

      public RandomSparseTensor()
      Constructs a new pseudorandom tensor generator with seed set to RandomState.getGlobalSeed().

    • RandomSparseTensor

      public RandomSparseTensor(long seed)
      Constructs a pseudorandom tensor generator with a specified seed. Use this constructor for reproducible results.
      Parameters:
      seed - Seed of the pseudorandom tensor generator.

  • Method Details

    • randomCooVector

      public CooVector randomCooVector(int size, double min, double max, double sparsity)
      Constructs a COO vector with the specified sparsity filled with pseudo-random values from a uniform distribution in [min, max).
      Parameters:
      size - Full size of the COO vector.
      min - Minimum value of the uniform distribution to sample from (inclusive).
      max - Maximum value of the uniform distribution to sample from (exclusive).
      sparsity - The sparsity of the COO vector.
      Returns:
      A sparse COO vector whose entries are uniformly distributed in [min, max).

    • randomCooVector

      public CooVector randomCooVector(int size, double min, double max, int nnz)
      Constructs a COO vector with the specified number of non-zero entries filled with pseudo-random values from a uniform distribution in [min, max).
      Parameters:
      size - Full size of the COO vector.
      min - Minimum value of the uniform distribution to sample from (inclusive).
      max - Maximum value of the uniform distribution to sample from (exclusive).
      nnz - The number of non-zero value to include in the vector.
      Returns:
      A sparse COO vector whose entries are uniformly distributed in [min, max).

    • randomCooCVector

      public CooCVector randomCooCVector(int size, double min, double max, double sparsity)
      Constructs a COO vector with the specified sparsity entries filled with pseudo-random values uniformly distributed in an annulus centered on the complex plane.
      Parameters:
      size - Full size of the COO vector.
      min - Inner radius of the annulus (inclusive).
      max - Outer radius of the annulus (exclusive).
      sparsity - The sparsity of the COO vector.
      Returns:
      A sparse COO vector whose entries are uniformly distributed in [min, max).

    • randomCooCVector

      public CooCVector randomCooCVector(int size, double min, double max, int nnz)
      Constructs a COO vector with the specified number of non-zero entries filled with pseudo-random values uniformly distributed in an annulus centered on the complex plane.
      Parameters:
      size - Full size of the COO vector.
      min - Inner radius of the annulus (inclusive).
      max - Outer radius of the annulus (exclusive).
      nnz - The number of non-zero value to include in the vector.
      Returns:
      A sparse COO vector whose entries are uniformly distributed in [min, max).

    • randomCooMatrix

      public CooMatrix randomCooMatrix(int rows, int cols, double min, double max, double sparsity)
      Generates a random sparse matrix with the specified sparsity. The non-zero values will have a uniform distribution in [min, max). Values will be uniformly distributed throughout the matrix.
      Parameters:
      rows - Number of rows in the sparse matrix.
      cols - Number of columns in the sparse matrix.
      min - Minimum value for random non-zero values in the sparse matrix.
      max - Maximum value for random non-zero values
      sparsity - Desired sparsity of the resulting matrix. i.e. the percent of values which are zero. Must be a value in [0.0, 1.0].
      Returns:
      A sparse matrix with sparsity approximately equal to sparsity filled with random values uniformly distributed in [min, max).

    • randomCooMatrix

      public CooMatrix randomCooMatrix(Shape shape, double min, double max, double sparsity)
      Generates a random sparse matrix with the specified sparsity. The non-zero values will have a uniform distribution in [min, max). Values will be uniformly distributed throughout the matrix.
      Parameters:
      shape - Shape of the sparse matrix to generate.
      min - Minimum value for random non-zero values in the sparse matrix.
      max - Maximum value for random non-zero values
      sparsity - Desired sparsity of the resulting matrix. i.e. the percent of values which are zero. Must be a value in [0.0, 1.0].
      Returns:
      A sparse matrix with sparsity approximately equal to sparsity filled with random values uniformly distributed in [min, max).

    • randomCooMatrix

      public CooMatrix randomCooMatrix(int rows, int cols, double min, double max, int nnz)
      Generates a random sparse matrix with the specified number of non-zero data. The non-zero values will have a uniform distribution in [min, max). Values will be uniformly distributed throughout the matrix.
      Parameters:
      rows - Number of rows in the random sparse matrix.
      cols - Number of columns in the random sparse matrix.
      min - Minimum value for random non-zero values in the sparse matrix.
      max - Maximum value for random non-zero values
      nnz - Desired number of non-zero data int the random sparse matrix.
      Returns:
      A sparse matrix filled with the specified number of non-zero data uniformly distributed in [min, max).

    • randomCooMatrix

      public CooMatrix randomCooMatrix(Shape shape, double min, double max, int nnz)
      Generates a random sparse matrix with the specified number of non-zero data. The non-zero values will have a uniform distribution in [min, max). Values will be uniformly distributed throughout the matrix.
      Parameters:
      shape - Shape of the sparse matrix to generate.
      min - Minimum value for random non-zero values in the sparse matrix.
      max - Maximum value for random non-zero values
      nnz - Desired number of non-zero data int the random sparse matrix.
      Returns:
      A sparse matrix filled with the specified number of non-zero data uniformly distributed in [min, max).

    • randomCsrMatrix

      public CsrMatrix randomCsrMatrix(int rows, int cols, double min, double max, double sparsity)
      Generates a random sparse matrix with the specified sparsity. The non-zero values will have a uniform distribution in [min, max). Values will be uniformly distributed throughout the matrix.
      Parameters:
      rows - Number of rows in the sparse matrix.
      cols - Number of columns in the sparse matrix.
      min - Minimum value for random non-zero values in the sparse matrix.
      max - Maximum value for random non-zero values
      sparsity - Desired sparsity of the resulting matrix. i.e. the percent of values which are zero. Must be a value in [0.0, 1.0].
      Returns:
      A sparse matrix with sparsity approximately equal to sparsity filled with random values uniformly distributed in [min, max).

    • randomCsrMatrix

      public CsrMatrix randomCsrMatrix(Shape shape, double min, double max, double sparsity)
      Generates a random sparse matrix with the specified sparsity. The non-zero values will have a uniform distribution in [min, max). Values will be uniformly distributed throughout the matrix.
      Parameters:
      shape - Shape of the sparse matrix to generate.
      min - Minimum value for random non-zero values in the sparse matrix.
      max - Maximum value for random non-zero values
      sparsity - Desired sparsity of the resulting matrix. i.e. the percent of values which are zero. Must be a value in [0.0, 1.0].
      Returns:
      A sparse matrix with sparsity approximately equal to sparsity filled with random values uniformly distributed in [min, max).

    • randomCsrMatrix

      public CsrMatrix randomCsrMatrix(int rows, int cols, double min, double max, int nnz)
      Generates a random sparse matrix with the specified number of non-zero data. The non-zero values will have a uniform distribution in [min, max). Values will be uniformly distributed throughout the matrix.
      Parameters:
      rows - Number of rows in the random sparse matrix.
      cols - Number of columns in the random sparse matrix.
      min - Minimum value for random non-zero values in the sparse matrix.
      max - Maximum value for random non-zero values
      nnz - Desired number of non-zero data int the random sparse matrix.
      Returns:
      A sparse matrix filled with the specified number of non-zero data uniformly distributed in [min, max).

    • randomCsrMatrix

      public CsrMatrix randomCsrMatrix(Shape shape, double min, double max, int nnz)
      Generates a random sparse matrix with the specified number of non-zero data. The non-zero values will have a uniform distribution in [min, max). Values will be uniformly distributed throughout the matrix.
      Parameters:
      shape - Shape of the sparse matrix to generate.
      min - Minimum value for random non-zero values in the sparse matrix.
      max - Maximum value for random non-zero values
      nnz - Desired number of non-zero data int the random sparse matrix.
      Returns:
      A sparse matrix filled with the specified number of non-zero data uniformly distributed in [min, max).

    • randomSymmetricCooMatrix

      public CooMatrix randomSymmetricCooMatrix(int size, int min, int max, double sparsity)
      Generates a symmetric COO matrix filled with pseudorandom values uniformly distributed in [min, max).
      Parameters:
      size - Number of rows and columns in the resulting matrix (the result will be a square matrix).
      min - Minimum value in uniform distribution.
      max - Maximum value in uniform distribution.
      sparsity - Desired sparsity of the resulting matrix. i.e. the percent of values which are zero. Must be a value in [0.0, 1.0]. The true sparsity may slightly differ to ensure the matrix is symmetric.
      Returns:
      A symmetric matrix filled with pseudorandom values uniformly distributed in [min, max).
      Throws:
      IllegalArgumentException - If sparsity is not in the range [0.0, 1.0].

    • randomSymmetricCsrMatrix

      public CsrMatrix randomSymmetricCsrMatrix(int size, int min, int max, double sparsity)
      Generates a symmetric CSR matrix filled with pseudorandom values uniformly distributed in [min, max).
      Parameters:
      size - Number of rows and columns in the resulting matrix (the result will be a square matrix).
      min - Minimum value in uniform distribution (inclusive).
      max - Maximum value in uniform distribution (exclusive).
      sparsity - Desired sparsity of the resulting matrix. i.e. the percent of values which are zero. Must be a value in [0.0, 1.0]. The true sparsity may slightly differ to ensure the matrix is symmetric.
      Returns:
      A symmetric matrix filled with pseudorandom values uniformly distributed in [min, max).
      Throws:
      IllegalArgumentException - If sparsity is not in the range [0.0, 1.0].

    • randomCooCMatrix

      public CooCMatrix randomCooCMatrix(int rows, int cols, double min, double max, double sparsity)
      Generates a random sparse matrix with the specified sparsity. The non-zero values will have a uniform distribution in the annulus (i.e. washer) with inner radius min (inclusive) and outer radius max (exclusive). Values will be uniformly distributed throughout the matrix.
      Parameters:
      rows - Number of rows in the sparse matrix.
      cols - Number of columns in the sparse matrix.
      min - Inner radius of the annular distribution (inclusive).
      max - Outer radius of the annular distribution (exclusive).
      sparsity - Desired sparsity of the resulting matrix. i.e. the percent of values which are zero. Must be a value in [0.0, 1.0].
      Returns:
      A sparse matrix with sparsity approximately equal to sparsity filled with random values uniformly distributed in an annulus.

    • randomCooCMatrix

      public CooCMatrix randomCooCMatrix(Shape shape, double min, double max, double sparsity)
      Generates a random sparse matrix with the specified sparsity. The non-zero values will have a uniform distribution in the annulus (i.e. washer) with inner radius min (inclusive) and outer radius max (exclusive). Values will be uniformly distributed throughout the matrix.
      Parameters:
      shape - Shape of the sparse matrix to generate.
      min - Inner radius of the annular distribution (inclusive).
      max - Outer radius of the annular distribution (exclusive).
      sparsity - Desired sparsity of the resulting matrix. i.e. the percent of values which are zero. Must be a value in [0.0, 1.0].
      Returns:
      A sparse matrix with sparsity approximately equal to sparsity filled with random values uniformly distributed in an annulus.

    • randomCooCMatrix

      public CooCMatrix randomCooCMatrix(int rows, int cols, double min, double max, int nnz)
      Generates a random sparse matrix with the specified number of non-zero data. The non-zero values will have a uniform distribution in the annulus (i.e. washer) with inner radius min (inclusive) and outer radius max (exclusive). Values will be uniformly distributed throughout the matrix.
      Parameters:
      rows - Number of rows in the random sparse matrix.
      cols - Number of columns in the random sparse matrix.
      min - Inner radius of the annular distribution (inclusive).
      max - Outer radius of the annular distribution (exclusive).
      nnz - Desired number of non-zero data int the random sparse matrix.
      Returns:
      A sparse matrix filled with the specified number of non-zero data uniformly distributed in an annulus.

    • randomCooCMatrix

      public CooCMatrix randomCooCMatrix(Shape shape, double min, double max, int nnz)
      Generates a random sparse matrix with the specified number of non-zero data. The non-zero values will have a uniform distribution in the annulus (i.e. washer) with inner radius min (inclusive) and outer radius max (exclusive). Non-zero values will be uniformly distributed throughout the matrix.
      Parameters:
      shape - Shape of the sparse matrix to generate.
      min - Inner radius of the annular distribution (inclusive).
      max - Outer radius of the annular distribution (exclusive).
      nnz - Desired number of non-zero data int the random sparse matrix.
      Returns:
      A sparse matrix filled with the specified number of non-zero data uniformly distributed in an annulus.

    • randomHermitianCooMatrix

      public CooCMatrix randomHermitianCooMatrix(int size, int min, int max, double sparsity)
      Generates a Hermitian complex COO matrix filled with pseudorandom values uniformly distributed in an annulus centered on the complex plane.
      Parameters:
      size - Number of rows and columns in the resulting matrix (the result will be a square matrix).
      min - Inner radius of the annulus (inclusive).
      max - Outer radius of the annulus (exclusive).
      sparsity - Desired sparsity of the resulting matrix. i.e. the percent of values which are zero. Must be a value in [0.0, 1.0]. The true sparsity may slightly differ to ensure the matrix is symmetric.
      Returns:
      A symmetric matrix filled with pseudorandom values uniformly distributed in [min, max).
      Throws:
      IllegalArgumentException - If sparsity is not in the range [0.0, 1.0].

    • randomHermitianCsrMatrix

      public CsrCMatrix randomHermitianCsrMatrix(int size, int min, int max, double sparsity)
      Generates a Hermitian complex CSR matrix filled with pseudorandom values uniformly distributed in an annulus centered on the complex plane.
      Parameters:
      size - Number of rows and columns in the resulting matrix (the result will be a square matrix).
      min - Inner radius of the annulus (inclusive).
      max - Outer radius of the annulus (exclusive).
      sparsity - Desired sparsity of the resulting matrix. i.e. the percent of values which are zero. Must be a value in [0.0, 1.0]. The true sparsity may slightly differ to ensure the matrix is symmetric.
      Returns:
      A symmetric matrix filled with pseudorandom values uniformly distributed in [min, max).
      Throws:
      IllegalArgumentException - If sparsity is not in the range [0.0, 1.0].

    • randomCooTensor

      public CooTensor randomCooTensor(Shape shape, double min, double max, double sparsity)
      Constructs a COO tensor with the specified shape and sparsity filled with pseudo-random values from a uniform distribution in [min, max).
      Parameters:
      shape - Full shape of the COO tensor.
      min - Minimum value of the uniform distribution to sample from (inclusive).
      max - Maximum value of the uniform distribution to sample from (exclusive).
      sparsity - The sparsity of the COO tensor.
      Returns:
      A sparse COO tensor whose entries are uniformly distributed in [min, max).

    • randomCooTensor

      public CooTensor randomCooTensor(Shape shape, double min, double max, int nnz)
      Constructs a COO tensor with the specified shape and number of non-zero entries filled with pseudo-random values from a uniform distribution in [min, max).
      Parameters:
      shape - Full shape of the COO tensor.
      min - Minimum value of the uniform distribution to sample from (inclusive).
      max - Maximum value of the uniform distribution to sample from (exclusive).
      nnz - The number of non-zero entries in the COO tensor.
      Returns:
      A sparse COO tensor whose entries are uniformly distributed in [min, max).

    • randomCooCTensor

      public CooCTensor randomCooCTensor(Shape shape, double min, double max, double sparsity)
      Constructs a complex COO tensor with the specified shape and sparsity filled with pseudo-random values uniformly distributed in an annulus centered on the origin of the complex plane.
      Parameters:
      shape - Full shape of the COO tensor.
      min - Minimum radius of the annulus (inclusive).
      max - Maximum radius of the annulus (exclusive).
      sparsity - The sparsity of the COO tensor.
      Returns:
      A sparse COO tensor whose entries are uniformly distributed in [min, max).

    • randomCooCTensor

      public CooCTensor randomCooCTensor(Shape shape, double min, double max, int nnz)
      Constructs a complex COO tensor with the specified shape and number of non-zero entries filled with pseudo-random values uniformly distributed in an annulus centered on the origin of the complex plane.
      Parameters:
      shape - Full shape of the COO tensor.
      min - Minimum radius of the annulus (inclusive).
      max - Maximum radius of the annulus (exclusive).
      nnz - The number of non-zero entries in the COO tensor.
      Returns:
      A sparse COO tensor whose entries are uniformly distributed in [min, max).