Coverage for install/scipp/core/math.py: 44%
43 statements
« prev ^ index » next coverage.py v7.4.0, created at 2024-04-28 01:28 +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
7from typing import Optional, Union
9from .._scipp import core as _cpp
10from ..typing import VariableLike
11from ._cpp_wrapper_util import call_func as _call_cpp_func
12from .variable import scalar
15def abs(
16 x: Union[VariableLike, _cpp.Unit], *, out: Optional[_cpp.Variable] = None
17) -> Union[VariableLike, _cpp.Unit]:
18 """Element-wise absolute value.
20 Parameters
21 ----------
22 x:
23 Input data.
24 out:
25 Optional output buffer. Only supported if `x` is a scipp.Variable.
27 Raises
28 ------
29 scipp.DTypeError
30 If the dtype has no absolute value, e.g., if it is a string.
32 Returns
33 -------
34 :
35 The absolute values of the input.
37 See Also
38 --------
39 scipp.norm
40 """
41 return _call_cpp_func(_cpp.abs, x, out=out)
44def cross(x: VariableLike, y: VariableLike) -> VariableLike:
45 """Element-wise cross product.
47 Parameters
48 ----------
49 x:
50 Left hand side operand.
51 y:
52 Right hand side operand.
54 Raises
55 ------
56 scipp.DTypeError
57 If the dtype of the input is not vector3.
59 Returns
60 -------
61 :
62 The cross product of the input vectors.
63 """
64 return _call_cpp_func(_cpp.cross, x, y)
67def dot(x: VariableLike, y: VariableLike) -> VariableLike:
68 """Element-wise dot product.
70 Parameters
71 ----------
72 x:
73 Left hand side operand.
74 y:
75 Right hand side operand.
77 Raises
78 ------
79 scipp.DTypeError
80 If the dtype of the input is not vector3.
82 Returns
83 -------
84 :
85 The dot product of the input vectors.
86 """
87 return _call_cpp_func(_cpp.dot, x, y)
90def nan_to_num(
91 x: _cpp.Variable,
92 *,
93 nan: _cpp.Variable = None,
94 posinf: _cpp.Variable = None,
95 neginf: _cpp.Variable = None,
96 out: _cpp.Variable = None,
97) -> _cpp.Variable:
98 """Element-wise special value replacement.
100 All elements in the output are identical to input except in the presence
101 of a NaN, Inf or -Inf.
102 The function allows replacements to be separately specified for NaN, Inf
103 or -Inf values.
104 You can choose to replace a subset of those special values by providing
105 just the required keyword arguments.
107 Parameters
108 ----------
109 x:
110 Input data.
111 nan:
112 Replacement values for NaN in the input.
113 posinf:
114 Replacement values for Inf in the input.
115 neginf:
116 Replacement values for -Inf in the input.
117 out:
118 Optional output buffer.
120 Raises
121 ------
122 scipp.DTypeError
123 If the types of input and replacement do not match.
125 Returns
126 -------
127 :
128 Input with specified substitutions.
129 """
130 return _call_cpp_func(
131 _cpp.nan_to_num, x, nan=nan, posinf=posinf, neginf=neginf, out=out
132 )
135def norm(x: VariableLike) -> VariableLike:
136 """Element-wise norm.
138 Parameters
139 ----------
140 x:
141 Input data.
143 Raises
144 ------
145 scipp.DTypeError
146 If the dtype has no norm, i.e., if it is not a vector.
148 Returns
149 -------
150 :
151 Scalar elements computed as the norm values of the input elements.
152 """
153 return _call_cpp_func(_cpp.norm, x, out=None)
156def reciprocal(
157 x: Union[VariableLike, _cpp.Unit], *, out: Optional[_cpp.Variable] = None
158) -> Union[VariableLike, _cpp.Unit]:
159 """Element-wise reciprocal.
161 Parameters
162 ----------
163 x:
164 Input data.
165 out:
166 Optional output buffer. Only supported when `x` is a scipp.Variable.
168 Raises
169 ------
170 scipp.DTypeError
171 If the dtype has no reciprocal, e.g., if it is a string.
173 Returns
174 -------
175 :
176 The reciprocal values of the input.
177 """
178 return _call_cpp_func(_cpp.reciprocal, x, out=out)
181def pow(
182 base: Union[VariableLike, _cpp.Unit], exponent: Union[VariableLike, Real]
183) -> Union[VariableLike, _cpp.Unit]:
184 """Element-wise power.
186 If the base has a unit, the exponent must be scalar in order to get
187 a well-defined unit in the result.
189 Parameters
190 ----------
191 base:
192 Base of the exponential.
193 exponent:
194 Raise ``base`` to this power.
196 Raises
197 ------
198 scipp.DTypeError
199 If the dtype does not have a power, e.g., if it is a string.
201 Returns
202 -------
203 :
204 ``base`` raised to the power of ``exp``.
205 """
206 if not isinstance(base, _cpp.Unit) and isinstance(exponent, Real):
207 exponent = scalar(exponent)
208 return _call_cpp_func(_cpp.pow, base, exponent)
211def sqrt(
212 x: Union[VariableLike, _cpp.Unit], *, out: Optional[_cpp.Variable] = None
213) -> Union[VariableLike, _cpp.Unit]:
214 """Element-wise square-root.
216 Parameters
217 ----------
218 x:
219 Input data.
220 out:
221 Optional output buffer. Only supported when `x` is a scipp.Variable.
223 Raises
224 ------
225 scipp.DTypeError
226 If the dtype has no square-root, e.g., if it is a string.
228 Returns
229 -------
230 :
231 The square-root values of the input.
232 """
233 return _call_cpp_func(_cpp.sqrt, x, out=out)
236def exp(x: VariableLike, *, out: Optional[VariableLike] = None) -> VariableLike:
237 """Element-wise exponential.
239 Parameters
240 ----------
241 x:
242 Input data.
243 out:
244 Optional output buffer.
246 Returns
247 -------
248 :
249 e raised to the power of the input.
250 """
251 return _call_cpp_func(_cpp.exp, x, out=out)
254def log(x: VariableLike, *, out: Optional[VariableLike] = None) -> VariableLike:
255 """Element-wise natural logarithm.
257 Parameters
258 ----------
259 x:
260 Input data.
261 out:
262 Optional output buffer.
264 Returns
265 -------
266 :
267 Base e logarithm of the input.
268 """
269 return _call_cpp_func(_cpp.log, x, out=out)
272def log10(x: VariableLike, *, out: Optional[VariableLike] = None) -> VariableLike:
273 """Element-wise base 10 logarithm.
275 Parameters
276 ----------
277 x:
278 Input data.
279 out:
280 Optional output buffer.
282 Returns
283 -------
284 :
285 Base 10 logarithm of the input.
286 """
287 return _call_cpp_func(_cpp.log10, x, out=out)
290def round(x: VariableLike, *, out: Optional[VariableLike] = None) -> VariableLike:
291 """
292 Round to the nearest integer of all values passed in x.
294 Note: if the number being rounded is halfway between two integers it will
295 round to the nearest even number. For example 1.5 and 2.5 will both round
296 to 2.0, -0.5 and 0.5 will both round to 0.0.
298 Parameters
299 ----------
300 x:
301 Input data.
302 out:
303 Optional output buffer.
305 Returns
306 -------
307 :
308 Rounded version of the data passed to the nearest integer.
309 """
310 return _call_cpp_func(_cpp.rint, x, out=out)
313def floor(x: VariableLike, *, out: Optional[VariableLike] = None) -> VariableLike:
314 """
315 Round down to the nearest integer of all values passed in x.
317 Parameters
318 ----------
319 x:
320 Input data.
321 out:
322 Optional output buffer.
324 Returns
325 -------
326 :
327 Rounded down version of the data passed.
328 """
329 return _call_cpp_func(_cpp.floor, x, out=out)
332def ceil(x: VariableLike, *, out: Optional[VariableLike] = None) -> VariableLike:
333 """
334 Round up to the nearest integer of all values passed in x.
336 Parameters
337 ----------
338 x:
339 Input data.
340 out:
341 Optional output buffer.
343 Returns
344 -------
345 :
346 Rounded up version of the data passed.
347 """
348 return _call_cpp_func(_cpp.ceil, x, out=out)
351def erf(x: VariableLike) -> VariableLike:
352 """
353 Computes the error function.
355 Parameters
356 ----------
357 x:
358 Input data.
359 """
360 return _cpp.erf(x)
363def erfc(x: VariableLike) -> VariableLike:
364 """
365 Computes the complementary error function.
367 Parameters
368 ----------
369 x:
370 Input data.
371 """
372 return _cpp.erfc(x)
375def midpoints(x: _cpp.Variable, dim: Optional[str] = None) -> _cpp.Variable:
376 """
377 Computes the points in the middle of adjacent elements of x.
379 The midpoint of two numbers :math:`a` and :math:`b` is
380 :math:`(a + b) / 2`.
381 This formula encounters under- or overflow for
382 very small or very large inputs.
383 The implementation deals with those cases properly.
385 Parameters
386 ----------
387 x:
388 Input data.
389 dim:
390 Dimension along which to compute midpoints.
391 Optional for 1D Variables.
393 Returns
394 -------
395 :
396 Midpoints of ``x`` along ``dim``.
398 Examples
399 --------
401 >>> x = sc.array(dims=['x'], values=[-2, 0, 4, 2])
402 >>> x
403 <scipp.Variable> (x: 4) int64 [dimensionless] [-2, 0, 4, 2]
404 >>> sc.midpoints(x)
405 <scipp.Variable> (x: 3) int64 [dimensionless] [-1, 2, 3]
407 For integers, when the difference of adjacent elements is odd,
408 `midpoints` rounds towards the number that comes first in the array:
410 >>> x = sc.array(dims=['x'], values=[0, 3, 0])
411 >>> x
412 <scipp.Variable> (x: 3) int64 [dimensionless] [0, 3, 0]
413 >>> sc.midpoints(x)
414 <scipp.Variable> (x: 2) int64 [dimensionless] [1, 2]
416 With multidimensional variables, `midpoints` is only applied
417 to the specified dimension:
419 >>> xy = sc.array(dims=['x', 'y'], values=[[1, 3, 5], [2, 6, 10]])
420 >>> xy.values
421 array([[ 1, 3, 5],
422 [ 2, 6, 10]])
423 >>> sc.midpoints(xy, dim='x').values
424 array([[1, 4, 7]])
425 >>> sc.midpoints(xy, dim='y').values
426 array([[2, 4],
427 [4, 8]])
428 """
429 return _cpp.midpoints(x, dim)