manual/input/scalarfunctions.tex

% MBDyn (C) is a multibody analysis code.
% http://www.mbdyn.org
%
% Copyright (C) 1996-2017
%
% Pierangelo Masarati  <masarati@aero.polimi.it>
%
% Dipartimento di Ingegneria Aerospaziale - Politecnico di Milano
% via La Masa, 34 - 20156 Milano, Italy
% http://www.aero.polimi.it
%
% Changing this copyright notice is forbidden.
%
% This program is free software; you can redistribute it and/or modify
% it under the terms of the GNU General Public License as published by
% the Free Software Foundation (version 2 of the License).
%
%
% 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 General Public License for more details.
%
% You should have received a copy of the GNU General Public License
% along with this program; if not, write to the Free Software
% Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

\section{Scalar functions}\label{sec:ScalarFunction}
A \hty{ScalarFunction} object computes the value of a function.
Almost every scalar function is of type \htmlref{\ty{DifferentiableScalarFunction}}{sec:ScalarFunction},
derived from \hty{ScalarFunction}, and allows to compute the derivatives of
the function as well. Currently implemented scalar functions are
\begin{itemize}
\item \kw{const}: $f(x)=c$
\item \kw{exp}: $f(x)=m\cdot b^{c\cdot{x}}$
\item \kw{log}: $f(x)=m\cdot\textrm{log}_b(c\cdot{x})$
\item \kw{pow}: $f(x)=x^p$
\item \kw{linear}: linear interpolation between the two points $(x_1,y_1)$
and $(x_2,y_2)$
\item \kw{cubicspline}: cubic natural spline interpolation between the
set of points $\{(x_i,y_i), i\in[1,k\geq3]\}$
\item \kw{multilinear}: multilinear interpolation between the
set of points $\{(x_i,y_i), i\in[1,k\geq2]\}$
\item \kw{chebychev}: Chebychev interpolation between the
set of points $\{a,b\}$
\item \kw{sum}: $f(x)=f_1(x) + f_2(x)$
\item \kw{sub}: $f(x)=f_1(x) - f_2(x)$
\item \kw{mul}: $f(x)=f_1(x) \cdot f_2(x)$
\item \kw{div}: $f(x)=f_1(x) / f_2(x)$
\end{itemize}

\noindent
Every \hty{ScalarFunction} card follows the format
%\begin{verbatim}
\begin{Verbatim}[commandchars=\\\{\}]
    \bnt{card} :: = \kw{scalar function} : " \bnt{unique_scalar_func_name} " ,
        \bnt{scalar_func_type} ,
        \bnt{scalar_func_args}
\end{Verbatim}
%\end{verbatim}
The name of the scalar function is a string, thus it needs to be enclosed
in double quotes.

The type of scalar function,
\nt{scalar\_func\_type}, together
with relevant arguments, \nt{scalar\_func\_args},
are as follows:
\subsubsection{Const Scalar Function}
%\begin{verbatim}
\begin{Verbatim}[commandchars=\\\{\}]
    \bnt{scalar_func_type} ::= \kw{const}

    \bnt{scalar_func_args} ::= \bnt{const_coef}
\end{Verbatim}
%\end{verbatim}
Note: if the \nt{scalar\_func\_type} is omitted,
a \kw{const} scalar function is assumed.

\paragraph{Example.} \
\begin{verbatim}
    scalar function: "const_function", const, 1.e-2;
\end{verbatim}

\subsubsection{Exp Scalar Function}
%\begin{verbatim}
\begin{Verbatim}[commandchars=\\\{\}]
    \bnt{scalar_func_type} ::= \kw{exp}

    \bnt{scalar_func_args} ::=
        [ \kw{base} , \bnt{base} , ]
        [ \kw{coefficient} , \bnt{coef} , ]
        \bnt{multiplier_coef}
\end{Verbatim}
%\end{verbatim}
\begin{align}
	f\plbr{x}
	&=
	\nt{multiplier\_coef} \cdot \nt{base}^{\plbr{\nt{coef} \cdot x}}
\end{align}
Note: the optional \nt{base} must be positive
(defaults to `$\textrm{e}$', Neper's number);
\nt{coef} defaults to 1.

\paragraph{Example.} \
\begin{verbatim}
    scalar function: "exp_function", exp, 1.e-2; # 1.e-2*e^x
\end{verbatim}

\subsubsection{Log Scalar Function}
%\begin{verbatim}
\begin{Verbatim}[commandchars=\\\{\}]
    \bnt{scalar_func_type} ::= \kw{log}

    \bnt{scalar_func_args} ::=
        [ \kw{base} , \bnt{base} , ]
        [ \kw{coefficient} , \bnt{coef} , ]
        \bnt{multiplier_coef}
\end{Verbatim}
%\end{verbatim}
\begin{align}
	f\plbr{x}
	&=
	\nt{multiplier\_coef} \cdot \log_{\nt{base}}\plbr{\nt{coef} \cdot x}
\end{align}
Note: the optional \kw{base} (defaults to `$\textrm{e}$', Neper's number,
resulting in natural logarithms)
must be positive.
The optional value \nt{coef}, prepended by the keyword \kw{coefficient},
(defaults to 1).
The argument must be positive, otherwise an exception is thrown.

\paragraph{Example.} \
\begin{verbatim}
    scalar function: "log_function", log, 1.e-2; # 1.e-2*log(x)
\end{verbatim}

\subsubsection{Pow Scalar Function}
%\begin{verbatim}
\begin{Verbatim}[commandchars=\\\{\}]
    \bnt{scalar_func_type} ::= \kw{pow}

    \bnt{scalar_func_args} ::= \bnt{exponent_coef}
\end{Verbatim}
%\end{verbatim}
\begin{align}
	f\plbr{x}
	&=
	x^{\nt{exponent\_coef}}
\end{align}

\paragraph{Example.} \
\begin{verbatim}
    scalar function: "pow_function", pow, 3.; # x^3.
\end{verbatim}

\subsubsection{Linear Scalar Function}
%\begin{verbatim}
\begin{Verbatim}[commandchars=\\\{\}]
    \bnt{scalar_func_type} ::= \kw{linear}

    \bnt{scalar_func_args} ::= \bnt{point} , \bnt{point}

    \bnt{point}            ::= \bnt{x}, \bnt{y}
\end{Verbatim}
%\end{verbatim}
A line passing through the two points,
\begin{align}
	f\plbr{x}
	&=
	\nt{y}_i
	+
	\frac{\nt{y}_f - \nt{y}_i}{\nt{x}_f - \nt{x}_i} \plbr{x - \nt{x}_i}
\end{align}
where $\nt{x}_i$, $\nt{y}_i$ are the coordinates of the first point,
while $\nt{x}_f$, $\nt{y}_f$ are the coordinates of the second point.

\paragraph{Example.} \
\begin{verbatim}
    scalar function: "linear_function", linear, 0., 0., 1., 1.;
\end{verbatim}

\subsubsection{Cubic Natural Spline Scalar Function}
%\begin{verbatim}
\begin{Verbatim}[commandchars=\\\{\}]
    \bnt{scalar_func_type} ::= \kw{cubic spline}

    \bnt{scalar_func_args} ::= [ \kw{do not extrapolate} , ]
        \bnt{point} ,
        \bnt{point}
        [ , ... ]
        [ , \kw{end} ]

    \bnt{point}            ::= \bnt{x} , \bnt{y}
\end{Verbatim}
%\end{verbatim}
The \kw{end} delimiter is required if the card needs to continue
(i.e.\ the \hty{ScalarFunction} definition is embedded in a more complex
statement); it can be omitted if the card ends with a semicolon
right after the last point.

\subsubsection{Multilinear Scalar Function}
%\begin{verbatim}
\begin{Verbatim}[commandchars=\\\{\}]
    \bnt{scalar_func_type} ::= \kw{multilinear}

    \bnt{scalar_func_args} ::= [ \kw{do not extrapolate} , ]
        \bnt{point} ,
        \bnt{point}
        [ , ... ]
        [ , \kw{end} ]

    \bnt{point}            ::= \bnt{x} , \bnt{y}
\end{Verbatim}
%\end{verbatim}
Unless \kw{do not extrapolate} is set, when the input is outside
the provided values of \nt{x} the value is extrapolated using the slope
of the nearest point pair.

\subsubsection{Chebychev Scalar Function}
%\begin{verbatim}
\begin{Verbatim}[commandchars=\\\{\}]
    \bnt{scalar_func_type} ::= \kw{chebychev}

    \bnt{scalar_func_args} ::=
        \bnt{lower_bound} , \bnt{upper_bound} ,
        [ \kw{do not extrapolate} , ]
        \bnt{coef_0} [ , \bnt{coef_1} [ , ... ] ]
        [ , \kw{end} ]
\end{Verbatim}
%\end{verbatim}
Chebychev polynomials of the first kind are defined as
\begin{equation}
	T_n\plbr{\xi} = \cos\plbr{n \cos^{-1}\plbr{\xi}} ,
\end{equation}
with
\begin{equation}
	\xi = 2 \frac{x}{b - a} - \frac{b + a}{b - a} ,
\end{equation}
where $a = \nt{lower\_bound}$ and $b = \nt{upper\_bound}$,
which corresponds to the series
\begin{align}
	T_0\plbr{\xi} &= 1 \\
	T_1\plbr{\xi} &= \xi \\
	\ldots \nonumber \\
	T_n\plbr{\xi} &= 2 \xi T_{n-1}\plbr{\xi} - T_{n-2}\plbr{\xi} .
\end{align}
For example, the first five coefficients are
\begin{align}
	T_0\plbr{\xi} &= 1 \\
	T_1\plbr{\xi} &= \xi \\
	T_2\plbr{\xi} &= 2\xi^2 - 1 \\
	T_3\plbr{\xi} &= 4\xi^3 - 3\xi \\
	T_4\plbr{\xi} &= 8\xi^4 - 8\xi^2 + 1
\end{align}
This scalar function implements the truncated series in the form
\begin{equation}
	f\plbr{x} = \sum_{k=0,n} c_k T_k\plbr{\xi} ,
\end{equation}
where $c_k = \nt{coef\_}\texttt{<k>}$.
The first derivative of the series is obtained by considering
\begin{align}
	\frac{\mathrm{d}}{\mathrm{d}\xi}T_0\plbr{\xi} &= 0 \\
	\frac{\mathrm{d}}{\mathrm{d}\xi}T_1\plbr{\xi} &= 1 \\
	\ldots \nonumber \\
	\frac{\mathrm{d}}{\mathrm{d}\xi}T_n\plbr{\xi} &=
		2 T_{n-1}\plbr{\xi}
		+ 2 \xi \frac{\mathrm{d}}{\mathrm{d}\xi}T_{n-1}\plbr{\xi}
		- \frac{\mathrm{d}}{\mathrm{d}\xi}T_{n-2}\plbr{\xi} ,
\end{align}
so the first derivative of the scalar function is
\begin{equation}
	\frac{\mathrm{d}}{\mathrm{d}x}f\plbr{x} = \frac{\mathrm{d}\xi}{\mathrm{d}x} \sum_{k=1,n} c_k \frac{\mathrm{d}}{\mathrm{d}\xi} T_k\plbr{\xi} .
\end{equation}
Subsequent derivatives follow the rule
\begin{equation}
	\frac{\mathrm{d}^i}{\mathrm{d}\xi^i}T_n\plbr{\xi} =
		2 i \frac{\mathrm{d}^{i-1}}{\mathrm{d}\xi^{i-1}}T_{n-1}\plbr{\xi}
		+ 2 \xi \frac{\mathrm{d}^i}{\mathrm{d}\xi^i}T_{n-1}\plbr{\xi}
		- \frac{\mathrm{d}^i}{\mathrm{d}\xi^i}T_{n-2}\plbr{\xi} .
\end{equation}
Differentiation of order higher than 1 is not currently implemented.


\subsubsection{Sum Scalar Function}
%\begin{verbatim}
\begin{Verbatim}[commandchars=\\\{\}]
    \bnt{scalar_func_type} ::= \kw{sum}

    \bnt{scalar_func_args} ::= (\hty{ScalarFunction}) \bnt{f1} , (\hty{ScalarFunction}) \bnt{f2}
\end{Verbatim}
%\end{verbatim}
\begin{align}
	f\plbr{x}
	&=
	\nt{f1}\plbr{x} + \nt{f2}\plbr{x}
\end{align}

\paragraph{Example.} \
\begin{verbatim}
    scalar function: "first_function", const, 1.;
    scalar function: "second_function", const, 2.;
    scalar function: "sum_function", sum, "first_function", "second_function";
\end{verbatim}


\subsubsection{Sub Scalar Function}
%\begin{verbatim}
\begin{Verbatim}[commandchars=\\\{\}]
    \bnt{scalar_func_type} ::= \kw{sub}

    \bnt{scalar_func_args} ::= (\hty{ScalarFunction}) \bnt{f1} , (\hty{ScalarFunction}) \bnt{f2}
\end{Verbatim}
%\end{verbatim}
\begin{align}
	f\plbr{x}
	&=
	\nt{f1}\plbr{x} - \nt{f2}\plbr{x}
\end{align}

\paragraph{Example.} \
\begin{verbatim}
    scalar function: "first_function", const, 1.;
    scalar function: "second_function", const, 2.;
    scalar function: "sub_function", sub, "first_function", "second_function";
\end{verbatim}

\subsubsection{Mul Scalar Function}
%\begin{verbatim}
\begin{Verbatim}[commandchars=\\\{\}]
    \bnt{scalar_func_type} ::= \kw{mul}

    \bnt{scalar_func_args} ::= (\hty{ScalarFunction}) \bnt{f1} , (\hty{ScalarFunction}) \bnt{f2}
\end{Verbatim}
%\end{verbatim}
\begin{align}
	f\plbr{x}
	&=
	\nt{f1}\plbr{x} \cdot \nt{f2}\plbr{x}
\end{align}

\paragraph{Example.} \
\begin{verbatim}
    scalar function: "first_function", const, 1.;
    scalar function: "second_function", const, 2.;
    scalar function: "mul_function", mul, "first_function", "second_function";
\end{verbatim}

\subsubsection{Div Scalar Function}
%\begin{verbatim}
\begin{Verbatim}[commandchars=\\\{\}]
    \bnt{scalar_func_type} ::= \kw{div}

    \bnt{scalar_func_args} ::= (\hty{ScalarFunction}) \bnt{f1} , (\hty{ScalarFunction}) \bnt{f2}
\end{Verbatim}
%\end{verbatim}
\begin{align}
	f\plbr{x}
	&=
	\nt{f1}\plbr{x} / \nt{f2}\plbr{x}
\end{align}
Note: division by zero is checked, and an exception is thrown.

\paragraph{Example.} \
\begin{verbatim}
    scalar function: "first_function", const, 1.;
    scalar function: "second_function", const, 2.;
    scalar function: "div_function", div, "first_function", "second_function";
\end{verbatim}