0
# Mathematical Functions
1

2
Complete GLSL-compatible mathematical function library covering trigonometry, exponentials, common functions, and interpolation. These functions work with both scalar values and vectors, applying operations component-wise for vector inputs.
3

4
## Capabilities
5

6
### Basic Mathematical Functions
7

8
Fundamental mathematical operations including absolute value, rounding, and comparison functions.
9

10
```python { .api }
11
def abs(x):
12
    """
13
    Calculate absolute value.
14

15
    Args:
16
        x: Scalar or vector input
17

18
    Returns:
19
        Absolute value(s) of the input
20

21
    Example:
22
        abs(-5.0)  # 5.0
23
        abs(glm.vec3(-1, 2, -3))  # vec3(1, 2, 3)
24
    """
25

26
def sign(x):
27
    """
28
    Extract the sign of the input.
29

30
    Args:
31
        x: Scalar or vector input
32

33
    Returns:
34
        -1.0 for negative, 0.0 for zero, 1.0 for positive
35

36
    Example:
37
        sign(-2.5)  # -1.0
38
        sign(glm.vec2(3, -1))  # vec2(1.0, -1.0)
39
    """
40

41
def floor(x):
42
    """
43
    Find the largest integer less than or equal to x.
44

45
    Args:
46
        x: Scalar or vector input
47

48
    Returns:
49
        Floor value(s)
50

51
    Example:
52
        floor(3.7)  # 3.0
53
        floor(glm.vec2(2.1, -1.8))  # vec2(2.0, -2.0)
54
    """
55

56
def ceil(x):
57
    """
58
    Find the smallest integer greater than or equal to x.
59

60
    Args:
61
        x: Scalar or vector input
62

63
    Returns:
64
        Ceiling value(s)
65

66
    Example:
67
        ceil(3.2)  # 4.0
68
        ceil(glm.vec2(2.1, -1.2))  # vec2(3.0, -1.0)
69
    """
70

71
def fract(x):
72
    """
73
    Extract the fractional part of x.
74

75
    Args:
76
        x: Scalar or vector input
77

78
    Returns:
79
        Fractional part (x - floor(x))
80

81
    Example:
82
        fract(3.7)  # 0.7
83
        fract(glm.vec2(2.3, -1.7))  # vec2(0.3, 0.3)
84
    """
85

86
def trunc(x):
87
    """
88
    Truncate x to remove fractional part.
89

90
    Args:
91
        x: Scalar or vector input
92

93
    Returns:
94
        Integer part of x
95

96
    Example:
97
        trunc(3.7)  # 3.0
98
        trunc(-2.8)  # -2.0
99
    """
100

101
def round(x):
102
    """
103
    Round x to the nearest integer.
104

105
    Args:
106
        x: Scalar or vector input
107

108
    Returns:
109
        Rounded value(s)
110

111
    Example:
112
        round(3.6)  # 4.0
113
        round(glm.vec2(2.3, 2.7))  # vec2(2.0, 3.0)
114
    """
115

116
def roundEven(x):
117
    """
118
    Round x to the nearest even integer.
119

120
    Args:
121
        x: Scalar or vector input
122

123
    Returns:
124
        Rounded value(s) (ties go to even numbers)
125

126
    Example:
127
        roundEven(2.5)  # 2.0 (even)
128
        roundEven(3.5)  # 4.0 (even)
129
    """
130
```
131

132
### Min, Max, and Clamping
133

134
Functions for constraining values within ranges and finding extremes.
135

136
```python { .api }
137
def min(x, y):
138
    """
139
    Return the smaller of two values.
140

141
    Args:
142
        x: First value (scalar or vector)
143
        y: Second value (same type as x, or scalar)
144

145
    Returns:
146
        Component-wise minimum
147

148
    Example:
149
        min(3.0, 5.0)  # 3.0
150
        min(glm.vec3(1, 4, 2), glm.vec3(3, 2, 5))  # vec3(1, 2, 2)
151
        min(glm.vec3(1, 4, 2), 2.5)  # vec3(1, 2.5, 2)
152
    """
153

154
def max(x, y):
155
    """
156
    Return the larger of two values.
157

158
    Args:
159
        x: First value (scalar or vector)
160
        y: Second value (same type as x, or scalar)
161

162
    Returns:
163
        Component-wise maximum
164

165
    Example:
166
        max(3.0, 5.0)  # 5.0
167
        max(glm.vec3(1, 4, 2), glm.vec3(3, 2, 5))  # vec3(3, 4, 5)
168
    """
169

170
def clamp(x, minVal, maxVal):
171
    """
172
    Constrain x to lie between minVal and maxVal.
173

174
    Args:
175
        x: Value to clamp (scalar or vector)
176
        minVal: Minimum value (same type as x, or scalar)
177
        maxVal: Maximum value (same type as x, or scalar)
178

179
    Returns:
180
        Clamped value(s)
181

182
    Example:
183
        clamp(7.0, 2.0, 5.0)  # 5.0
184
        clamp(glm.vec3(-1, 3, 8), 0.0, 5.0)  # vec3(0, 3, 5)
185
    """
186

187
def fmin(x, y):
188
    """
189
    Return the minimum of two values (handles NaN differently than min).
190

191
    Args:
192
        x: First value (scalar or vector)
193
        y: Second value (same type as x, or scalar)
194

195
    Returns:
196
        Component-wise minimum, with NaN handling
197
    """
198

199
def fmax(x, y):
200
    """
201
    Return the maximum of two values (handles NaN differently than max).
202

203
    Args:
204
        x: First value (scalar or vector)
205
        y: Second value (same type as x, or scalar)
206

207
    Returns:
208
        Component-wise maximum, with NaN handling
209
    """
210

211
def fma(a, b, c):
212
    """
213
    Fused multiply-add operation: (a * b) + c.
214

215
    Args:
216
        a: First multiplicand (scalar or vector)
217
        b: Second multiplicand (same type as a)
218
        c: Addend (same type as a)
219

220
    Returns:
221
        Fused multiply-add result with higher precision
222
    """
223
```
224

225
### Trigonometric Functions
226

227
Complete set of trigonometric functions including basic, inverse, and hyperbolic variants.
228

229
```python { .api }
230
def radians(degrees):
231
    """
232
    Convert degrees to radians.
233

234
    Args:
235
        degrees: Angle in degrees (scalar or vector)
236

237
    Returns:
238
        Angle in radians
239

240
    Example:
241
        radians(90.0)  # ~1.5708 (π/2)
242
        radians(glm.vec3(0, 90, 180))  # vec3(0, π/2, π)
243
    """
244

245
def degrees(radians):
246
    """
247
    Convert radians to degrees.
248

249
    Args:
250
        radians: Angle in radians (scalar or vector)
251

252
    Returns:
253
        Angle in degrees
254

255
    Example:
256
        degrees(glm.pi() / 2)  # 90.0
257
    """
258

259
def sin(angle):
260
    """
261
    Calculate sine of angle.
262

263
    Args:
264
        angle: Angle in radians (scalar or vector)
265

266
    Returns:
267
        Sine value(s)
268

269
    Example:
270
        sin(glm.pi() / 2)  # 1.0
271
        sin(glm.vec3(0, glm.pi()/2, glm.pi()))  # vec3(0, 1, 0)
272
    """
273

274
def cos(angle):
275
    """
276
    Calculate cosine of angle.
277

278
    Args:
279
        angle: Angle in radians (scalar or vector)
280

281
    Returns:
282
        Cosine value(s)
283

284
    Example:
285
        cos(0.0)  # 1.0
286
        cos(glm.pi() / 2)  # ~0.0
287
    """
288

289
def tan(angle):
290
    """
291
    Calculate tangent of angle.
292

293
    Args:
294
        angle: Angle in radians (scalar or vector)
295

296
    Returns:
297
        Tangent value(s)
298

299
    Example:
300
        tan(glm.pi() / 4)  # 1.0
301
    """
302

303
def asin(x):
304
    """
305
    Calculate arcsine (inverse sine).
306

307
    Args:
308
        x: Input value in range [-1, 1] (scalar or vector)
309

310
    Returns:
311
        Angle in radians [-π/2, π/2]
312

313
    Example:
314
        asin(1.0)  # π/2
315
        asin(0.5)  # π/6
316
    """
317

318
def acos(x):
319
    """
320
    Calculate arccosine (inverse cosine).
321

322
    Args:
323
        x: Input value in range [-1, 1] (scalar or vector)
324

325
    Returns:
326
        Angle in radians [0, π]
327

328
    Example:
329
        acos(0.0)  # π/2
330
        acos(-1.0)  # π
331
    """
332

333
def atan(y, x=None):
334
    """
335
    Calculate arctangent.
336

337
    Args:
338
        y: Y coordinate or y/x ratio (scalar or vector)
339
        x: X coordinate (optional, scalar or vector)
340

341
    Returns:
342
        Angle in radians
343
        - atan(y): range [-π/2, π/2]
344
        - atan(y, x): range [-π, π] (two-argument version)
345

346
    Example:
347
        atan(1.0)  # π/4
348
        atan(1.0, 1.0)  # π/4
349
        atan(-1.0, 1.0)  # -π/4
350
    """
351

352
def sinh(x):
353
    """
354
    Calculate hyperbolic sine.
355

356
    Args:
357
        x: Input value (scalar or vector)
358

359
    Returns:
360
        Hyperbolic sine value(s)
361
    """
362

363
def cosh(x):
364
    """
365
    Calculate hyperbolic cosine.
366

367
    Args:
368
        x: Input value (scalar or vector)
369

370
    Returns:
371
        Hyperbolic cosine value(s)
372
    """
373

374
def tanh(x):
375
    """
376
    Calculate hyperbolic tangent.
377

378
    Args:
379
        x: Input value (scalar or vector)
380

381
    Returns:
382
        Hyperbolic tangent value(s)
383
    """
384

385
def asinh(x):
386
    """
387
    Calculate inverse hyperbolic sine.
388

389
    Args:
390
        x: Input value (scalar or vector)
391

392
    Returns:
393
        Inverse hyperbolic sine value(s)
394
    """
395

396
def acosh(x):
397
    """
398
    Calculate inverse hyperbolic cosine.
399

400
    Args:
401
        x: Input value >= 1 (scalar or vector)
402

403
    Returns:
404
        Inverse hyperbolic cosine value(s)
405
    """
406

407
def atanh(x):
408
    """
409
    Calculate inverse hyperbolic tangent.
410

411
    Args:
412
        x: Input value in range (-1, 1) (scalar or vector)
413

414
    Returns:
415
        Inverse hyperbolic tangent value(s)
416
    """
417
```
418

419
### Extended Trigonometric Functions
420

421
Additional trigonometric functions including secant, cosecant, and cotangent variants.
422

423
```python { .api }
424
def sec(angle):
425
    """
426
    Calculate secant (1/cos).
427

428
    Args:
429
        angle: Angle in radians (scalar or vector)
430

431
    Returns:
432
        Secant value(s)
433
    """
434

435
def csc(angle):
436
    """
437
    Calculate cosecant (1/sin).
438

439
    Args:
440
        angle: Angle in radians (scalar or vector)
441

442
    Returns:
443
        Cosecant value(s)
444
    """
445

446
def cot(angle):
447
    """
448
    Calculate cotangent (1/tan).
449

450
    Args:
451
        angle: Angle in radians (scalar or vector)
452

453
    Returns:
454
        Cotangent value(s)
455
    """
456

457
def asec(x):
458
    """
459
    Calculate inverse secant.
460

461
    Args:
462
        x: Input value |x| >= 1 (scalar or vector)
463

464
    Returns:
465
        Inverse secant value(s) in radians
466
    """
467

468
def acsc(x):
469
    """
470
    Calculate inverse cosecant.
471

472
    Args:
473
        x: Input value |x| >= 1 (scalar or vector)
474

475
    Returns:
476
        Inverse cosecant value(s) in radians
477
    """
478

479
def acot(x):
480
    """
481
    Calculate inverse cotangent.
482

483
    Args:
484
        x: Input value (scalar or vector)
485

486
    Returns:
487
        Inverse cotangent value(s) in radians
488
    """
489

490
def sech(x):
491
    """
492
    Calculate hyperbolic secant.
493

494
    Args:
495
        x: Input value (scalar or vector)
496

497
    Returns:
498
        Hyperbolic secant value(s)
499
    """
500

501
def csch(x):
502
    """
503
    Calculate hyperbolic cosecant.
504

505
    Args:
506
        x: Input value != 0 (scalar or vector)
507

508
    Returns:
509
        Hyperbolic cosecant value(s)
510
    """
511

512
def coth(x):
513
    """
514
    Calculate hyperbolic cotangent.
515

516
    Args:
517
        x: Input value != 0 (scalar or vector)
518

519
    Returns:
520
        Hyperbolic cotangent value(s)
521
    """
522

523
def asech(x):
524
    """
525
    Calculate inverse hyperbolic secant.
526

527
    Args:
528
        x: Input value in range (0, 1] (scalar or vector)
529

530
    Returns:
531
        Inverse hyperbolic secant value(s)
532
    """
533

534
def acsch(x):
535
    """
536
    Calculate inverse hyperbolic cosecant.
537

538
    Args:
539
        x: Input value != 0 (scalar or vector)
540

541
    Returns:
542
        Inverse hyperbolic cosecant value(s)
543
    """
544

545
def acoth(x):
546
    """
547
    Calculate inverse hyperbolic cotangent.
548

549
    Args:
550
        x: Input value |x| > 1 (scalar or vector)
551

552
    Returns:
553
        Inverse hyperbolic cotangent value(s)
554
    """
555
```
556

557
### Exponential and Logarithmic Functions
558

559
Power, exponential, and logarithmic functions for scientific calculations.
560

561
```python { .api }
562
def pow(x, y):
563
    """
564
    Calculate x raised to the power of y.
565

566
    Args:
567
        x: Base value (scalar or vector)
568
        y: Exponent (scalar or vector, same type as x)
569

570
    Returns:
571
        x^y
572

573
    Example:
574
        pow(2.0, 3.0)  # 8.0
575
        pow(glm.vec3(2, 3, 4), 2.0)  # vec3(4, 9, 16)
576
    """
577

578
def exp(x):
579
    """
580
    Calculate e raised to the power of x.
581

582
    Args:
583
        x: Exponent (scalar or vector)
584

585
    Returns:
586
        e^x
587

588
    Example:
589
        exp(1.0)  # e (~2.718)
590
        exp(0.0)  # 1.0
591
    """
592

593
def exp2(x):
594
    """
595
    Calculate 2 raised to the power of x.
596

597
    Args:
598
        x: Exponent (scalar or vector)
599

600
    Returns:
601
        2^x
602

603
    Example:
604
        exp2(3.0)  # 8.0
605
        exp2(glm.vec2(1, 4))  # vec2(2, 16)
606
    """
607

608
def log(x):
609
    """
610
    Calculate natural logarithm of x.
611

612
    Args:
613
        x: Input value > 0 (scalar or vector)
614

615
    Returns:
616
        ln(x)
617

618
    Example:
619
        log(glm.e())  # 1.0
620
        log(1.0)  # 0.0
621
    """
622

623
def log2(x):
624
    """
625
    Calculate base-2 logarithm of x.
626

627
    Args:
628
        x: Input value > 0 (scalar or vector)
629

630
    Returns:
631
        log₂(x)
632

633
    Example:
634
        log2(8.0)  # 3.0
635
        log2(glm.vec3(2, 4, 8))  # vec3(1, 2, 3)
636
    """
637

638
def sqrt(x):
639
    """
640
    Calculate square root of x.
641

642
    Args:
643
        x: Input value >= 0 (scalar or vector)
644

645
    Returns:
646
        √x
647

648
    Example:
649
        sqrt(9.0)  # 3.0
650
        sqrt(glm.vec2(4, 25))  # vec2(2, 5)
651
    """
652

653
def inversesqrt(x):
654
    """
655
    Calculate inverse square root (1/√x).
656

657
    Args:
658
        x: Input value > 0 (scalar or vector)
659

660
    Returns:
661
        1/√x
662

663
    Example:
664
        inversesqrt(4.0)  # 0.5
665
        inversesqrt(glm.vec2(1, 9))  # vec2(1, 1/3)
666
    """
667

668
def modf(x, i):
669
    """
670
    Extract integer and fractional parts of x.
671

672
    Args:
673
        x: Input value (scalar or vector)
674
        i: Output parameter for integer part
675

676
    Returns:
677
        Fractional part of x (x - floor(x))
678
    """
679

680
def frexp(x, exp):
681
    """
682
    Extract mantissa and exponent from floating-point number.
683

684
    Args:
685
        x: Input value (scalar or vector)
686
        exp: Output parameter for exponent
687

688
    Returns:
689
        Mantissa (significand) in range [0.5, 1.0) or 0
690
    """
691

692
def ldexp(x, exp):
693
    """
694
    Construct floating-point number from mantissa and exponent.
695

696
    Args:
697
        x: Mantissa (scalar or vector)
698
        exp: Exponent (scalar or integer vector)
699

700
    Returns:
701
        x * 2^exp
702
    """
703
```
704

705
### Interpolation Functions
706

707
Functions for smooth blending and transitions between values.
708

709
```python { .api }
710
def mix(x, y, a):
711
    """
712
    Linear interpolation between x and y.
713

714
    Args:
715
        x: Start value (scalar or vector)
716
        y: End value (same type as x)
717
        a: Interpolation factor (scalar or vector)
718

719
    Returns:
720
        x * (1 - a) + y * a
721

722
    Example:
723
        mix(0.0, 10.0, 0.5)  # 5.0
724
        mix(glm.vec3(0), glm.vec3(10), 0.3)  # vec3(3, 3, 3)
725
    """
726

727
def step(edge, x):
728
    """
729
    Step function: 0.0 if x < edge, 1.0 otherwise.
730

731
    Args:
732
        edge: Threshold value (scalar or vector)
733
        x: Input value (scalar or vector)
734

735
    Returns:
736
        0.0 or 1.0 based on comparison
737

738
    Example:
739
        step(0.5, 0.3)  # 0.0
740
        step(0.5, 0.7)  # 1.0
741
        step(0.5, glm.vec3(0.2, 0.6, 0.8))  # vec3(0, 1, 1)
742
    """
743

744
def smoothstep(edge0, edge1, x):
745
    """
746
    Smooth Hermite interpolation between 0 and 1.
747

748
    Args:
749
        edge0: Lower edge of the transition (scalar or vector)
750
        edge1: Upper edge of the transition (scalar or vector)
751
        x: Input value (scalar or vector)
752

753
    Returns:
754
        Smooth transition from 0.0 to 1.0
755

756
    Example:
757
        smoothstep(0.0, 1.0, 0.5)  # 0.5 with smooth curve
758
        smoothstep(0.0, 10.0, glm.vec3(2, 5, 8))  # Smooth transitions
759
    """
760
```
761

762
### Usage Examples
763

764
```python
765
from pyglm import glm
766
import math
767

768
# === Basic Math Operations ===
769

770
# Scalar operations
771
value = -3.7
772
abs_val = glm.abs(value)  # 3.7
773
floor_val = glm.floor(value)  # -4.0
774
ceil_val = glm.ceil(value)  # -3.0
775
fract_val = glm.fract(value)  # 0.3
776

777
# Component-wise vector operations
778
vec = glm.vec3(-2.3, 4.7, -1.1)
779
abs_vec = glm.abs(vec)  # vec3(2.3, 4.7, 1.1)
780
floor_vec = glm.floor(vec)  # vec3(-3.0, 4.0, -2.0)
781

782
# === Trigonometry ===
783

784
# Convert degrees to radians
785
angle_deg = 45.0
786
angle_rad = glm.radians(angle_deg)  # π/4
787

788
# Basic trig functions
789
sin_val = glm.sin(angle_rad)  # ~0.707
790
cos_val = glm.cos(angle_rad)  # ~0.707
791
tan_val = glm.tan(angle_rad)  # 1.0
792

793
# Vector trigonometry
794
angles = glm.vec3(0.0, glm.pi()/4, glm.pi()/2)
795
sin_values = glm.sin(angles)  # vec3(0, ~0.707, 1)
796

797
# Inverse trigonometry
798
asin_val = glm.asin(0.5)  # π/6 (30 degrees)
799
atan2_val = glm.atan(1.0, 1.0)  # π/4 (45 degrees)
800

801
# === Exponentials and Logarithms ===
802

803
# Power functions
804
power_result = glm.pow(2.0, 3.0)  # 8.0
805
exp_result = glm.exp(1.0)  # e (~2.718)
806
exp2_result = glm.exp2(3.0)  # 8.0
807

808
# Logarithms
809
log_result = glm.log(glm.e())  # 1.0
810
log2_result = glm.log2(8.0)  # 3.0
811

812
# Square roots
813
sqrt_result = glm.sqrt(16.0)  # 4.0
814
inv_sqrt = glm.inversesqrt(4.0)  # 0.5
815

816
# Vector exponentials
817
bases = glm.vec3(2, 3, 4)
818
powers = glm.vec3(2, 2, 2)
819
powered = glm.pow(bases, powers)  # vec3(4, 9, 16)
820

821
# === Min, Max, and Clamping ===
822

823
# Scalar operations
824
min_val = glm.min(3.0, 7.0)  # 3.0
825
max_val = glm.max(3.0, 7.0)  # 7.0
826
clamped = glm.clamp(15.0, 0.0, 10.0)  # 10.0
827

828
# Vector operations
829
vec1 = glm.vec3(1, 8, 3)
830
vec2 = glm.vec3(5, 2, 7)
831
min_vec = glm.min(vec1, vec2)  # vec3(1, 2, 3)
832
max_vec = glm.max(vec1, vec2)  # vec3(5, 8, 7)
833

834
# Clamp vector to range
835
input_vec = glm.vec3(-2, 5, 12)
836
clamped_vec = glm.clamp(input_vec, 0.0, 10.0)  # vec3(0, 5, 10)
837

838
# === Interpolation ===
839

840
# Linear interpolation
841
start = 0.0
842
end = 100.0
843
t = 0.3
844
interpolated = glm.mix(start, end, t)  # 30.0
845

846
# Vector interpolation
847
start_vec = glm.vec3(0, 0, 0)
848
end_vec = glm.vec3(10, 20, 30)
849
interpolated_vec = glm.mix(start_vec, end_vec, 0.5)  # vec3(5, 10, 15)
850

851
# Step function for thresholding
852
values = glm.vec4(0.2, 0.5, 0.8, 1.2)
853
threshold = 0.6
854
stepped = glm.step(threshold, values)  # vec4(0, 0, 1, 1)
855

856
# Smooth step for easing
857
smooth_values = glm.smoothstep(0.0, 1.0, glm.vec4(0, 0.25, 0.5, 0.75))
858
# Results in smooth curve instead of linear
859

860
# === Practical Examples ===
861

862
# Normalize angle to [0, 2π] range
863
def normalize_angle(angle):
864
    two_pi = 2.0 * glm.pi()
865
    return angle - glm.floor(angle / two_pi) * two_pi
866

867
# Smooth falloff function for lighting
868
def smooth_falloff(distance, max_distance):
869
    t = glm.clamp(distance / max_distance, 0.0, 1.0)
870
    return 1.0 - glm.smoothstep(0.0, 1.0, t)
871

872
# Convert temperature (Celsius to Fahrenheit)
873
celsius_temps = glm.vec3(0, 25, 100)  # Freezing, room temp, boiling
874
fahrenheit_temps = celsius_temps * (9.0/5.0) + 32.0  # vec3(32, 77, 212)
875

876
# Oscillating movement using sine wave
877
time = 2.5
878
amplitude = 5.0
879
frequency = 1.0
880
position = amplitude * glm.sin(frequency * time)
881

882
# Exponential decay (e.g., for fade effects)
883
initial_value = 100.0
884
decay_rate = 0.1
885
time_elapsed = 3.0
886
current_value = initial_value * glm.exp(-decay_rate * time_elapsed)
887

888
# Distance-based color mixing
889
distance = 15.0
890
near_color = glm.vec3(1.0, 0.0, 0.0)  # Red
891
far_color = glm.vec3(0.0, 0.0, 1.0)   # Blue
892
max_distance = 20.0
893

894
t = glm.clamp(distance / max_distance, 0.0, 1.0)
895
final_color = glm.mix(near_color, far_color, t)
896
```
897

898
### Mathematical Constants
899

900
PyGLM provides convenient access to mathematical constants:
901

902
```python
903
from pyglm import glm
904

905
# Common constants
906
pi_val = glm.pi()           # π
907
half_pi = glm.half_pi()     # π/2
908
two_pi = glm.two_pi()       # 2π
909
e_val = glm.e()             # Euler's number
910
golden_ratio = glm.golden_ratio()  # φ
911
root_two = glm.root_two()   # √2
912
```
913

914
All functions support both scalar and vector inputs, making them highly versatile for graphics programming where component-wise operations on vectors are common.