0
# Mathematical Operations
1
2
Comprehensive mathematical functions including arithmetic, trigonometric, logarithmic, and specialized operations with automatic unit propagation, uncertainty handling, and element-wise computation. All operations preserve dimensional labels and propagate units according to physical laws.
3
4
## Capabilities
5
6
### Arithmetic Operations
7
8
Basic arithmetic operations with automatic unit propagation and uncertainty handling.
9
10
```python { .api }
11
def add(x, y):
12
"""
13
Element-wise addition with unit checking
14
15
Args:
16
x (Variable or DataArray): First operand
17
y (Variable or DataArray): Second operand
18
19
Returns:
20
Variable or DataArray: Element-wise sum
21
22
Raises:
23
UnitError: If units are incompatible
24
"""
25
26
def subtract(x, y):
27
"""
28
Element-wise subtraction with unit checking
29
30
Args:
31
x (Variable or DataArray): First operand
32
y (Variable or DataArray): Second operand
33
34
Returns:
35
Variable or DataArray: Element-wise difference
36
37
Raises:
38
UnitError: If units are incompatible
39
"""
40
41
def multiply(x, y):
42
"""
43
Element-wise multiplication with unit multiplication
44
45
Args:
46
x (Variable or DataArray): First operand
47
y (Variable or DataArray): Second operand
48
49
Returns:
50
Variable or DataArray: Element-wise product
51
"""
52
53
def divide(x, y):
54
"""
55
Element-wise division with unit division
56
57
Args:
58
x (Variable or DataArray): Dividend
59
y (Variable or DataArray): Divisor
60
61
Returns:
62
Variable or DataArray: Element-wise quotient
63
"""
64
65
def floor_divide(x, y):
66
"""
67
Element-wise floor division
68
69
Args:
70
x (Variable or DataArray): Dividend
71
y (Variable or DataArray): Divisor
72
73
Returns:
74
Variable or DataArray: Element-wise floor quotient
75
"""
76
77
def mod(x, y):
78
"""
79
Element-wise modulo operation
80
81
Args:
82
x (Variable or DataArray): Dividend
83
y (Variable or DataArray): Divisor
84
85
Returns:
86
Variable or DataArray: Element-wise remainder
87
"""
88
89
def negative(x):
90
"""
91
Element-wise negation
92
93
Args:
94
x (Variable or DataArray): Input
95
96
Returns:
97
Variable or DataArray: Element-wise negation
98
"""
99
```
100
101
### Power and Root Functions
102
103
Exponential and root operations with proper unit handling.
104
105
```python { .api }
106
def pow(x, y):
107
"""
108
Element-wise power operation
109
110
Args:
111
x (Variable or DataArray): Base
112
y (Variable or DataArray): Exponent (must be dimensionless)
113
114
Returns:
115
Variable or DataArray: x raised to power y
116
117
Raises:
118
UnitError: If exponent has units
119
"""
120
121
def sqrt(x):
122
"""
123
Element-wise square root
124
125
Args:
126
x (Variable or DataArray): Input
127
128
Returns:
129
Variable or DataArray: Element-wise square root
130
"""
131
132
def reciprocal(x):
133
"""
134
Element-wise reciprocal (1/x)
135
136
Args:
137
x (Variable or DataArray): Input
138
139
Returns:
140
Variable or DataArray: Element-wise reciprocal
141
"""
142
```
143
144
### Exponential and Logarithmic Functions
145
146
Exponential and logarithmic operations requiring dimensionless inputs.
147
148
```python { .api }
149
def exp(x):
150
"""
151
Element-wise exponential function
152
153
Args:
154
x (Variable or DataArray): Input (must be dimensionless)
155
156
Returns:
157
Variable or DataArray: e^x
158
159
Raises:
160
UnitError: If input has units
161
"""
162
163
def log(x):
164
"""
165
Element-wise natural logarithm
166
167
Args:
168
x (Variable or DataArray): Input (must be dimensionless and positive)
169
170
Returns:
171
Variable or DataArray: ln(x)
172
173
Raises:
174
UnitError: If input has units
175
"""
176
177
def log10(x):
178
"""
179
Element-wise base-10 logarithm
180
181
Args:
182
x (Variable or DataArray): Input (must be dimensionless and positive)
183
184
Returns:
185
Variable or DataArray: log10(x)
186
187
Raises:
188
UnitError: If input has units
189
"""
190
```
191
192
### Rounding Functions
193
194
Functions for rounding and truncating values.
195
196
```python { .api }
197
def round(x, decimals=0):
198
"""
199
Element-wise rounding
200
201
Args:
202
x (Variable or DataArray): Input
203
decimals (int): Number of decimal places
204
205
Returns:
206
Variable or DataArray: Rounded values
207
"""
208
209
def floor(x):
210
"""
211
Element-wise floor operation
212
213
Args:
214
x (Variable or DataArray): Input
215
216
Returns:
217
Variable or DataArray: Floor values
218
"""
219
220
def ceil(x):
221
"""
222
Element-wise ceiling operation
223
224
Args:
225
x (Variable or DataArray): Input
226
227
Returns:
228
Variable or DataArray: Ceiling values
229
"""
230
```
231
232
### Trigonometric Functions
233
234
Trigonometric functions with proper angle unit handling.
235
236
```python { .api }
237
def sin(x):
238
"""
239
Element-wise sine
240
241
Args:
242
x (Variable or DataArray): Angle (rad or deg units)
243
244
Returns:
245
Variable or DataArray: sin(x) (dimensionless)
246
247
Raises:
248
UnitError: If input is not an angle
249
"""
250
251
def cos(x):
252
"""
253
Element-wise cosine
254
255
Args:
256
x (Variable or DataArray): Angle (rad or deg units)
257
258
Returns:
259
Variable or DataArray: cos(x) (dimensionless)
260
261
Raises:
262
UnitError: If input is not an angle
263
"""
264
265
def tan(x):
266
"""
267
Element-wise tangent
268
269
Args:
270
x (Variable or DataArray): Angle (rad or deg units)
271
272
Returns:
273
Variable or DataArray: tan(x) (dimensionless)
274
275
Raises:
276
UnitError: If input is not an angle
277
"""
278
279
def asin(x):
280
"""
281
Element-wise arcsine
282
283
Args:
284
x (Variable or DataArray): Input (dimensionless, [-1, 1])
285
286
Returns:
287
Variable or DataArray: arcsin(x) in radians
288
289
Raises:
290
UnitError: If input has units
291
"""
292
293
def acos(x):
294
"""
295
Element-wise arccosine
296
297
Args:
298
x (Variable or DataArray): Input (dimensionless, [-1, 1])
299
300
Returns:
301
Variable or DataArray: arccos(x) in radians
302
303
Raises:
304
UnitError: If input has units
305
"""
306
307
def atan(x):
308
"""
309
Element-wise arctangent
310
311
Args:
312
x (Variable or DataArray): Input (dimensionless)
313
314
Returns:
315
Variable or DataArray: arctan(x) in radians
316
317
Raises:
318
UnitError: If input has units
319
"""
320
321
def atan2(y, x):
322
"""
323
Element-wise two-argument arctangent
324
325
Args:
326
y (Variable or DataArray): Y coordinates
327
x (Variable or DataArray): X coordinates (same units as y)
328
329
Returns:
330
Variable or DataArray: atan2(y, x) in radians
331
332
Raises:
333
UnitError: If x and y have different units
334
"""
335
```
336
337
### Hyperbolic Functions
338
339
Hyperbolic trigonometric functions for dimensionless inputs.
340
341
```python { .api }
342
def sinh(x):
343
"""
344
Element-wise hyperbolic sine
345
346
Args:
347
x (Variable or DataArray): Input (dimensionless)
348
349
Returns:
350
Variable or DataArray: sinh(x)
351
352
Raises:
353
UnitError: If input has units
354
"""
355
356
def cosh(x):
357
"""
358
Element-wise hyperbolic cosine
359
360
Args:
361
x (Variable or DataArray): Input (dimensionless)
362
363
Returns:
364
Variable or DataArray: cosh(x)
365
366
Raises:
367
UnitError: If input has units
368
"""
369
370
def tanh(x):
371
"""
372
Element-wise hyperbolic tangent
373
374
Args:
375
x (Variable or DataArray): Input (dimensionless)
376
377
Returns:
378
Variable or DataArray: tanh(x)
379
380
Raises:
381
UnitError: If input has units
382
"""
383
384
def asinh(x):
385
"""
386
Element-wise inverse hyperbolic sine
387
388
Args:
389
x (Variable or DataArray): Input (dimensionless)
390
391
Returns:
392
Variable or DataArray: asinh(x)
393
394
Raises:
395
UnitError: If input has units
396
"""
397
398
def acosh(x):
399
"""
400
Element-wise inverse hyperbolic cosine
401
402
Args:
403
x (Variable or DataArray): Input (dimensionless, >= 1)
404
405
Returns:
406
Variable or DataArray: acosh(x)
407
408
Raises:
409
UnitError: If input has units
410
"""
411
412
def atanh(x):
413
"""
414
Element-wise inverse hyperbolic tangent
415
416
Args:
417
x (Variable or DataArray): Input (dimensionless, (-1, 1))
418
419
Returns:
420
Variable or DataArray: atanh(x)
421
422
Raises:
423
UnitError: If input has units
424
"""
425
```
426
427
### Special Mathematical Functions
428
429
Specialized mathematical functions for scientific computing.
430
431
```python { .api }
432
def abs(x):
433
"""
434
Element-wise absolute value
435
436
Args:
437
x (Variable or DataArray): Input
438
439
Returns:
440
Variable or DataArray: |x|
441
"""
442
443
def erf(x):
444
"""
445
Element-wise error function
446
447
Args:
448
x (Variable or DataArray): Input (dimensionless)
449
450
Returns:
451
Variable or DataArray: erf(x)
452
453
Raises:
454
UnitError: If input has units
455
"""
456
457
def erfc(x):
458
"""
459
Element-wise complementary error function
460
461
Args:
462
x (Variable or DataArray): Input (dimensionless)
463
464
Returns:
465
Variable or DataArray: erfc(x) = 1 - erf(x)
466
467
Raises:
468
UnitError: If input has units
469
"""
470
471
def nan_to_num(x, *, nan=0.0, posinf=None, neginf=None):
472
"""
473
Replace NaN and infinity with finite numbers
474
475
Args:
476
x (Variable or DataArray): Input
477
nan: Value to replace NaN with
478
posinf: Value to replace positive infinity with
479
neginf: Value to replace negative infinity with
480
481
Returns:
482
Variable or DataArray: Array with finite values
483
"""
484
```
485
486
### Vector Operations
487
488
Operations specific to vector data types and multi-dimensional analysis.
489
490
```python { .api }
491
def dot(x, y):
492
"""
493
Dot product of vectors
494
495
Args:
496
x (Variable or DataArray): First vector
497
y (Variable or DataArray): Second vector
498
499
Returns:
500
Variable or DataArray: Dot product
501
"""
502
503
def cross(x, y):
504
"""
505
Cross product of 3D vectors
506
507
Args:
508
x (Variable or DataArray): First 3D vector
509
y (Variable or DataArray): Second 3D vector
510
511
Returns:
512
Variable or DataArray: Cross product (3D vector)
513
"""
514
515
def norm(x):
516
"""
517
L2 norm of vectors
518
519
Args:
520
x (Variable or DataArray): Vector data
521
522
Returns:
523
Variable or DataArray: L2 norm
524
"""
525
526
def midpoints(x, dim):
527
"""
528
Calculate midpoints between adjacent elements
529
530
Args:
531
x (Variable or DataArray): Input array
532
dim (str): Dimension along which to calculate midpoints
533
534
Returns:
535
Variable or DataArray: Midpoint values
536
"""
537
```
538
539
## Usage Examples
540
541
### Basic Arithmetic with Units
542
543
```python
544
import scipp as sc
545
546
# Create physical quantities
547
distance = sc.array(dims=['x'], values=[1, 2, 3], unit='m')
548
time = sc.array(dims=['x'], values=[0.5, 1.0, 1.5], unit='s')
549
550
# Calculate velocity (units automatically computed)
551
velocity = distance / time # Result has unit 'm/s'
552
553
# Add compatible quantities
554
total_distance = distance + sc.array(dims=['x'], values=[0.5, 0.5, 0.5], unit='m')
555
556
# Multiply by dimensionless factor
557
doubled = distance * 2 # Units preserved
558
```
559
560
### Mathematical Functions with Uncertainty Propagation
561
562
```python
563
import numpy as np
564
565
# Create data with uncertainties
566
angles = sc.array(
567
dims=['angle'],
568
values=np.linspace(0, np.pi, 10),
569
variances=np.full(10, 0.01), # Small uncertainties
570
unit='rad'
571
)
572
573
# Apply trigonometric functions (uncertainties propagated automatically)
574
sin_values = sc.sin(angles) # Dimensionless result
575
cos_values = sc.cos(angles) # Dimensionless result
576
577
# Combine with arithmetic
578
amplitude = sc.scalar(2.5, variance=0.01, unit='V')
579
signal = amplitude * sin_values # Result in volts with propagated uncertainty
580
```
581
582
### Vector Operations
583
584
```python
585
# Create 3D vectors
586
vec1 = sc.vectors(dims=['point'], values=[[1, 0, 0], [0, 1, 0], [0, 0, 1]], unit='m')
587
vec2 = sc.vectors(dims=['point'], values=[[1, 1, 0], [1, 0, 1], [0, 1, 1]], unit='m')
588
589
# Vector operations
590
dot_products = sc.dot(vec1, vec2) # Dot product in m^2
591
cross_products = sc.cross(vec1, vec2) # Cross product in m^2
592
magnitudes = sc.norm(vec1) # Vector magnitudes in m
593
```
594
595
### Logarithmic and Exponential Operations
596
597
```python
598
# Create dimensionless data for logarithmic functions
599
ratios = sc.array(dims=['measurement'], values=[0.1, 1.0, 10.0])
600
601
# Apply logarithmic functions
602
ln_ratios = sc.log(ratios) # Natural logarithm
603
log10_ratios = sc.log10(ratios) # Base-10 logarithm
604
605
# Exponential operations
606
exp_values = sc.exp(ln_ratios) # Should recover original ratios
607
608
# Power operations with proper unit handling
609
squared = sc.pow(distance, 2) # Result in m^2
610
```
611
612
### Complex Mathematical Workflows
613
614
```python
615
# Scientific data processing workflow
616
raw_signal = sc.array(
617
dims=['time'],
618
values=np.sin(np.linspace(0, 4*np.pi, 100)) + 0.1*np.random.random(100),
619
unit='V'
620
)
621
622
# Apply mathematical transformations
623
normalized = raw_signal / sc.max(sc.abs(raw_signal)) # Normalize to [-1, 1]
624
squared = sc.pow(normalized, 2) # Square the signal
625
smoothed = sc.sqrt(squared) # Smooth via absolute value
626
627
# Phase analysis
628
time_coord = sc.linspace('time', 0, 4*np.pi, 100, unit='s')
629
phase = sc.atan2(raw_signal, sc.cos(time_coord)) # Calculate phase
630
```