Because we do not have a technical documentation of Maxima internals, I
have started to write some documentations of functions I have worked on.
The following examples try to document the functions PLS, ADDK, EXPTA,
and EXPTB in simp.lisp. I have taken the Common Lisp HyperSpec as a
guide to document the functions.
I am interested to add the documentations to the project. We might add
it to the Lisp files (the documentation might be to verbose) or we start
to add a technical documentation in a TEXI format.
Opinions or suggestions?
Dieter Kaiser
;;;-----------------------------------------------------------------------------
;;; PLS
;;;
;;; Arguments and values:
;;; x - a Maxima expression or an atom
;;; out - a form ((mplus) <number> term1 term2 ...) or NIL
;;; result - a form ((mplus) <number> term1 ...), where x is added in.
;;;
;;; Description:
;;; Adds the argument x into the form out. If out is NIL a form
;;; ((mplus) 0 x) is initialized, if x is an expression or a symbol,
;;; or ((mplus) x), if x is a number. Numbers are added to the first
;;; term <number> of the form. Any other symbol or expression is added
;;; into the canonical ordered list of arguments. The result is in a
;;; canonical order, but it is not a valid Maxima expression. To get a
;;; valid Maxima expression the result has to be checked with the
;;; function TESTP. This is done by the calling routine SIMPLUS.
;;;
;;; Examples:
;;; (pls 2 nil) -> ((MPLUS) 2)
;;; (pls '$A nil) -> ((MPLUS) 0 $A)
;;; (pls '$B '((mplus) 0 $A)) -> ((MPLUS) 0 $A $B)
;;; (pls '$A '((mplus) 0 $A)) -> ((MPLUS) 0 ((MTIMES SIMP) 2 $A))
;;;
;;; Examples with the option variables $NUMER and $NEGDISTRIB:
;;; (let (($numer t)) (pls '$%e nil)) -> ((MPLUS) 2.718281828459045)
;;; (let (($negdistrib t)) (pls '((mtimes) -1 ((mplus) $A $B)) nil))
;;; -> ((MPLUS) 0 ((MTIMES SIMP) -1 $A) ((MTIMES SIMP) -1 $B))
;;; (let (($negdistrib nil)) (pls '((mtimes) -1 ((mplus) $A $B)) nil))
;;; -> ((MPLUS) 0 ((MTIMES) -1 ((MPLUS) $A $B)))
;;;
;;; Affected by;
;;; The option variables $NUMER and $NEGDISTRIB.
;;;
;;; See also:
;;; PLUSIN and ADDK which are called from PLS and SIMPLUS.
;;;
;;; Notes:
;;; To add an expression into the list (cdr out), the list is passed
;;; to the routine PLUSIN as an argument. PLUSIN adds the argument to
;;; the list of terms by modifying the list (cdr out) destructively.
;;; The new value of out is returned as a result by PLS.
;;;
;;;-----------------------------------------------------------------------------
;;; ADDK
;;;
;;; Arguments and result:
;;; xx - a Maxima number
;;; yy - a Maxima number
;;; result - a simplified Maxima number
;;;
;;; Description:
;;; Adds two Maxima numbers and returns a simplified Maxima number.
;;; ADDK can be called in Lisp code, whenever the arguments are valid
;;; Maxima numbers, these are integer, float, Maxima rational, or
;;; Maxima bigfloat numbers. The arguments must not be simplified. The
;;; precision of a bigfloat result depends on the setting of the
;;; global variable $FPPREC. If the option variable $FlOAT is T, a
;;; Maxima rational as a result is converted to a float number.
;;;
;;; Examples:
;;; (addk 2 3) -> 5
;;; (addk 2.0 3) -> 5.0
;;; (addk ($bfloat 2) 3)-> ((BIGFLOAT SIMP 56) 45035996273704960 3)
;;; (addk 2 '((rat) 1 2)) -> ((RAT SIMP) 5 2)
;;; (let (($float t)) (addk 2 '((rat) 1 2))) -> 2.5
;;;
;;; Affected by:
;;; The option variables $FLOAT and $FPPREC.
;;;
;;; See also:
;;; TIMESK to multiply and EXPTRL to exponentiate two Maxima numbers.
;;;
;;; Notes:
;;; The routine works for Lisp rational and Lisp complex numbers too.
;;; This feature is not used in Maxima code. If Lisp complex and
;;; rational numbers are mixed with Maxima rational or bigfloat
;;; numbers the result is wrong or a Lisp error is generated.
;;;
;;;-----------------------------------------------------------------------------
;;; EXPTA
;;;
;;; Arguments and result:
;;; x - a Maxima number
;;; y - an integer number
;;; result - a simplified Maxima number
;;;
;;; Description:
;;; Computes x^y, where x is Maxima number and y an integer. The
;;; result is a simplified Maxima number.
;;;
;;; Affected by:
;;; The option variables $FLOAT and $FPPREC.
;;;
;;; Notes:
;;; This routine is not used within the simplifier. There is only one
;;; call from the file hayat.lisp. This call can be replaced with a
;;; call of the function power.
;;;
;;;-----------------------------------------------------------------------------
;;; EXPTB
;;;
;;; Arguments and values:
;;; a - a float or integer number
;;; b - an integer number
;;; result - a simplified Maxima number
;;;
;;; Description:
;;; Computes a^b, where a is a float or an integer number and b is an
;;; integer number. The result is an integer, float, or Maxima
;;; rational number.
;;;
;;; Examples:
;;; (exptb 3 2) -> 9
;;; (exptb 3.0 2) -> 9.0
;;; (exptb 3 -2) -> ((RAT SiMP) 1 9)
;;; (let (($float t)) (exptb 3 -2)) -> 0.1111111111111111
;;;
;;; Affected by:
;;; The option variable $FLOAT.
;;;
;;; Notes:
;;; EXPTB calls the Lisp functions EXP or EXPT to compute the result.
;;;-----------------------------------------------------------------------------