tessl/pypi-sparse

Sparse n-dimensional arrays for the PyData ecosystem with multiple backend implementations

—

Pending

Overview

Eval results

Files

Mathematical Operations

Name: tessl/pypi-sparse
Author: tessl

Comprehensive mathematical functions including arithmetic, trigonometric, exponential, and comparison operations optimized for sparse arrays. These operations preserve sparsity when mathematically appropriate and provide element-wise computations.

Capabilities

Arithmetic Operations

Basic arithmetic operations supporting element-wise computation between sparse arrays, sparse and dense arrays, and sparse arrays with scalars.

def add(x1, x2):
    """
    Element-wise addition of sparse arrays.
    
    Parameters:
    - x1, x2: sparse arrays or scalars to add
    
    Returns:
    Sparse array with element-wise sum
    """

def subtract(x1, x2):
    """
    Element-wise subtraction of sparse arrays.
    
    Parameters:
    - x1, x2: sparse arrays or scalars, computes x1 - x2
    
    Returns:
    Sparse array with element-wise difference
    """

def multiply(x1, x2):
    """
    Element-wise multiplication of sparse arrays.
    
    Parameters:
    - x1, x2: sparse arrays or scalars to multiply
    
    Returns:
    Sparse array with element-wise product
    """

def divide(x1, x2):
    """
    Element-wise division of sparse arrays.
    
    Parameters:
    - x1, x2: sparse arrays or scalars, computes x1 / x2
    
    Returns:
    Sparse array with element-wise quotient
    """

def floor_divide(x1, x2):
    """
    Element-wise floor division of sparse arrays.
    
    Parameters:
    - x1, x2: sparse arrays or scalars, computes x1 // x2
    
    Returns:
    Sparse array with element-wise floor division
    """

def remainder(x1, x2):
    """
    Element-wise remainder of sparse arrays.
    
    Parameters:
    - x1, x2: sparse arrays or scalars, computes x1 % x2
    
    Returns:
    Sparse array with element-wise remainder
    """

def pow(x1, x2):
    """
    Element-wise power operation.
    
    Parameters:
    - x1: sparse array or scalar, base values
    - x2: sparse array or scalar, exponent values
    
    Returns:
    Sparse array with x1 raised to power x2
    """

Trigonometric Functions

Trigonometric functions operating element-wise on sparse arrays.

def sin(x):
    """
    Element-wise sine function.
    
    Parameters:
    - x: sparse array, input angles in radians
    
    Returns:
    Sparse array with sine values
    """

def cos(x):
    """
    Element-wise cosine function.
    
    Parameters:
    - x: sparse array, input angles in radians
    
    Returns:
    Sparse array with cosine values
    """

def tan(x):
    """
    Element-wise tangent function.
    
    Parameters:
    - x: sparse array, input angles in radians
    
    Returns:
    Sparse array with tangent values
    """

def sinh(x):
    """
    Element-wise hyperbolic sine function.
    
    Parameters:
    - x: sparse array, input values
    
    Returns:
    Sparse array with hyperbolic sine values
    """

def cosh(x):
    """
    Element-wise hyperbolic cosine function.
    
    Parameters:
    - x: sparse array, input values
    
    Returns:
    Sparse array with hyperbolic cosine values
    """

def tanh(x):
    """
    Element-wise hyperbolic tangent function.
    
    Parameters:
    - x: sparse array, input values
    
    Returns:
    Sparse array with hyperbolic tangent values
    """

Inverse Trigonometric Functions

Inverse trigonometric functions for sparse arrays.

def asin(x):
    """
    Element-wise inverse sine function.
    
    Parameters:
    - x: sparse array, input values in range [-1, 1]
    
    Returns:
    Sparse array with arcsine values in radians
    """

def acos(x):
    """
    Element-wise inverse cosine function.
    
    Parameters:
    - x: sparse array, input values in range [-1, 1]
    
    Returns:
    Sparse array with arccosine values in radians
    """

def atan(x):
    """
    Element-wise inverse tangent function.
    
    Parameters:
    - x: sparse array, input values
    
    Returns:
    Sparse array with arctangent values in radians
    """

def atan2(y, x):
    """
    Element-wise 2-argument inverse tangent.
    
    Parameters:
    - y: sparse array, y-coordinates
    - x: sparse array, x-coordinates
    
    Returns:
    Sparse array with arctangent of y/x in correct quadrant
    """

def asinh(x):
    """
    Element-wise inverse hyperbolic sine function.
    
    Parameters:
    - x: sparse array, input values
    
    Returns:
    Sparse array with inverse hyperbolic sine values
    """

def acosh(x):
    """
    Element-wise inverse hyperbolic cosine function.
    
    Parameters:
    - x: sparse array, input values >= 1
    
    Returns:
    Sparse array with inverse hyperbolic cosine values
    """

def atanh(x):
    """
    Element-wise inverse hyperbolic tangent function.
    
    Parameters:
    - x: sparse array, input values in range (-1, 1)
    
    Returns:
    Sparse array with inverse hyperbolic tangent values
    """

Exponential and Logarithmic Functions

Exponential and logarithmic functions for sparse arrays.

def exp(x):
    """
    Element-wise exponential function.
    
    Parameters:
    - x: sparse array, input values
    
    Returns:
    Sparse array with e^x values
    """

def expm1(x):
    """
    Element-wise exp(x) - 1, computed accurately for small x.
    
    Parameters:
    - x: sparse array, input values
    
    Returns:
    Sparse array with exp(x) - 1 values
    """

def log(x):
    """
    Element-wise natural logarithm.
    
    Parameters:
    - x: sparse array, input values > 0
    
    Returns:
    Sparse array with natural log values
    """

def log1p(x):
    """
    Element-wise log(1 + x), computed accurately for small x.
    
    Parameters:
    - x: sparse array, input values > -1
    
    Returns:
    Sparse array with log(1 + x) values
    """

def log2(x):
    """
    Element-wise base-2 logarithm.
    
    Parameters:
    - x: sparse array, input values > 0
    
    Returns:
    Sparse array with base-2 log values
    """

def log10(x):
    """
    Element-wise base-10 logarithm.
    
    Parameters:
    - x: sparse array, input values > 0
    
    Returns:
    Sparse array with base-10 log values
    """

def logaddexp(x1, x2):
    """
    Element-wise log(exp(x1) + exp(x2)).
    
    Parameters:
    - x1, x2: sparse arrays, input values
    
    Returns:
    Sparse array with log(exp(x1) + exp(x2)) values
    """

def sqrt(x):
    """
    Element-wise square root function.
    
    Parameters:
    - x: sparse array, input values >= 0
    
    Returns:
    Sparse array with square root values
    """

def square(x):
    """
    Element-wise square function.
    
    Parameters:
    - x: sparse array, input values
    
    Returns:
    Sparse array with squared values
    """

Other Mathematical Functions

Additional mathematical functions for sparse arrays.

def abs(x):
    """
    Element-wise absolute value function.
    
    Parameters:
    - x: sparse array, input values
    
    Returns:
    Sparse array with absolute values
    """

def sign(x):
    """
    Element-wise sign function (-1, 0, or 1).
    
    Parameters:
    - x: sparse array, input values
    
    Returns:
    Sparse array with sign values
    """

def signbit(x):
    """
    Element-wise sign bit test.
    
    Parameters:
    - x: sparse array, input values
    
    Returns:
    Sparse array with True where sign bit is set
    """

def positive(x):
    """
    Element-wise unary positive (+x).
    
    Parameters:
    - x: sparse array, input values
    
    Returns:
    Sparse array, copy of input
    """

def negative(x):
    """
    Element-wise unary negative (-x).
    
    Parameters:
    - x: sparse array, input values
    
    Returns:
    Sparse array with negated values
    """

def reciprocal(x):
    """
    Element-wise reciprocal (1/x).
    
    Parameters:
    - x: sparse array, input values != 0
    
    Returns:
    Sparse array with reciprocal values
    """

def conj(x):
    """
    Element-wise complex conjugate.
    
    Parameters:
    - x: sparse array, input values (real or complex)
    
    Returns:
    Sparse array with complex conjugate values
    """

Rounding and Related Functions

Functions for rounding and related operations.

def ceil(x):
    """
    Element-wise ceiling function.
    
    Parameters:
    - x: sparse array, input values
    
    Returns:
    Sparse array with ceiling values (smallest integer >= x)
    """

def floor(x):
    """
    Element-wise floor function.
    
    Parameters:
    - x: sparse array, input values
    
    Returns:
    Sparse array with floor values (largest integer <= x)
    """

def trunc(x):
    """
    Element-wise truncation to integer.
    
    Parameters:
    - x: sparse array, input values
    
    Returns:
    Sparse array with truncated values
    """

def round(x, decimals=0):
    """
    Element-wise rounding to given number of decimals.
    
    Parameters:
    - x: sparse array, input values
    - decimals: int, number of decimal places
    
    Returns:
    Sparse array with rounded values
    """

Floating Point Utilities

Utility functions for floating point operations.

def copysign(x1, x2):
    """
    Element-wise copy sign of x2 to x1.
    
    Parameters:
    - x1: sparse array, magnitude values
    - x2: sparse array, sign values
    
    Returns:
    Sparse array with magnitude of x1 and sign of x2
    """

def nextafter(x1, x2):
    """
    Element-wise next representable floating point value.
    
    Parameters:
    - x1: sparse array, starting values
    - x2: sparse array, direction values
    
    Returns:
    Sparse array with next representable values toward x2
    """

def hypot(x1, x2):
    """
    Element-wise Euclidean distance sqrt(x1²+x2²).
    
    Parameters:
    - x1, x2: sparse arrays, input values
    
    Returns:
    Sparse array with Euclidean distances
    """

Comparison Operations

Element-wise comparison functions returning boolean sparse arrays.

def equal(x1, x2):
    """
    Element-wise equality comparison.
    
    Parameters:
    - x1, x2: sparse arrays or scalars to compare
    
    Returns:
    Sparse boolean array with True where x1 == x2
    """

def not_equal(x1, x2):
    """
    Element-wise inequality comparison.
    
    Parameters:
    - x1, x2: sparse arrays or scalars to compare
    
    Returns:
    Sparse boolean array with True where x1 != x2
    """

def less(x1, x2):
    """
    Element-wise less-than comparison.
    
    Parameters:
    - x1, x2: sparse arrays or scalars to compare
    
    Returns:
    Sparse boolean array with True where x1 < x2
    """

def less_equal(x1, x2):
    """
    Element-wise less-than-or-equal comparison.
    
    Parameters:
    - x1, x2: sparse arrays or scalars to compare
    
    Returns:
    Sparse boolean array with True where x1 <= x2
    """

def greater(x1, x2):
    """
    Element-wise greater-than comparison.
    
    Parameters:
    - x1, x2: sparse arrays or scalars to compare
    
    Returns:
    Sparse boolean array with True where x1 > x2
    """

def greater_equal(x1, x2):
    """
    Element-wise greater-than-or-equal comparison.
    
    Parameters:
    - x1, x2: sparse arrays or scalars to compare
    
    Returns:
    Sparse boolean array with True where x1 >= x2
    """

Logical Operations

Element-wise logical operations on boolean sparse arrays.

def logical_and(x1, x2):
    """
    Element-wise logical AND operation.
    
    Parameters:
    - x1, x2: sparse boolean arrays
    
    Returns:
    Sparse boolean array with True where both x1 and x2 are True
    """

def logical_or(x1, x2):
    """
    Element-wise logical OR operation.
    
    Parameters:
    - x1, x2: sparse boolean arrays
    
    Returns:
    Sparse boolean array with True where x1 or x2 is True
    """

def logical_not(x):
    """
    Element-wise logical NOT operation.
    
    Parameters:
    - x: sparse boolean array
    
    Returns:
    Sparse boolean array with negated boolean values
    """

def logical_xor(x1, x2):
    """
    Element-wise logical XOR operation.
    
    Parameters:
    - x1, x2: sparse boolean arrays
    
    Returns:
    Sparse boolean array with True where exactly one of x1, x2 is True
    """

Bitwise Operations

Element-wise bitwise operations on integer sparse arrays.

def bitwise_and(x1, x2):
    """
    Element-wise bitwise AND operation.
    
    Parameters:
    - x1, x2: sparse integer arrays
    
    Returns:
    Sparse array with bitwise AND of x1 and x2
    """

def bitwise_or(x1, x2):
    """
    Element-wise bitwise OR operation.
    
    Parameters:
    - x1, x2: sparse integer arrays
    
    Returns:
    Sparse array with bitwise OR of x1 and x2
    """

def bitwise_xor(x1, x2):
    """
    Element-wise bitwise XOR operation.
    
    Parameters:
    - x1, x2: sparse integer arrays
    
    Returns:
    Sparse array with bitwise XOR of x1 and x2
    """

def bitwise_not(x):
    """
    Element-wise bitwise NOT operation.
    
    Parameters:
    - x: sparse integer array
    
    Returns:
    Sparse array with bitwise complement of x
    """

def bitwise_invert(x):
    """
    Element-wise bitwise inversion (alias for bitwise_not).
    
    Parameters:
    - x: sparse integer array
    
    Returns:
    Sparse array with bitwise complement of x
    """

def bitwise_left_shift(x1, x2):
    """
    Element-wise left bit shift operation.
    
    Parameters:
    - x1: sparse integer array, values to shift
    - x2: sparse integer array, shift amounts
    
    Returns:
    Sparse array with x1 left-shifted by x2 positions
    """

def bitwise_right_shift(x1, x2):
    """
    Element-wise right bit shift operation.
    
    Parameters:
    - x1: sparse integer array, values to shift
    - x2: sparse integer array, shift amounts
    
    Returns:
    Sparse array with x1 right-shifted by x2 positions
    """

Usage Examples

Basic Arithmetic

import sparse
import numpy as np

# Create sparse arrays
a = sparse.COO.from_numpy(np.array([[1, 0, 3], [0, 2, 0]]))
b = sparse.COO.from_numpy(np.array([[2, 1, 0], [1, 0, 3]]))

# Arithmetic operations
sum_result = sparse.add(a, b)              # Element-wise addition
diff_result = sparse.subtract(a, b)        # Element-wise subtraction  
prod_result = sparse.multiply(a, b)        # Element-wise multiplication

# Operations with scalars
scaled = sparse.multiply(a, 3.14)          # Scale by scalar
shifted = sparse.add(a, 1.0)               # Add scalar to all elements

print(f"Sum nnz: {sum_result.nnz}")       # Non-zero count in result
print(f"Product nnz: {prod_result.nnz}")  # Sparsity preserved in multiplication

Mathematical Functions

# Trigonometric operations
angles = sparse.COO.from_numpy(np.array([[0, np.pi/4], [np.pi/2, np.pi]]))
sin_vals = sparse.sin(angles)
cos_vals = sparse.cos(angles)

# Exponential and logarithmic functions
x = sparse.random((50, 50), density=0.1) + 1.0  # Ensure positive values
exp_x = sparse.exp(x)
log_x = sparse.log(x)
sqrt_x = sparse.sqrt(x)

print(f"Original range: [{sparse.min(x).todense():.2f}, {sparse.max(x).todense():.2f}]")
print(f"Log range: [{sparse.min(log_x).todense():.2f}, {sparse.max(log_x).todense():.2f}]")

Comparison and Logical Operations

# Create test arrays
x = sparse.random((10, 10), density=0.2)
y = sparse.random((10, 10), density=0.2)

# Comparison operations
greater_mask = sparse.greater(x, y)
equal_mask = sparse.equal(x, 0.0)  # Find zeros

# Logical operations on boolean arrays
combined_mask = sparse.logical_and(greater_mask, 
                                 sparse.logical_not(equal_mask))

print(f"Elements where x > y: {sparse.sum(greater_mask).todense()}")
print(f"Zero elements: {sparse.sum(equal_mask).todense()}")

Complex Mathematical Operations

# Complex number operations
complex_array = sparse.COO.from_numpy(np.array([[1+2j, 0], [3-1j, 2+0j]]))
conjugate = sparse.conj(complex_array)
magnitude = sparse.abs(complex_array)

# Advanced mathematical functions  
x = sparse.random((100, 100), density=0.05)
# Avoid log(0) by adding small value to sparse elements only
x_positive = sparse.COO(x.coords, x.data + 1e-10, x.shape)
complex_result = sparse.exp(sparse.multiply(1j, sparse.log(x_positive)))

print(f"Complex array conjugate nnz: {conjugate.nnz}")
print(f"Complex result nnz: {complex_result.nnz}")

Sparsity Preservation

Mathematical operations in sparse preserve sparsity structure when mathematically valid:

Multiplication: sparse * 0 results in true zeros (removed from storage)
Addition: sparse + 0 preserves original sparsity
Trigonometric: sin(sparse) where sparse contains zeros becomes sin(0) = 0
Logarithmic: Operations may increase density (e.g., log(sparse + 1))
Comparisons: May result in different sparsity patterns based on comparison results