Coverage for install/scipp/core/math.py: 45%
42 statements
« prev ^ index » next coverage.py v7.6.1, created at 2024-11-17 01:51 +0000
1# SPDX-License-Identifier: BSD-3-Clause
2# Copyright (c) 2023 Scipp contributors (https://github.com/scipp)
3# @author Simon Heybrock
4from __future__ import annotations
6from numbers import Real
8from .._scipp import core as _cpp
9from ..typing import VariableLike, VariableLikeType
10from ._cpp_wrapper_util import call_func as _call_cpp_func
11from .variable import scalar
14def abs(
15 x: VariableLike | _cpp.Unit, *, out: _cpp.Variable | None = None
16) -> VariableLike | _cpp.Unit:
17 """Element-wise absolute value.
19 Parameters
20 ----------
21 x:
22 Input data.
23 out:
24 Optional output buffer. Only supported if `x` is a scipp.Variable.
26 Raises
27 ------
28 scipp.DTypeError
29 If the dtype has no absolute value, e.g., if it is a string.
31 Returns
32 -------
33 :
34 The absolute values of the input.
36 See Also
37 --------
38 scipp.norm
39 """
40 return _call_cpp_func(_cpp.abs, x, out=out)
43def cross(x: VariableLike, y: VariableLike) -> VariableLike:
44 """Element-wise cross product.
46 Parameters
47 ----------
48 x:
49 Left hand side operand.
50 y:
51 Right hand side operand.
53 Raises
54 ------
55 scipp.DTypeError
56 If the dtype of the input is not vector3.
58 Returns
59 -------
60 :
61 The cross product of the input vectors.
62 """
63 return _call_cpp_func(_cpp.cross, x, y)
66def dot(x: VariableLike, y: VariableLike) -> VariableLike:
67 """Element-wise dot product.
69 Parameters
70 ----------
71 x:
72 Left hand side operand.
73 y:
74 Right hand side operand.
76 Raises
77 ------
78 scipp.DTypeError
79 If the dtype of the input is not vector3.
81 Returns
82 -------
83 :
84 The dot product of the input vectors.
85 """
86 return _call_cpp_func(_cpp.dot, x, y)
89def nan_to_num(
90 x: _cpp.Variable,
91 *,
92 nan: _cpp.Variable = None,
93 posinf: _cpp.Variable = None,
94 neginf: _cpp.Variable = None,
95 out: _cpp.Variable = None,
96) -> _cpp.Variable:
97 """Element-wise special value replacement.
99 All elements in the output are identical to input except in the presence
100 of a NaN, Inf or -Inf.
101 The function allows replacements to be separately specified for NaN, Inf
102 or -Inf values.
103 You can choose to replace a subset of those special values by providing
104 just the required keyword arguments.
106 Parameters
107 ----------
108 x:
109 Input data.
110 nan:
111 Replacement values for NaN in the input.
112 posinf:
113 Replacement values for Inf in the input.
114 neginf:
115 Replacement values for -Inf in the input.
116 out:
117 Optional output buffer.
119 Raises
120 ------
121 scipp.DTypeError
122 If the types of input and replacement do not match.
124 Returns
125 -------
126 :
127 Input with specified substitutions.
128 """
129 return _call_cpp_func(
130 _cpp.nan_to_num, x, nan=nan, posinf=posinf, neginf=neginf, out=out
131 )
134def norm(x: VariableLike) -> VariableLike:
135 """Element-wise norm.
137 Parameters
138 ----------
139 x:
140 Input data.
142 Raises
143 ------
144 scipp.DTypeError
145 If the dtype has no norm, i.e., if it is not a vector.
147 Returns
148 -------
149 :
150 Scalar elements computed as the norm values of the input elements.
151 """
152 return _call_cpp_func(_cpp.norm, x, out=None)
155def reciprocal(
156 x: VariableLike | _cpp.Unit, *, out: _cpp.Variable | None = None
157) -> VariableLike | _cpp.Unit:
158 """Element-wise reciprocal.
160 Parameters
161 ----------
162 x:
163 Input data.
164 out:
165 Optional output buffer. Only supported when `x` is a scipp.Variable.
167 Raises
168 ------
169 scipp.DTypeError
170 If the dtype has no reciprocal, e.g., if it is a string.
172 Returns
173 -------
174 :
175 The reciprocal values of the input.
176 """
177 return _call_cpp_func(_cpp.reciprocal, x, out=out)
180def pow(
181 base: VariableLike | _cpp.Unit, exponent: VariableLike | Real
182) -> VariableLike | _cpp.Unit:
183 """Element-wise power.
185 If the base has a unit, the exponent must be scalar in order to get
186 a well-defined unit in the result.
188 Parameters
189 ----------
190 base:
191 Base of the exponential.
192 exponent:
193 Raise ``base`` to this power.
195 Raises
196 ------
197 scipp.DTypeError
198 If the dtype does not have a power, e.g., if it is a string.
200 Returns
201 -------
202 :
203 ``base`` raised to the power of ``exp``.
204 """
205 if not isinstance(base, _cpp.Unit) and isinstance(exponent, Real):
206 exponent = scalar(exponent)
207 return _call_cpp_func(_cpp.pow, base, exponent)
210def sqrt(
211 x: VariableLike | _cpp.Unit, *, out: _cpp.Variable | None = None
212) -> VariableLike | _cpp.Unit:
213 """Element-wise square-root.
215 Parameters
216 ----------
217 x:
218 Input data.
219 out:
220 Optional output buffer. Only supported when `x` is a scipp.Variable.
222 Raises
223 ------
224 scipp.DTypeError
225 If the dtype has no square-root, e.g., if it is a string.
227 Returns
228 -------
229 :
230 The square-root values of the input.
231 """
232 return _call_cpp_func(_cpp.sqrt, x, out=out)
235def exp(x: VariableLike, *, out: VariableLike | None = None) -> VariableLike:
236 """Element-wise exponential.
238 Parameters
239 ----------
240 x:
241 Input data.
242 out:
243 Optional output buffer.
245 Returns
246 -------
247 :
248 e raised to the power of the input.
249 """
250 return _call_cpp_func(_cpp.exp, x, out=out)
253def log(x: VariableLike, *, out: VariableLike | None = None) -> VariableLike:
254 """Element-wise natural logarithm.
256 Parameters
257 ----------
258 x:
259 Input data.
260 out:
261 Optional output buffer.
263 Returns
264 -------
265 :
266 Base e logarithm of the input.
267 """
268 return _call_cpp_func(_cpp.log, x, out=out)
271def log10(x: VariableLike, *, out: VariableLike | None = None) -> VariableLike:
272 """Element-wise base 10 logarithm.
274 Parameters
275 ----------
276 x:
277 Input data.
278 out:
279 Optional output buffer.
281 Returns
282 -------
283 :
284 Base 10 logarithm of the input.
285 """
286 return _call_cpp_func(_cpp.log10, x, out=out)
289def round(
290 x: VariableLikeType, *, out: VariableLikeType | None = None
291) -> VariableLikeType:
292 """
293 Round to the nearest integer of all values passed in x.
295 Note: if the number being rounded is halfway between two integers it will
296 round to the nearest even number. For example 1.5 and 2.5 will both round
297 to 2.0, -0.5 and 0.5 will both round to 0.0.
299 Parameters
300 ----------
301 x:
302 Input data.
303 out:
304 Optional output buffer.
306 Returns
307 -------
308 :
309 Rounded version of the data passed to the nearest integer.
310 """
311 return _call_cpp_func(_cpp.rint, x, out=out) # type: ignore[return-value]
314def floor(x: VariableLike, *, out: VariableLike | None = None) -> VariableLike:
315 """
316 Round down to the nearest integer of all values passed in x.
318 Parameters
319 ----------
320 x:
321 Input data.
322 out:
323 Optional output buffer.
325 Returns
326 -------
327 :
328 Rounded down version of the data passed.
329 """
330 return _call_cpp_func(_cpp.floor, x, out=out)
333def ceil(x: VariableLike, *, out: VariableLike | None = None) -> VariableLike:
334 """
335 Round up to the nearest integer of all values passed in x.
337 Parameters
338 ----------
339 x:
340 Input data.
341 out:
342 Optional output buffer.
344 Returns
345 -------
346 :
347 Rounded up version of the data passed.
348 """
349 return _call_cpp_func(_cpp.ceil, x, out=out)
352def erf(x: VariableLike) -> VariableLike:
353 """
354 Computes the error function.
356 Parameters
357 ----------
358 x:
359 Input data.
360 """
361 return _call_cpp_func(_cpp.erf, x)
364def erfc(x: VariableLike) -> VariableLike:
365 """
366 Computes the complementary error function.
368 Parameters
369 ----------
370 x:
371 Input data.
372 """
373 return _call_cpp_func(_cpp.erfc, x)
376def midpoints(x: _cpp.Variable, dim: str | None = None) -> _cpp.Variable:
377 """
378 Computes the points in the middle of adjacent elements of x.
380 The midpoint of two numbers :math:`a` and :math:`b` is
381 :math:`(a + b) / 2`.
382 This formula encounters under- or overflow for
383 very small or very large inputs.
384 The implementation deals with those cases properly.
386 Parameters
387 ----------
388 x:
389 Input data.
390 dim:
391 Dimension along which to compute midpoints.
392 Optional for 1D Variables.
394 Returns
395 -------
396 :
397 Midpoints of ``x`` along ``dim``.
399 Examples
400 --------
402 >>> x = sc.array(dims=['x'], values=[-2, 0, 4, 2])
403 >>> x
404 <scipp.Variable> (x: 4) int64 [dimensionless] [-2, 0, 4, 2]
405 >>> sc.midpoints(x)
406 <scipp.Variable> (x: 3) int64 [dimensionless] [-1, 2, 3]
408 For integers, when the difference of adjacent elements is odd,
409 `midpoints` rounds towards the number that comes first in the array:
411 >>> x = sc.array(dims=['x'], values=[0, 3, 0])
412 >>> x
413 <scipp.Variable> (x: 3) int64 [dimensionless] [0, 3, 0]
414 >>> sc.midpoints(x)
415 <scipp.Variable> (x: 2) int64 [dimensionless] [1, 2]
417 With multidimensional variables, `midpoints` is only applied
418 to the specified dimension:
420 >>> xy = sc.array(dims=['x', 'y'], values=[[1, 3, 5], [2, 6, 10]])
421 >>> xy.values
422 array([[ 1, 3, 5],
423 [ 2, 6, 10]])
424 >>> sc.midpoints(xy, dim='x').values
425 array([[1, 4, 7]])
426 >>> sc.midpoints(xy, dim='y').values
427 array([[2, 4],
428 [4, 8]])
429 """
430 return _cpp.midpoints(x, dim)