Phausto — Math & Conversion Tools

Arithmetic, mathematical functions, constants and unit conversions — as objects in the signal graph rather than as operators between them.

1. Operator or UGen?

Most of what is on this page exists twice: as a message you send to a signal, and as a UGen class you instantiate. aSignal log and PhLog2 do comparable jobs by different routes.

Form	When to use it
Message — `aSignal abs`	Inline in an expression. Shorter, and reads naturally
UGen — `PhSignum new`	When you need an object: to name it, reuse it, or place it in a collection

The operator forms are documented in Connecting Unit Generators §8. This page catalogues the classes.

Everything here is sample-by-sample These are not computed once when the patch is built. Each one is part of the running signal graph and evaluates at audio rate, which is what makes them usable as modulation shapers.

2. Arithmetic operations

2.1 Binary operations

Class	Operation	Operator form
PhAdder	Sum	`+`
PhSubtractor	Difference	`-`
PhMultiplicator	Product	`*`
PhDivider	Quotient	`/`
PhModulor	Modulo	`%`
PhPower	Exponentiation	—

2.2 Routing operations

Class	Role
PhBinaryOperation	Superclass of the two-input operations
PhUnaryOperation	Superclass of the one-input operations
PhSplitOperation	Fan one signal out to several destinations
PhMergeOperation	Fold several channels into fewer
PhCrossnn	Cross-route n channels

3. Unary functions

3.1 General

Class	Computes
PhNeg	Negation
PhInverse	Reciprocal
PhSignum	Sign: −1, 0 or 1
PhFrac	Fractional part
PhSub	Subtraction as a unary operation
PhCubeRoot	Cube root
PhNextPowerOf2	Next power of two
PhDiffn	Difference between successive samples
PhZeroCrossing	Zero-crossing detection
PhFTZ	Flush denormals to zero
PhPrimes	Prime number generation
PhDeg2Rad, PhRad2Deg	Degrees and radians

PhZeroCrossing is a pitch detector's front end Counting zero crossings over a window is the cheapest usable estimate of frequency, and PhDiffn next to it gives you slope. Together they are a lightweight analysis pair for driving something from an input signal.

3.2 Exponential and logarithmic

Class	Computes
PhLog2	Base-2 logarithm
PhLogB	Exponent of the floating-point representation
PhILogB	The same, as an integer
PhLog1p	log(1 + x) — accurate for small x
PhExpM1	exp(x) − 1 — accurate for small x

Why log1p and expm1 exist For very small x, computing log(1 + x) directly loses most of its precision to rounding. These variants keep it. It matters in filter coefficient computation and in anything working near unity gain.

3.3 Special functions

Class	Computes
PhErf	Error function
PhErfC	Complementary error function
PhLGamma	Log gamma function
PhJ0, PhJ1	Bessel functions of the first kind, orders 0 and 1
PhY0, PhY1	Bessel functions of the second kind, orders 0 and 1
PhChebychev	Chebyshev polynomial
PhChebychevPoly	Chebyshev polynomial series

Chebyshev polynomials are a waveshaping tool The nth Chebyshev polynomial maps a sine wave to its nth harmonic exactly. Feeding a sine through a weighted sum of them gives precise control over the harmonic spectrum — classic waveshaping synthesis, and far more predictable than an arbitrary saturator.

The Bessel functions appear in FM and in circular-membrane models, where they describe the distribution of sideband energy and the modes of a drum head respectively.

3.4 Tests and predicates

Class	Returns 1 when
PhIsNan	The value is not a number
PhIsInf	The value is infinite
PhNot	Logical negation

A use for PhIsNan Feedback networks and unstable filters can produce NaN, at which point the whole patch goes silent and stays silent. Inserting a NaN test lets you detect that in the graph rather than wondering why the sound stopped.

4. Binary mathematical functions

Class	Computes
PhHypothenuse	√(x² + y²) without overflow
PhCopySign	Magnitude of one operand with the sign of the other
PhModuloMath	Mathematical modulo
PhLdExp	x × 2ⁿ
PhScalb	Scale by a power of the radix
PhJn, PhYn	Bessel functions of arbitrary order

5. Trigonometry and antialiasing

Ordinary trigonometric messages — sin, cos, aTan — are available on any signal. The Trigonometry family under the Antialiased tag is different: these are band-limited implementations built for waveshaping.

Class	Function
AASine, AASine2	Antialiased sine
Cosine1, Cosine2	Antialiased cosine
Tangent	Antialiased tangent
ArcSin, ArcSin2	Arcsine
ArcCos, ArcCos2	Arccosine
ACosh1, ACosh2	Inverse hyperbolic cosine
ATanh1, Atanh2	Inverse hyperbolic tangent

Why antialiased versions exist Waveshaping generates harmonics above the Nyquist frequency, which fold back down as inharmonic aliasing — the metallic grit that makes naïve digital distortion sound cheap. These implementations use antiderivative antialiasing to suppress it. Use them wherever a function is being applied to a full-scale audio signal rather than to a control value.

The saturators in Effects §3 are the applied form of the same idea.

6. Constants and the environment

Class	Value
PhConstantPI	π
PhConstantE	e
PhConstantEpsilon	Smallest representable difference
PhConstantMin, PhConstantMax	Representable range bounds
PhConstantT	The sample period
PhSampleRate	Current sample rate, as a signal
PhSampleDuration	Duration of one sample
PhBlockSize	Current audio block size

Write sample-rate-independent patches A delay of "2000 samples" means different things at 44.1 and 96 kHz. Expressing it through PhSampleRate or PhSec2Samp keeps a patch sounding the same wherever it runs — which matters as soon as you export it. See Exporting.

7. Unit conversions

Sixteen PhConversionTool subclasses translate between the units audio actually uses. Each has an inverse, and they come in pairs.

7.1 Gain

Class	Converts
PhDb2Linear	Decibels to a linear multiplier
PhLinear2Db	Linear multiplier to decibels
PhLinear2LogGain	Linear to logarithmic gain
PhLog2LinearGain	Logarithmic to linear gain

uLevel is linear, but loudness perception is closer to logarithmic. Putting a fader through PhDb2Linear is what makes it feel even across its travel — see Unit Generators §2.1.

7.2 Pitch

Class	Converts
PhMidiKey2Hz	MIDI note number to hertz — key 69 is 440 Hz
PhHz2MidiKey	Hertz to MIDI note number
PhPianoKey2Hz	Piano key number to hertz
PhHz2PianoKey	Hertz to piano key number
PhSemi2Ratio	Semitones to a frequency ratio
PhRatio2Semitone	Frequency ratio to semitones
PhCent2Ratio	Cents to a frequency ratio
PhRatio2Cent	Frequency ratio to cents

Semitone and cent conversions are the right tools for transposition and detuning, because a musical interval is a ratio, not an offset — detuning by "2 Hz" means something different at every pitch, while detuning by 5 cents does not.

7.3 Time and filter coefficients

Class	Converts
PhSec2Samp	Seconds to samples
PhSamp2Sec	Samples to seconds
PhTau2Pole	A time constant to a one-pole filter coefficient
PhPole2tau	A one-pole coefficient back to a time constant

Tau and pole A one-pole smoother is normally specified by a coefficient between 0 and 1, which is meaningless to think in. PhTau2Pole lets you say "settle in 30 milliseconds" instead. The same reasoning produces the T60 and Tau filter variants in Filters §8.

8. Interpolation and quantisation

Class	Role
PhInterpolateLinear	Linear interpolation between two values
PhInterpolateRaiseModulo	Interpolation with modulo wrapping — for phase and index values
PhInterpolate	General interpolation
PhQuantize	Quantise a signal to discrete steps

Interpolation controls come from the PhInterpSetter trait — v0:, v1:, dv: and interpControl:. See Setter Traits §7.

Quantise pitch, not frequency PhQuantize on a frequency signal gives arbitrary steps; on a MIDI note number it gives semitones. Convert to note numbers, quantise, convert back — which is how a random-walk melody is kept in a scale.

9. Where to go next

Document	What it covers
Connecting UGens	The operator forms of everything here.
Filters	Where time constants and coefficients are used.
Effects	Waveshaping as an applied use of these functions.
UGen Library	The complete class list.

10. Troubleshooting

My patch went silent and will not come back

Something produced NaN or an infinity — usually a division by zero or a runaway feedback loop. Rebuild the DSP, and consider a PhIsNan test while debugging — §3.4.

Waveshaping sounds gritty and metallic

Aliasing. Use the antialiased functions — §5.

My fader feels uneven — all the action is at the bottom

It is linear. Put it through PhDb2Linear — §7.1.

A detuned pair sounds right low down and wrong high up

You are detuning by a frequency offset rather than a ratio. Use cents — §7.2.

The patch sounds different at a different sample rate

A time is specified in samples. Express it in seconds — §6.

Quantising the frequency gives out-of-tune notes

Quantise MIDI note numbers instead, then convert — §8.