maths.lib

//################################### maths.lib ##########################################
//  Mathematic library for Faust. Its official prefix is `ma`.
//########################################################################################
// Some functions are implemented as Faust foreign functions of `math.h` functions
// that are not part of Faust's primitives. Defines also various constants and several
// utilities.
//########################################################################################

// ## History
// * 06/13/2016 [RM]	normalizing and integrating to new libraries
// * 07/08/2015	[YO]	documentation comments
// * 20/06/2014	[SL]	added FTZ function
// * 22/06/2013	[YO]	added float|double|quad variants of some foreign functions
// * 28/06/2005	[YO]	postfixed functions with 'f' to force float version instead of double
// * 28/06/2005	[YO]	removed 'modf' because it requires a pointer as argument

/************************************************************************
************************************************************************
FAUST library file
Copyright (C) 2003-2016 GRAME, Centre National de Creation Musicale
----------------------------------------------------------------------
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU Lesser General Public License as
published by the Free Software Foundation; either version 2.1 of the
License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public
License along with the GNU C Library; if not, write to the Free
Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
02111-1307 USA.

EXCEPTION TO THE LGPL LICENSE : As a special exception, you may create a
larger FAUST program which directly or indirectly imports this library
file and still distribute the compiled code generated by the FAUST
compiler, or a modified version of this compiled code, under your own
copyright and license. This EXCEPTION TO THE LGPL LICENSE explicitly
grants you the right to freely choose the license for the resulting
compiled code. In particular the resulting compiled code has no obligation
to be LGPL or GPL. For example you are free to choose a commercial or
closed source license or any other license if you decide so.
************************************************************************
************************************************************************/

declare name "Faust Math Library";
declare version "2.3";
declare author "GRAME";
declare copyright "GRAME";
declare license "LGPL with exception";

// This library contains platform specific constants 
pl = library("platform.lib");
ma = library("maths.lib"); // for compatible copy/paste out of this file

//=============================Functions Reference========================================
//========================================================================================


//---------------------------------`(ma.)SR`---------------------------------------
// Current sampling rate. Constant during
// program execution.
//
// #### Usage
//
// ```
// SR : _
// ```
//-----------------------------------------------------------------------------
SR = pl.SR;


//---------------------------------`(ma.)BS`---------------------------------------
// Current block-size. Can change during the execution.
//
// #### Usage
//
// ```
// BS : _
// ```
//-----------------------------------------------------------------------------
BS = fvariable(int count, <math.h>);


//---------------------------------`(ma.)PI`---------------------------------------
// Constant PI in double precision.
//
// #### Usage
//
// ```
// PI : _
// ```
//-----------------------------------------------------------------------------
PI = 3.14159265358979323846;


//---------------------------------`(ma.)E`---------------------------------------
// Constant e in double precision.
//
// #### Usage
//
// ```
// E : _
// ```
//-----------------------------------------------------------------------------
E = 2.71828182845904523536;


//---------------------------------`(ma.)EPSILON`---------------------------------------
// Constant EPSILON in simple/double/quad precision.
//
// #### Usage
//
// ```
// EPSILON : _
// ```
//-----------------------------------------------------------------------------
singleprecision EPSILON = 1.192092896e-07;
doubleprecision EPSILON = 2.2204460492503131e-016;
quadprecision EPSILON = 2.2204460492503131e-016;
fixedpointprecision EPSILON = 2.2204460492503131e-016;


//---------------------------------`(ma.)MIN`---------------------------------------
// Constant MIN in simple/double/quad precision (minimal positive value).
//
// #### Usage
//
// ```
// MIN : _
// ```
//-----------------------------------------------------------------------------
singleprecision MIN = 1.175494351e-38;
doubleprecision MIN = 2.2250738585072014e-308;
quadprecision MIN = 2.2250738585072014e-308;
fixedpointprecision MIN = 2.2250738585072014e-308;


//---------------------------------`(ma.)INFINITY`------------------------------
// Constant INFINITY in simple/double/quad precision (maximal positive value).
//
// #### Usage
//
// ```
// INFINITY : _
// ```
//-----------------------------------------------------------------------------
singleprecision INFINITY = 3.402823466e+38;
doubleprecision INFINITY = 1.7976931348623158e+308;
quadprecision INFINITY = 1.7976931348623158e+308;
fixedpointprecision INFINITY = 1.7976931348623158e+308;


//---------------------------------`(ma.)FTZ`---------------------------------------
// Flush to zero: force samples under the "maximum subnormal number"
// to be zero. Usually not needed in C++ because the architecture
// file take care of this, but can be useful in JavaScript for instance.
//
// #### Usage
//
// ```
// _ : FTZ : _
// ```
//
// #### Reference
//
// <http://docs.oracle.com/cd/E19957-01/806-3568/ncg_math.html>
//-----------------------------------------------------------------------------
FTZ(x) = x * (abs(x) > MIN);


//---------------------------------`(ma.)neg`---------------------------------------
// Invert the sign (-x) of a signal.
//
// #### Usage
//
// ```
// _ : neg : _
// ```
//-----------------------------------------------------------------------------
neg(x) = -x;


//-------`(ma.)sub(x,y)`------------------
// Subtract `x` and `y`.
//------------------------------
sub(x,y) = y-x;


//---------------------------------`(ma.)inv`---------------------------------------
// Compute the inverse (1/x) of the input signal.
//
// #### Usage
//
// ```
// _ : inv : _
// ```
//-----------------------------------------------------------------------------
inv(x) = 1/x;


//---------------------------------`(ma.)cbrt`--------------------------------------
// Computes the cube root of of the input signal.
//
// #### Usage
//
// ```
// _ : cbrt : _
// ```
//-----------------------------------------------------------------------------
cbrt = ffunction(float cbrtf|cbrt|cbrtl (float), <math.h>,"");


//---------------------------------`(ma.)hypot`-------------------------------------
// Computes the euclidian distance of the two input signals
// sqrt(x*x+y*y) without undue overflow or underflow.
//
// #### Usage
//
// ```
// _,_ : hypot : _
// ```
//-----------------------------------------------------------------------------
hypot = ffunction(float hypotf|hypot|hypotl (float, float), <math.h>,"");


//---------------------------------`(ma.)ldexp`-------------------------------------
// Takes two input signals: x and n, and multiplies x by 2 to the power n.
//
// #### Usage
//
// ```
// _,_ : ldexp : _
// ```
//-----------------------------------------------------------------------------
ldexp = ffunction(float ldexpf|ldexp|ldexpl (float, int), <math.h>,"");


//---------------------------------`(ma.)scalb`-------------------------------------
// Takes two input signals: x and n, and multiplies x by 2 to the power n.
//
// #### Usage
//
// ```
// _,_ : scalb : _
// ```
//-----------------------------------------------------------------------------
scalb = ffunction(float scalbnf|scalbn|scalbnl (float, int), <math.h>,"");


//---------------------------------`(ma.)log1p`----------------------------------
// Computes log(1 + x) without undue loss of accuracy when x is nearly zero.
//
// #### Usage
//
// ```
// _ : log1p : _
// ```
//-----------------------------------------------------------------------------
log1p = ffunction(float log1pf|log1p|log1pl (float), <math.h>,"");


//---------------------------------`(ma.)logb`---------------------------------------
// Return exponent of the input signal as a floating-point number.
//
// #### Usage
//
// ```
// _ : logb : _
// ```
//-----------------------------------------------------------------------------
logb = ffunction(float logbf|logb|logbl (float), <math.h>,"");


//---------------------------------`(ma.)ilogb`-------------------------------------
// Return exponent of the input signal as an integer number.
//
// #### Usage
//
// ```
// _ : ilogb : _
// ```
//-----------------------------------------------------------------------------
ilogb = ffunction(int ilogbf|ilogb|ilogbl (float), <math.h>,"");


//---------------------------------`(ma.)log2`-------------------------------------
// Returns the base 2 logarithm of x.
//
// #### Usage
//
// ```
// _ : log2 : _
// ```
//-----------------------------------------------------------------------------
log2(x) = log(x)/log(2.0);


//---------------------------------`(ma.)expm1`-------------------------------------
// Return exponent of the input signal minus 1 with better precision.
//
// #### Usage
//
// ```
// _ : expm1 : _
// ```
//-----------------------------------------------------------------------------
expm1 = ffunction(float expm1f|expm1|expm1l (float), <math.h>,"");


//---------------------------------`(ma.)acosh`-------------------------------------
// Computes the principle value of the inverse hyperbolic cosine
// of the input signal.
//
// #### Usage
//
// ```
// _ : acosh : _
// ```
//-----------------------------------------------------------------------------
acosh = ffunction(float acoshf|acosh|acoshl (float), <math.h>, "");


//--------------------------------`(ma.)asinh`-----------------------------------
// Computes the inverse hyperbolic sine of the input signal.
//
// #### Usage
//
// ```
// _ : asinh : _
// ```
//-----------------------------------------------------------------------------
asinh = ffunction(float asinhf|asinh|asinhl (float), <math.h>, "");


//--------------------------------`(ma.)atanh`-----------------------------------
// Computes the inverse hyperbolic tangent of the input signal.
//
// #### Usage
//
// ```
// _ : atanh : _
// ```
//-----------------------------------------------------------------------------
atanh = ffunction(float atanhf|atanh|atanhl (float), <math.h>, "");


//---------------------------------`(ma.)sinh`---------------------------------------
// Computes the hyperbolic sine of the input signal.
//
// #### Usage
//
// ```
// _ : sinh : _
// ```
//-----------------------------------------------------------------------------
sinh = ffunction(float sinhf|sinh|sinhl (float), <math.h>, "");


//---------------------------------`(ma.)cosh`--------------------------------------
// Computes the hyperbolic cosine of the input signal.
//
// #### Usage
//
// ```
// _ : cosh : _
// ```
//-----------------------------------------------------------------------------
cosh = ffunction(float coshf|cosh|coshl (float), <math.h>, "");


//---------------------------------`(ma.)tanh`--------------------------------------
// Computes the hyperbolic tangent of the input signal.
//
// #### Usage
//
// ```
// _ : tanh : _
// ```
//-----------------------------------------------------------------------------
tanh = ffunction(float tanhf|tanh|tanhl (float), <math.h>,"");


//---------------------------------`(ma.)erf`---------------------------------------
// Computes the error function of the input signal.
//
// #### Usage
//
// ```
// _ : erf : _
// ```
//-----------------------------------------------------------------------------
erf = ffunction(float erff|erf|erfl(float), <math.h>,"");


//---------------------------------`(ma.)erfc`---------------------------------------
// Computes the complementary error function of the input signal.
//
// #### Usage
//
// ```
// _ : erfc : _
// ```
//-----------------------------------------------------------------------------
erfc = ffunction(float erfcf|erfc|erfcl(float), <math.h>,"");


//---------------------------------`(ma.)gamma`-------------------------------------
// Computes the gamma function of the input signal.
//
// #### Usage
//
// ```
// _ : gamma : _
// ```
//-----------------------------------------------------------------------------
gamma = ffunction(float tgammaf|tgamma|tgammal(float), <math.h>,"");


//---------------------------------`(ma.)lgamma`------------------------------------
// Calculates the natural logorithm of the absolute value of
// the gamma function of the input signal.
//
// #### Usage
//
// ```
// _ : lgamma : _
// ```
//-----------------------------------------------------------------------------
lgamma = ffunction(float lgammaf|lgamma|lgammal(float), <math.h>,"");


//----------------------------------`(ma.)J0`---------------------------------------
// Computes the Bessel function of the first kind of order 0
// of the input signal.
//
// #### Usage
//
// ```
// _ : J0 : _
// ```
//-----------------------------------------------------------------------------
J0 = ffunction(float j0(float), <math.h>,"");


//----------------------------------`(ma.)J1`---------------------------------------
// Computes the Bessel function of the first kind of order 1
// of the input signal.
//
// #### Usage
//
// ```
// _ : J1 : _
// ```
//-----------------------------------------------------------------------------
J1 = ffunction(float j1(float), <math.h>,"");


//----------------------------------`(ma.)Jn`---------------------------------------
// Computes the Bessel function of the first kind of order n
// (first input signal) of the second input signal.
//
// #### Usage
//
// ```
// _,_ : Jn : _
// ```
//-----------------------------------------------------------------------------
Jn = ffunction(float jn(int, float), <math.h>,"");


//----------------------------------`(ma.)Y0`---------------------------------------
// Computes the linearly independent Bessel function of the second kind
// of order 0 of the input signal.
//
// #### Usage
//
// ```
// _ : Y0 : _
// ```
//-----------------------------------------------------------------------------
Y0 = ffunction(float y0(float), <math.h>,"");


//----------------------------------`(ma.)Y1`---------------------------------------
// Computes the linearly independent Bessel function of the second kind
// of order 1 of the input signal.
//
// #### Usage
//
// ```
// _ : Y0 : _
// ```
//-----------------------------------------------------------------------------
Y1 = ffunction(float y1(float), <math.h>,"");


//----------------------------------`(ma.)Yn`---------------------------------------
// Computes the linearly independent Bessel function of the second kind
// of order n (first input signal) of the second input signal.
//
// #### Usage
//
// ```
// _,_ : Yn : _
// ```
//-----------------------------------------------------------------------------
Yn = ffunction(float yn(int, float), <math.h>,"");


//----------------------------`(ma.)fabs`, `(ma.)fmax`, `(ma.)fmin`---------------------------
// Just for compatibility...
//
// ```
// fabs = abs
// fmax = max
// fmin = min
// ```
//-----------------------------------------------------------------------------
fabs = abs;
fmax = max;
fmin = min;

//-------------------------------`(ma.)np2`--------------------------------------
// Gives the next power of 2 of x.
//
// #### Usage
//
// ```
// np2(n) : _
// ```
//
// Where:
//
// * `n`: an integer
//-----------------------------------------------------------------------------
np2 = -(1) <: >>(1)|_ <: >>(2)|_ <: >>(4)|_ <: >>(8)|_ <: >>(16)|_ : +(1);


//-----------------------------`(ma.)frac`---------------------------------------
// Gives the fractional part of n.
//
// #### Usage
//
// ```
// frac(n) : _
// ```
//
// Where:
//
// * `n`: a decimal number
//------------------------------------------------------------------------------
frac(n) = n - floor(n);
decimal = frac;
// NOTE: decimal does the same thing as frac but using floor instead. JOS uses frac a lot
// in filters.lib so we decided to keep that one... decimal is declared though for
// backward compatibility.
// decimal(n) = n - floor(n);


//-------------------------------`(ma.)modulo`---------------------------------------
// Modulus operation.
//
// #### Usage
//
// ```
// modulo(x,N) : _
// ```
//
// Where:
//
// * `x`: the numerator
// * `N`: the denominator
//------------------------------------------------------------------------------
modulo(x,N) = (x % N + N) % N;


//---------------`(ma.)isnan`----------------
// Return non-zero if x is a NaN.
//
// #### Usage
//
// ```
// isnan(x)
// _ : isnan : _
// ```
//
// Where:
//
// * `x`: signal to analyse
//------------------------------------------
isnan = ffunction(int isnanf|isnan|isnanl (float),<math.h>,"");


//---------------`(ma.)isinf`----------------
// Return non-zero if x is a positive or negative infinity.
//
// #### Usage
//
// ```
// isinf(x)
// _ : isinf : _
// ```
//
// Where:
//
// * `x`: signal to analyse
//------------------------------------------
isinf = ffunction(int isinff|isinf|isinfl (float),<math.h>,"");

nextafter = ffunction(float nextafter(float, float),<math.h>,"");


//---------------------------`(ma.)chebychev`-------------------------------
// Chebychev transformation of order n.
//
// #### Usage
//
// ```
// _ : chebychev(n) : _
// ```
//
// Where:
//
// * `n`: the order of the polynomial
//
// #### Semantics
//
// ```
// T[0](x) = 1,
// T[1](x) = x,
// T[n](x) = 2x*T[n-1](x) - T[n-2](x)
// ```
//
// #### Reference
//
// <http://en.wikipedia.org/wiki/Chebyshev_polynomial>
//-------------------------------------------------------------------------
chebychev(0,x) = 1;
chebychev(1,x) = x;
chebychev(n,x) = 2*x*chebychev(n-1, x) - chebychev(n-2, x);


//------------------------`(ma.)chebychevpoly`-------------------------------
// Linear combination of the first Chebyshev polynomials.
//
// #### Usage
//
// ```
// _ : chebychevpoly((c0,c1,...,cn)) : _
// ```
//
// Where:
//
// * `cn`: the different Chebychevs polynomials such that:
// 	chebychevpoly((c0,c1,...,cn)) = Sum of chebychev(i)*ci
//
// #### Reference
//
// <http://www.csounds.com/manual/html/chebyshevpoly.html>
//-------------------------------------------------------------------------
chebychevpoly(lcoef) = _ <: L(0,lcoef) :> _
	with {
		L(n,(c,cs)) = chebychev(n)*c, L(n+1,cs);
		L(n,c)      = chebychev(n)*c;
	};


//------------------`(ma.)diffn`----------------------------
// Negated first-order difference.
//
// #### Usage
//
// ```
// _ : diffn : _
// ```
//--------------------------------------------------------
diffn(x) = x' - x; // negated first-order difference


//------------------`(ma.)signum`----------------------------
// The signum function signum(x) is defined as
// -1 for x<0, 0 for x==0, and 1 for x>0.
//
// #### Usage
//
// ```
// _ : signum : _
// ```
//--------------------------------------------------------
signum(x) = (x>0)-(x<0);


//------------------`(ma.)nextpow2`----------------------------
// The nextpow2(x) returns the lowest integer m such that
// 2^m >= x.
//
// #### Usage
//
// ```
// 2^nextpow2(n)
// ```
// Useful for allocating delay lines, e.g., 
// ```
// delay(2^nextpow2(maxDelayNeeded), currentDelay);
// ```
//--------------------------------------------------------
nextpow2(x) = ceil(log(x)/log(2.0));


//--------------------`(ma.)zc`------------------------------------------------
// Indicator function for zero-crossing: it returns 1 if a zero-crossing
// occurs, 0 otherwise.
//
// #### Usage
//
// ```
// _ : zc : _
// ```
//-----------------------------------------------------------------------------
zc(x) = x * x' < 0;