@c end concepts Simplification
@menu
* Functions and Variables for Simplification::  
@end menu

@node Functions and Variables for Simplification,  , Simplification, Simplification
@section Functions and Variables for Simplification

@c After studying src/compar.lisp, it appears that askexp would
@c work as advertised, except that it doesn't appear to be possible
@c to open a break prompt with ^A or any other character.
@c What should we do about askexp ???
@defvr {System variable} askexp
When @code{asksign} is called,
@code{askexp} is the expression @code{asksign} is testing.

At one time, it was possible for a user to inspect @code{askexp}
by entering a Maxima break with control-A.

@opencatbox
@category{Declarations and inferences}
@closecatbox

@end defvr

@c THERE IS PROBABLY MORE TO THE STORY THAN WHAT IS INDICATED HERE ...
@deffn {Function} askinteger (@var{expr}, integer)
@deffnx {Function} askinteger (@var{expr})
@deffnx {Function} askinteger (@var{expr}, even)
@deffnx {Function} askinteger (@var{expr}, odd)

@code{askinteger (@var{expr}, integer)} attempts to determine from the @code{assume} database
whether @var{expr} is an integer.
@code{askinteger} prompts the user if it cannot tell otherwise,
@c UMM, askinteger AND asksign DO NOT APPEAR TO HAVE ANY EFFECT ON THE assume DATABASE !!!
and attempt to install the information in the database if possible.
@code{askinteger (@var{expr})} is equivalent to @code{askinteger (@var{expr}, integer)}.

@code{askinteger (@var{expr}, even)} and @code{askinteger (@var{expr}, odd)}
likewise attempt to determine if @var{expr} is an even integer or odd integer, respectively.

@opencatbox
@category{Declarations and inferences}
@closecatbox
@end deffn

@c THERE IS PROBABLY MORE TO THE STORY THAN WHAT IS INDICATED HERE ...
@deffn {Function} asksign (@var{expr})
First attempts to determine whether the specified
expression is positive, negative, or zero.  If it cannot, it asks the
user the necessary questions to complete its deduction.  The user's
answer is recorded in the data base for the duration of the current
computation. The return value of @code{asksign} is one of @code{pos}, @code{neg},
or @code{zero}.

@opencatbox
@category{Declarations and inferences}
@closecatbox
@end deffn

@c NEEDS CLARIFICATION, EXAMPLES
@deffn {Function} demoivre (@var{expr})
@deffnx {Option variable} demoivre

The function @code{demoivre (expr)} converts one expression
without setting the global variable @code{demoivre}.

When the variable @code{demoivre} is @code{true},
complex exponentials are converted into equivalent expressions in terms of circular functions:
@code{exp (a + b*%i)} simplifies to @code{%e^a * (cos(b) + %i*sin(b))}
if @code{b} is free of @code{%i}.
@code{a} and @code{b} are not expanded.

The default value of @code{demoivre} is @code{false}.

@code{exponentialize} converts circular and hyperbolic functions to exponential form.
@code{demoivre} and @code{exponentialize} cannot
both be true at the same time.

@opencatbox
@category{Complex variables} @category{Trigonometric functions} @category{Hyperbolic functions}
@closecatbox
@end deffn

@c -----------------------------------------------------------------------------
@defvr {Option variable} distribute_over
Default value: @code{true}

@code{distribute_over} controls the mapping of functions over bags like lists, 
matrices, and equations. At this time this feature is implemented for the
trigonometric functions, the exponential integrals, and the integer 
functions like @code{mod}, @code{floor}, @code{ceiling}, @code{round}.

The mapping of functions is switched off, when setting @code{distribute_over} 
to the value @code{false}.

Examples:

The @code{sin} function maps over a list:

@c ===beg===
@c sin([x,1,1.0]);
@c ===end===
@example
(%i1) sin([x,1,1.0]);
(%o1)                 [sin(x), sin(1), .8414709848078965]
@end example

@code{mod} is a function with two arguments which maps over lists. Mapping over 
nested lists is possible too:

@c ===beg===
@c mod([x,11,2*a],10);
@c mod([[x,y,z],11,2*a],10);
@c ===end===
@example
(%i2) mod([x,11,2*a],10);
(%o2)                    [mod(x, 10), 1, 2 mod(a, 5)]
(%i3) mod([[x,y,z],11,2*a],10);
(%o3)       [[mod(x, 10), mod(y, 10), mod(z, 10)], 1, 2 mod(a, 5)]
@end example

Mapping of the @code{floor} function over a matrix and an equation:

@c ===beg===
@c floor(matrix([a,b],[c,d]));
@c floor(a=b);
@c ===end===
@example
(%i4) floor(matrix([a,b],[c,d]));
                            [ floor(a)  floor(b) ]
(%o4)                       [                    ]
                            [ floor(c)  floor(d) ]
(%i5) floor(a=b);
(%o5)                         floor(a) = floor(b)
@end example

Functions with more than one argument map over any of the arguments or all
arguments:

@c ===beg===
@c expintegral_e([1,2],[x,y]);
@c ===end===
@example
(%i6) expintegral_e([1,2],[x,y]);
(%o6) [[expintegral_e(1, x), expintegral_e(1, y)], 
       [expintegral_e(2, x), expintegral_e(2, y)]]
@end example

@opencatbox
@category{Simplification flags and variables}
@closecatbox
@end defvr

@defvr {Option variable} domain
Default value: @code{real}

When @code{domain} is set to @code{complex}, @code{sqrt (x^2)} will remain
@code{sqrt (x^2)} instead of returning @code{abs(x)}.

@c PRESERVE EDITORIAL COMMENT -- MAY HAVE SOME SIGNIFICANCE NOT YET UNDERSTOOD !!!
@c The notion of a "domain" of simplification is still in its infancy,
@c and controls little more than this at the moment.

@opencatbox
@category{Simplification flags and variables}
@closecatbox

@end defvr

@c -----------------------------------------------------------------------------
@deffn {Function} expand (@var{expr})
@deffnx {Function} expand (@var{expr}, @var{p}, @var{n})
Expand expression @var{expr}.
Products of sums and exponentiated sums are
multiplied out, numerators of rational expressions which are sums are
split into their respective terms, and multiplication (commutative
and non-commutative) are distributed over addition at all levels of
@var{expr}.

For polynomials one should usually use @code{ratexpand} which uses a
more efficient algorithm.

@code{maxnegex} and @code{maxposex} control the maximum negative and
positive exponents, respectively, which will expand.

@code{expand (@var{expr}, @var{p}, @var{n})} expands @var{expr}, 
using @var{p} for @code{maxposex} and @var{n} for @code{maxnegex}.
This is useful in order to expand part but not all of an expression.

@code{expon} - the exponent of the largest negative power which is
automatically expanded (independent of calls to @code{expand}).  For example
if @code{expon} is 4 then @code{(x+1)^(-5)} will not be automatically expanded.

@code{expop} - the highest positive exponent which is automatically
expanded.  Thus @code{(x+1)^3}, when typed, will be automatically expanded
only if @code{expop} is greater than or equal to 3.  If it is desired to have
@code{(x+1)^n} expanded where @code{n} is greater than @code{expop} then executing
@code{expand ((x+1)^n)} will work only if @code{maxposex} is not less than @code{n}.

@code{expand(expr, 0, 0)} causes a resimplification of @code{expr}. @code{expr}
is not reevaluated. In distinction from @code{ev(expr, noeval)} a special 
representation (e. g. a CRE form) is removed. See also @code{ev}.

The @code{expand} flag used with @code{ev} causes expansion.

The file @file{simplification/facexp.mac}
@c I should really use a macro which expands to something like
@c @uref{file://...,,simplification/facexp.mac}.  But texi2html
@c currently supports @uref only with one argument.
@c Worse, the `file:' scheme is OS and browser dependent.
contains several related functions (in particular @code{facsum}, @code{factorfacsum}
and @code{collectterms}, which are autoloaded) and variables (@code{nextlayerfactor}
and @code{facsum_combine}) that provide the user with the ability to structure
expressions by controlled expansion.
@c MERGE share/simplification/facexp.usg INTO THIS FILE OR CREATE NEW FILE facexp.texi
Brief function descriptions are available in @file{simplification/facexp.usg}.
A demo is available by doing @code{demo("facexp")}.

Examples:
@c ===beg===
@c expr:(x+1)^2*(y+1)^3;
@c expand(expr);
@c expand(expr,2);
@c expr:(x+1)^-2*(y+1)^3;
@c expand(expr);
@c expand(expr,2,2);
@c ===end===
@example
(%i1) expr:(x+1)^2*(y+1)^3;
                                      2        3
(%o1)                          (x + 1)  (y + 1)
(%i2) expand(expr);
       2  3        3    3      2  2        2      2      2
(%o2) x  y  + 2 x y  + y  + 3 x  y  + 6 x y  + 3 y  + 3 x  y
                                                 2
                                + 6 x y + 3 y + x  + 2 x + 1

(%i3) expand(expr,2);
                      2        3              3          3
(%o3)                x  (y + 1)  + 2 x (y + 1)  + (y + 1)

(%i4) expr:(x+1)^-2*(y+1)^3;
                                          3
                                   (y + 1)
(%o4)                              --------
                                          2
                                   (x + 1)
(%i5) expand(expr);
                 3               2
                y             3 y            3 y             1
(%o5)      ------------ + ------------ + ------------ + ------------
            2              2              2              2
           x  + 2 x + 1   x  + 2 x + 1   x  + 2 x + 1   x  + 2 x + 1

(%i6) expand(expr,2,2);
                                          3
                                   (y + 1)
(%o6)                            ------------
                                  2
                                 x  + 2 x + 1
@end example

Resimplify an expression without expansion:

@c ===beg===
@c expr:(1+x)^2*sin(x);
@c exponentialize:true;
@c expand(expr,0,0);
@c ===end===
@example
(%i7) expr:(1+x)^2*sin(x);
                                       2
(%o7)                           (x + 1)  sin(x)
(%i8) exponentialize:true;
(%o8)                                true
(%i9) expand(expr,0,0);
                                   2    %i x     - %i x
                         %i (x + 1)  (%e     - %e      )
(%o9)                  - -------------------------------
                                        2
@end example

@opencatbox
@category{Expressions}
@closecatbox
@end deffn

@c NEEDS EXAMPLES
@deffn {Function} expandwrt (@var{expr}, @var{x_1}, ..., @var{x_n})
Expands expression @code{expr} with respect to the 
variables @var{x_1}, ..., @var{x_n}.
All products involving the variables appear explicitly.  The form returned
will be free of products of sums of expressions that are not free of
the variables.   @var{x_1}, ..., @var{x_n}
may be variables, operators, or expressions.

By default, denominators are not expanded, but this can be controlled by
means of the switch @code{expandwrt_denom}.

This function is autoloaded from
@file{simplification/stopex.mac}.

@opencatbox
@category{Expressions}
@closecatbox
@end deffn


@defvr {Option variable} expandwrt_denom
Default value: @code{false}

@code{expandwrt_denom} controls the treatment of rational
expressions by @code{expandwrt}.  If @code{true}, then both the numerator and
denominator of the expression will be expanded according to the
arguments of @code{expandwrt}, but if @code{expandwrt_denom} is @code{false}, then only the
numerator will be expanded in that way.

@opencatbox
@category{Expressions}
@closecatbox

@end defvr

@c NEEDS A STAND-ALONE DESCRIPTION (NOT "IS SIMILAR TO")
@c NEEDS EXAMPLES
@deffn {Function} expandwrt_factored (@var{expr}, @var{x_1}, ..., @var{x_n})
is similar to @code{expandwrt}, but treats expressions that are products somewhat differently.
@code{expandwrt_factored} expands only on those factors of @code{expr}
that contain the variables @var{x_1}, ..., @var{x_n}.

@c NOT SURE WHY WE SHOULD MENTION THIS HERE
This function is autoloaded from @file{simplification/stopex.mac}.

@opencatbox
@category{Expressions}
@closecatbox
@end deffn


@defvr {Option variable} expon
Default value: 0

@code{expon} is the exponent of the largest negative power which
is automatically expanded (independent of calls to @code{expand}).  For
example, if @code{expon} is 4 then @code{(x+1)^(-5)} will not be automatically
expanded.

@opencatbox
@category{Expressions}
@closecatbox

@end defvr


@deffn {Function} exponentialize (@var{expr})
@deffnx {Option variable} exponentialize

The function @code{exponentialize (expr)} converts 
circular and hyperbolic functions in @var{expr} to exponentials,
without setting the global variable @code{exponentialize}.

When the variable @code{exponentialize} is @code{true},
all circular and hyperbolic functions are converted to exponential form.
The default value is @code{false}.

@code{demoivre} converts complex exponentials into circular functions.
@code{exponentialize} and @code{demoivre} cannot
both be true at the same time.

@opencatbox
@category{Complex variables} @category{Trigonometric functions} @category{Hyperbolic functions}
@closecatbox
@end deffn

@c NEEDS CLARIFICATION
@c NEEDS EXAMPLES
@defvr {Option variable} expop
Default value: 0

@code{expop} is the highest positive exponent which is
automatically expanded.  Thus @code{(x + 1)^3}, when typed, will be
automatically expanded only if @code{expop} is greater than or equal to 3.
If it is desired to have @code{(x + 1)^n} expanded where @code{n} is greater than
@code{expop} then executing @code{expand ((x + 1)^n)} will work only if @code{maxposex} is
not less than n.

@opencatbox
@category{Expressions}
@closecatbox

@end defvr

@c NEEDS EXAMPLES
@defvr {Option variable} factlim
Default value: -1

@code{factlim} specifies the highest factorial which is
automatically expanded.  If it is -1 then all integers are expanded.

@opencatbox
@category{Gamma and factorial functions}
@closecatbox

@end defvr

@c NEEDS CLARIFICATION, EXAMPLES
@deffn {Function} intosum (@var{expr})
Moves multiplicative factors outside a summation to inside.
If the index is used in the
outside expression, then the function tries to find a reasonable
index, the same as it does for @code{sumcontract}.  This is essentially the
reverse idea of the @code{outative} property of summations, but note that it
does not remove this property, it only bypasses it.

@c WHAT ARE THESE CASES ??
In some cases,
a @code{scanmap (multthru, @var{expr})} may be necessary before the @code{intosum}.

@opencatbox
@category{Expressions}
@closecatbox
@end deffn

@c NEEDS CLARIFICATION, EXAMPLES
@defvr {Declaration} lassociative
@code{declare (g, lassociative)} tells the
Maxima simplifier that @code{g} is left-associative.  E.g., @code{g (g (a, b), g (c, d))} will
simplify to @code{g (g (g (a, b), c), d)}.

@opencatbox
@category{Declarations and inferences} @category{Operators} @category{Simplification}
@closecatbox
@end defvr

@c NEEDS CLARIFICATION, EXAMPLES
@c WHAT'S UP WITH THE QUOTE MARKS ??
@defvr {Declaration} linear
One of Maxima's operator properties.  For univariate @code{f} so
declared, "expansion" @code{f(x + y)} yields @code{f(x) + f(y)},
@code{f(a*x)} yields @code{a*f(x)} takes
place where @code{a} is a "constant".  For functions of two or more arguments,
"linearity" is defined to be as in the case of @code{sum} or @code{integrate},
i.e., @code{f (a*x + b, x)} yields @code{a*f(x,x) + b*f(1,x)}
for @code{a} and @code{b} free of @code{x}.

@code{linear} is equivalent to @code{additive} and @code{outative}.
See also @code{opproperties}.

@opencatbox
@category{Declarations and inferences} @category{Operators} @category{Simplification}
@closecatbox
@end defvr

@c NEEDS CLARIFICATION, EXAMPLES
@defvr {Declaration} mainvar
You may declare variables to be @code{mainvar}.  The ordering
scale for atoms is essentially: numbers < constants (e.g., @code{%e}, @code{%pi}) <
scalars < other variables < mainvars.  E.g., compare @code{expand ((X+Y)^4)}
with @code{(declare (x, mainvar), expand ((x+y)^4))}.  (Note: Care should be
taken if you elect to use the above feature.  E.g., if you subtract an
expression in which @code{x} is a @code{mainvar} from one in which @code{x} isn't a
@code{mainvar}, resimplification e.g. with @code{ev (expr, simp)} may be
necessary if cancellation is to occur.  Also, if you save an
expression in which @code{x} is a @code{mainvar}, you probably should also save @code{x}.)

@opencatbox
@category{Declarations and inferences} @category{Expressions}
@closecatbox
@end defvr

@c NEEDS EXAMPLES
@defvr {Option variable} maxapplydepth
Default value: 10000

@code{maxapplydepth} is the maximum depth to which @code{apply1}
and @code{apply2} will delve.

@opencatbox
@category{Function application}
@closecatbox

@end defvr

@c NEEDS EXAMPLES
@defvr {Option variable} maxapplyheight
Default value: 10000

@code{maxapplyheight} is the maximum height to which @code{applyb1}
will reach before giving up.

@opencatbox
@category{Function application}
@closecatbox

@end defvr

@c NEEDS EXAMPLES
@defvr {Option variable} maxnegex
Default value: 1000

@code{maxnegex} is the largest negative exponent which will
be expanded by the @code{expand} command (see also @code{maxposex}).

@opencatbox
@category{Expressions}
@closecatbox

@end defvr

@c NEEDS EXAMPLES
@defvr {Option variable} maxposex
Default value: 1000

@code{maxposex} is the largest exponent which will be
expanded with the @code{expand} command (see also @code{maxnegex}).

@opencatbox
@category{Expressions}
@closecatbox

@end defvr

@c NEEDS EXAMPLES
@defvr {Declaration} multiplicative
@code{declare (f, multiplicative)} tells the Maxima simplifier that @code{f} is multiplicative.

@enumerate
@item
If @code{f} is univariate, whenever the simplifier encounters @code{f} applied
to a product, @code{f} distributes over that product.  E.g., @code{f(x*y)}
simplifies to @code{f(x)*f(y)}.
@item
If @code{f} is a function of 2 or more arguments, multiplicativity is
defined as multiplicativity in the first argument to @code{f}, e.g.,
@code{f (g(x) * h(x), x)} simplifies to @code{f (g(x) ,x) * f (h(x), x)}.
@end enumerate

This simplification does not occur when @code{f} is applied to expressions of
the form @code{product (x[i], i, m, n)}.

@opencatbox
@category{Declarations and inferences} @category{Expressions} @category{Simplification}
@closecatbox
@end defvr

@c NEEDS CLARIFICATION, EXAMPLES
@defvr {Option variable} negdistrib
Default value: @code{true}

When @code{negdistrib} is @code{true}, -1 distributes
over an expression.  E.g., @code{-(x + y)} becomes @code{- y - x}.  Setting it to @code{false}
will allow @code{- (x + y)} to be displayed like that.  This is sometimes useful
but be very careful: like the @code{simp} flag, this is one flag you do not
want to set to @code{false} as a matter of course or necessarily for other
than local use in your Maxima.

@opencatbox
@category{Simplification flags and variables}
@closecatbox

@end defvr

@c NEEDS CLARIFICATION, EXAMPLES
@defvr {Option variable} negsumdispflag
Default value: @code{true}

When @code{negsumdispflag} is @code{true}, @code{x - y} displays as @code{x - y}
instead of as @code{- y + x}.  Setting it to @code{false} causes the special check in
display for the difference of two expressions to not be done.  One
application is that thus @code{a + %i*b} and @code{a - %i*b} may both be displayed the
same way.

@opencatbox
@category{Display flags and variables}
@closecatbox

@end defvr

@c NEEDS CLARIFICATION, EXAMPLES
@c NEED TO MENTION THIS IS AN evflag
@defvr {Special symbol} noeval
@code{noeval} suppresses the evaluation phase of @code{ev}.  This is useful in
conjunction with other switches and in causing expressions      
to be resimplified without being reevaluated.

@opencatbox
@category{Evaluation flags}
@closecatbox
@end defvr

@c NEEDS CLARIFICATION, EXAMPLES
@defvr {Declaration} noun
@code{noun} is one of the options of the @code{declare} command.  It makes a
function so declared a "noun", meaning that it won't be evaluated
automatically.

@opencatbox
@category{Nouns and verbs}
@closecatbox
@end defvr

@c NEEDS CLARIFICATION, EXAMPLES
@defvr {Option variable} noundisp
Default value: @code{false}

When @code{noundisp} is @code{true}, nouns display with
a single quote.  This switch is always @code{true} when displaying function
definitions.

@opencatbox
@category{Display flags and variables} @category{Nouns and verbs}
@closecatbox

@end defvr

@c NEEDS CLARIFICATION, EXAMPLES
@defvr {Special symbol} nouns
@code{nouns} is an @code{evflag}. When used as an option to the @code{ev} command,
@code{nouns} converts all
"noun" forms occurring in the expression being @code{ev}'d to "verbs", i.e.,
evaluates them.  See also @code{noun}, @code{nounify}, @code{verb}, and @code{verbify}.

@opencatbox
@category{Evaluation flags} @category{Nouns and verbs}
@closecatbox
@end defvr

@c NEEDS CLARIFICATION, EXAMPLES
@c WHAT ARE THE FUNCTIONS WHICH ARE EVALUATED IN FLOATING POINT ??
@c WHAT IS A "NUMERVAL" ?? (SOMETHING DIFFERENT FROM A NUMERIC VALUE ??)
@c NEED TO MENTION THIS IS AN evflag

@c -----------------------------------------------------------------------------
@defvr {Option variable} numer
@code{numer} causes some mathematical functions (including exponentiation)
with numerical arguments to be evaluated in floating point. It causes
variables in @code{expr} which have been given numerals to be replaced by
their values.  It also sets the @code{float} switch on.

See also @code{%enumer}.

Examples:

@c ===beg===
@c [sqrt(2), sin(1), 1/(1+sqrt(3))];
@c [sqrt(2), sin(1), 1/(1+sqrt(3))],numer;
@c ===end===
@example
(%i1) [sqrt(2), sin(1), 1/(1+sqrt(3))];
                                               1
(%o1)                   [sqrt(2), sin(1), -----------]
                                          sqrt(3) + 1
(%i2) [sqrt(2), sin(1), 1/(1+sqrt(3))],numer;
(%o2)      [1.414213562373095, .8414709848078965, .3660254037844387]
@end example

@opencatbox
@category{Numerical evaluation} @category{Evaluation flags}
@closecatbox
@end defvr


@c NEEDS CLARIFICATION, EXAMPLES
@c HOW TO FIND ALL VARIABLES WHICH HAVE NUMERVALS ??
@deffn {Function} numerval (@var{x_1}, @var{expr_1}, ..., @var{var_n}, @var{expr_n})
Declares the variables @code{x_1}, ..., @var{x_n} to have
numeric values equal to @code{expr_1}, ..., @code{expr_n}.
The numeric value is evaluated and substituted for the variable
in any expressions in which the variable occurs if the @code{numer} flag is
@code{true}. See also @code{ev}.

The expressions @code{expr_1}, ..., @code{expr_n} can be any expressions,
not necessarily numeric.

@opencatbox
@category{Declarations and inferences} @category{Numerical evaluation}
@closecatbox

@end deffn


@defvr {System variable} opproperties

@code{opproperties} is the list of the special operator properties recognized by
the Maxima simplifier:
@code{linear}, @code{additive}, @code{multiplicative}, @code{outative}, @code{evenfun},
@code{oddfun}, @code{commutative}, @code{symmetric}, @code{antisymmetric}, @code{nary}, 
@code{lassociative}, @code{rassociative}.

@opencatbox
@category{Global variables} @category{Operators}
@closecatbox

@end defvr


@c NEEDS CLARIFICATION, EXAMPLES
@defvr {Option variable} opsubst
Default value: @code{true}

When @code{opsubst} is @code{false}, @code{subst} does not attempt to
substitute into the operator of an expression.  E.g., 
@code{(opsubst: false, subst (x^2, r, r+r[0]))} will work.

@opencatbox
@category{Expressions}
@closecatbox

@end defvr

@c NEEDS EXAMPLES
@defvr {Declaration} outative
@code{declare (f, outative)} tells the Maxima simplifier that constant factors
in the argument of @code{f} can be pulled out.

@enumerate
@item
If @code{f} is univariate, whenever the simplifier encounters @code{f} applied
to a product, that product will be partitioned into factors that are
constant and factors that are not and the constant factors will be
pulled out.  E.g., @code{f(a*x)} will simplify to @code{a*f(x)} where @code{a} is a
constant.  Non-atomic constant factors will not be pulled out.
@item
If @code{f} is a function of 2 or more arguments, outativity is defined
as in the case of @code{sum} or @code{integrate}, i.e., @code{f (a*g(x), x)} will simplify
to @code{a * f(g(x), x)} for @code{a} free of @code{x}.
@end enumerate

@code{sum}, @code{integrate}, and @code{limit} are all @code{outative}.

@opencatbox
@category{Declarations and inferences} @category{Operators}
@closecatbox
@end defvr

@c NEEDS EXAMPLES
@defvr {Declaration} posfun
@code{declare (f, posfun)} declares @code{f} to be a positive function.
@code{is (f(x) > 0)} yields @code{true}.

@opencatbox
@category{Declarations and inferences} @category{Operators}
@closecatbox
@end defvr

@c -----------------------------------------------------------------------------
@defvr {Special symbol} pred
As an argument in a call to @code{ev (@var{expr})}, @code{pred} causes 
predicates (expressions which evaluate to @code{true} or @code{false}) to be 
evaluated. See @code{ev}.

Example:

@c ===beg===
@c 1<2;
@c 1<2,pred;
@c ===end===
@example
(%i1) 1<2;
(%o1)                                1 < 2
(%i2) 1<2,pred;
(%o2)                                true
@end example

@opencatbox
@category{Evaluation flags}
@closecatbox
@end defvr

@c -----------------------------------------------------------------------------
@deffn {Function} radcan (@var{expr})
Simplifies @var{expr}, which can contain logs, exponentials, and radicals, by 
converting it into a form which is canonical over a large class of expressions 
and a given ordering of variables; that is, all functionally equivalent forms 
are mapped into a unique form.  For a somewhat larger class of expressions, 
@code{radcan} produces a regular form. Two equivalent expressions in this class 
do not necessarily have the same appearance, but their difference can be 
simplified by @code{radcan} to zero.

For some expressions @code{radcan} is quite time consuming.  This is the cost 
of exploring certain relationships among the components of the expression for 
simplifications based on factoring and partial-fraction expansions of exponents.  

@c %e_to_numlog NEEDS ITS OWN @defvar !!!

@c %e_to_numlog HAS NO EFFECT ON RADCAN. RADCAN ALWAYS SIMPLIFIES 
@c exp(a*log(x)) --> x^a. Commenting the following out. 11/2009
@c When @code{%e_to_numlog} is @code{true}, @code{%e^(r*log(expr))} simplifies 
@c to @code{expr^r} if @code{r} is a rational number.

@c RADEXPAND CONTROLS THE SIMPLIFICATION OF THE POWER FUNCTION, E.G.
@c (x*y)^a --> x^a*y^a AND (x^a)^b --> x^(a*b), IF RADEXPAND HAS THE VALUE 'ALL.
@c THE VALUE OF RADEXPAND HAS NO EFFECT ON RADCAN. RADCAN ALWAYS SIMPLIFIES
@c THE ABOVE EXPRESSIONS. COMMENTING THE FOLLOWING OUT. 11/2009
@c When @code{radexpand} is @code{false}, certain transformations are inhibited.
@c @code{radcan (sqrt (1-x))} remains @code{sqrt (1-x)} and is not simplified 
@c to @code{%i sqrt (x-1)}. @code{radcan (sqrt (x^2 - 2*x + 1))} remains 
@c @code{sqrt (x^2 - 2*x + 1)} and is not simplified to @code{x - 1}.

Examples:

@c ===beg===
@c radcan((log(x+x^2)-log(x))^a/log(1+x)^(a/2));
@c radcan((log(1+2*a^x+a^(2*x))/log(1+a^x)));
@c radcan((%e^x-1)/(1+%e^(x/2)));
@c ===end===
@example
(%i1) radcan((log(x+x^2)-log(x))^a/log(1+x)^(a/2));
                                           a/2
(%o1)                            log(x + 1)

(%i2) radcan((log(1+2*a^x+a^(2*x))/log(1+a^x)));
(%o2)                                  2

(%i3) radcan((%e^x-1)/(1+%e^(x/2)));
                                     x/2
(%o3)                              %e    - 1
@end example

@opencatbox
@category{Simplification functions}
@closecatbox
@end deffn

@c NEEDS CLARIFICATION, EXAMPLES
@defvr {Option variable} radexpand
Default value: @code{true}

@code{radexpand} controls some simplifications of radicals.

When @code{radexpand} is @code{all}, causes nth roots of
factors of a product which are powers of n to be pulled outside of the
radical.  E.g. if @code{radexpand} is @code{all}, @code{sqrt (16*x^2)} simplifies to @code{4*x}.

@c EXPRESS SIMPLIFICATON RULES IN GENERAL CASE, NOT SPECIAL CASE
More particularly, consider @code{sqrt (x^2)}.
@itemize @bullet
@item
If @code{radexpand} is @code{all} or @code{assume (x > 0)} has been executed, 
@code{sqrt(x^2)} simplifies to @code{x}.
@item
If @code{radexpand} is @code{true} and @code{domain} is @code{real} (its default), 
@code{sqrt(x^2)} simplifies to @code{abs(x)}.
@item
If @code{radexpand} is @code{false}, or @code{radexpand} is @code{true} and @code{domain} is @code{complex}, 
@code{sqrt(x^2)} is not simplified.
@end itemize

@c CORRECT STATEMENT HERE ???
Note that @code{domain} only matters when @code{radexpand} is @code{true}.

@opencatbox
@category{Simplification flags and variables}
@closecatbox

@end defvr


@defvr {Option variable} radsubstflag
Default value: @code{false}

@code{radsubstflag}, if @code{true}, permits @code{ratsubst} to make
substitutions such as @code{u} for @code{sqrt (x)} in @code{x}.

@opencatbox
@category{Simplification flags and variables}
@closecatbox

@end defvr

@c NEEDS CLARIFICATION, EXAMPLES
@defvr {Declaration} rassociative
@code{declare (g, rassociative)} tells the Maxima
simplifier that @code{g} is right-associative.  E.g.,
@code{g(g(a, b), g(c, d))} simplifies to @code{g(a, g(b, g(c, d)))}.

@opencatbox
@category{Declarations and inferences} @category{Operators}
@closecatbox
@end defvr

@c NEEDS CLARIFICATION, EXAMPLES
@deffn {Function} scsimp (@var{expr}, @var{rule_1}, ..., @var{rule_n})
Sequential Comparative Simplification (method due to Stoute).
@code{scsimp} attempts to simplify @var{expr}
according to the rules @var{rule_1}, ..., @var{rule_n}.
If a smaller expression is obtained, the process
repeats.  Otherwise after all simplifications are tried, it returns
the original answer.

@c MERGE EXAMPLES INTO THIS FILE
@code{example (scsimp)} displays some examples.

@opencatbox
@category{Simplification functions}
@closecatbox
@end deffn

@c -----------------------------------------------------------------------------
@defvr {Option variable} simp
Default value: @code{true}

@code{simp} enables simplification. This is the standard. @code{simp} is also 
an @code{evflag}, which is recognized by the function @code{ev}. See @code{ev}.

When @code{simp} is used as an @code{evflag} with a value @code{false}, the 
simplification is suppressed only during the evaluation phase of an expression. 
The flag can not suppress the simplification which follows the evaluation 
phase.

Examples:

The simplification is switched off globally. The expression @code{sin(1.0)} is 
not simplified to its numerical value. The @code{simp}-flag switches the 
simplification on.

@c ===beg===
@c simp:false;
@c sin(1.0);
@c sin(1.0),simp;
@c ===end===
@example
(%i1) simp:false;
(%o1)                                false
(%i2) sin(1.0);
(%o2)                              sin(1.0)
(%i3) sin(1.0),simp;
(%o3)                          .8414709848078965
@end example

The simplification is switched on again. The @code{simp}-flag cannot suppress 
the simplification completely. The output shows a simplified expression, but 
the variable @code{x} has an unsimplified expression as a value, because the 
assignment has occurred during the evaluation phase of the expression.

@c ===beg===
@c simp:true;
@c x:sin(1.0),simp:false;
@c :lisp $x
@c ===end===
@example
(%i4) simp:true;
(%o4)                                true
(%i5) x:sin(1.0),simp:false;
(%o5)                          .8414709848078965
(%i6) :lisp $X
((%SIN) 1.0)
@end example

@opencatbox
@category{Evaluation flags}
@closecatbox
@end defvr


@c NEEDS CLARIFICATION, EXAMPLES
@defvr {Option variable} simpsum
Default value: @code{false}

When @code{simpsum} is @code{true}, the result of a @code{sum} is
simplified.  This simplification may sometimes be able to produce a
closed form.  If @code{simpsum} is @code{false} or if the quoted form @code{'sum} is used, the value is a
sum noun form which is a representation of the sigma notation used in
mathematics.

@opencatbox
@category{Sums and products} @category{Simplification flags and variables}
@closecatbox

@end defvr

@c NEEDS CLARIFICATION, EXAMPLES
@deffn {Function} sumcontract (@var{expr})
Combines all sums of an addition that have
upper and lower bounds that differ by constants. The result is an
expression containing one summation for each set of such summations
added to all appropriate extra terms that had to be extracted to form
this sum.  @code{sumcontract} combines all compatible sums and uses one of
the indices from one of the sums if it can, and then try to form a
reasonable index if it cannot use any supplied.

@c WHEN IS intosum NECESSARY BEFORE sumcontract ??
It may be necessary to do an @code{intosum (@var{expr})} before the @code{sumcontract}.

@opencatbox
@category{Sums and products}
@closecatbox
@end deffn


@defvr {Option variable} sumexpand
Default value: @code{false}

When @code{sumexpand} is @code{true}, products of sums and
exponentiated sums simplify to nested sums.

See also @code{cauchysum}.

Examples:

@example
(%i1) sumexpand: true$
(%i2) sum (f (i), i, 0, m) * sum (g (j), j, 0, n);
                     m      n
                    ====   ====
                    \      \
(%o2)                >      >     f(i1) g(i2)
                    /      /
                    ====   ====
                    i1 = 0 i2 = 0
(%i3) sum (f (i), i, 0, m)^2;
                     m      m
                    ====   ====
                    \      \
(%o3)                >      >     f(i3) f(i4)
                    /      /
                    ====   ====
                    i3 = 0 i4 = 0
@end example

@opencatbox
@category{Sums and products} @category{Simplification flags and variables}
@closecatbox

@end defvr

@defvr {Option variable} sumsplitfact
Default value: @code{true}

When @code{sumsplitfact} is @code{false},
@c "IS APPLIED" -- UNDER WHAT CIRCUMSTANCES EXACTLY ??
@code{minfactorial} is applied after a @code{factcomb}.

@opencatbox
@category{Gamma and factorial functions} @category{Simplification flags and variables}
@closecatbox

@end defvr

@c NEEDS CLARIFICATION, EXAMPLES
@defvr {Declaration} symmetric
@code{declare (h, symmetric)} tells the Maxima
simplifier that @code{h} is a symmetric function.  E.g., @code{h (x, z, y)} 
simplifies to @code{h (x, y, z)}.

@code{commutative} is synonymous with @code{symmetric}.

@opencatbox
@category{Declarations and inferences} @category{Operators}
@closecatbox
@end defvr


@deffn {Function} unknown (@var{expr})
Returns @code{true} if and only if @var{expr} contains an operator or function
not recognized by the Maxima simplifier.

@opencatbox
@category{Predicate functions} @category{Simplification functions}
@closecatbox
@end deffn