Math¶

A comprehensive mathematical utilities library providing

Import¶

import "_IVLS/std-library/nodes/components/math.ksp"

Node: `Stl.Math`¶

Uses: Init

Overview¶

A comprehensive mathematical utilities library providing:

- Type conversion helpers (float casting, bipolar/unipolar conversion)
- Audio utilities (dB/amplitude conversion, equal power curves)
- Pseudo-random number generation with seeding support
- Bitwise operations and bitmask utilities
- Curve functions (power, exponential, manual exponent)
- Comparison and range checking functions
- Value scaling and partitioned crossfading
- Advanced math functions (logarithms, powers, roots, norms)
- String formatting for fixed-point decimals

Constants¶

Constant	Value	Description
`~math.PI`	`3.14159265358979`	real
`~math.TAU`	`6.28318530717958`	real
`~math.PI_2`	`~math.PI / 2.0`	real
`~math.PI_4`	`~math.PI / 4.0`	real
`~math._1_PI`	`1.0 / ~math.PI`	real
`~math._2_PI`	`2.0 / ~math.PI`	real
`~math.SQRT_2`	`1.4142135623731`	real
`~math._1_SQRT_2`	`1.0 / ~math.SQRT_2`	real
`~math.LOG_2`	`log(2.0)`	real
`~math.E`	`2.71828182845905`	real
`math.INT_MAX`	`0x7FFFFFFF`	integer
`math.INT_MIN`	`0x80000000`	integer
`math.ALLMASK`	`11111111111111111111111111111111b`	integer

API¶

Nodes¶

Name	Description
`node Stl.Math`	Node providing a comprehensive mathematical utilities library with constants, au...

Defines¶

Name	Description
`define BOOL.CHOOSE(#bool#, #a#, #b#)`	Branchless conditional selector.
`define CONDITION.IS_BITMASK_COMMON(A, B)`	Checks if two bitmasks share any common bits.
`define float(#x#)`	Casts an integer to a real (float) value for stylistic clarity
`define MATH.DECIMAL_STRING(#n#, #pos#, #prec#)`	Formats a number as a decimal string (alternative to math.print_decimal)
`define MATH.SEARCHFOUND(#array#, #value#)`	Checks if a value exists in an array (returns 1 or 0)

Macros¶

Name	Description
`op_self(#var#, #op#, #val#)`	Applies a binary operation to a variable in place.

Functions¶

Name	Description
`math.amp_to_db(a) -> return`	Converts linear amplitude to decibels
`math.bit_to_decimal(N) -> return`	Converts bit position to decimal value (power of 2)
`math.cbrt(value) -> return`	Cube root
`math.clamp(num, min, max) -> return`	Clamps a value between minimum and maximum bounds
`math.clip(value, top) -> return`	Clips a value to a maximum threshold (branchless)
`math.curve(ex, x, a, b) -> return`	Calculates value on a curved line using power function
`math.curve_exp(ex, x, a, b) -> return`	Calculates value on exponential curve Alternative to power curve with different ...
`math.curve_manual(ex, x, a, b) -> return`	Curved interpolation with manual exponent Provides direct control over curve sha...
`math.db_to_amp(db) -> return`	Converts decibels to linear amplitude
`math.equal_power(in) -> ratio`	Calculates equal-power crossfade curve Used for smooth panning and crossfading b...
`math.equals(A, B) -> return`	Checks if two integers are equal (branchless)
`math.exp2(value) -> return`	Exponential function base 2
`math.f_curve(ex, x, a, b) -> return`	Power curve with all float arguments Same as math.curve() but with float start/e...
`math.f_curve_exp(ex, x, a, b) -> return`	Exponential curve with all float arguments Same as math.curve_exp() but with flo...
`math.f_mod(b, a) -> return`	Floating-point modulo operation
`math.flip(value, bit_pos) -> return`	Flips a specific bit in a bitmask
`math.gate(value, bottom) -> return`	Gates a value to a minimum threshold (branchless)
`math.gcd(x, y) -> return`	Calculates Greatest Common Divisor using Euclidean algorithm
`math.get_nth_bit(B, N) -> return`	Gets the value of a specific bit (0 or 1)
`math.get_timestretched_offset(root_note, result_note, ideal_transient, extra_offset) -> result`	Calculates sample start offset to maintain transient alignment after time-stretc...
`math.has_shared_bits(A, B) -> return`	Checks if two bitmasks share any common bits
`math.inv(x) -> return`	Calculates reciprocal of a value
`math.is_equal(a, b) -> return`	Tests if a == b (branchless)
`math.is_greater(a, b) -> return`	Tests if a > b (branchless)
`math.is_in_range(value, a, b) -> return`	Tests if value is within range [a, b] (branchless)
`math.is_not_equal(a, b) -> return`	Tests if a ≠ b (branchless)
`math.is_not_greater(a, b) -> return`	Tests if a ≤ b (branchless)
`math.kontakt_db_clamp(unsafe_db) -> db`	Clamps dB values to Kontakt's safe range Prevents crashes from extreme dB values
`math.lcm(x, y) -> return`	Calculates Least Common Multiple
`math.lcm_array(array) -> return`	Calculates LCM of all values in an array
`math.ln(value) -> return`	Natural logarithm (base e) Alias for KSP's log() function for clarity
`math.log10(value) -> return`	Common logarithm (base 10)
`math.log2(value) -> return`	Binary logarithm (base 2)
`math.log_b(base, value) -> return`	Logarithm with arbitrary base
`math.max(a, b) -> return`	Returns maximum of two values (branchless)
`math.min(a, b) -> return`	Returns minimum of two values (branchless)
`math.mod_loop(in, loop_size) -> return`	Performs modulo operation with positive wraparound Useful for circular buffer in...
`math.norm(a, b) -> return`	Calculates 2D vector norm (Euclidean distance) Also known as: hypotenuse, magnit...
`math.norm_vect(vector) -> return`	Calculates n-dimensional vector norm
`math.nrt(n, value) -> return`	Calculates nth root of a value
`math.parity(value) -> return`	Checks if value is even
`math.pow2(value) -> return`	Squares a value
`math.pow3(value) -> return`	Cubes a value
`math.print_decimal(num, rsh, trunc) -> str`	Formats an integer as a decimal string with fixed-point representation
`math.print_magnitude(x, degree, precision) -> str`	Formats a normalized float as a decimal string scaled by a power of ten.
`math.rand(min, max) -> return`	Generates pseudo-random integer in specified range Uses Linear Congruential Gene...
`math.rand_reseed()`	Re-seeds the random number generator using current timer Provides non-determinis...
`math.rand_reset()`	Resets random number generator to default seed Provides repeatable random sequen...
`math.rand_seeded(min, max, seed) -> return`	Generates pseudo-random integer with external seed Allows multiple independent r...
`math.range(a, b) -> return`	Calculates absolute difference between two values
`math.safe_db_add(a, b) -> sum`	Safely adds two dB values with Kontakt range protection
`math.safe_db_subtract(a, b) -> diff`	Safely subtracts two dB values with Kontakt range protection
`math.scale(value, in_min, in_max, out_min, out_max) -> return`	Fast integer scaling (less accurate than scale_accurate) Uses pure integer math ...
`math.scale_accurate(value, in_min, in_max, out_min, out_max) -> return`	Accurately rescales value from one range to another Uses floating-point math for...
`math.scale_partitioned(out_min, out_max, in, in_min, in_max, part_in, part_min, part_max, blend) -> return`	Creates n-partitioned crossfades within a range Useful for multi-layer velocity ...
`math.set_nth_bit(B, N, val)`	Sets or clears a specific bit in a bitmask
`math.sign(value, return_mode) -> return`	Returns sign of value
`math.sign_div(value) -> return`	Returns sign of value with zero support Works with both int and float
`math.to_bipolar(in) -> return`	Converts unipolar signal to bipolar
`math.to_unipolar(in) -> return`	Converts bipolar signal to unipolar
`math.trim(num, places) -> return`	Rounds floating-point number to specified decimal places
`math.value_flag_verify(flag, query, value) -> return`	Returns flag value if query matches flag, otherwise returns default value Useful...
`math.xor(A, B) -> return`	Performs bitwise XOR (exclusive OR)

Preprocessor Macros¶

`define float(#x#)`¶

Casts an integer to a real (float) value for stylistic clarity

Parameter	Type	Description
`#x#`	integer	the integer value to cast to real

`define BOOL.CHOOSE(#bool#, #a#, #b#)`¶

Branchless conditional selector.

Parameter	Type	Description
`#bool#`	integer	boolean condition (1 = true, 0 = false)
`#a#`	integer	value returned when #bool# is true
`#b#`	integer	value returned when #bool# is false

Post: (integer) - #a# if #bool# is 1, otherwise #b#

`define CONDITION.IS_BITMASK_COMMON(A, B)`¶

Checks if two bitmasks share any common bits.

Parameter	Type	Description
`A`	integer	base-10 encoded bitmask (e.g. binary 1000 is stored as 8)
`B`	integer	base-10 encoded bitmask (e.g. binary 1000 is stored as 8)

Post: (integer) - 1 if bitmasks share any bits, 0 otherwise

`define MATH.SEARCHFOUND(#array#, #value#)`¶

Checks if a value exists in an array (returns 1 or 0)

Parameter	Description
`#array#`	the array name to search
`#value#`	the value to search for

Post: Returns 1 if value is found in array, 0 otherwise

`op_self(#var#, #op#, #val#)`¶

Applies a binary operation to a variable in place.

Parameter	Description
`#var#`	variable to modify
`#op#`	operator to apply (e.g. +, -, *, /)
`#val#`	right-hand operand

`define MATH.DECIMAL_STRING(#n#, #pos#, #prec#)`¶

Formats a number as a decimal string (alternative to math.print_decimal)

Parameter	Description
`#n#`	number to interpret
`#pos#`	the position of the decimal point, with 0 being at the one's digit
`#prec#`	the cutoff of the decimal places, 0 being the one's digit

Post: Returns readable decimal string.

Usage: n = 12000, pos = 2, prec = 1 -> "120.0" n = 45600, pos = 3, prec = 1 -> "45.6"

`node Stl.Math`¶

Callbacks: Init

Node providing a comprehensive mathematical utilities library with constants, audio utilities, pseudo-random number generation, bitwise operations, curve functions, comparison predicates, value scaling, and advanced math functions

====================================================================¶

`math.amp_to_db(a) -> return`¶

Converts linear amplitude to decibels

Parameter	Type	Description
`a`	float	linear amplitude value (typically 0.0 to 1.0 or higher)

Returns: return — decibel value (dB)

Formula: dB = 20 × log₁₀(amplitude)

`math.db_to_amp(db) -> return`¶

Converts decibels to linear amplitude

Parameter	Type	Description
`db`	float	decibel value

Returns: return — linear amplitude value

Formula: amplitude = 10^(dB/20)

`math.mod_loop(in, loop_size) -> return`¶

Performs modulo operation with positive wraparound Useful for circular buffer indexing and loop points

Parameter	Type	Description
`in`	int	input value (can be negative)
`loop_size`	int	size of the loop range

Returns: return — wrapped value always in range [0, loop_size-1]

Usage: math.mod_loop(-1, 8) returns 7 math.mod_loop(9, 8) returns 1

`math.equal_power(in) -> ratio`¶

Calculates equal-power crossfade curve Used for smooth panning and crossfading between two signals

Parameter	Type	Description
`in`	float	crossfade position (0.0 to 1.0)

Returns: ratio — curve value maintaining constant power

Notes: Equal-power law ensures perceived loudness remains constant during crossfade. Uses sine curve for smooth transition.

====================================================================¶

`math.print_decimal(num, rsh, trunc) -> str`¶

Formats an integer as a decimal string with fixed-point representation

Parameter	Type	Description
`num`	int	The integer value to format (treated as a fixed-point number)
`rsh`	int	Right shift: specifies the decimal point position (the number represents num / 10^rsh)
`trunc`	int	Truncation: number of decimal places to display

Returns: str — formatted decimal string

Usage:

math.print_decimal(12345, 2, 1)

Treats 12345 as 123.45 (divided by 10²)
Shows 1 decimal place
Returns "123.4"

math.print_decimal(5678, 3, 2)

Treats 5678 as 5.678 (divided by 10³)
Shows 2 decimal places
Returns "5.67"

Implementation Note: Integer part: num / 10^rsh Decimal part: (num mod 10^rsh) / 10^(rsh-trunc) The abs() ensures decimal part is always positive

`math.print_magnitude(x, degree, precision) -> str`¶

Formats a normalized float as a decimal string scaled by a power of ten.

Parameter	Type	Description
`x`	float	normalized input value (1.0 = full scale)
`degree`	int	scaling exponent; output is multiplied by 10^degree
`precision`	int	number of decimal places to display

Returns: str — formatted decimal string

====================================================================¶

`math.kontakt_db_clamp(unsafe_db) -> db`¶

Clamps dB values to Kontakt's safe range Prevents crashes from extreme dB values

Parameter	Type	Description
`unsafe_db`	int	potentially unsafe dB value

Returns: db — clamped dB value in safe range [-200000, 200000]

`math.safe_db_add(a, b) -> sum`¶

Safely adds two dB values with Kontakt range protection

Parameter	Type	Description
`a`	int	first dB value
`b`	int	second dB value

Returns: sum — clamped sum of dB values

`math.safe_db_subtract(a, b) -> diff`¶

Safely subtracts two dB values with Kontakt range protection

Parameter	Type	Description
`a`	int	first dB value (minuend)
`b`	int	second dB value (subtrahend)

Returns: diff — clamped difference of dB values

====================================================================¶

`math.to_unipolar(in) -> return`¶

Converts bipolar signal to unipolar

Parameter	Type	Description
`in`	float	Bipolar value, should be normalized to [-1.0, 1.0]

Returns: return — Unipolar value in range [0.0, 1.0]

Formula: unipolar = (bipolar × 0.5) + 0.5

Usage: -1.0 → 0.0 0.0 → 0.5 1.0 → 1.0

`math.to_bipolar(in) -> return`¶

Converts unipolar signal to bipolar

Parameter	Type	Description
`in`	float	Unipolar value, should be normalized to [0.0, 1.0]

Returns: return — Bipolar value in range [-1.0, 1.0]

Formula: bipolar = (unipolar × 2.0) - 1.0

Usage: 0.0 → -1.0 0.5 → 0.0 1.0 → 1.0

====================================================================¶

`math.get_timestretched_offset(root_note, result_note, ideal_transient, extra_offset) -> result`¶

Calculates sample start offset to maintain transient alignment after time-stretching.

Parameter	Type	Description
`root_note`	int	sample's original root note (MIDI note number)
`result_note`	int	target playback note (MIDI note number)
`ideal_transient`	float	transient position in the original sample (ms or μs)
`extra_offset`	float	additional desired offset (same units as ideal_transient)

Returns: result — offset to apply to the sample start

====================================================================¶

`math.rand(min, max) -> return`¶

Generates pseudo-random integer in specified range Uses Linear Congruential Generator (LCG) algorithm

Parameter	Type	Description
`min`	int	Minimum value (inclusive)
`max`	int	Maximum value (inclusive)

Returns: return — Random integer where min ≤ return ≤ max

Notes:

Uses internal seed (math.rand_seed) that updates on each call
Only lowest 24 bits used for better randomness
Range (max - min) must be less than 2^24 (16,777,216)
Not cryptographically secure
Sequence is deterministic given same seed

Lcg Parameters: Multiplier: 8088405 Increment: 1 These values chosen for good distribution properties

`math.rand_seeded(min, max, seed) -> return`¶

Generates pseudo-random integer with external seed Allows multiple independent random sequences

Parameter	Type	Description
`min`	int	Minimum value (inclusive)
`max`	int	Maximum value (inclusive)
`seed`	int	External seed variable (modified by this function)

Returns: return — Random integer where min ≤ return ≤ max

declare my_seed := 12345
value1 := math.rand_seeded(0, 100, my_seed)  // my_seed is updated
value2 := math.rand_seeded(0, 100, my_seed)  // different from value1

Notes:

Developer must initialize seed to a value of choice in init callback
Seed should be reset when repeatability is required (e.g. on transport start)
Same constraints as math.rand() regarding range

`math.rand_reseed()`¶

Re-seeds the random number generator using current timer Provides non-deterministic starting point

Post: Updates math.rand_seed with current KSP_TIMER value

Usage: Call this at script initialization or when unpredictable randomness is desired

`math.rand_reset()`¶

Resets random number generator to default seed Provides repeatable random sequences

Post: Sets math.rand_seed to default value (1107155288)

Usage: Call when you need the same random sequence every time Useful for testing or synchronized randomization

====================================================================¶

`math.bit_to_decimal(N) -> return`¶

Converts bit position to decimal value (power of 2)

Parameter	Type	Description
`N`	int	Bit position (0-based, LSB-right)

Returns: return — Decimal value 2^N

Usage: N = 0 → 1 (binary: 0001) N = 3 → 8 (binary: 1000) N = 7 → 128 (binary: 10000000)

`math.has_shared_bits(A, B) -> return`¶

Checks if two bitmasks share any common bits

Parameter	Type	Description
`A`	int	Base-10 encoded bitmask (e.g. binary 1000 stored as 8)
`B`	int	Base-10 encoded bitmask (e.g. binary 1000 stored as 8)

Returns: return — 1 if bitmasks share any bits, 0 otherwise

Usage:

A = 12 (binary: 1100) B = 10 (binary: 1010) Shared bits: 1000 (position 3) Returns: 1

`math.equals(A, B) -> return`¶

Checks if two integers are equal (branchless)

Parameter	Type	Description
`A`	int	First integer
`B`	int	Second integer

Returns: return — 1 if A == B, 0 otherwise

Implementation Note: Uses bit manipulation to avoid branching for performance

`math.value_flag_verify(flag, query, value) -> return`¶

Returns flag value if query matches flag, otherwise returns default value Useful for parameter validation and default handling

Parameter	Type	Description
`flag`	int	The flag value to check for
`query`	int	The value to test
`value`	int	Default value to return if query != flag

Returns: return — flag if query == flag, otherwise value

Usage: math.value_flag_verify(100, 100, 50) → 100 math.value_flag_verify(100, 75, 50) → 50

`math.xor(A, B) -> return`¶

Performs bitwise XOR (exclusive OR)

Parameter	Type	Description
`A`	int	First operand
`B`	int	Second operand

Returns: return — Bitwise XOR of A and B

Truth Table:

0 XOR 0 = 0 0 XOR 1 = 1 1 XOR 0 = 1 1 XOR 1 = 0

`math.set_nth_bit(B, N, val)`¶

Sets or clears a specific bit in a bitmask

Parameter	Type	Description
`B`	int	Base-10 encoded bitmask
`N`	int	Bit position (0-based, LSB-right)
`val`	int	1 to set bit, 0 to clear bit

Post: (int) B - Updated bitmask (modified by reference)

Usage: B = 5 (binary: 0101), N = 1, val = 1 Result: 7 (binary: 0111)

`math.get_nth_bit(B, N) -> return`¶

Gets the value of a specific bit (0 or 1)

Parameter	Type	Description
`B`	int	Base-10 encoded bitmask
`N`	int	Bit position (0-based, LSB-right)

Returns: return — 1 if bit is set, 0 if bit is clear

Usage: B = 12 (binary: 1100), N = 2 → returns 1 B = 12 (binary: 1100), N = 0 → returns 0