0
# Trigonometric Functions
1

2
This document covers all trigonometric functions in Math.js, including basic trigonometric functions, inverse functions, hyperbolic functions, and their inverses. All functions support complex numbers, arrays, and matrices.
3

4
## Import
5

6
```typescript
7
import { 
8
  // Basic trigonometric
9
  sin, cos, tan, csc, sec, cot,
10
  // Inverse trigonometric  
11
  asin, acos, atan, atan2, acsc, asec, acot,
12
  // Hyperbolic
13
  sinh, cosh, tanh, csch, sech, coth,
14
  // Inverse hyperbolic
15
  asinh, acosh, atanh, acsch, asech, acoth,
16
  // Constants
17
  pi, e
18
} from 'mathjs'
19
```
20

21
## Basic Trigonometric Functions
22

23
All trigonometric functions expect angles in radians by default. Use `unit()` for degree input.
24

25
### Sine
26

27
```typescript
28
sin(x: MathType): MathType
29
```
30
{ .api }
31

32
```typescript
33
sin(0) // 0
34
sin(pi / 6) // 0.5
35
sin(pi / 2) // 1
36
sin(pi) // ~0 (floating point approximation)
37

38
// With degrees using units
39
sin(unit('30 deg')) // 0.5
40
sin(unit('90 deg')) // 1
41

42
// Complex numbers
43
sin(complex(0, 1)) // Complex(0, 1.175...) = i * sinh(1)
44

45
// Arrays and matrices (element-wise)
46
sin([0, pi/6, pi/4, pi/3, pi/2]) 
47
// [0, 0.5, 0.707..., 0.866..., 1]
48
```
49

50
### Cosine
51

52
```typescript
53
cos(x: MathType): MathType
54
```
55
{ .api }
56

57
```typescript
58
cos(0) // 1
59
cos(pi / 3) // 0.5
60
cos(pi / 2) // ~0
61
cos(pi) // -1
62

63
// With degrees
64
cos(unit('60 deg')) // 0.5
65
cos(unit('90 deg')) // ~0
66

67
// Complex numbers  
68
cos(complex(1, 0)) // Complex(0.540..., 0)
69
```
70

71
### Tangent
72

73
```typescript
74
tan(x: MathType): MathType
75
```
76
{ .api }
77

78
```typescript
79
tan(0) // 0
80
tan(pi / 4) // 1
81
tan(pi / 3) // √3 ≈ 1.732
82

83
// Undefined at π/2, 3π/2, etc.
84
tan(pi / 2) // Infinity (or very large number)
85

86
// With degrees
87
tan(unit('45 deg')) // 1
88
```
89

90
### Cosecant, Secant, Cotangent
91

92
```typescript
93
csc(x: MathType): MathType  // 1 / sin(x)
94
sec(x: MathType): MathType  // 1 / cos(x)  
95
cot(x: MathType): MathType  // cos(x) / sin(x)
96
```
97
{ .api }
98

99
```typescript
100
csc(pi / 6) // 2 (since sin(π/6) = 0.5)
101
sec(pi / 3) // 2 (since cos(π/3) = 0.5)
102
cot(pi / 4) // 1 (since tan(π/4) = 1)
103

104
// Undefined where denominator is zero
105
csc(0) // Infinity (sin(0) = 0)
106
sec(pi / 2) // Infinity (cos(π/2) = 0)
107
cot(0) // Infinity (sin(0) = 0)
108
```
109

110
## Inverse Trigonometric Functions
111

112
Inverse functions return angles in radians. Results are in the principal value range.
113

114
### Arcsine
115

116
```typescript
117
asin(x: MathType): MathType
118
```
119
{ .api }
120

121
```typescript
122
asin(0) // 0
123
asin(0.5) // π/6 ≈ 0.524
124
asin(1) // π/2 ≈ 1.571
125
asin(-1) // -π/2 ≈ -1.571
126

127
// Domain: [-1, 1], Range: [-π/2, π/2]
128
asin(2) // Complex result: Complex(1.571..., -1.317...)
129

130
// Complex input
131
asin(complex(2, 0)) // Complex(1.571..., -1.317...)
132
```
133

134
### Arccosine
135

136
```typescript
137
acos(x: MathType): MathType  
138
```
139
{ .api }
140

141
```typescript
142
acos(1) // 0
143
acos(0.5) // π/3 ≈ 1.047  
144
acos(0) // π/2 ≈ 1.571
145
acos(-1) // π ≈ 3.142
146

147
// Domain: [-1, 1], Range: [0, π]
148
acos(2) // Complex result
149
```
150

151
### Arctangent
152

153
```typescript
154
atan(x: MathType): MathType
155
```
156
{ .api }
157

158
```typescript
159
atan(0) // 0
160
atan(1) // π/4 ≈ 0.785
161
atan(Infinity) // π/2 ≈ 1.571
162
atan(-Infinity) // -π/2 ≈ -1.571
163

164
// Domain: (-∞, ∞), Range: (-π/2, π/2)
165
atan(complex(0, 1)) // Complex result
166
```
167

168
### Two-argument Arctangent
169

170
```typescript
171
atan2(y: MathType, x: MathType): MathType
172
```
173
{ .api }
174

175
```typescript
176
// Returns angle from x-axis to point (x, y)
177
atan2(1, 1) // π/4 ≈ 0.785 (45 degrees)
178
atan2(1, 0) // π/2 (90 degrees)  
179
atan2(0, 1) // 0 (0 degrees)
180
atan2(-1, -1) // -3π/4 ≈ -2.356 (-135 degrees)
181

182
// Handles all quadrants correctly
183
// Range: (-π, π]
184
```
185

186
### Inverse Cosecant, Secant, Cotangent
187

188
```typescript
189
acsc(x: MathType): MathType  // asin(1/x)
190
asec(x: MathType): MathType  // acos(1/x)
191
acot(x: MathType): MathType  // atan(1/x) or π/2 - atan(x)
192
```
193
{ .api }
194

195
```typescript
196
acsc(2) // π/6 (since csc(π/6) = 2)
197
asec(2) // π/3 (since sec(π/3) = 2)  
198
acot(1) // π/4 (since cot(π/4) = 1)
199

200
// Domain restrictions
201
acsc(0.5) // Error: |x| must be >= 1
202
asec(0.5) // Error: |x| must be >= 1
203
```
204

205
## Hyperbolic Functions
206

207
Hyperbolic functions are analogs of trigonometric functions based on the hyperbola rather than the circle.
208

209
### Hyperbolic Sine
210

211
```typescript
212
sinh(x: MathType): MathType  // (e^x - e^(-x)) / 2
213
```
214
{ .api }
215

216
```typescript
217
sinh(0) // 0
218
sinh(1) // (e - 1/e) / 2 ≈ 1.175
219
sinh(-1) // -(e - 1/e) / 2 ≈ -1.175
220

221
// Relationship to trig functions
222
sinh(complex(0, pi/2)) // Complex(0, 1) = i
223
```
224

225
### Hyperbolic Cosine
226

227
```typescript
228
cosh(x: MathType): MathType  // (e^x + e^(-x)) / 2
229
```
230
{ .api }
231

232
```typescript
233
cosh(0) // 1
234
cosh(1) // (e + 1/e) / 2 ≈ 1.543
235
cosh(-1) // (e + 1/e) / 2 ≈ 1.543 (even function)
236

237
// Always >= 1 for real numbers
238
cosh(complex(pi/2, 0)) // Complex(0, 0) ≈ 0 + 0i
239
```
240

241
### Hyperbolic Tangent
242

243
```typescript
244
tanh(x: MathType): MathType  // sinh(x) / cosh(x)
245
```
246
{ .api }
247

248
```typescript
249
tanh(0) // 0
250
tanh(Infinity) // 1  
251
tanh(-Infinity) // -1
252

253
// Sigmoid-like function: Range (-1, 1)
254
tanh(1) // (e^2 - 1) / (e^2 + 1) ≈ 0.762
255
```
256

257
### Hyperbolic Cosecant, Secant, Cotangent
258

259
```typescript
260
csch(x: MathType): MathType  // 1 / sinh(x)
261
sech(x: MathType): MathType  // 1 / cosh(x)
262
coth(x: MathType): MathType  // cosh(x) / sinh(x)
263
```
264
{ .api }
265

266
```typescript
267
csch(1) // 1 / sinh(1) ≈ 0.851
268
sech(0) // 1 / cosh(0) = 1
269
coth(1) // cosh(1) / sinh(1) ≈ 1.313
270

271
// Undefined where denominator is zero  
272
csch(0) // Infinity (sinh(0) = 0)
273
coth(0) // Infinity (sinh(0) = 0)
274
```
275

276
## Inverse Hyperbolic Functions
277

278
### Inverse Hyperbolic Sine
279

280
```typescript
281
asinh(x: MathType): MathType  // ln(x + sqrt(x^2 + 1))
282
```
283
{ .api }
284

285
```typescript
286
asinh(0) // 0
287
asinh(1) // ln(1 + √2) ≈ 0.881
288
asinh(-1) // -ln(1 + √2) ≈ -0.881
289

290
// Domain: (-∞, ∞), Range: (-∞, ∞)
291
asinh(sinh(5)) // 5 (inverse property)
292
```
293

294
### Inverse Hyperbolic Cosine
295

296
```typescript
297
acosh(x: MathType): MathType  // ln(x + sqrt(x^2 - 1))
298
```
299
{ .api }
300

301
```typescript
302
acosh(1) // 0
303
acosh(2) // ln(2 + √3) ≈ 1.317
304

305
// Domain: [1, ∞), Range: [0, ∞)  
306
acosh(0.5) // Complex result (outside domain)
307
acosh(cosh(3)) // 3 (inverse property)
308
```
309

310
### Inverse Hyperbolic Tangent
311

312
```typescript
313
atanh(x: MathType): MathType  // 0.5 * ln((1 + x) / (1 - x))
314
```
315
{ .api }
316

317
```typescript
318
atanh(0) // 0
319
atanh(0.5) // 0.5 * ln(3) ≈ 0.549
320

321
// Domain: (-1, 1), Range: (-∞, ∞)
322
atanh(1) // Infinity
323
atanh(-1) // -Infinity  
324
atanh(2) // Complex result (outside domain)
325
```
326

327
### Inverse Hyperbolic Cosecant, Secant, Cotangent
328

329
```typescript
330
acsch(x: MathType): MathType  // asinh(1/x)
331
asech(x: MathType): MathType  // acosh(1/x)  
332
acoth(x: MathType): MathType  // atanh(1/x)
333
```
334
{ .api }
335

336
```typescript
337
acsch(1) // asinh(1) ≈ 0.881
338
asech(0.5) // acosh(2) ≈ 1.317
339
acoth(2) // atanh(0.5) ≈ 0.549
340

341
// Domain restrictions apply based on underlying functions
342
acsch(0) // Infinity
343
asech(0) // Infinity
344
asech(2) // Complex result (1/x not in [0,1])
345
```
346

347
## Complex Number Support
348

349
All trigonometric functions support complex numbers using standard mathematical definitions:
350

351
```typescript
352
// Euler's formula: e^(ix) = cos(x) + i*sin(x)
353
sin(complex(0, 1)) // i * sinh(1) ≈ Complex(0, 1.175)
354
cos(complex(0, 1)) // cosh(1) ≈ Complex(1.543, 0)
355

356
// Complex argument
357
const z = complex(1, 2) // 1 + 2i
358
sin(z) // Complex result
359
cos(z) // Complex result  
360

361
// Inverse functions with complex results
362
asin(2) // Complex(π/2, -ln(2 + √3)) 
363
acos(2) // Complex(0, ln(2 + √3))
364
```
365

366
## Working with Units (Degrees)
367

368
Math.js can work with angular units:
369

370
```typescript
371
import { unit, sin, cos, evaluate } from 'mathjs'
372

373
// Using degree units
374
sin(unit('30 deg')) // 0.5
375
cos(unit('60 deg')) // 0.5  
376
tan(unit('45 deg')) // 1
377

378
// Converting between radians and degrees
379
const angle = unit('π/4 rad')
380
unit(angle, 'deg') // 45 deg
381

382
// In expressions
383
evaluate('sin(30 deg)') // 0.5
384
evaluate('cos(π/3 rad)') // 0.5
385
```
386

387
## Array and Matrix Operations
388

389
All trigonometric functions work element-wise on arrays and matrices:
390

391
```typescript
392
// Arrays
393
const angles = [0, pi/6, pi/4, pi/3, pi/2]
394
sin(angles) // [0, 0.5, 0.707..., 0.866..., 1]
395
cos(angles) // [1, 0.866..., 0.707..., 0.5, 0]
396

397
// Matrices
398
const angleMatrix = [[0, pi/4], [pi/3, pi/2]]
399
sin(angleMatrix) // [[0, 0.707...], [0.866..., 1]]
400

401
// Complex matrices
402
const complexMatrix = [[complex(1, 1), complex(0, 1)]]
403
sin(complexMatrix) // Element-wise complex sine
404
```
405

406
## Identities and Relationships
407

408
Math.js respects mathematical identities (within floating-point precision):
409

410
```typescript
411
// Pythagorean identity
412
const x = 0.7
413
pow(sin(x), 2) + pow(cos(x), 2) // ≈ 1
414

415
// Angle sum formulas (implemented internally)
416
sin(add(a, b)) // sin(a)cos(b) + cos(a)sin(b)
417

418
// Hyperbolic identities  
419
const y = 1.5
420
pow(cosh(y), 2) - pow(sinh(y), 2) // ≈ 1
421

422
// Euler's formula
423
const theta = pi/3
424
exp(complex(0, theta)) // cos(theta) + i*sin(theta)
425
```
426

427
## Performance Considerations
428

429
### Use Radians When Possible
430
```typescript
431
// Faster: direct radian input
432
sin(1.047) // π/3 in radians
433

434
// Slower: unit conversion overhead  
435
sin(unit('60 deg'))
436
```
437

438
### Batch Operations with Arrays
439
```typescript
440
// Faster: single function call on array
441
sin([0, pi/4, pi/2, pi])
442

443
// Slower: multiple function calls
444
[0, pi/4, pi/2, pi].map(x => sin(x))
445
```
446

447
### Precompute Common Values
448
```typescript
449
// For repeated use
450
const sin30 = sin(pi/6) // 0.5
451
const cos60 = cos(pi/3) // 0.5
452
```
453

454
## Constants and Special Values
455

456
```typescript
457
import { pi, e, i } from 'mathjs'
458

459
// Key angles in radians
460
pi/6    // 30°
461
pi/4    // 45°  
462
pi/3    // 60°
463
pi/2    // 90°
464
pi      // 180°
465
2*pi    // 360°
466

467
// Special values
468
sin(0) // 0
469
sin(pi/2) // 1
470
cos(0) // 1  
471
cos(pi) // -1
472

473
// Complex unit circle
474
exp(multiply(i, pi)) // -1 (Euler's identity)
475
```
476

477
## Error Handling
478

479
```typescript
480
import { ArgumentsError } from 'mathjs'
481

482
try {
483
  // Some functions have domain restrictions
484
  asin(2) // Returns complex number (not error)
485
  acosh(0.5) // Returns complex number
486
  
487
  // Unit compatibility  
488
  sin(unit('5 meter')) // Error: expecting angle unit
489
} catch (error) {
490
  if (error instanceof ArgumentsError) {
491
    console.log('Invalid arguments provided')
492
  }
493
}
494
```
495

496
## Chain Operations  
497

498
All trigonometric functions work in the chain interface:
499

500
```typescript
501
chain(pi/6)
502
  .sin()     // 0.5
503
  .asin()    // π/6 (back to original)
504
  .multiply(180/pi) // Convert to degrees
505
  .done()    // 30
506
```
507

508
## Common Use Cases
509

510
### Convert Between Coordinate Systems
511
```typescript
512
// Cartesian to polar
513
function toPolar(x, y) {
514
  const r = hypot(x, y)
515
  const theta = atan2(y, x)
516
  return { r, theta }
517
}
518

519
// Polar to Cartesian  
520
function toCartesian(r, theta) {
521
  const x = multiply(r, cos(theta))
522
  const y = multiply(r, sin(theta))
523
  return { x, y }
524
}
525
```
526

527
### Oscillating Functions
528
```typescript
529
// Sine wave generator
530
function sineWave(amplitude, frequency, phase, time) {
531
  return multiply(amplitude, sin(add(multiply(frequency, time), phase)))
532
}
533

534
const wave = range(0, 2*pi, 0.1).map(t => sineWave(1, 1, 0, t))
535
```
536

537
### Trigonometric Polynomial Approximation
538
```typescript
539
// Taylor series approximation (Math.js does this internally)
540
function sinApprox(x, terms = 10) {
541
  let result = 0
542
  for (let n = 0; n < terms; n++) {
543
    const term = multiply(
544
      pow(-1, n),
545
      divide(pow(x, 2*n + 1), factorial(2*n + 1))
546
    )
547
    result = add(result, term)
548
  }
549
  return result
550
}
551
```