Coverage for install/scipp/core/trigonometry.py: 37%

1# SPDX-License-Identifier: BSD-3-Clause 

2# Copyright (c) 2023 Scipp contributors (https://github.com/scipp) 

3# @author Simon Heybrock 

4 

5from __future__ import annotations 

6 

7from .._scipp import core as _cpp 

8from ..typing import VariableLikeType 

9from ._cpp_wrapper_util import call_func as _call_cpp_func 

10from .cpp_classes import Variable 

11 

12 

13def sin( 

14 x: VariableLikeType, *, out: VariableLikeType | None = None 

15) -> VariableLikeType: 

16 """Element-wise sine. 

17 

18 The input must have a plane-angle unit, i.e. ``rad``, ``deg``. 

19 

20 Parameters 

21 ---------- 

22 x: scipp.typing.VariableLike 

23 Input data. 

24 out: 

25 Optional output buffer. 

26 

27 Returns 

28 ------- 

29 : Same type as input 

30 The sine values of the input. 

31 """ 

32 return _call_cpp_func(_cpp.sin, x, out=out) # type: ignore[return-value] 

33 

34 

35def cos( 

36 x: VariableLikeType, *, out: VariableLikeType | None = None 

37) -> VariableLikeType: 

38 """Element-wise cosine. 

39 

40 The input must have a plane-angle unit, i.e. ``rad``, ``deg``. 

41 

42 Parameters 

43 ---------- 

44 x: scipp.typing.VariableLike 

45 Input data. 

46 out: 

47 Optional output buffer. 

48 

49 Returns 

50 ------- 

51 : Same type as input 

52 The cosine values of the input. 

53 """ 

54 return _call_cpp_func(_cpp.cos, x, out=out) # type: ignore[return-value] 

55 

56 

57def tan( 

58 x: VariableLikeType, *, out: VariableLikeType | None = None 

59) -> VariableLikeType: 

60 """Element-wise tangent. 

61 

62 The input must have a plane-angle unit, i.e. ``rad``, ``deg``. 

63 

64 Parameters 

65 ---------- 

66 x: scipp.typing.VariableLike 

67 Input data. 

68 out: 

69 Optional output buffer. 

70 

71 Returns 

72 ------- 

73 : Same type as input 

74 The tangent values of the input. 

75 """ 

76 return _call_cpp_func(_cpp.tan, x, out=out) # type: ignore[return-value] 

77 

78 

79def asin( 

80 x: VariableLikeType, *, out: VariableLikeType | None = None 

81) -> VariableLikeType: 

82 """Element-wise inverse sine. 

83 

84 Parameters 

85 ---------- 

86 x: scipp.typing.VariableLike 

87 Input data. 

88 out: 

89 Optional output buffer. 

90 

91 Returns 

92 ------- 

93 : Same type as input 

94 The inverse sine values of the input in radians. 

95 """ 

96 return _call_cpp_func(_cpp.asin, x, out=out) # type: ignore[return-value] 

97 

98 

99def acos( 

100 x: VariableLikeType, *, out: VariableLikeType | None = None 

101) -> VariableLikeType: 

102 """Element-wise inverse cosine. 

103 

104 Parameters 

105 ---------- 

106 x: scipp.typing.VariableLike 

107 Input data. 

108 out: 

109 Optional output buffer. 

110 

111 Returns 

112 ------- 

113 : Same type as input 

114 The inverse cosine values of the input in radians. 

115 """ 

116 return _call_cpp_func(_cpp.acos, x, out=out) # type: ignore[return-value] 

117 

118 

119def atan( 

120 x: VariableLikeType, *, out: VariableLikeType | None = None 

121) -> VariableLikeType: 

122 """Element-wise inverse tangent. 

123 

124 Parameters 

125 ---------- 

126 x: scipp.typing.VariableLike 

127 Input data. 

128 out: 

129 Optional output buffer. 

130 

131 Returns 

132 ------- 

133 : Same type as input 

134 The inverse tangent values of the input in radians. 

135 """ 

136 return _call_cpp_func(_cpp.atan, x, out=out) # type: ignore[return-value] 

137 

138 

139def atan2(*, y: Variable, x: Variable, out: Variable | None = None) -> Variable: 

140 """Element-wise inverse tangent of y/x determining the correct quadrant. 

141 

142 Parameters 

143 ---------- 

144 y: 

145 Input y values. 

146 x: 

147 Input x values. 

148 out: 

149 Optional output buffer. 

150 

151 Returns 

152 ------- 

153 : 

154 The signed inverse tangent values of y/x in the range [-π, π]. 

155 

156 See Also 

157 -------- 

158 `<https://en.cppreference.com/w/c/numeric/math/atan2>`_: 

159 Documentation of all edge cases. 

160 Note that domain errors are *not* propagated to Python. 

161 numpy.arctan2: 

162 The equivalent in NumPy with additional explanations. 

163 """ 

164 return _call_cpp_func(_cpp.atan2, y=y, x=x, out=out) # type: ignore[return-value]