0
# Mathematical Operations
1

2
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.
3

4
## Capabilities
5

6
### Arithmetic Operations
7

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

10
```python { .api }
11
def add(x1, x2):
12
    """
13
    Element-wise addition of sparse arrays.
14
    
15
    Parameters:
16
    - x1, x2: sparse arrays or scalars to add
17
    
18
    Returns:
19
    Sparse array with element-wise sum
20
    """
21

22
def subtract(x1, x2):
23
    """
24
    Element-wise subtraction of sparse arrays.
25
    
26
    Parameters:
27
    - x1, x2: sparse arrays or scalars, computes x1 - x2
28
    
29
    Returns:
30
    Sparse array with element-wise difference
31
    """
32

33
def multiply(x1, x2):
34
    """
35
    Element-wise multiplication of sparse arrays.
36
    
37
    Parameters:
38
    - x1, x2: sparse arrays or scalars to multiply
39
    
40
    Returns:
41
    Sparse array with element-wise product
42
    """
43

44
def divide(x1, x2):
45
    """
46
    Element-wise division of sparse arrays.
47
    
48
    Parameters:
49
    - x1, x2: sparse arrays or scalars, computes x1 / x2
50
    
51
    Returns:
52
    Sparse array with element-wise quotient
53
    """
54

55
def floor_divide(x1, x2):
56
    """
57
    Element-wise floor division of sparse arrays.
58
    
59
    Parameters:
60
    - x1, x2: sparse arrays or scalars, computes x1 // x2
61
    
62
    Returns:
63
    Sparse array with element-wise floor division
64
    """
65

66
def remainder(x1, x2):
67
    """
68
    Element-wise remainder of sparse arrays.
69
    
70
    Parameters:
71
    - x1, x2: sparse arrays or scalars, computes x1 % x2
72
    
73
    Returns:
74
    Sparse array with element-wise remainder
75
    """
76

77
def pow(x1, x2):
78
    """
79
    Element-wise power operation.
80
    
81
    Parameters:
82
    - x1: sparse array or scalar, base values
83
    - x2: sparse array or scalar, exponent values
84
    
85
    Returns:
86
    Sparse array with x1 raised to power x2
87
    """
88
```
89

90
### Trigonometric Functions
91

92
Trigonometric functions operating element-wise on sparse arrays.
93

94
```python { .api }
95
def sin(x):
96
    """
97
    Element-wise sine function.
98
    
99
    Parameters:
100
    - x: sparse array, input angles in radians
101
    
102
    Returns:
103
    Sparse array with sine values
104
    """
105

106
def cos(x):
107
    """
108
    Element-wise cosine function.
109
    
110
    Parameters:
111
    - x: sparse array, input angles in radians
112
    
113
    Returns:
114
    Sparse array with cosine values
115
    """
116

117
def tan(x):
118
    """
119
    Element-wise tangent function.
120
    
121
    Parameters:
122
    - x: sparse array, input angles in radians
123
    
124
    Returns:
125
    Sparse array with tangent values
126
    """
127

128
def sinh(x):
129
    """
130
    Element-wise hyperbolic sine function.
131
    
132
    Parameters:
133
    - x: sparse array, input values
134
    
135
    Returns:
136
    Sparse array with hyperbolic sine values
137
    """
138

139
def cosh(x):
140
    """
141
    Element-wise hyperbolic cosine function.
142
    
143
    Parameters:
144
    - x: sparse array, input values
145
    
146
    Returns:
147
    Sparse array with hyperbolic cosine values
148
    """
149

150
def tanh(x):
151
    """
152
    Element-wise hyperbolic tangent function.
153
    
154
    Parameters:
155
    - x: sparse array, input values
156
    
157
    Returns:
158
    Sparse array with hyperbolic tangent values
159
    """
160
```
161

162
### Inverse Trigonometric Functions
163

164
Inverse trigonometric functions for sparse arrays.
165

166
```python { .api }
167
def asin(x):
168
    """
169
    Element-wise inverse sine function.
170
    
171
    Parameters:
172
    - x: sparse array, input values in range [-1, 1]
173
    
174
    Returns:
175
    Sparse array with arcsine values in radians
176
    """
177

178
def acos(x):
179
    """
180
    Element-wise inverse cosine function.
181
    
182
    Parameters:
183
    - x: sparse array, input values in range [-1, 1]
184
    
185
    Returns:
186
    Sparse array with arccosine values in radians
187
    """
188

189
def atan(x):
190
    """
191
    Element-wise inverse tangent function.
192
    
193
    Parameters:
194
    - x: sparse array, input values
195
    
196
    Returns:
197
    Sparse array with arctangent values in radians
198
    """
199

200
def atan2(y, x):
201
    """
202
    Element-wise 2-argument inverse tangent.
203
    
204
    Parameters:
205
    - y: sparse array, y-coordinates
206
    - x: sparse array, x-coordinates
207
    
208
    Returns:
209
    Sparse array with arctangent of y/x in correct quadrant
210
    """
211

212
def asinh(x):
213
    """
214
    Element-wise inverse hyperbolic sine function.
215
    
216
    Parameters:
217
    - x: sparse array, input values
218
    
219
    Returns:
220
    Sparse array with inverse hyperbolic sine values
221
    """
222

223
def acosh(x):
224
    """
225
    Element-wise inverse hyperbolic cosine function.
226
    
227
    Parameters:
228
    - x: sparse array, input values >= 1
229
    
230
    Returns:
231
    Sparse array with inverse hyperbolic cosine values
232
    """
233

234
def atanh(x):
235
    """
236
    Element-wise inverse hyperbolic tangent function.
237
    
238
    Parameters:
239
    - x: sparse array, input values in range (-1, 1)
240
    
241
    Returns:
242
    Sparse array with inverse hyperbolic tangent values
243
    """
244
```
245

246
### Exponential and Logarithmic Functions
247

248
Exponential and logarithmic functions for sparse arrays.
249

250
```python { .api }
251
def exp(x):
252
    """
253
    Element-wise exponential function.
254
    
255
    Parameters:
256
    - x: sparse array, input values
257
    
258
    Returns:
259
    Sparse array with e^x values
260
    """
261

262
def expm1(x):
263
    """
264
    Element-wise exp(x) - 1, computed accurately for small x.
265
    
266
    Parameters:
267
    - x: sparse array, input values
268
    
269
    Returns:
270
    Sparse array with exp(x) - 1 values
271
    """
272

273
def log(x):
274
    """
275
    Element-wise natural logarithm.
276
    
277
    Parameters:
278
    - x: sparse array, input values > 0
279
    
280
    Returns:
281
    Sparse array with natural log values
282
    """
283

284
def log1p(x):
285
    """
286
    Element-wise log(1 + x), computed accurately for small x.
287
    
288
    Parameters:
289
    - x: sparse array, input values > -1
290
    
291
    Returns:
292
    Sparse array with log(1 + x) values
293
    """
294

295
def log2(x):
296
    """
297
    Element-wise base-2 logarithm.
298
    
299
    Parameters:
300
    - x: sparse array, input values > 0
301
    
302
    Returns:
303
    Sparse array with base-2 log values
304
    """
305

306
def log10(x):
307
    """
308
    Element-wise base-10 logarithm.
309
    
310
    Parameters:
311
    - x: sparse array, input values > 0
312
    
313
    Returns:
314
    Sparse array with base-10 log values
315
    """
316

317
def logaddexp(x1, x2):
318
    """
319
    Element-wise log(exp(x1) + exp(x2)).
320
    
321
    Parameters:
322
    - x1, x2: sparse arrays, input values
323
    
324
    Returns:
325
    Sparse array with log(exp(x1) + exp(x2)) values
326
    """
327

328
def sqrt(x):
329
    """
330
    Element-wise square root function.
331
    
332
    Parameters:
333
    - x: sparse array, input values >= 0
334
    
335
    Returns:
336
    Sparse array with square root values
337
    """
338

339
def square(x):
340
    """
341
    Element-wise square function.
342
    
343
    Parameters:
344
    - x: sparse array, input values
345
    
346
    Returns:
347
    Sparse array with squared values
348
    """
349
```
350

351
### Other Mathematical Functions
352

353
Additional mathematical functions for sparse arrays.
354

355
```python { .api }
356
def abs(x):
357
    """
358
    Element-wise absolute value function.
359
    
360
    Parameters:
361
    - x: sparse array, input values
362
    
363
    Returns:
364
    Sparse array with absolute values
365
    """
366

367
def sign(x):
368
    """
369
    Element-wise sign function (-1, 0, or 1).
370
    
371
    Parameters:
372
    - x: sparse array, input values
373
    
374
    Returns:
375
    Sparse array with sign values
376
    """
377

378
def signbit(x):
379
    """
380
    Element-wise sign bit test.
381
    
382
    Parameters:
383
    - x: sparse array, input values
384
    
385
    Returns:
386
    Sparse array with True where sign bit is set
387
    """
388

389
def positive(x):
390
    """
391
    Element-wise unary positive (+x).
392
    
393
    Parameters:
394
    - x: sparse array, input values
395
    
396
    Returns:
397
    Sparse array, copy of input
398
    """
399

400
def negative(x):
401
    """
402
    Element-wise unary negative (-x).
403
    
404
    Parameters:
405
    - x: sparse array, input values
406
    
407
    Returns:
408
    Sparse array with negated values
409
    """
410

411
def reciprocal(x):
412
    """
413
    Element-wise reciprocal (1/x).
414
    
415
    Parameters:
416
    - x: sparse array, input values != 0
417
    
418
    Returns:
419
    Sparse array with reciprocal values
420
    """
421

422
def conj(x):
423
    """
424
    Element-wise complex conjugate.
425
    
426
    Parameters:
427
    - x: sparse array, input values (real or complex)
428
    
429
    Returns:
430
    Sparse array with complex conjugate values
431
    """
432
```
433

434
### Rounding and Related Functions
435

436
Functions for rounding and related operations.
437

438
```python { .api }
439
def ceil(x):
440
    """
441
    Element-wise ceiling function.
442
    
443
    Parameters:
444
    - x: sparse array, input values
445
    
446
    Returns:
447
    Sparse array with ceiling values (smallest integer >= x)
448
    """
449

450
def floor(x):
451
    """
452
    Element-wise floor function.
453
    
454
    Parameters:
455
    - x: sparse array, input values
456
    
457
    Returns:
458
    Sparse array with floor values (largest integer <= x)
459
    """
460

461
def trunc(x):
462
    """
463
    Element-wise truncation to integer.
464
    
465
    Parameters:
466
    - x: sparse array, input values
467
    
468
    Returns:
469
    Sparse array with truncated values
470
    """
471

472
def round(x, decimals=0):
473
    """
474
    Element-wise rounding to given number of decimals.
475
    
476
    Parameters:
477
    - x: sparse array, input values
478
    - decimals: int, number of decimal places
479
    
480
    Returns:
481
    Sparse array with rounded values
482
    """
483
```
484

485
### Floating Point Utilities
486

487
Utility functions for floating point operations.
488

489
```python { .api }
490
def copysign(x1, x2):
491
    """
492
    Element-wise copy sign of x2 to x1.
493
    
494
    Parameters:
495
    - x1: sparse array, magnitude values
496
    - x2: sparse array, sign values
497
    
498
    Returns:
499
    Sparse array with magnitude of x1 and sign of x2
500
    """
501

502
def nextafter(x1, x2):
503
    """
504
    Element-wise next representable floating point value.
505
    
506
    Parameters:
507
    - x1: sparse array, starting values
508
    - x2: sparse array, direction values
509
    
510
    Returns:
511
    Sparse array with next representable values toward x2
512
    """
513

514
def hypot(x1, x2):
515
    """
516
    Element-wise Euclidean distance sqrt(x1²+x2²).
517
    
518
    Parameters:
519
    - x1, x2: sparse arrays, input values
520
    
521
    Returns:
522
    Sparse array with Euclidean distances
523
    """
524
```
525

526
### Comparison Operations
527

528
Element-wise comparison functions returning boolean sparse arrays.
529

530
```python { .api }
531
def equal(x1, x2):
532
    """
533
    Element-wise equality comparison.
534
    
535
    Parameters:
536
    - x1, x2: sparse arrays or scalars to compare
537
    
538
    Returns:
539
    Sparse boolean array with True where x1 == x2
540
    """
541

542
def not_equal(x1, x2):
543
    """
544
    Element-wise inequality comparison.
545
    
546
    Parameters:
547
    - x1, x2: sparse arrays or scalars to compare
548
    
549
    Returns:
550
    Sparse boolean array with True where x1 != x2
551
    """
552

553
def less(x1, x2):
554
    """
555
    Element-wise less-than comparison.
556
    
557
    Parameters:
558
    - x1, x2: sparse arrays or scalars to compare
559
    
560
    Returns:
561
    Sparse boolean array with True where x1 < x2
562
    """
563

564
def less_equal(x1, x2):
565
    """
566
    Element-wise less-than-or-equal comparison.
567
    
568
    Parameters:
569
    - x1, x2: sparse arrays or scalars to compare
570
    
571
    Returns:
572
    Sparse boolean array with True where x1 <= x2
573
    """
574

575
def greater(x1, x2):
576
    """
577
    Element-wise greater-than comparison.
578
    
579
    Parameters:
580
    - x1, x2: sparse arrays or scalars to compare
581
    
582
    Returns:
583
    Sparse boolean array with True where x1 > x2
584
    """
585

586
def greater_equal(x1, x2):
587
    """
588
    Element-wise greater-than-or-equal comparison.
589
    
590
    Parameters:
591
    - x1, x2: sparse arrays or scalars to compare
592
    
593
    Returns:
594
    Sparse boolean array with True where x1 >= x2
595
    """
596
```
597

598
### Logical Operations
599

600
Element-wise logical operations on boolean sparse arrays.
601

602
```python { .api }
603
def logical_and(x1, x2):
604
    """
605
    Element-wise logical AND operation.
606
    
607
    Parameters:
608
    - x1, x2: sparse boolean arrays
609
    
610
    Returns:
611
    Sparse boolean array with True where both x1 and x2 are True
612
    """
613

614
def logical_or(x1, x2):
615
    """
616
    Element-wise logical OR operation.
617
    
618
    Parameters:
619
    - x1, x2: sparse boolean arrays
620
    
621
    Returns:
622
    Sparse boolean array with True where x1 or x2 is True
623
    """
624

625
def logical_not(x):
626
    """
627
    Element-wise logical NOT operation.
628
    
629
    Parameters:
630
    - x: sparse boolean array
631
    
632
    Returns:
633
    Sparse boolean array with negated boolean values
634
    """
635

636
def logical_xor(x1, x2):
637
    """
638
    Element-wise logical XOR operation.
639
    
640
    Parameters:
641
    - x1, x2: sparse boolean arrays
642
    
643
    Returns:
644
    Sparse boolean array with True where exactly one of x1, x2 is True
645
    """
646
```
647

648
### Bitwise Operations
649

650
Element-wise bitwise operations on integer sparse arrays.
651

652
```python { .api }
653
def bitwise_and(x1, x2):
654
    """
655
    Element-wise bitwise AND operation.
656
    
657
    Parameters:
658
    - x1, x2: sparse integer arrays
659
    
660
    Returns:
661
    Sparse array with bitwise AND of x1 and x2
662
    """
663

664
def bitwise_or(x1, x2):
665
    """
666
    Element-wise bitwise OR operation.
667
    
668
    Parameters:
669
    - x1, x2: sparse integer arrays
670
    
671
    Returns:
672
    Sparse array with bitwise OR of x1 and x2
673
    """
674

675
def bitwise_xor(x1, x2):
676
    """
677
    Element-wise bitwise XOR operation.
678
    
679
    Parameters:
680
    - x1, x2: sparse integer arrays
681
    
682
    Returns:
683
    Sparse array with bitwise XOR of x1 and x2
684
    """
685

686
def bitwise_not(x):
687
    """
688
    Element-wise bitwise NOT operation.
689
    
690
    Parameters:
691
    - x: sparse integer array
692
    
693
    Returns:
694
    Sparse array with bitwise complement of x
695
    """
696

697
def bitwise_invert(x):
698
    """
699
    Element-wise bitwise inversion (alias for bitwise_not).
700
    
701
    Parameters:
702
    - x: sparse integer array
703
    
704
    Returns:
705
    Sparse array with bitwise complement of x
706
    """
707

708
def bitwise_left_shift(x1, x2):
709
    """
710
    Element-wise left bit shift operation.
711
    
712
    Parameters:
713
    - x1: sparse integer array, values to shift
714
    - x2: sparse integer array, shift amounts
715
    
716
    Returns:
717
    Sparse array with x1 left-shifted by x2 positions
718
    """
719

720
def bitwise_right_shift(x1, x2):
721
    """
722
    Element-wise right bit shift operation.
723
    
724
    Parameters:
725
    - x1: sparse integer array, values to shift
726
    - x2: sparse integer array, shift amounts
727
    
728
    Returns:
729
    Sparse array with x1 right-shifted by x2 positions
730
    """
731
```
732

733
## Usage Examples
734

735
### Basic Arithmetic
736

737
```python
738
import sparse
739
import numpy as np
740

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

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

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

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

758
### Mathematical Functions
759

760
```python
761
# Trigonometric operations
762
angles = sparse.COO.from_numpy(np.array([[0, np.pi/4], [np.pi/2, np.pi]]))
763
sin_vals = sparse.sin(angles)
764
cos_vals = sparse.cos(angles)
765

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

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

776
### Comparison and Logical Operations
777

778
```python
779
# Create test arrays
780
x = sparse.random((10, 10), density=0.2)
781
y = sparse.random((10, 10), density=0.2)
782

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

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

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

795
### Complex Mathematical Operations
796

797
```python
798
# Complex number operations
799
complex_array = sparse.COO.from_numpy(np.array([[1+2j, 0], [3-1j, 2+0j]]))
800
conjugate = sparse.conj(complex_array)
801
magnitude = sparse.abs(complex_array)
802

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

809
print(f"Complex array conjugate nnz: {conjugate.nnz}")
810
print(f"Complex result nnz: {complex_result.nnz}")
811
```
812

813
## Sparsity Preservation
814

815
Mathematical operations in sparse preserve sparsity structure when mathematically valid:
816

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