\documentclass[a4paper,11pt]{article}
\usepackage{hyperref,verbatim}
\title{On conversion from Maxima lisp output to OpenMath}
\author{Rahul Sharma}
\date{9$^{th}$ June 2008}
\begin{document}
\maketitle
\begin{abstract}
 This document is for those who want to use the code for conversion of output from Maxima into OpenMath. Section \ref{1} introduces OpenMath and Maxima. In section \ref{2} we explain the essentials of the program. In section \ref{3} we explain the Lisp functions used and can be skipped if reader has proficiency in it. in section \ref{4} we talk about some library functions which were added to provide additional functionalities. Section \ref{5} is for those who want to add more symbols in the code. Section \ref{6} is a list of functions in the order in which they appear in code.
\end{abstract}

\section{Introduction}\label{1}
We use maxima as a computation engine. It produces its output in its own syntax. But we need to display the maxima expressions and do further calculations with them. This is the documentation of our program used to convert an expression written in Maxima syntax into OpenMath. This section discusses OpenMath and Maxima.
\subsection{OpenMath}\label{1.1}
 OpenMath is an XML standard for representing mathematics in a way such that the  expressions are written in a form that describes the meaning (or semantics) and not the presentation.  The OpenMath expressions can be OMA, OMBIND, OMF, OMI, OMS or OMV. Here OMA stands for Open Math Applications like functions or constructors, OMBIND refers to binding elements i.e symbols which allow us to bind variables, OMF for floating point numbers, OMI for integers, OMS for symbols which can be part of applications or can be constants, or OMV for variables.
More information on OpenMath can be found at \href{http://www.openmath.org/}{http://www.openmath.org/}.
\subsection{Maxima}\label{1.2}
Maxima is a computer algebra system (CAS) that can evaluate mathematical expressions. It has its own syntax. It can do symbolic computations and is free software. For more information refer to \href{http://maxima.sourceforge.net}{http://maxima.sourceforge.net}.

\section{Fundamentals of Program}\label{2}
\subsection{to\_openmath}\label{2.1}

The top level function \verb+to_openmath+ takes an expression in Maxima syntax as 
input and returns an object of OpenMath type. For example \verb+?to_openmath(1) +  gives \verb+((OPENMATH SIMP) "<OMOBJ> <OMI>1</OMI> </OMOBJ>") +. To call this function from Maxima write \verb+?to_openmath(expression)+. The openmath output string can be extracted from an OpenMath type object by using \verb+second+. So \verb+?second(?to_openmath(1))+ returns \verb+"<OMOBJ> <OMI>1</OMI> </OMOBJ>"+.

\subsection{Output Buffer}\label{2.2}
A global output buffer is used, for it provides a convenient mean of storing intermediate results. It is used to store the OpenMath code as a string as the expression gets translated, and when the whole expression has been converted then \verb+to_openmath+ retrieves  this string from the buffer and coverts it into an OpenMath object. The buffer is not transparent, and can be accessed only through specific functions described in the section \ref{6.1}. To put \verb+ <OMOBJ> + in the buffer and then printing it, we write:\\
 \begin{verbatim}
	(clear-output-buffer)
	(append-to-buffer T "<OMOBJ>")
	(print (get-buffer-content))
\end{verbatim}
 
\subsection{OpenMath applications}\label{2.3}

The applications have been split into two parts, some can be directly translated into OpenMath in the function \verb+openmathOMA+, while the other contains the symbols which require something extra for the conversion, and hence there are seperate functions for these symbols. The top level function for these cases is \verb+openmathOMAHd. OMAhardp+ is used to check whether an expression can or cannot be directly translated. The symbols for which direct translation is not possible are listed in section \ref{6.3}.\\e.g 
\verb+((MPLUS) 1 2)+ can be directly translated to:\\
\begin{verbatim}
<OMA>
   <OMS cd="arith1" name="plus"/>
   <OMI>1</OMI>
   <OMI>2</OMI>
</OMA> 
\end{verbatim}
in \verb+openmathOMA+, since there is a direct one to one corrospondence between the two.\\
But if we want to translate \verb+((CEILING) ((MTIMES) 1.0 2.5)))+, which is Maxima syntax for ceiling of \verb+2.5+; then a direct translation will also translate \verb+1.0+. So we needs to make a seperate function to translate it to:\\ \begin{verbatim}
<OMA>
   <OMS cd="rounding1" name="ceiling"/> 
   <OMF dec="2.5"/>
</OMA> 
\end{verbatim}
 Because it needs a seperate function, it is handled by \verb+openmathOMAhd+ and \verb+openmathRounding1Ceiling+. \\
Furthermore \verb+ ((MLIST) 1 2)+ can be either a vector (linalg2.vector) or a matrix row(linalg2.matrixrow) or a list(list1.list), and a selection has to be made by \verb+openmathOMAHd+ and respective function has to be called.
For example In \verb+(($MATRIX)((MLIST) 1 2)((MLIST) 1 2)), MLIST + refers to a matrixrow, whereas \verb+ ((MLIST) 3 4)+ can be a list or a vector.

\section{Common Lisp Functions}\label{3}
This section talks about the Common Lisp functions, whose understanding is essential to understand the code. They are listed below:
\begin{description}
 \item[concatenate] for appending the second string to the first.\\
		\verb+(concatenate 'string result str)+ appends \verb+str+ to	\verb+result+.	
\item[first, second, \ldots and nth] for extracting the respective element of list.\\
		     \verb+(first '(a b c))+ gives \verb+a+.\\
		     \verb+(nth '(a b c) 2)+ and \verb+(second '(a b c))+ give \verb+b+.
\item[char-downcase] for converting a character into lower case.\\
		\verb+(char-downcase #\A)+ gives \verb+a+.

\item[map] for applying a function to all elements of a list.\\
	\verb+(map returntype #'f l)+ applies function f to all the elements stored in the list and returns the resulting list converted into type of the returntype specified. Some examples:
\begin{itemize}
 \item \verb+(map 'list #'first '((a b) (c d)))+ gives \verb+(a c)+.
 \item \verb+(map 'string #'char-downcase '(#\A #\B))+ gives \verb+"ab"+.
 \item If we are interested only in effects and not the returned list then the returntype can be specified as nil.
\end{itemize}

\item[case] a simple case statement, the statement corresponding to matching tag is executed.\\
\begin{verbatim}
(case expr 
   (LAMBDA T)
   (FALL T)
   (otherwise NIL)
) 
\end{verbatim}
if \verb+expr+,the input to this case is \verb+LAMBDA+ or \verb+FALL+ then \verb+T+ is returned, otherwise \verb+NIL+ is returned. So this code can be used to test if the Maxima expression is a binding or not.

\item[cond] It contains a list of conditions. Each condition has some code associated with it. When a condition becomes true, the code with it is executed.\\
\begin{verbatim}
(cond 
   (( > p 1) 'a)
   (( < p 1) 'b)
   (( = p 1) 'c)
 )
\end{verbatim}
 returns a if p $>$ 1.
 \end{description}
\section{Extra Functions}\label{4}
There are some functions which have been defined for computational purpose and added as library. They have been added since additional functionality was required. From Maxima they can be called with ?functionname(arguments).
\begin{description}
 \item[xor]  Openmath requires xor with arbitary number of arguments, but Maxima provides only xor with two arguments. So an n-ary xor was coded.
\item[filter] takes a list and a predicate as input, and returns the sublist such that the elements satisfy the predicate.
 \end{description}
\section{Extending the code}\label{5}
\subsection{Introduction}\label{5.1}
This code does not handle all symbols of OpenMath. Also OpenMath is designed so that more symbols can be added to it. This code can be easily updated to take care of that. This section is for those who want to add symbols which are not currently handled, to the phrasebook.
\subsection{Steps}\label{5.2}
\begin{enumerate}
 \item First check if the symbol can appear as Maxima output, if not then nothing needs to be done. For example logic1.impies of a and b is translated as logic1.or(logic1.not(a),b), and hence logic1.implies can never be in output, and output will be in form of not and or.
 \item If it does occur in output, then check from the symbol description on OpenMath CD that is it translated to an OpenMath application or an OpenMath binding. If it is a binding, that is a symbol like lambda and forall which bind some variables then add the symbol to \verb+binderp+ and \verb+openmathOMS+.
\item   If it is an application then check if it can be directly translated, i.e whether a one to one correspondence exists between the Maxima syntax and OpenMath. If yes, then add it to \verb+openmathOMS+.
\item If it can not be directly translated make a seperate function for it, and add the symbol to \verb+hardSymbol+ and \verb+openmathOMAHd+. Some examples are in source code.
\end{enumerate}
\section{List of functions}\label{6}
This is a list of functions as they appear in the code.
\subsection{Utility functions for Buffer}\label{6.1}
These functions are used for manipulating the output buffer described in section \ref{2.2}. They are listed here with their short descriptions:
\begin{description}
 \item[append-to-buffer]: appends a string into the output buffer.
 \item[clear-output-buffer]: initializes the output buffer to empty string.
 \item[get-buffer-content]: returns the contents of output buffer
\end{description}
\subsection{Functions for testing the type}\label{6.2}
This is a list of functions for testing the type of Maxima references. The types checked are those refered in section \ref{1.1}.
\begin{itemize}
 \item[binderp] helper function of \verb+OMBINDp+.
 \item[OMAp] checks if symbol corresponds to an OMA type.
 \item[OMBINDp] checks if symbol corresponds to an OMBIND type.
 \item[OMVp] checks if symbol corresponds to an OMV type.
 \item[hardSymbol] helper function for \verb+OMAhardp+.
 \item[OMAhardp] checks if symbol is an application and cannot be directly translated to OMA.
 \item[OPENMATHSTRp] checks the type of output is OpenMath output
\end{itemize}
\subsection{Symbols with seperate Functions}\label{6.3}
 This section lists the CDs and symbols, which cannot be translated directly (recall section \ref{2.3}), i.e those for which, to generate some OpenMath expressions special functions are needed.The naming convention is OpenMath followed by the capitilized CD name and then the capitalized symbol name so, for example the function corresponding to set1.set is openmathSet1Set. \\[2 ex]
\begin{tabular}{|l|l|}
\hline
CD & Symbols\\
\hline
arith1 & product, sum\\
bigfloat1 &  bigfloat\\
calculus1 & defint, diff, int, nthdiff\\
integer1 & factorof\\
interval1 & integer\_interval\\
limit1 & limit\\
linalg1 & matrix\_selector, outerproduct, vector\_selector\\
linalg2 & matrix, matrix\_row, vector\\
linalg3 & characterstic\_eqn\\
list1 & list, map\\
logic1 & equivalent\\
relation1 & eq, geq, gt, leq, lt, neq\\
rounding1 & ceiling, floor, round, trunc\\
s\_data1 & mean, median, std, var\\
set1 & emptyset, map, set \\
\hline
 \end{tabular}
\subsection{Functions Generating OpenMath}\label{6.4}
The output in Maxima syntax is first tested for the type of OpenMath expression it is.
Then there is a function for generating the OpenMath code from Maxima code corresponding to each OpenMath type. For example the function to generate OpenMath code for an OMI is \verb+openmathOMI+, and it converts integers in Maxima syntax to OpenMath integers.
\begin{description}
 \item[openmathOMA]  adds an application as OpenMath to the buffer (which have one to one corrospondences, refer to section \ref{2.3})
\item[openmathOMAHd]  adds an application as OpenMath to the buffer (which cannot be directly translated, see section \ref{2.3}).
\item[openmathOMBIND] adds a binding as OpenMath to the buffer
\item[openmathOMF] adds a floating point number as OpenMath to the buffer
\item[openmathOMI] adds an integer as OpenMath to the buffer
\item[openmathOMS] adds a symbol as OpenMath to the buffer 
\item[openmathOMV] adds a variable as OpenMath to the buffer
\item[openmath] adds a generic expression as OpenMath to the buffer
\emph{\item[to\_openmath] converts an expression into an OpenMath typed string. It is the topmost function for OpenMath conversion.} More information about this function and how to call it can be found in section \ref{2.1}.
\end{description}\
\appendix
\section{Maxima Functions of Matrices(Not in OpenMath)}
%\include{/home/rsharma/reports/maximaMatrix.tex} 
There are many useful functions in maxima for matrices. But they are not present in OpenMath. Here they are listed with their functionalities.
 \subsection{Adjoint}
   \subsubsection{Syntax}
	\verb+ adjoint(M) + where M is a matrix
   \subsubsection{Description}
	Returns the adjoint of the matrix M. The adjoint matrix is the transpose of the matrix of cofactors of M. In other words: \\
	$ A*adjoint(A)=determinant(A)*I $ where I is the identity matrix.
\subsection{Extracting collumns}
\subsubsection{Syntax}
	\verb+ collumn(M,i) + where M is a matrix and i an integer.
   \subsubsection{Description}
	Returns the i'th collumn of the matrix M. The return value is a matrix.
 \subsection{Conjugate}
  \subsubsection{Syntax}
	\verb+ conjugate(M) + where M is a matrix
   \subsubsection{Description}	
	Returns the complex conjugate of a matrix. It can be clubbed with complex1.conjugate
\subsection{Echelon Form}
 \subsubsection{Syntax}
	\verb+ echelon(M) + where M is a matrix
   \subsubsection{Description}
	Returns the echelon form of the matrix M, as produced by Gaussian elimination. The echelon form is computed from M by elementary row operations such that the first non-zero element in each row in the resulting matrix is one and the column elements under the first one in each row are all zero.
 \subsection{Gram Schmidt Orthogonalization}
   \subsubsection{Syntax}
	\verb+ gramschmidt(x,[F]) + where x is a matrix, and F is an optional argument, and specifies the inner product to be used.
   \subsubsection{Description}
	Carries out the Gram-Schmidt orthogonalization algorithm on x, which is either a matrix or a list of lists. x is not modified by gramschmidt. The inner product employed by gramschmidt is F, if present, otherwise the inner product is the function innerproduct.
 \subsection{Inner Product}
   \subsubsection{Syntax}
	\verb+ inprod(x,y) + where x,y are lists of equal length, or both 1-column or 1-row matrices of equal length.
   \subsubsection{Description}
	The return value is \verb+ conjugate (x) . y + , the standard innerproduct.
 \subsection{Inverse}
     \subsubsection{Syntax}
	\verb+ invert(M) + where M is a matrix.
   \subsubsection{Description}
 Returns the inverse of the matrix M. The inverse is computed by the adjoint method.
\verb+ invert (m) := adjoint (m) / determinant (m) + 
\subsection{Trace}
\subsubsection{Syntax}
	\verb+ mattrace(M) + where M is a matrix.
   \subsubsection{Description}
	Returns the trace (that is, the sum of the elements on the main diagonal) of the square matrix M.
\subsection{Extracting rows}
\subsubsection{Syntax}
	\verb+ row(M,i) + where M is a matrix and i an integer.
   \subsubsection{Description}
	Returns the i'th row of the matrix M. The return value is a matrix.
\subsection{Submatrix}
\subsubsection{Syntax}
	\verb+ submatrix (i\_1, ..., i\_m, M, j\_1, ..., j\_n) + where M is a matrix and rest natural numbers.
   \subsubsection{Description}
	Returns the i'th row of the matrix M. The return value is a matrix.
\subsection{Triangularize}
\subsubsection{Syntax}
	\verb+ triangularize(M) + where M is a matrix.
   \subsubsection{Description}
Returns the upper triangular form of the matrix M, as produced by Gaussian elimination. The return value is the same as echelon, except that the leading nonzero coefficient in each row is not normalized to 1.
\subsection{Unit Vectors}
\subsubsection{Syntax}
	\verb+ uvect(x) + where x is a vector.
   \subsubsection{Description}
Returns \verb+ x/norm(x) + this is a unit vector in the same direction as x.
\\[2 ex]
\section{The RIACA cds}
This appendix lists the RIACA CDs and tells about their implementation. 
\verbatiminput{../../../../../maximaclient/documentation/riacaSymbols.txt}
\end{document}
