\input texinfo

@c makeinfo simplification.texi         to make .info
@c texi2html simplification.texi        to make .html
@c texi2pdf simplification.texi         to make .pdf

@setfilename simplification.info
@settitle simplification

@format
INFO-DIR-SECTION Math
START-INFO-DIR-ENTRY
* Maxima-simplification: (simplification).  A computer algebra system -- contributions.
END-INFO-DIR-ENTRY
@end format
@ifinfo 
@macro var {expr}
<\expr\>
@end macro
@end ifinfo

@node Top, Introduction to simplification, (dir), (dir)
@top
@menu
* Introduction to simplification::
* Definitions for simplification::
* Function and variable index::
@end menu

@node Introduction to simplification, Definitions for simplification, Top, Top
@section Introduction to simplification

The directory @code{maxima/share/simplification} contains several scripts
which implement simplification rules and functions,
and also some functions not related to simplification.

@node Definitions for simplification, Function and variable index, Introduction to simplification, Top
@section Definitions for simplification

@c Adapted from absimp.usg ----------------------

@c @defvr {Add-on package} (WITH HYPHEN) CONFUSES DESCRIBE (CAN'T FIND END OF ITEM)
@c SAME WITH OTHER "ADD-ON PACKAGES" HERE (FACEXP, INEQ)
@defvr {Add on package} absimp

The @code{absimp} package contains pattern-matching rules that
extend the built-in simplification rules for the @code{abs} and @code{signum}
functions.
@code{absimp} respects relations
established with the built-in @code{assume} function and by declarations such
as  @code{modedeclare (m, even, n, odd)}  for even or odd integers.

@code{absimp} defines @code{unitramp} and @code{unitstep} functions
in terms of @code{abs} and @code{signum}.

@code{load (absimp)} loads this package.
@code{demo (absimp)} shows a demonstration of this package.

Examples:

@example
(%i1) load (absimp);
(%o1) /usr/share/maxima/5.9.2/share/simplification/absimp.mac
(%i2) (abs (x))^2;
                                2
(%o2)                          x
(%i3) diff (abs (x), x);
                               x
(%o3)                        ------
                             abs(x)
(%i4) cosh (abs (x));
(%o4)                        cosh(x)
@end example
@end defvr

@c disol.usg: "disolate" already in doc/info/Expressions.texi

@c elim.usg: "eliminate" already in doc/info/Polynomials.texi

@c Adapted from facexp.usg ----------------------
@c ALL OF THE TEXT IN FACEXP.USG IS VERY VAGUE.
@c I HAVE NO IDEA WHAT THESE FUNCTIONS DO.
@c ALL OF THESE ITEMS NEED TO BE HEAVILY REVISED
@c (ASSUMING THIS PACKAGE IS SOMETHING WE WANT TO INVEST TIME IN)
@defvr {Add on package} facexp

@c THIS IS VERY VAGUE. JUST WHAT DOES THIS DO?
The @code{facexp} package contains several related  functions that
provide the user with the ability to structure expressions by controlled
expansion.   This capability  is especially  useful when  the expression
contains variables that have physical meaning, because it is  often true
that the most economical form  of such an expression can be  obtained by
fully expanding the expression with respect to those variables, and then
factoring their coefficients.  While it is  true that this  procedure is
not difficult to carry out using standard Maxima  functions, additional
fine-tuning may also  be desirable, and  these finishing touches  can be
more  difficult to  apply.

The  function @code{facsum}  and its  related forms
provide a convenient means for controlling the structure  of expressions
in this way.  Another function, @code{collectterms}, can be used to add  two or
more expressions that have already been simplified to this form, without
resimplifying the whole expression again.  This function may be
useful when the expressions are very large.

@c CAN'T FIND ANY SUCH FILE "DIAGEVAL".
@c THERE ARE COMMENTED-OUT DEFNS OF FACTENEXPAND, FACEXPTEN, AND FACTORFACEXPTEN
@c IN FACEXP (AND NOWHERE ELSE).
@c COMMENTING OUT THIS TEXT FOR NOW.
@c Note:  @code{factenexpand}, @code{facexpten}, and @code{factorfacexpten}  are available  only
@c after loading @code{diageval}. They are special functions used for  tensor
@c manipulation.

@code{load (facexp)} loads this package.
@code{demo (facexp)} shows a demonstration of this package.
@end defvr

@c THIS IS VERY VAGUE. JUST WHAT DOES THIS DO?
@c SOME EXAMPLES WOULD HELP HERE
@deffn {Function} facsum (@var{expr}, @var{arg_1}, ..., @var{arg_n})
Returns  a form  of @var{expr}  which depends  on the
arguments @var{arg_1}, ..., @var{arg_n}.
The arguments can be any form suitable for @code{ratvars}, or they can be
lists  of such  forms.  If  the arguments  are not  lists, then  the form
returned is  fully expanded with respect  to the arguments,  and the
coefficients of the arguments are factored.  These  coefficients are
free of the arguments, except perhaps in a non-rational sense.

If any of the arguments are  lists, then all such lists are combined
into  a  single  list,   and  instead  of  calling  @code{factor}   on  the
coefficients  of  the  arguments,  @code{facsum}  calls  itself   on  these
coefficients, using  this newly constructed  single list as  the new
argument list  for this  recursive  call.  This  process can  be  repeated to
arbitrary depth by nesting the desired elements in lists.

It is possible that one may wish to @code{facsum} with respect  to more
complicated subexpressions,  such as  @code{log (x + y)}.  Such  arguments are
also  permissible.   With  no  variable  specification,  for example
@code{facsum (@var{expr})}, the  result returned  is the same  as that  returned by
@code{ratsimp (@var{expr})}.

Occasionally the user may wish to obtain any of the  above forms
for expressions which are specified only by their leading operators.
For example, one may wish  to @code{facsum} with respect to all  @code{log}'s.  In
this situation, one may  include among the arguments either  the specific
@code{log}'s which are to be treated in this way, or  alternatively, either
the expression  @code{operator (log)} or @code{'operator (log)}.   If one  wished to
@code{facsum} the expression @var{expr} with respect to the operators @var{op_1}, ..., @var{op_n},
one   would  evaluate  @code{facsum (@var{expr}, operator (@var{op_1}, ..., @var{op_n}))}.
The @code{operator} form may also appear inside list arguments.

In  addition,  the  setting  of  the  switches   @code{facsum_combine}  and
@code{nextlayerfactor} may affect the result of @code{facsum}.
@end deffn

@defvr {Global variable} nextlayerfactor
Default value: @code{false}

When @code{nextlayerfactor} is @code{true}, recursive calls  of @code{facsum}
are applied  to  the  factors  of  the  factored  form   of  the
coefficients of the arguments.

When  @code{false}, @code{facsum} is applied to
each coefficient as a whole whenever recusive calls to  @code{facsum} occur.

Inclusion   of   the  atom
@code{nextlayerfactor} in  the argument  list of @code{facsum}  has the  effect of
@code{nextlayerfactor: true}, but for the next level of the expression @i{only}.
Since @code{nextlayerfactor} is  always bound to  either @code{true} or  @code{false}, it
must be presented single-quoted whenever it appears in the argument list of @code{facsum}.
@end defvr

@defvr {Global variable} facsum_combine
Default value: @code{true}

@code{facsum_combine} controls the form  of the final result  returned by
@code{facsum}  when  its  argument  is  a  quotient  of   polynomials.   If
@code{facsum_combine} is @code{false}  then the form will  be returned as  a fully
expanded  sum  as described  above,  but if  @code{true},  then  the expression
returned is a ratio of polynomials, with each polynomial in the form
described above.

The @code{true} setting of this switch is useful when one
wants to  @code{facsum} both  the numerator and  denominator of  a rational
expression,  but  does not  want  the denominator  to  be multiplied
through the terms of the numerator.
@end defvr

@deffn {Function} factorfacsum (@var{expr}, @var{arg_1}, ... @var{arg_n})
Returns a  form of @var{expr}  which is
obtained by calling  @code{facsum} on the factors  of @var{expr} with @var{arg_1}, ... @var{arg_n} as
arguments.  If any of the factors of @var{expr} is raised to a  power, both
the factor and the exponent will be processed in this way.
@end deffn

@deffn {Function} collectterms (@var{arg_1}, ..., @var{arg_n})
If several  expressions  have been
simplified  with  @code{facsum}, @code{factorfacsum},  @code{factenexpand},  @code{facexpten} or
@code{factorfacexpten},  and  they are  to  be added  together,  it  may be
desirable   to  combine   them  using   the   function  @code{collecterms}.
@code{collecterms} can take as arguments  all of the arguments that  can be
given  to these  other associated  functions with  the  exception of
@code{nextlayerfactor}, which has no effect on @code{collectterms}.  The advantage
of @code{collectterms}  is that it  returns a form  similar to  @code{facsum}, but
since it is adding forms that have already been processed by @code{facsum},
it  does  not  need  to  repeat  that  effort.   This  capability is
especially useful when the expressions to be summed are very large.
@end deffn

@c Adapted from functs.usg ----------------------

@c conjugate already described in doc/info/Matrices.texi

@deffn {Function} rempart (@var{expr}, @var{n})
Removes part @var{n} from the expression @var{expr}.

If @var{n} is a list of the form @code{[@var{l}, @var{m}]}
then parts @var{l} thru @var{m} are removed.
@end deffn

@deffn {Function} wronskian ([@var{f_1}, ..., @var{f_n}], @var{x})
Returns the Wronskian matrix of the functions @var{f_1}, ..., @var{f_n} in the variable @var{x}.

@var{f_1}, ..., @var{f_n} may be the names of user-defined functions,
or expressions in the variable @var{x}.

The determinant of the Wronskian matrix is the Wronskian determinant of the set of functions.
The functions are linearly dependent if this determinant is zero.
@end deffn

@c adjoint already described in doc/info/Matrices.texi

@deffn {Function} tracematrix (@var{M})
Returns the trace (sum of the diagonal elements) of matrix @var{M}.
@end deffn

@deffn {Function} rational (z)
Multiplies numerator and denominator of @var{z} by the complex conjugate of denominator,
thus rationalizing the denominator.
Returns canonical rational expression (CRE) form if given one, else returns general form.
@end deffn

@deffn {Function} logand (x,y)
Returns logical (bit-wise) "and" of arguments x and y.
@end deffn

@deffn {Function} logor (x,y)
Returns logical (bit-wise) "or" of arguments x and y.
@end deffn

@deffn {Function} logxor (x,y)
Returns logical (bit-wise) exclusive-or of arguments x and y.
@end deffn

@c uprobe calls ?uprobe and assumes file is a list => obsolete, not common lisp

@c kronecker superseded by kron_delta in src/nset.lisp

@deffn {Function} nonzeroandfreeof (@var{x}, @var{expr})
Returns @code{true} if @var{expr} is nonzero and @code{freeof (@var{x}, @var{expr})} returns @code{true}.
Returns @code{false} otherwise.
@end deffn

@deffn {Function} linear (@var{expr}, @var{x})
When @var{expr} is an expression linear in variable @var{x},
@code{linear} returns @code{@var{a}*@var{x} + @var{b}} where @var{a} is nonzero,
and @var{a} and @var{b} are free of @var{x}.
Otherwise, @code{linear} returns @var{expr}.
@end deffn

@deffn {Function} quadratic (@var{expr}, @var{x})
When @var{expr} is an expression quadratic in variable @var{x},
@code{quadratic} returns @code{@var{a}*@var{x}^2 + @var{b}*x + @var{c}} where @var{a} is nonzero,
and @var{a}, @var{b}, and @var{c} are free of @var{x}.
Otherwise, @code{quadratic} returns @var{expr}.
@end deffn

@deffn {Function} gcdivide (@var{p}, @var{q})
When @code{takegcd} is @code{true},
@code{gcdivide} divides the polynomials @var{p} and @var{q} by their greatest common divisor
and returns the ratio of the results.

When @code{takegcd} is @code{false},
@code{gcdivide} returns the ratio @code{@var{p}/@var{q}}.
@end deffn

@c lcm already described in doc/info/Number.texi

@deffn {Function} arithmetic (@var{a}, @var{d}, @var{n})
Returns the @var{n}-th term of the arithmetic series
@code{@var{a}, @var{a} + @var{d}, @var{a} + 2*@var{d}, ..., @var{a} + (@var{n} - 1)*@var{d}}.
@end deffn

@deffn {Function} geometric (@var{a}, @var{r}, @var{n})
Returns the @var{n}-th term of the geometric series
@code{@var{a}, @var{a}*@var{r}, @var{a}*@var{r}^2, ..., @var{a}*@var{r}^(@var{n} - 1)}.
@end deffn

@deffn {Function} harmonic (@var{a}, @var{b}, @var{c}, @var{n})
Returns the @var{n}-th term of the harmonic series
@code{@var{a}/@var{b}, @var{a}/(@var{b} + @var{c}), @var{a}/(@var{b} + 2*@var{c}), ..., @var{a}/(@var{b} + (@var{n} - 1)*@var{c})}.
@end deffn

@deffn {Function} arithsum (@var{a}, @var{d}, @var{n})
Returns the sum of the arithmetic series from 1 to @var{n}.
@end deffn

@deffn {Function} geosum (@var{a}, @var{r}, @var{n})
Returns the sum of the geometric series from 1 to @var{n}.  If @var{n} is
infinity (@code{inf}) then a sum is finite only if the value
of @var{r} is not equal to 1.
@end deffn

@deffn {Function} gaussprob (@var{x})
Returns the Gaussian probability function
@code{%e^(-@var{x}^2/2) / sqrt(2*%pi)}.
@end deffn

@deffn {Function} gd (@var{x})
Returns the Gudermannian function
@code{2 * atan(%e^@var{x} - %pi/2)}.
@end deffn

@deffn {Function} agd (@var{x})
Returns the inverse Gudermannian function
@code{log (tan (%pi/4 + x/2)))}.
@end deffn

@deffn {Function} vers (@var{x})
Returns the versed sine @code{1 - cos (x)}.
@end deffn

@deffn {Function} covers (@var{x})
Returns the coversed sine @code{1 - sin (@var{x})}.
@end deffn

@deffn {Function} exsec (@var{x})
Returns the exsecant @code{sec (@var{x}) - 1}.
@end deffn

@deffn {Function} hav (@var{x})
Returns the haversine @code{(1 - cos(x))/2}.
@end deffn

@c REDUNDANT WITH BINOMIAL COEFFICIENT; CUT IT ??
@deffn {Function} combination (@var{n}, @var{r})
Returns the number of combinations of @var{n} objects
taken @var{r} at a time.
@end deffn

@c REDUNDANT WITH PERMUTATIONS FUNCTION IN NSET; CUT IT ??
@deffn {Function} permutation (@var{n}, @var{r})
Returns the number of permutations of @var{r} objects
selected from a set of @var{n} objects.
@end deffn

@c Adapted from ineq.usg ----------------------
@c THIS PACKAGE IS INTERESTING BUT THIS TEXT NEEDS WORK AND EXAMPLES
@defvr {Add on package} ineq
The @code{ineq} package contains simplification rules
for inequalities.

Be careful about using parentheses
around the inequalities: when the user types in @code{(A > B) + (C = 5)} the
result is @code{A + C > B + 5}, but @code{A > B + C = 5} is a syntax error,
and @code{(A > B + C) = 5} is something else entirely.

Do @code{disprule (all)} to see a complete listing
of the rule definitions.

The user will be queried if Maxima is
unable to decide the sign of a quantity multiplying an inequality.

The most common mis-feature is illustrated by:

@example
eq: a > b;
2*eq;
% - eq;
@end example

Another problem is 0 times an inequality; the default to have this
turn into 0 has been left alone. However, if you type 
@code{X*@var{some_inequality}} and Maxima asks about the sign of @code{X} and you
respond @code{zero} (or @code{z}), the program returns @code{X*@var{some_inequality}}
and not use the information that @code{X} is 0. You should do @code{ev (%, x: 0)} in such
a case, as the database will only be used for comparison purposes
in decisions, and not for the purpose of evaluating @code{X}.

The user may note a slower response when this package is loaded, as
the simplifier is forced to examine more rules than without the
package, so you might wish to remove the rules after making use of
them. Do @code{kill (rules)} to eliminate all of the rules (including any
that you might have defined); or you may be more selective by
killing only some of them; or use @code{remrule} on a specific rule.

Note that if you load this package after defining your own
rules you will clobber your rules that have the same name. The
rules in this package are:
@code{*rule1}, ..., @code{*rule8},
@code{+rule1}, ..., @code{+rule18},
and you must enclose the rulename in quotes to refer to it, as
in @code{remrule ("+", "+rule1")} to specifically remove the first rule on @code{"+"}
or @code{disprule ("*rule2")} to display the definition of the second multiplicative rule.
@end defvr

@c lrats.usg: "lratsubst" and "fullratsubst" already in doc/info/Polynomials.texi

@c Adapted from rducon.usg ----------------------
@c THIS IS AN INTERESTING FUNCTION BUT THIS TEXT NEEDS WORK AND EXAMPLES
@deffn {Function} reduce_consts (@var{expr})
Replaces constant subexpressions of @var{expr} with
constructed constant atoms, saving the definition of all these
constructed constants in the list of equations @code{const_eqns}, and
returning the modified @var{expr}.  Those parts of @var{expr} are constant which
return @code{true} when operated on by the function @code{constantp}.  Hence,
before invoking @code{reduce_consts}, one should do

@example
declare ([@var{objects to be given the constant property}], constant)$
@end example

to set up a database of the constant quantities occurring in your
expressions.

If you are planning to generate Fortran output after these symbolic
calculations, one of the first code sections should be the calculation
of all constants.  To generate this code segment, do

@example
map ('fortran, const_eqns)$
@end example

Variables besides @code{const_eqns} which affect @code{reduce_consts} are:

@code{const_prefix} (default value: @code{xx}) is the string of characters used to prefix all
symbols generated by @code{reduce_consts} to represent constant subexpressions.

@code{const_counter} (default value: 1) is the integer index used to generate unique
symbols to represent each constant subexpression found by @code{reduce_consts}.

@code{load (rducon)} loads this function.
@code{demo (rducon)} shows a demonstration of this function.
@end deffn

@c rncomb.usg: "rncombine" already in doc/info/Miscellaneous.texi

@c Adapted from scifac.usg ----------------------
@deffn {Function} gcfac (@var{expr})
@code{gcfac} is a factoring function that attempts to apply the same heuristics which
scientists apply in trying to make expressions simpler.  @code{gcfac} is limited
to monomial-type factoring.  For a sum, @code{gcfac} does the following:

@enumerate
@item
Factors over the integers.
@item
Factors out the largest powers of terms occurring as
coefficients, regardless of the complexity of the terms.
@item
Uses (1) and (2) in factoring adjacent pairs of terms.
@item
Repeatedly and recursively applies these techniques until
the expression no longer changes.
@end enumerate

Item (3) does not necessarily do an optimal job of pairwise
factoring because of the combinatorially-difficult nature of finding
which of all possible rearrangements of the pairs yields the most
compact pair-factored result.

@code{load (scifac)} loads this function.
@code{demo (scifac)} shows a demonstration of this function.
@end deffn

@c Adapted from sqdnst.usg ----------------------
@c THIS FUNCTION IS INTERESTING BUT THIS TEXT NEEDS WORK. HOW DEEPLY CAN SQRT BE NESTED ??
@deffn {Function} sqrtdenest (@var{expr})
Denests @code{sqrt} of simple, numerical, binomial surds, where possible.  E.g.

@example
(c1) sqrt(sqrt(3)/2+1)/sqrt(11*sqrt(2)-12);

              sqrt(3)
         sqrt(------- + 1)
                 2
(d1)   --------------------- 
       sqrt(11 sqrt(2) - 12)

(c2) sqrtdenest(%);

          sqrt(3)   1
          ------- + -
             2      2
(d2)     -------------
            1/4    3/4
         3 2    - 2
@end example

Sometimes it helps to apply @code{sqrtdenest} more than once, on such as
@code{(19601-13860 sqrt(2))^(7/4)}.

@code{load (sqdnst)} loads this function.
@end deffn

@c stopex.usg: "expandwrt", "expandwrt_denom", and "expandwrt_factored" already in doc/info/Simplification.texi

@node Function and variable index,  , Definitions for simplification, Top
@appendix Function and variable index
@printindex fn
@printindex vr

@bye