Coverage for install/scipp/core/arithmetic.py: 39%
18 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 Jan-Lukas Wynen
5from __future__ import annotations
7from .._scipp import core as _cpp
8from ..typing import VariableLike, VariableLikeType
9from ._cpp_wrapper_util import call_func as _call_cpp_func
12def add(a: VariableLike, b: VariableLike) -> VariableLike:
13 """Element-wise addition.
15 Equivalent to::
17 a + b
19 Parameters
20 ----------
21 a :
22 First summand.
23 b :
24 Second summand.
27 Returns
28 -------
29 :
30 Sum of ``a`` and ``b``.
32 Note
33 ----
34 See the guide on `computation <../../user-guide/computation.rst>`_ for
35 general concepts and broadcasting behavior.
36 """
38 return _call_cpp_func(_cpp.add, a, b)
41def divide(dividend: VariableLike, divisor: VariableLike) -> VariableLike:
42 """Element-wise true division.
44 Equivalent to::
46 dividend / divisor
48 The result always contains fractional parts even when
49 the inputs are integers:
51 Parameters
52 ----------
53 dividend :
54 Dividend of the quotient.
55 divisor :
56 Divisor of the quotient.
58 Returns
59 -------
60 :
61 Quotient of ``divident`` and ``divisor``.
63 Examples
64 --------
65 >>> sc.divide(sc.arange('x', -2, 3), sc.scalar(2)).values
66 array([-1. , -0.5, 0. , 0.5, 1. ])
67 >>> sc.divide(sc.arange('x', -2.0, 3.0), sc.scalar(2.0)).values
68 array([-1. , -0.5, 0. , 0.5, 1. ])
70 Of equivalently in operator notation
72 >>> (sc.arange('x', -2.0, 3.0) / sc.scalar(2.0)).values
73 array([-1. , -0.5, 0. , 0.5, 1. ])
75 See Also
76 --------
77 scipp.floor_divide
79 Note
80 ----
81 See the guide on `computation <../../user-guide/computation.rst>`_ for
82 general concepts and broadcasting behavior.
83 """
84 return _call_cpp_func(_cpp.divide, dividend, divisor)
87def floor_divide(dividend: VariableLike, divisor: VariableLike) -> VariableLike:
88 """Element-wise floor division.
90 Equivalent to::
92 dividend // divisor
94 Parameters
95 ----------
96 dividend:
97 Dividend of the quotient.
98 divisor:
99 Divisor of the quotient.
101 Returns
102 -------
103 :
104 Rounded down quotient.
106 Examples
107 --------
109 >>> sc.floor_divide(sc.arange('x', -2, 3), sc.scalar(2)).values
110 array([-1, -1, 0, 0, 1])
111 >>> sc.floor_divide(sc.arange('x', -2.0, 3.0), sc.scalar(2.0)).values
112 array([-1., -1., 0., 0., 1.])
114 Or equivalently in operator notation
116 >>> (sc.arange('x', -2.0, 3.0) // sc.scalar(2.0)).values
117 array([-1., -1., 0., 0., 1.])
119 See Also
120 --------
121 scipp.divide, scipp.mod
123 Note
124 ----
125 See the guide on `computation <../../user-guide/computation.rst>`_ for
126 general concepts and broadcasting behavior.
127 """
128 return _call_cpp_func(_cpp.floor_divide, dividend, divisor)
131def mod(dividend: VariableLike, divisor: VariableLike) -> VariableLike:
132 """Element-wise remainder.
134 Equivalent to::
136 dividend % divisor
138 In Scipp, the remainder is defined to complement
139 :py:func:`scipp.floor_divide` meaning that::
141 a == floor(a / b) * b + a % b
143 This is the same definition as in :py:data:`numpy.mod`
144 and :py:data:`numpy.remainder`.
146 Warning
147 -------
148 This differs from the IEEE 754 remainder as implemented by
149 :py:func:`math.remainder` and C's remainder function and modulus
150 operator, which complement ``round(a / b)``.
152 Parameters
153 ----------
154 dividend:
155 Dividend of the quotient.
156 divisor:
157 Divisor of the quotient.
159 Returns
160 -------
161 :
162 Quotient.
164 Examples
165 --------
167 >>> sc.mod(sc.arange('x', -3, 5), sc.scalar(3)).values
168 array([0, 1, 2, 0, 1, 2, 0, 1])
169 >>> sc.mod(sc.arange('x', -3, 5), sc.scalar(-3)).values
170 array([ 0, -2, -1, 0, -2, -1, 0, -2])
172 Or equivalently in operator notation
174 >>> (sc.arange('x', -3, 5) % sc.scalar(3)).values
175 array([0, 1, 2, 0, 1, 2, 0, 1])
177 See Also
178 --------
179 scipp.floor_divide, scipp.divide
181 Note
182 ----
183 See the guide on `computation <../../user-guide/computation.rst>`_ for
184 general concepts and broadcasting behavior.
185 """
186 return _call_cpp_func(_cpp.mod, dividend, divisor)
189def multiply(left: VariableLike, right: VariableLike) -> VariableLike:
190 """Element-wise product.
192 Equivalent to::
194 left * right
196 In cases where the order of the operands matters, e.g. with vectors
197 or matrices, it is as shown above.
199 Parameters
200 ----------
201 left:
202 Left factor
203 right:
204 Right factor.
206 Returns
207 -------
208 :
209 Product of ``left`` and ``right``.
211 Note
212 ----
213 See the guide on `computation <../../user-guide/computation.rst>`_ for
214 general concepts and broadcasting behavior.
215 """
216 return _call_cpp_func(_cpp.multiply, left, right)
219def negative(a: VariableLikeType) -> VariableLikeType:
220 """Element-wise negative.
222 Equivalent to::
224 -a
226 Parameters
227 ----------
228 a:
229 Input data.
231 Returns
232 -------
233 :
234 ``a`` with flipped signs.
235 """
236 return _call_cpp_func(_cpp.negative, a) # type: ignore[return-value]
239def subtract(minuend: VariableLike, subtrahend: VariableLike) -> VariableLike:
240 """Element-wise difference.
242 Equivalent to::
244 minuend - subtrahend
246 Parameters
247 ----------
248 minuend:
249 Minuend.
250 subtrahend:
251 Subtrahend.
253 Returns
254 -------
255 :
256 ``subtrahend`` subtracted from ``minuend``.
258 Notes
259 -----
260 See the guide on `computation <../../user-guide/computation.rst>`_ for
261 general concepts and broadcasting behavior.
262 """
263 return _call_cpp_func(_cpp.subtract, minuend, subtrahend)