0
# Mathematical Functions
1

2
Comprehensive mathematical functions through the clojure.math namespace. These functions provide Clojure wrappers for java.lang.Math static methods, optimized for performance with inlined calls and proper type hints.
3

4
## Capabilities
5

6
### Mathematical Constants
7

8
Mathematical constants for use in calculations.
9

10
```clojure { .api }
11
clojure.math/E
12
;; Euler's number e, the base for natural logarithms (≈2.718)
13
;; Type: double constant
14

15
clojure.math/PI  
16
;; Pi, ratio of circumference to diameter (≈3.14159)
17
;; Type: double constant
18
```
19

20
### Trigonometric Functions
21

22
Standard trigonometric functions with angles in radians.
23

24
```clojure { .api }
25
(clojure.math/sin a)
26
;; Returns sine of angle a in radians
27
;; Returns: double
28

29
(clojure.math/cos a)  
30
;; Returns cosine of angle a in radians
31
;; Returns: double
32

33
(clojure.math/tan a)
34
;; Returns tangent of angle a in radians  
35
;; Returns: double
36

37
(clojure.math/asin a)
38
;; Returns arc sine of a, result in range -π/2 to π/2
39
;; Returns: double
40

41
(clojure.math/acos a)
42
;; Returns arc cosine of a, result in range 0 to π
43
;; Returns: double
44

45
(clojure.math/atan a)
46
;; Returns arc tangent of a, result in range -π/2 to π/2
47
;; Returns: double
48

49
(clojure.math/atan2 y x)
50
;; Returns angle θ from rectangular (x,y) to polar (r,θ) coordinates
51
;; Result in range -π to π
52
;; Returns: double
53
```
54

55
### Angle Conversion
56

57
Functions for converting between degrees and radians.
58

59
```clojure { .api }
60
(clojure.math/to-radians degrees)
61
;; Converts angle from degrees to radians
62
;; Returns: double
63

64
(clojure.math/to-degrees radians)
65
;; Converts angle from radians to degrees  
66
;; Returns: double
67
```
68

69
### Exponential and Logarithmic Functions
70

71
Exponential, logarithmic, and power functions.
72

73
```clojure { .api }
74
(clojure.math/exp a)
75
;; Returns e raised to power a
76
;; Returns: double
77

78
(clojure.math/expm1 x)
79
;; Returns e^x - 1, more accurate than (- (exp x) 1) for small x
80
;; Returns: double
81

82
(clojure.math/log a)
83
;; Returns natural logarithm (base e) of a
84
;; Returns: double
85

86
(clojure.math/log10 a)
87
;; Returns base-10 logarithm of a
88
;; Returns: double
89

90
(clojure.math/log1p x)  
91
;; Returns ln(1+x), more accurate than (log (+ 1 x)) for small x
92
;; Returns: double
93

94
(clojure.math/pow a b)
95
;; Returns a raised to power b
96
;; Returns: double
97
```
98

99
### Root Functions
100

101
Square root, cube root, and hypotenuse calculations.
102

103
```clojure { .api }
104
(clojure.math/sqrt a)
105
;; Returns positive square root of a
106
;; Returns: double
107

108
(clojure.math/cbrt a)
109
;; Returns cube root of a
110
;; Returns: double
111

112
(clojure.math/hypot x y)
113
;; Returns sqrt(x² + y²) without intermediate overflow/underflow
114
;; Returns: double
115
```
116

117
### Rounding and Ceiling Functions
118

119
Functions for rounding to integers and controlling precision.
120

121
```clojure { .api }
122
(clojure.math/ceil a)
123
;; Returns smallest double >= a that equals mathematical integer
124
;; Returns: double
125

126
(clojure.math/floor a)
127
;; Returns largest double <= a that equals mathematical integer  
128
;; Returns: double
129

130
(clojure.math/rint a)
131
;; Returns double closest to a that equals mathematical integer
132
;; If two values equally close, returns the even one
133
;; Returns: double
134

135
(clojure.math/round a)
136
;; Returns closest long to a, ties round toward positive infinity
137
;; Returns: long
138
```
139

140
### Exact Arithmetic
141

142
Overflow-detecting arithmetic operations that throw on overflow.
143

144
```clojure { .api }
145
(clojure.math/add-exact x y)
146
;; Returns x + y, throws ArithmeticException on overflow
147
;; Returns: long
148

149
(clojure.math/subtract-exact x y)
150
;; Returns x - y, throws ArithmeticException on overflow
151
;; Returns: long
152

153
(clojure.math/multiply-exact x y)
154
;; Returns x * y, throws ArithmeticException on overflow
155
;; Returns: long
156

157
(clojure.math/increment-exact a)
158
;; Returns a + 1, throws ArithmeticException on overflow
159
;; Returns: long
160

161
(clojure.math/decrement-exact a)
162
;; Returns a - 1, throws ArithmeticException on overflow
163
;; Returns: long
164

165
(clojure.math/negate-exact a)
166
;; Returns -a, throws ArithmeticException on overflow
167
;; Returns: long
168
```
169

170
### Division and Modulus
171

172
Floor-based division and modulus operations.
173

174
```clojure { .api }
175
(clojure.math/floor-div x y)
176
;; Integer division rounding toward negative infinity
177
;; Returns: long
178

179
(clojure.math/floor-mod x y)
180
;; Integer modulus: x - (floor-div x y) * y
181
;; Sign matches y, result in range -|y| < r < |y|
182
;; Returns: long
183

184
(clojure.math/IEEE-remainder dividend divisor)
185
;; Returns IEEE 754 remainder: dividend - divisor * n
186
;; where n is integer closest to dividend/divisor
187
;; Returns: double
188
```
189

190
### Hyperbolic Functions
191

192
Hyperbolic trigonometric functions.
193

194
```clojure { .api }
195
(clojure.math/sinh x)
196
;; Returns hyperbolic sine: (e^x - e^-x)/2
197
;; Returns: double
198

199
(clojure.math/cosh x)
200
;; Returns hyperbolic cosine: (e^x + e^-x)/2  
201
;; Returns: double
202

203
(clojure.math/tanh x)
204
;; Returns hyperbolic tangent: sinh(x)/cosh(x)
205
;; Returns: double
206
```
207

208
### Sign and Magnitude Functions
209

210
Functions for working with signs, magnitudes, and floating-point representation.
211

212
```clojure { .api }
213
(clojure.math/signum d)
214
;; Returns sign of d: -1.0 if negative, 0.0 if zero, 1.0 if positive
215
;; Returns: double
216

217
(clojure.math/copy-sign magnitude sign)
218
;; Returns value with magnitude of first arg and sign of second
219
;; Returns: double
220

221
(clojure.math/ulp d)
222
;; Returns size of unit in last place (ULP) for d
223
;; Returns: double
224
```
225

226
### Floating-Point Manipulation
227

228
Low-level floating-point number manipulation.
229

230
```clojure { .api }
231
(clojure.math/get-exponent d)
232
;; Returns exponent field of d
233
;; Returns: int
234

235
(clojure.math/next-after start direction)
236
;; Returns adjacent floating-point number to start toward direction
237
;; Returns: double
238

239
(clojure.math/next-up d)
240
;; Returns adjacent double in direction of positive infinity
241
;; Returns: double
242

243
(clojure.math/next-down d)
244
;; Returns adjacent double in direction of negative infinity
245
;; Returns: double
246

247
(clojure.math/scalb d scale-factor)
248
;; Returns d * 2^scale-factor
249
;; Returns: double
250
```
251

252
### Random Number Generation
253

254
Simple random number generation.
255

256
```clojure { .api }
257
(clojure.math/random)
258
;; Returns pseudorandom double between 0.0 (inclusive) and 1.0 (exclusive)
259
;; Returns: double
260
```
261

262
**Usage Examples:**
263

264
```clojure
265
;; Import the namespace
266
(require '[clojure.math :as math])
267

268
;; Basic trigonometry
269
(math/sin (/ math/PI 2))          ; => 1.0
270
(math/cos 0)                      ; => 1.0
271
(math/tan (/ math/PI 4))          ; => 1.0
272

273
;; Angle conversion
274
(math/to-degrees math/PI)         ; => 180.0
275
(math/to-radians 90)              ; => 1.5707963267948966
276

277
;; Exponential and logarithmic
278
(math/exp 1)                      ; => 2.718281828459045 (≈ e)
279
(math/log math/E)                 ; => 1.0
280
(math/log10 100)                  ; => 2.0
281
(math/pow 2 3)                    ; => 8.0
282

283
;; Roots and powers
284
(math/sqrt 16)                    ; => 4.0
285
(math/cbrt 27)                    ; => 3.0  
286
(math/hypot 3 4)                  ; => 5.0
287

288
;; Rounding
289
(math/ceil 3.2)                   ; => 4.0
290
(math/floor 3.8)                  ; => 3.0
291
(math/round 3.6)                  ; => 4
292
(math/rint 3.5)                   ; => 4.0 (rounds to even)
293

294
;; Exact arithmetic (throws on overflow)
295
(math/add-exact 1000000 2000000)  ; => 3000000
296
(try
297
  (math/multiply-exact Long/MAX_VALUE 2)
298
  (catch ArithmeticException e
299
    "Overflow detected"))
300

301
;; Floor division and modulus
302
(math/floor-div 7 3)              ; => 2
303
(math/floor-mod 7 3)              ; => 1
304
(math/floor-div -7 3)             ; => -3
305
(math/floor-mod -7 3)             ; => 2
306

307
;; Random numbers
308
(math/random)                     ; => random double in [0.0, 1.0)
309

310
;; Working with constants
311
(* 2 math/PI 5)                   ; circumference of circle with radius 5
312
(math/exp 1)                      ; => math/E (approximately)
313
```