Functions

This chapter describes some functions provided by the modules MAD.gmath and MAD.gfunc.

The module gmath extends the standard LUA module math with generic functions working on any types that support the methods with the same names. For example, the code gmath.sin(a) will call math.sin(a) if a is a number, otherwise it will call the method a:sin(), i.e. delegate the invocation to a. This is how MAD-NG handles several types like numbers, complex number and TPSA within a single polymorphic code that expects scalar-like behavior.

The module gfunc provides useful functions to help dealing with operators as functions and to manipulate functions in a functional way [1].

Mathematical Functions

Generic Real-like Functions

Real-like generic functions forward the call to the method of the same name from the first argument when the latter is not a number. The optional argument r_ represents a destination placeholder for results with reference semantic, i.e. avoiding memory allocation, which is ignored by results with value semantic. The C functions column lists the C implementation used when the argument is a number and the implementation does not rely on the standard math module but on functions provided with MAD-NG or by the standard math library described in the C Programming Language Standard [ISOC99].

Functions	Return values	C functions
abs(x,r_)	\(|x|\)
acos(x,r_)	\(\cos^{-1} x\)
acosh(x,r_)	\(\cosh^{-1} x\)	acosh()
acot(x,r_)	\(\cot^{-1} x\)
acoth(x,r_)	\(\coth^{-1} x\)	atanh()
asin(x,r_)	\(\sin^{-1} x\)
asinc(x,r_)	\(\frac{\sin^{-1} x}{x}\)	mad_num_asinc()
asinh(x,r_)	\(\sinh^{-1} x\)	asinh()
asinhc(x,r_)	\(\frac{\sinh^{-1} x}{x}\)	mad_num_asinhc()
atan(x,r_)	\(\tan^{-1} x\)
atan2(x,y,r_)	\(\tan^{-1} \frac{x}{y}\)
atanh(x,r_)	\(\tanh^{-1} x\)	atanh()
ceil(x,r_)	\(\lceil x \rceil\)
cos(x,r_)	\(\cos x\)
cosh(x,r_)	\(\cosh x\)
cot(x,r_)	\(\cot x\)
coth(x,r_)	\(\coth x\)
exp(x,r_)	\(\exp x\)
floor(x,r_)	\(\lfloor x \rfloor\)
frac(x,r_)	\(x - \operatorname{trunc}(x)\)
hypot(x,y,r_)	\(\sqrt{x^2+y^2}\)	hypot()
hypot3(x,y,z,r_)	\(\sqrt{x^2+y^2+z^2}\)	hypot()
inv(x,v_,r_) [2]	\(\frac{v}{x}\)
invsqrt(x,v_,r_) [2]	\(\frac{v}{\sqrt x}\)
lgamma(x,tol_,r_)	\(\ln|\Gamma(x)|\)	lgamma()
log(x,r_)	\(\log x\)
log10(x,r_)	\(\log_{10} x\)
powi(x,n,r_)	\(x^n\)	mad_num_powi()
round(x,r_)	\(\lfloor x \rceil\)	round()
sign(x)	\(-1, 0\text{ or }1\)	mad_num_sign() [3]
sign1(x)	\(-1\text{ or }1\)	mad_num_sign1() [3]
sin(x,r_)	\(\sin x\)
sinc(x,r_)	\(\frac{\sin x}{x}\)	mad_num_sinc()
sinh(x,r_)	\(\sinh x\)
sinhc(x,r_)	\(\frac{\sinh x}{x}\)	mad_num_sinhc()
sqrt(x,r_)	\(\sqrt{x}\)
tan(x,r_)	\(\tan x\)
tanh(x,r_)	\(\tanh x\)
tgamma(x,tol_,r_)	\(\Gamma(x)\)	tgamma()
trunc(x,r_)	\(\lfloor x \rfloor, x\geq 0;\lceil x \rceil, x<0\)
unit(x,r_)	\(\frac{x}{|x|}\)

Generic Complex-like Functions

Complex-like generic functions forward the call to the method of the same name from the first argument when the latter is not a number, otherwise it implements a real-like compatibility layer using the equivalent representation \(z=x+0i\). The optional argument r_ represents a destination for results with reference semantic, i.e. avoiding memory allocation, which is ignored by results with value semantic.

Functions	Return values
cabs(z,r_)	\(|z|\)
carg(z,r_)	\(\arg z\)
conj(z,r_)	\(z^*\)
cplx(x,y,r_)	\(x+i\,y\)
fabs(z,r_)	\(|\Re(z)|+i\,|\Im(z)|\)
imag(z,r_)	\(\Im(z)\)
polar(z,r_)	\(|z|\,e^{i \arg z}\)
proj(z,r_)	\(\operatorname{proj}(z)\)
real(z,r_)	\(\Re(z)\)
rect(z,r_)	\(\Re(z)\cos \Im(z)+i\,\Re(z)\sin \Im(z)\)
reim(z,re_,im_)	\(\Re(z), \Im(z)\)

Generic Vector-like Functions

Vector-like functions (also known as MapFold or MapReduce) are functions useful when used as high-order functions passed to methods like :map2(), :foldl() (fold left) or :foldr() (fold right) of containers like lists, vectors and matrices.

Functions	Return values
sumsqr(x,y)	\(x^2 + y^2\)
sumabs(x,y)	\(|x| + |y|\)
minabs(x,y)	\(\min(|x|, |y|)\)
maxabs(x,y)	\(\max(|x|, |y|)\)
sumsqrl(x,y)	\(x + y^2\)
sumabsl(x,y)	\(x + |y|\)
minabsl(x,y)	\(\min(x, |y|)\)
maxabsl(x,y)	\(\max(x, |y|)\)
sumsqrr(x,y)	\(x^2 + y\)
sumabsr(x,y)	\(|x| + y\)
minabsr(x,y)	\(\min(|x|, y)\)
maxabsr(x,y)	\(\max(|x|, y)\)

Generic Error-like Functions

Error-like generic functions forward the call to the method of the same name from the first argument when the latter is not a number, otherwise it calls C wrappers to the corresponding functions from the Faddeeva library from the MIT (see mad_num.c). The optional argument r_ represents a destination for results with reference semantic, i.e. avoiding memory allocation, which is ignored by results with value semantic.

Functions	Return values	C functions
erf(z,rtol_,r_)	\(\frac{2}{\sqrt\pi}\int_0^z e^{-t^2} dt\)	mad_num_erf()
erfc(z,rtol_,r_)	\(1-\operatorname{erf}(z)\)	mad_num_erfc()
erfi(z,rtol_,r_)	\(-i\operatorname{erf}(i z)\)	mad_num_erfi()
erfcx(z,rtol_,r_)	\(e^{z^2}\operatorname{erfc}(z)\)	mad_num_erfcx()
wf(z,rtol_,r_)	\(e^{-z^2}\operatorname{erfc}(-i z)\)	mad_num_wf()
dawson(z,rtol_,r_)	\(\frac{-i\sqrt\pi}{2}e^{-z^2}\operatorname{erf}(iz)\)	mad_num_dawson()

Special Functions

The special function fact() supports negative integers as input as it uses extended factorial definition, and the values are cached to make its complexity in \(O(1)\) after warmup.

The special function rangle() adjust the angle a versus the previous right angle r, e.g. during phase advance accumulation, to ensure proper value when passing through the \(\pm 2k\pi\) boundaries.

Functions	Return values	C functions
fact(n)	\(n!\)	mad_num_fact()
rangle(a,r)	\(a + 2\pi \lfloor \frac{r-a}{2\pi} \rceil\)	round()

Functions for Circular Sector

Basic functions for arc and cord lengths conversion rely on the following elementary relations:

\[ \begin{align}\begin{aligned}l_{\text{arc}} &= a r = \frac{l_{\text{cord}}}{\operatorname{sinc} \frac{a}{2}}\\l_{\text{cord}} &= 2 r \sin \frac{a}{2} = l_{\text{arc}} \operatorname{sinc} \frac{a}{2}\end{aligned}\end{align} \]

where \(r\) stands for the radius and \(a\) for the angle of the Circular Sector.

Functions	Return values
arc2cord(l,a)	\(l_{\text{arc}} \operatorname{sinc} \frac{a}{2}\)
arc2len(l,a)	\(l_{\text{arc}} \operatorname{sinc} \frac{a}{2}\, \cos a\)
cord2arc(l,a)	\(\frac{l_{\text{cord}}}{\operatorname{sinc} \frac{a}{2}}\)
cord2len(l,a)	\(l_{\text{cord}} \cos a\)
len2arc(l,a)	\(\frac{l}{\operatorname{sinc} \frac{a}{2}\, cos a}\)
len2cord(l,a)	\(\frac{l}{\cos a}\)

Operators as Functions

The module MAD.gfunc provides many functions that are named version of operators and useful when operators cannot be used directly, e.g. when passed as argument or to compose together. These functions can also be retrieved from the module MAD.gfunc.opstr by their associated string (if available).

Math Operators

Functions for math operators are wrappers to associated mathematical operators, which themselves can be overridden by their associated metamethods.

Functions	Return values	Operator string	Metamethods
unm(x)	\(-x\)	"~"	__unm(x,_)
inv(x)	\(1 / x\)	"1/"	__div(1,x)
sqr(x)	\(x \cdot x\)	"^2"	__mul(x,x)
add(x,y)	\(x + y\)	"+"	__add(x,y)
sub(x,y)	\(x - y\)	"-"	__sub(x,y)
mul(x,y)	\(x \cdot y\)	"*"	__mul(x,y)
div(x,y)	\(x / y\)	"/"	__div(x,y)
mod(x,y)	\(x \mod y\)	"%"	__mod(x,y)
pow(x,y)	\(x ^ y\)	"^"	__pow(x,y)

Element Operators

Functions for element-wise operators [4] are wrappers to associated mathematical operators of vector-like objects, which themselves can be overridden by their associated metamethods.

Functions	Return values	Operator string	Metamethods
emul(x,y,r_)	\(x\,.*\,y\)	".*"	__emul(x,y,r_)
ediv(x,y,r_)	\(x\,./\,y\)	"./"	__ediv(x,y,r_)
emod(x,y,r_)	\(x\,.\%\,y\)	".%"	__emod(x,y,r_)
epow(x,y,r_)	\(x\,.\hat\ \ y\)	".^"	__epow(x,y,r_)

Logical Operators

Functions for logical operators are wrappers to associated logical operators.

Functions	Return values	Operator string
lfalse()	true	"T"
ltrue()	false	"F"
lnot(x)	\(\lnot x\)	"!"
lbool(x)	\(\lnot\lnot x\)	"!!"
land(x,y)	\(x \land y\)	"&&"
lor(x,y)	\(x \lor y\)	"||"
lnum(x)	\(\lnot x\rightarrow 0\), \(\lnot\lnot x\rightarrow 1\)	"!#"

Relational Operators

Functions for relational operators are wrappers to associated logical operators, which themselves can be overridden by their associated metamethods. Relational ordering operators are available only for objects that are ordered.

Functions	Return values	Operator string	Metamethods
eq(x,y)	\(x = y\)	"=="	__eq(x,y)
ne(x,y)	\(x \neq y\)	"!=" or "~="	__eq(x,y)
lt(x,y)	\(x < y\)	"<"	__lt(x,y)
le(x,y)	\(x \leq y\)	"<="	__le(x,y)
gt(x,y)	\(x > y\)	">"	__le(y,x)
ge(x,y)	\(x \geq y\)	">="	__lt(y,x)
cmp(x,y)	\((x > y) - (x < y)\)	"?="

The special relational operator cmp() returns the number 1 for \(x<y\), -1 for \(x>y\), and 0 otherwise.

Object Operators

Functions for object operators are wrappers to associated object operators, which themselves can be overridden by their associated metamethods.

Functions	Return values	Operator string	Metamethods
get(x,k)	\(x[k]\)	"->"	__index(x,k)
set(x,k,v)	\(x[k]=v\)	"<-"	__newindex(x,k,v)
len(x)	\(\#x\)	"#"	__len(x)
cat(x,y)	\(x .. y\)	".."	__concat(x,y)
call(x,...)	\(x(...)\)	"()"	__call(x,...)

Bitwise Functions

Functions for bitwise operations are those from the LuaJIT module bit and imported into the module MAD.gfunc for convenience, see http://bitop.luajit.org/api.html for details. Note that all these functions have value semantic and normalise their arguments to the numeric range of a 32 bit integer before use.

Functions	Return values
tobit(x)	Return the normalized value of x to the range of a 32 bit integer
tohex(x,n_)	Return the hex string of x with n digits (\(n<0\) use caps)
bnot(x)	Return the bitwise reverse of x bits
band(x,...)	Return the bitwise AND of all arguments
bor(x,...)	Return the bitwise OR of all arguments
bxor(x,...)	Return the bitwise XOR of all arguments
lshift(x,n)	Return the bitwise left shift of x by n bits with 0-bit shift-in
rshift(x,n)	Return the bitwise right shift of x by n bits with 0-bit shift-in
arshift(x,n)	Return the bitwise right shift of x by n bits with sign bit shift-in
rol(x,n)	Return the bitwise left rotation of x by n bits
ror(x,n)	Return the bitwise right rotation of x by n bits
bswap(x)	Return the swapped bytes of x, i.e. convert big endian to/from little endian

Flags Functions

A flag is 32 bit unsigned integer used to store up to 32 binary states with the convention that 0 means disabled/cleared and 1 means enabled/set. Functions on flags are useful aliases to, or combination of, bitwise operations to manipulate their states (i.e. their bits). Flags are mainly used by the object model to keep track of hidden and user-defined states in a compact and efficient format.

Functions	Return values
bset(x,n)	Return the flag x with state n enabled
bclr(x,n)	Return the flag x with state n disabled
btst(x,n)	Return true if state n is enabled in x, false otherwise
fbit(n)	Return a flag with only state n enabled
fnot(x)	Return the flag x with all states flipped
fset(x,...)	Return the flag x with disabled states flipped if enabled in any flag passed as argument
fcut(x,...)	Return the flag x with enabled states flipped if disabled in any flag passed as argument
fclr(x,f)	Return the flag x with enabled states flipped if enabled in f
ftst(x,f)	Return true if all states enabled in f are enabled in x, false otherwise
fall(x)	Return true if all states are enabled in x, false otherwise
fany(x)	Return true if any state is enabled in x, false otherwise

Special Functions

The module MAD.gfunc provides some useful functions when passed as argument or composed with other functions.

Functions	Return values
narg(...)	Return the number of arguments
ident(...)	Return all arguments unchanged, i.e. functional identity
fnil()	Return nil, i.e. functional nil
ftrue()	Return true, i.e. functional true
ffalse()	Return false, i.e. functional false
fzero()	Return 0, i.e. functional zero
fone()	Return 1, i.e. functional one
first(a)	Return first argument and discard the others
second(a,b)	Return second argument and discard the others
third(a,b,c)	Return third argument and discard the others
swap(a,b)	Return first and second arguments swapped and discard the other arguments
swapv(a,b,...)	Return first and second arguments swapped followed by the other arguments
echo(...)	Return all arguments unchanged after echoing them on stdout

C API

These functions are provided for performance reason and compliance with the C API of other modules.

int mad_num_sign(num_t x)

Return an integer amongst {-1, 0, 1} representing the sign of the number x.

int mad_num_sign1(num_t x)

Return an integer amongst {-1, 1} representing the sign of the number x.

num_t mad_num_fact(int n)

Return the extended factorial the number x.

num_t mad_num_powi(num_t x, int n)

Return the number x raised to the power of the integer n using a fast algorithm.

num_t mad_num_sinc(num_t x)

Return the sine cardinal of the number x.

num_t mad_num_sinhc(num_t x)

Return the hyperbolic sine cardinal of the number x.

num_t mad_num_asinc(num_t x)

Return the arc sine cardinal of the number x.

num_t mad_num_asinhc(num_t x)

Return the hyperbolic arc sine cardinal of the number x.

num_t mad_num_wf(num_t x, num_t relerr)

Return the Faddeeva function of the number x.

num_t mad_num_erf(num_t x, num_t relerr)

Return the error function of the number x.

num_t mad_num_erfc(num_t x, num_t relerr)

Return the complementary error function of the number x.

num_t mad_num_erfcx(num_t x, num_t relerr)

Return the scaled complementary error function of the number x.

num_t mad_num_erfi(num_t x, num_t relerr)

Return the imaginary error function of the number x.

num_t mad_num_dawson(num_t x, num_t relerr)

Return the Dawson integral for the number x.

References

[ISOC99]

ISO/IEC 9899:1999 Programming Languages - C. https://www.iso.org/standard/29237.html.

Footnotes

[1]

For true Functional Programming, see the module MAD.lfun, a binding of the LuaFun library adapted to the ecosystem of MAD-NG.

[2] (1,2)

Default: v_ = 1.

[3] (1,2)

Sign and sign1 functions take care of special cases like ±0, ±inf and ±NaN.

[4]

Element-wise operators are not available directly in the programming language, here we use the Matlab-like notation for convenience.