\appendix
\chapter{The \texttt{math} Module}\label{chapter:math}
Picat provides a \texttt{math} module, which has common mathematical constants and functions.  The \texttt{math} module is imported by default.

%In order to use the examples in this chapter, first type \texttt{import math}\index{\texttt{import}} on the command line.

\section{Constants}
The \texttt{math} module provides two constants.
\begin{itemize}
\item \texttt{e = 2.71828182845904523536}\index{\texttt{e}}
\item \texttt{pi = 3.14159265358979323846}\index{\texttt{pi}}
%\item \texttt{inf}\index{\texttt{inf}}: This represents positive infinity.
%\item \texttt{ninf}\index{\texttt{ninf}}: This represents negative infinity.
\end{itemize}

\section{Functions}
The \texttt{math} module contains mathematical functions that serve a number of different purposes.  Note that the arguments must all be numbers.  If the arguments are not numbers, then Picat will throw an error.

\subsection{Sign and Absolute Value}
The following functions deal with the positivity and negativity of numbers.
\begin{itemize}
\item \texttt{sign($X$) = $Val$}\index{\texttt{sign/1}}: This function determines whether $X$ is positive or negative.  If $X$ is positive, then this function returns $1$.  If $X$ is negative, then this function returns $-1$.  If $X$ is $0$, then this function returns $0$.
\item \texttt{abs($X$) = $Val$}\index{\texttt{abs/1}}: This function returns the absolute value of $X$.  If $X \ge 0$, then this function returns $X$.  Otherwise, this function returns $-X$.
\end{itemize}

\subsection*{Example}
\begin{verbatim}
Picat> Val1 = sign(3), Val2 = sign(-3), Val3 = sign(0)
Val1 = 1
Val2 = -1
Val3 = 0
Picat> Val = abs(-3)
Val = 3
\end{verbatim}

\subsection{Rounding and Truncation}
The \texttt{math} module includes the following functions for converting a real number into the integers that are closest to the number.
\begin{itemize}
\item \texttt{ceiling($X$) = $Val$}\index{\texttt{ceiling/1}}: This function returns the closest integer that is greater than or equal to $X$.
\item \texttt{floor($X$) = $Val$}\index{\texttt{floor/1}}: This function returns the closest integer that is less than or equal to $X$.
\item \texttt{round($X$) = $Val$}\index{\texttt{round/1}}: This function returns the integer that is closest to $X$.
\item \texttt{truncate($X$) = $Val$}\index{\texttt{truncate/1}}: This function removes the fractional part from a real number.  
\item \texttt{modf($X$) = ($IntVal$,$FractVal$)}\index{\texttt{modf/1}}: This function splits a real number into its integer part and its fractional part.
\end{itemize}

\subsection*{Example}
\begin{verbatim}
Picat> Val1 = ceiling(-3.2), Val2 = ceiling(3)
Val1 = -3
Val2 = 3
Picat> Val1 = floor(-3.2), Val2 = floor(3)
Val1 = -4
Val2 = 3
Picat> Val1 = round(-3.2), Val2 = round(-3.5), Val3 = round(3.5)
Val1 = -3
Val2 = -4
Val3 = 4
Picat> Val1 = truncate(-3.2), Val2 = truncate(3)
Val1 = -3
Val2 = 3
Picat> IF = modf(3.2)
IF = (3.0 , 0.2)
\end{verbatim}

\subsection{Exponents, Roots, and Logarithms}
The following functions provide exponentiation, root, and logarithmic functions.  Note that, in the logarithmic functions, if $X \le 0$, then an error is thrown.
\begin{itemize}
\item \texttt{pow($X$,$Y$) = $Val$}\index{\texttt{pow/2}}:  This function returns $X^Y$.  It does the same thing as $X ** Y$.
\item \texttt{pow\_mod($X$,$Y$,$Z$) = $Val$}\index{\texttt{pow\_mod/3}}:  This function returns \texttt{$X^Y$ mod $Z$}.  All of the arguments must be integers, and $Y$ must not be negative.
\item \texttt{exp($X$) = $Val$}\index{\texttt{exp/1}}:  This function returns $e^X$.
\item \texttt{sqrt($X$) = $Val$}\index{\texttt{sqrt/1}}: This function returns the square root of $X$.  Note that the \texttt{math} module does not support imaginary numbers.  Therefore, if $X < 0$, this function throws an error.
%\item \texttt{cbrt($X$) = $Val$}\index{\texttt{cbrt/1}}: This function returns the cube root of $X$.
%\item \texttt{nthrt($N$,$X$) = $Val$}\index{\texttt{nthrt/2}}: This function returns the $N$th root of $X$.  Note that, if $N$ is even, and $X < 0$, then this function throws an error. 
\item \texttt{log($X$) = $Val$}\index{\texttt{log/1}}: This function returns $log_e(X)$.
\item \texttt{log10($X$) = $Val$}\index{\texttt{log10/1}}: This function returns $log_{10}(X)$.
\item \texttt{log2($X$) = $Val$}\index{\texttt{log2/1}}: This function returns $log_2(X)$.
\item \texttt{log($B$,$X$) = $Val$}\index{\texttt{log/2}}:  This function returns $log_B(X)$.
\end{itemize}

\subsection*{Example}
\begin{verbatim}
Picat> P1 = pow(2, 5), P2 = exp(2)
P1 = 32
P2 = 7.38906
Picat> S = sqrt(1)
S = 1.0
Picat> E = log(7), T = log10(7), T2 = log2(7), B = log(7, 7)
E = 1.94591
T = 0.845098
T2 = 2.80735
B = 1.0
\end{verbatim}

\subsection{Converting Between Degrees and Radians}
The \texttt{math} module has two functions to convert between degrees and radians.
\begin{itemize}
\item \texttt{to\_radians($Degree$) = $Radian$}\index{\texttt{to\_radians/1}}: This function converts from degrees to radians.
\item \texttt{to\_degrees($Radian$) = $Degree$}\index{\texttt{to\_degrees/1}}: This function converts from radians to degrees.
\end{itemize}

\subsection*{Example}
\begin{verbatim}
Picat> R = to_radians(180)
R = 3.14159
Picat> D = to_degrees(pi)
D = 180.0
\end{verbatim}

\subsection{Trigonometric Functions}
The \texttt{math} module provides the following trigonometric functions.
\begin{itemize}
\item \texttt{sin($X$) = $Val$}\index{\texttt{sin/1}}: This function returns the sine of $X$, where $X$ is given in radians.
\item \texttt{cos($X$) = $Val$}\index{\texttt{cos/1}}: This function returns the cosine of $X$, where $X$ is given in radians.
\item \texttt{tan($X$) = $Val$}\index{\texttt{tan/1}}: This function returns the tangent of $X$, where $X$ is given in radians.  \ignore{If the tangent is undefined, such as at \texttt{pi / 2}, then this function throws an error.}
\item \texttt{sec($X$) = $Val$}\index{\texttt{sec/1}}: This function returns the secant of $X$, where $X$ is given in radians.  If \texttt{cos($X$)} is $0$, then this function throws an error.
\item \texttt{csc($X$) = $Val$}\index{\texttt{csc/1}}: This function returns the cosecant of $X$, where $X$ is given in radians.  If \texttt{sin($X$)} is $0$, then this function throws an error.
\item \texttt{cot($X$) = $Val$}\index{\texttt{cot/1}}: This function returns the cotangent of $X$, where $X$ is given in radians.  If \texttt{tan($X$)} is $0$, then this function throws an error.
\item \texttt{asin($X$) = $Val$}\index{\texttt{asin/1}}: This function returns the arc sine of $X$, in radians.  The returned value is in the range [\texttt{-pi / 2}, \texttt{pi / 2}].  $X$ must be in the range [$-1$, $1$]; otherwise, this function throws an error.
\item \texttt{acos($X$) = $Val$}\index{\texttt{acos/1}}: This function returns the arc cosine of $X$, in radians.  The returned value is in the range [$0$, \texttt{pi}].  $X$ must be in the range [$-1$, $1$]; otherwise, this function throws an error.
\item \texttt{atan($X$) = $Val$}\index{\texttt{atan/1}}: This function returns the arc tangent of $X$, in radians.  The returned value is in the range [\texttt{-pi / 2}, \texttt{pi / 2}].
\item \texttt{atan2($X$,$Y$) = $Val$}\index{\texttt{atan2/2}}: This function returns the arc tangent of $Y$ / $X$, in radians.  $X$ and $Y$ are coordinates.  The returned value is in the range [\texttt{-pi}, \texttt{pi}].  
\ignore{Note that, if both $X$ and $Y$ are $0$, then this function throws an error.}
\item \texttt{asec($X$) = $Val$}\index{\texttt{asin/1}}: This function returns the arc secant of $X$, in radians.  The returned value is in the range [$0$, \texttt{pi}].  $X$ must be in the range ($-\infty$, $-1$] or [$1$, $\infty$); otherwise, this function throws an error.
\item \texttt{acsc($X$) = $Val$}\index{\texttt{acsc/1}}: This function returns the arc cosecant of $X$, in radians.  The returned value is in the range [\texttt{-pi / 2}, \texttt{pi / 2}].  $X$ must be in the range ($-\infty$, $-1$] or [$1$, $\infty$); otherwise, this function throws an error.
\item \texttt{acot($X$) = $Val$}\index{\texttt{acot/1}}: This function returns the arc cotangent of $X$, in radians.  The returned value is in the range [\texttt{-pi / 2}, \texttt{pi / 2}].
\end{itemize}

\subsection*{Example}
\begin{verbatim}
Picat> S = sin(pi), C = cos(pi), T = tan(pi)
S = 0.0
C = -1.0
T = 0.0
Picat> S = asin(0), C = acos(0), T = atan(0), T2 = atan2(-10, 10)
S = 0.0
C = 1.5708
T = 0.0
T2 = -0.785398
Picat> S = sec(pi / 4), C = csc(pi / 4), T = cot(pi / 4)
S = 1.41421
C = 1.41421
T = 1.0
Picat> S = asec(2), C = acsc(2), T = acot(0)
S = 1.0472
C = 0.5236
T = 1.5708
\end{verbatim}

\subsection{Hyperbolic Functions}
The \texttt{math} module provides the following hyperbolic functions.
\begin{itemize}
\item \texttt{sinh($X$) = $Val$}\index{\texttt{sinh/1}}: This function returns the hyperbolic sine of $X$.
\item \texttt{cosh($X$) = $Val$}\index{\texttt{cosh/1}}: This function returns the hyperbolic cosine of $X$.
\item \texttt{tanh($X$) = $Val$}\index{\texttt{tanh/1}}: This function returns the hyperbolic tangent of $X$.
\item \texttt{sech($X$) = $Val$}\index{\texttt{sech/1}}: This function returns the hyperbolic secant of $X$. 
\item \texttt{csch($X$) = $Val$}\index{\texttt{csch/1}}: This function returns the hyperbolic cosecant of $X$.  If $X$ is $0$, then this function throws an error.
\item \texttt{coth($X$) = $Val$}\index{\texttt{coth/1}}: This function returns the hyperbolic cotangent of $X$.  If $X$ is $0$, then this function throws an error.
\item \texttt{asinh($X$) = $Val$}\index{\texttt{asinh/1}}: This function returns the arc hyperbolic sine of $X$.
\item \texttt{acosh($X$) = $Val$}\index{\texttt{acosh/1}}: This function returns the arc hyperbolic cosine of $X$.  If $X < 1$, then this function throws an error.
\item \texttt{atanh($X$) = $Val$}\index{\texttt{atanh/1}}: This function returns the arc hyperbolic tangent of $X$.  $X$ must be in the range ($-1$, $1$); otherwise, this function throws an error.
\item \texttt{asech($X$) = $Val$}\index{\texttt{asech/1}}: This function returns the arc hyperbolic secant of $X$.  $X$ must be in the range ($0$, $1$]; otherwise, this function throws an error.
\item \texttt{acsch($X$) = $Val$}\index{\texttt{acsch/1}}: This function returns the arc hyperbolic cosecant of $X$.  If $X$ is $0$, then this function throws an error.
\item \texttt{acoth($X$) = $Val$}\index{\texttt{acoth/1}}: This function returns the arc hyperbolic cotangent of $X$.  $X$ must be in the range ($-\infty$, $-1$) or ($1$, $\infty$); otherwise, this function throws an error.
\end{itemize}

\subsection*{Example}
\begin{verbatim}
Picat> S = sinh(pi), C = cosh(pi), T = tanh(pi)
S = 11.54874
C = 11.59195
T = 0.99627
Picat> S = sech(pi / 4), C = csch(pi / 4), T = coth(pi / 4)
S = 0.75494
C = 1.15118
T = 1.52487
Picat> S = asinh(0), C = acosh(1),  T = atanh(0)
S = 0.0
C = 0.0
T = 0.0
\end{verbatim}

\subsection{Random Numbers}
The following functions provide access to a random number generator.
\begin{itemize}
\item \texttt{random() = $Val$}\index{\texttt{random/0}}: This function returns a random integer.
\item \texttt{random2() = $Val$}\index{\texttt{random2/0}}: This function returns a random integer, using an environment-dependent seed.
\item \texttt{rand\_max() = $Val$}\index{\texttt{rand\_max/0}}: This function returns the maximum random integer.
\item \texttt{random($Seed$) = $Val$}\index{\texttt{random/1}}: This function returns a random integer.  At the same time, it changes the seed of the random number generator.
\item \texttt{random($Low$,$High$) = $Val$}\index{\texttt{random/2}}: This function returns a random integer in the range $Low$..$High$.
\item \texttt{frand() = $Val$}\index{\texttt{frand/0}}: This function returns a random real number between 0.0 and 1.0, inclusive.
\item \texttt{frand($Low$,$High$) = $Val$}\index{\texttt{frand/2}}: This function returns a random real number between $Low$ and $High$, inclusive.

%\item \texttt{randrange($From$,$To$) = $Val$}\index{\texttt{randrange/2}}: This function returns a random integer in the range [$From$, $To$).
%\item \texttt{randrange($From$,$Step$,$To$) = $Val$}\index{\texttt{randrange/3}}: This function returns a random integer in the range [$From$, $To$).  The integer will be equal to $From + K * Step$, for some integer $K$.
\end{itemize}

\subsection{Other Built-ins}
\begin{itemize}
\item \texttt{even($N$)}\index{\texttt{even/1}}: This predicate is true if $N$ is an even integer.
\item \texttt{gcd($A$,$B$)}\index{\texttt{gcd/2}}: This function returns the greatest common divisor of integer $A$ and integer $B$.
\item \texttt{odd($N$)}\index{\texttt{odd/1}}: This predicate is true if $N$ is an odd integer.
\item \texttt{prime($N$)}\index{\texttt{prime/1}}: This predicate is true if $N$ is a prime number.
\item \texttt{primes($N$) = $List$}\index{\texttt{primes/1}}: This function returns a list of prime numbers that are less than or equal to $N$.
\end{itemize}


\ignore{
\end{document}
}
