% Copyright 2007 by Mark Wibrow
%
% This file may be distributed and/or modified
%
% 1. under the LaTeX Project Public License and/or
% 2. under the GNU Free Documentation License.
%
% See the file doc/generic/pgf/licenses/LICENSE for more details.

\section{Evaluating Mathematical Operations}

\label{pgfmath-commands}

Instead of parsing and evaluating complex expressions, you can also
use the mathematical engine to evaluate a single mathematical
operation. The macros used for these computations are described in the
following. 


\subsection{Basic Operations and Functions}

\label{pgfmath-operations}

\begin{command}{\pgfmathadd\marg{x}\marg{y}}  
	Defines |\pgfmathresult| as $\meta{x}+\meta{y}$.
\end{command}

\begin{command}{\pgfmathsubtract\marg{x}\marg{y}}      
	Defines |\pgfmathresult| as $\meta{x}-\meta{y}$.                                       
\end{command}

\begin{command}{\pgfmathmultiply\marg{x}\marg{y}}      
	Defines |\pgfmathresult| as $\meta{x}\times\meta{y}$.                                
\end{command}

\begin{command}{\pgfmathdivide\marg{x}\marg{y}}        
	Defines |\pgfmathresult| as $\meta{x}\div\meta{y}$. An error will
	result if \meta{y} is	|0|, or if the result of the division is
	too big for the mathematical engine.
	Please remember	when using this command that accurate (and reasonably 
	quick) division of non-integers is particularly tricky in \TeX{}. 	
	There are three different forms of division used in this command:
	\begin{itemize}
		\item 
		If \meta{y} is an integer then the native |\divide| operation of 
		\TeX{} is used.
		\item
		If \vrule\meta{y}\vrule$<1$, then |\pgfmathreciprocal| is employed.
		\item
		For all other values of \meta{y} an optimised long division 
		algorithm is used. In theory this should be accurate
		to any finite precision, but in practice it is constrained by the
		limits of \TeX{}'s native mathematics.
	\end{itemize}
	                             
\end{command}

\begin{command}{\pgfmathreciprocal\marg{x}}         
	Defines |\pgfmathresult| as $1\div\meta{x}$.                            
\end{command}

\begin{command}{\pgfmathgreaterthan\marg{x}\marg{y}}   
	Defines |\pgfmathresult| as 1.0 if \meta{x} $>$ \meta{y}, but 0.0 otherwise.                 
\end{command}

\begin{command}{\pgfmathlessthan\marg{x}\marg{y}} 
	Defines |\pgfmathresult| as 1.0 if \meta{x} $<$ \meta{y}, but 0.0 otherwise.             
\end{command}
	
\begin{command}{\pgfmathequalto\marg{x}\marg{y}}       
	Defines |\pgfmathresult| 1.0 if \meta{x} $=$ \meta{y}, but 0.0 otherwise.                    
\end{command}

\begin{command}{\pgfmathround\marg{x}}              
	Defines |\pgfmathresult| as $\left\lfloor\textrm{\meta{x}}\right\rceil$.	
	This uses asymmetric	half-up rounding.                          
\end{command}

\begin{command}{\pgfmathfloor\marg{x}}              
	Defines |\pgfmathresult| as $\left\lfloor\textrm{\meta{x}}\right\rfloor$.
\end{command}

\begin{command}{\pgfmathceil\marg{x}}               
	Defines |\pgfmathresult| as $\left\lceil\textrm{\meta{x}}\right\rceil$.                           
\end{command}
	
\begin{command}{\pgfmathpow\marg{x}\marg{y}}         
	Defines |\pgfmathresult| as $\meta{x}^{\meta{y}}$.  For greatest 
	accuracy \mvar{y} should be an integer. If \mvar{y} is not an integer 
	the actual calculation will be an approximation of $e^{y\ln(x)}$.
\end{command}

\begin{command}{\pgfmathmod\marg{x}\marg{y}}           
	Defines |\pgfmathresult| as \meta{x} modulo \meta{y}.                       
\end{command}

\begin{command}{\pgfmathmax\marg{x}\marg{y}}           
	Defines |\pgfmathresult| as the maximum of \meta{x} or \meta{y}.                       
\end{command}

\begin{command}{\pgfmathmin\marg{x}\marg{y}}           
	Defines |\pgfmathresult| as the minimum \meta{x} or \meta{y}.                       
\end{command}
	
\begin{command}{\pgfmathabs\marg{x}}                
	Defines |\pgfmathresult| as  absolute value of \meta{x}.                                 
\end{command}
	
\begin{command}{\pgfmathexp\marg{x}}                
	Defines |\pgfmathresult| as $e^{\meta{x}}$. Here, \meta{x} can be a 
	non-integer. The algorithm	uses a Maclaurin series.               
\end{command}

\begin{command}{\pgfmathln\marg{x}}                
	Defines |\pgfmathresult| as $\ln{\meta{x}}$. This uses an algorithm
	due to Rouben Rostamian, and coefficients suggested by
	Alain Matthes.             
\end{command}
	
\begin{command}{\pgfmathsqrt\marg{x}} 
	Defines |\pgfmathresult| as $\sqrt{\meta{x}}$. 
\end{command}
	
\begin{command}{\pgfmathveclen\marg{x}\marg{y}}        
	Defines |\pgfmathresult| as $\sqrt{\meta{x}^2+\meta{y}^2}$. This uses
	a polynomial approximation, based on ideas due to Rouben Rostamian.                                    
\end{command}

\subsection{Trignometric Functions}

\label{pgfmath-trigonmetry}

\begin{command}{\pgfmathpi}
  	Defines |\pgfmathresult| as $3.14159$.
\end{command}
   
\begin{command}{\pgfmathdeg{\marg{x}}} 
	Defines |\pgfmathresult| as \meta{x} (given in radians) converted to 
	degrees. 
\end{command}

\begin{command}{\pgfmathrad{\marg{x}}} 
	Defines |\pgfmathresult| as \meta{x} (given in degrees) converted to 
	radians. 
\end{command}

\begin{command}{\pgfmathsin{\marg{x}}}  
	Defines |\pgfmathresult| as the sine of \meta{x}.  
\end{command}

\begin{command}{\pgfmathcos{\marg{x}}}
	Defines |\pgfmathresult| as the cosine of \meta{x}.
\end{command}

\begin{command}{\pgfmathtan{\marg{x}}}  
	Defines |\pgfmathresult| as the tangant of \meta{x}.  
\end{command}

\begin{command}{\pgfmathsec{\marg{x}}}
	Defines |\pgfmathresult| as the secant of \meta{x}.
\end{command}

\begin{command}{\pgfmathcosec{\marg{x}}}  
	Defines |\pgfmathresult| as the cosecant of \meta{x}.  
\end{command}

\begin{command}{\pgfmathcot{\marg{x}}}  
	Defines |\pgfmathresult| as the cotangant of \meta{x}.  
\end{command}

\begin{command}{\pgfmathasin{\marg{x}}}
	Defines |\pgfmathresult| as the arcsine of \meta{x}. 
	The result will be in the range $\pm90^\circ$.
\end{command}

\begin{command}{\pgfmathacos{\marg{x}}}
	Defines |\pgfmathresult| as the arccosine of \meta{x}.
	The result will be in the range $\pm90^\circ$.
\end{command}

\begin{command}{\pgfmathatan{\marg{x}}}
 	Defines |\pgfmathresult| as the arctangent of \meta{x}.
\end{command}



\subsection{Pseudo-Random Numbers}

\label{pgfmath-random}


\begin{command}{\pgfmathgeneratepseudorandomnumber}
	Defines |\pgfmathresult| as a pseudo-random integer between 1 and 
	$2^{31}-1$. This uses a linear congruency generator, based on ideas
	due to Erich Janka.
\end{command}

\begin{command}{\pgfmathrnd}
	Defines |\pgfmathresult| as a pseudo-random number between |0| and |1|.
\end{command}

\begin{command}{\pgfmathrand}
	Defines |\pgfmathresult| as a pseudo-random number between |-1| and |1|.
\end{command}

\begin{command}{\pgfmathrandominteger\marg{macro}\marg{maximum}\marg{minimum}}
	This defines \meta{macro} as a pseudo-randomly generated integer from 
	the range \meta{maximum} to \meta{minimum} (inclusive).
	
\begin{codeexample}[]
\begin{pgfpicture}
   \foreach \x in {1,...,50}{
      \pgfmathrandominteger{\a}{1}{50}
      \pgfmathrandominteger{\b}{1}{50}
      \pgfpathcircle{\pgfpoint{+\a pt}{+\b pt}}{+2pt}
      \color{blue!40!white}
      \pgfsetstrokecolor{blue!80!black}
      \pgfusepath{stroke, fill}
   }	  
\end{pgfpicture}
\end{codeexample}
\end{command}

\begin{command}{\pgfmathdeclarerandomlist\marg{list name}\{\marg{item-1}\marg{item 2}...\}}
	This creates a list of items with the name \meta{list name}.
\end{command}

\begin{command}{\pgfmathrandomitem\marg{macro}\marg{list name}}
	Select an item from a random list \meta{list name}. The
	selected item is placed in \meta{macro}.
\end{command}

\begin{codeexample}[]
\begin{pgfpicture}
   \pgfmathdeclarerandomlist{color}{{red}{blue}{green}{yellow}{white}}
   \foreach \a in {1,...,50}{
      \pgfmathrandominteger{\x}{1}{85}
      \pgfmathrandominteger{\y}{1}{85}
      \pgfmathrandominteger{\r}{5}{10}
      \pgfmathrandomitem{\c}{color}
      \pgfpathcircle{\pgfpoint{+\x pt}{+\y pt}}{+\r pt}
      \color{\c!40!white}
      \pgfsetstrokecolor{\c!80!black}
      \pgfusepath{stroke, fill}
   }	  
\end{pgfpicture}
\end{codeexample}

\begin{command}{\pgfmathsetseed\marg{integer}}
  Explicitly set seed for the pseudo-random number generator. By
  default it is set to the value of |\time|$\times$|\year|.
\end{command}


      
\subsection{Conversion Between Bases}
	
\label{pgfmath-bases}

\pgfname{} provides limited support for conversion between 
\emph{representations} of numbers. Currently the numbers must be
positive integers in the range $0$ to $2^{31}-1$, and the bases in the
range $2$ to $36$. All digits representing numbers greater than 9 (in
base ten), are alphabetic, but may be upper or lower case. 

\begin{command}{\pgfmathbasetodec\marg{macro}\marg{number}\marg{base}}
	Defines \meta{macro} as the result of converting \meta{number} from
	base \meta{base} to base 10. Alphabetic digits can be upper or lower
	case.

\medskip{\def\medskip{}

\begin{codeexample}[]
\pgfmathbasetodec\mynumber{107f}{16} \mynumber
\end{codeexample}


\begin{codeexample}[]
\pgfmathbasetodec\mynumber{33FC}{20} \mynumber
\end{codeexample}

}\medskip

\end{command}

\begin{command}{\pgfmathdectobase\marg{macro}\marg{number}\marg{base}}
	Defines \meta{macro} as the result of converting \meta{number} from
	base 10 to base \meta{base}. Any resulting alphabetic digits are in
	\emph{lower case}.
	
\begin{codeexample}[]
\pgfmathdectobase\mynumber{65535}{16} \mynumber
\end{codeexample}

\end{command}

\begin{command}{\pgfmathdectoBase\marg{macro}\marg{number}\marg{base}}
	Defines \meta{macro} as the result of converting \meta{number} from
	base 10 to base \meta{base}. Any resulting alphabetic digits are in
	\emph{upper case}.
	
\begin{codeexample}[]
\pgfmathdectoBase\mynumber{65535}{16} \mynumber
\end{codeexample}

\end{command}

\begin{command}{\pgfmathbasetobase\marg{macro}\marg{number}\marg{base-1}\marg{base-2}}
	Defines \meta{macro} as the result of converting \meta{number} from
	base \meta{base-1} to base \meta{base-2}. Alphabetic digits in 
	\meta{number} can be upper or lower case, but any resulting 
	alphabetic digits are in \emph{lower case}.
	
\begin{codeexample}[]
\pgfmathbasetobase\mynumber{11011011}{2}{16} \mynumber
\end{codeexample}

\end{command}

\begin{command}{\pgfmathbasetoBase\marg{macro}\marg{number}\marg{base-1}\marg{base-2}}
	Defines \meta{macro} as the result of converting \meta{number} from
	base \meta{base-1} to base \meta{base-2}. Alphabetic digits in 
	\meta{number} can be upper or lower case, but any resulting 
	alphabetic digits are in \emph{upper case}.
	
\begin{codeexample}[]
\pgfmathbasetoBase\mynumber{121212}{3}{12} \mynumber
\end{codeexample}

\end{command}


\begin{command}{\pgfmathsetbasenumberlength\marg{integer}}
	Set the number of digits in the result of a base conversion to 
	\meta{integer}. If the result of a conversion has less digits
	than this number it is prefixed with zeros.

\begin{codeexample}[]
\pgfmathsetbasenumberlength{8}
\pgfmathdectobase\mynumber{15}{2} \mynumber
\end{codeexample}

\end{command}