@c -----------------------------------------------------------------------------
@c File        : affine.de.texi
@c License     : GNU General Public License (GPL)
@c Language    : German
@c Translation : Dr. Dieter Kaiser
@c Original    : Affine.texi revision 04.02.2008
@c Date        : 14.11.2010
@c Revision    : 10.05.2011
@c 
@c This file is part of Maxima -- GPL CAS based on DOE-MACSYMA
@c -----------------------------------------------------------------------------

@menu
* Introduction to Affine::
* Functions and Variables for Affine::
@end menu

@c -----------------------------------------------------------------------------
@node Introduction to Affine, Functions and Variables for Affine, affine, affine
@section Introduction to Affine
@c -----------------------------------------------------------------------------

@code{affine} is a package to work with groups of polynomials.

@c -----------------------------------------------------------------------------
@node Functions and Variables for Affine,  , Introduction to Affine, affine
@section Functions and Variables for Affine
@c -----------------------------------------------------------------------------

@c -----------------------------------------------------------------------------
@anchor{fast_linsolve}
@deffn {Function} fast_linsolve ([@var{expr_1}, @dots{}, @var{expr_m}], [@var{x_1}, @dots{}, @var{x_n}])

Solves the simultaneous linear equations @var{expr_1}, @dots{}, @var{expr_m}
for the variables @var{x_1}, @dots{}, @var{x_n}.  Each @var{expr_i} may be an 
equation or a general expression; if given as a general expression, it is 
treated as an equation of the form @code{@var{expr_i} = 0}.

The return value is a list of equations of the form @code{[@var{x_1} = 
@var{a_1}, ..., @var{x_n} = @var{a_n}]} where @var{a_1}, @dots{}, @var{a_n} are
all free of @var{x_1}, @dots{}, @var{x_n}.

@code{fast_linsolve} is faster than @mref{linsolve} for system of equations
which are sparse.

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

@c TODO: POLYSIMP IS NOT DOCUMENTED.

@c -----------------------------------------------------------------------------
@anchor{grobner_basis}
@deffn {Function} grobner_basis ([@var{expr_1}, @dots{}, @var{expr_m}])

Returns a Groebner basis for the equations @var{expr_1}, @dots{}, @var{expr_m}.
The function @code{polysimp} can then be used to simplify other functions 
relative to the equations.

@code{polysimp(f)} yields 0 if and only if @var{f} is in the ideal generated by
@var{expr_1}, @dots{}, @var{expr_m}, that is, if and only if @var{f} is a
polynomial combination of the elements of @var{expr_1}, @dots{}, @var{expr_m}.

@code{load(affine)} loads this function.

Beispiel:

@example
(%i1) load(affine)$

(%i2) grobner_basis ([3*x^2+1, y*x]);
eliminated one
 . 0 . 0                                   2
(%o2)/R/                [- y, - 3 x  - 1]
(%i3) polysimp(y^2*x+x^3*9+2);
(%o3)/R/                    - 3 x + 2
@end example
@end deffn

@c NEEDS CLARIFICATION IN A SERIOUS WAY
@c TODO: CURRENT_SIMPLIFICATIONS AND DOT_SIMPLIFICATIONS IS NOT DOCUMENTED.

@c -----------------------------------------------------------------------------
@anchor{set_up_dot_simplifications}
@deffn  {Function} set_up_dot_simplifications (@var{eqns}, @var{check_through_degree})
@deffnx {Function} set_up_dot_simplifications (@var{eqns})

The @var{eqns} are polynomial equations in non commutative variables.  The 
value of @code{current_variables} is the list of variables used for computing 
degrees.  The equations must be homogeneous, in order for the procedure to 
terminate.

If you have checked overlapping simplifications in @code{dot_simplifications}
above the degree of @var{f}, then the following is true: 
@code{dotsimp(@var{f})} yields 0 if and only if @var{f} is in the ideal 
generated by the equations, i.e., if and only if @var{f} is a polynomial 
combination of the elements of the equations.

The degree is that returned by @mrefdot{nc_degree} This in turn is influenced 
by the weights of individual variables.

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

@c -----------------------------------------------------------------------------
@anchor{declare_weights}
@deffn {Function} declare_weights (@var{x_1}, @var{w_1}, @dots{}, @var{x_n}, @var{w_n})

Assigns weights @var{w_1}, @dots{}, @var{w_n} to @var{x_1}, @dots{}, @var{x_n}, 
respectively.  These are the weights used in computing @mrefdot{nc_degree}

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

@c -----------------------------------------------------------------------------
@anchor{nc_degree}
@deffn {Function} nc_degree (@var{p})

Returns the degree of a noncommutative polynomial @var{p}.
See @mrefdot{declare_weights}

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

@c NEEDS CLARIFICATION -- TO WHICH EQUATIONS DOES THIS DESCRIPTION REFER ??

@c -----------------------------------------------------------------------------
@anchor{dotsimp}
@deffn {Function} dotsimp (@var{f})

Returns 0 if and only if @var{f} is in the ideal generated by the equations, 
i.e., if and only if @var{f} is a polynomial combination of the elements of 
the equations.

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

@c -----------------------------------------------------------------------------
@anchor{fast_central_elements}
@deffn {Function} fast_central_elements ([@var{x_1}, @dots{}, @var{x_n}], @var{n})

If @mref{set_up_dot_simplifications} has been previously done, finds the 
central polynomials in the variables @var{x_1}, @dots{}, @var{x_n} in the given 
degree, @var{n}.

For example:

@c TODO: DIESES BEISPIEL PRUEFEN. SCHEINT NICHT ZU FUNKTIONIEREN?!

@example
set_up_dot_simplifications ([y.x + x.y], 3);
fast_central_elements ([x, y], 2);
[y.y, x.x];
@end example

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

@c THIS IS NOT AT ALL CLEAR

@c -----------------------------------------------------------------------------
@anchor{check_overlaps}
@deffn {Function} check_overlaps (@var{n}, @var{add_to_simps})

Checks the overlaps thru degree @var{n}, making sure that you have sufficient
simplification rules in each degree, for @mref{dotsimp} to work correctly.
This process can be speeded up if you know before hand what the dimension of
the space of monomials is.  If it is of finite global dimension, then
@code{hilbert} should be used.  If you don't know the monomial dimensions, do
not specify a @code{rank_function}.  An optional third argument @code{reset},
@code{false} says don't bother to query about resetting things.

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

@c -----------------------------------------------------------------------------
@anchor{mono}
@deffn {Function} mono ([@var{x_1}, @dots{}, @var{x_n}], @var{n})

Returns the list of independent monomials relative to the current dot 
simplifications of degree @var{n} in the variables @var{x_1}, @dots{},
@var{x_n}.

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

@c -----------------------------------------------------------------------------
@anchor{monomial_dimensions}
@deffn {Function} monomial_dimensions (@var{n})

Compute the Hilbert series through degree @var{n} for the current algebra.

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

@c -----------------------------------------------------------------------------
@anchor{extract_linear_equations}
@deffn {Function} extract_linear_equations ([@var{p_1}, @dots{}, @var{p_n}], [@var{m_1}, @dots{}, @var{m_n}])

Makes a list of the coefficients of the noncommutative polynomials @var{p_1},
@dots{}, @var{p_n} of the noncommutative monomials @var{m_1}, @dots{},
@var{m_n}.  The coefficients should be scalars.  Use @code{list_nc_monomials} 
to build the list of monomials.

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

@c -----------------------------------------------------------------------------
@anchor{list_nc_monomials}
@deffn  {Function} list_nc_monomials ([@var{p_1}, @dots{}, @var{p_n}])
@deffnx {Function} list_nc_monomials (@var{p})

Returns a list of the non commutative monomials occurring in a polynomial 
@var{p} or a list of polynomials @var{p_1}, @dots{}, @var{p_n}.

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

@c THIS FUNCTION DOESN'T SEEM TO BE APPROPRIATE IN USER-LEVEL DOCUMENTATION
@c PRESERVE THIS DESCRIPTION PENDING FURTHER DECISION
@c @defun pcoeff (poly monom [variables-to-exclude-from-cof (list-variables monom)])
@c 
@c This function is called from Lisp level, and uses internal poly format.
@c @example
@c 
@c CL-MAXIMA>>(setq me (st-rat #$x^2*u+y+1$))
@c (#:Y 1 1 0 (#:X 2 (#:U 1 1) 0 1))
@c 
@c CL-MAXIMA>>(pcoeff me (st-rat #$x^2$))
@c (#:U 1 1)
@c @end example
@c @noindent
@c 
@c Rule: if a variable appears in monom it must be to the exact power,
@c and if it is in variables to exclude it may not appear unless it was
@c in monom to the exact power.  (pcoeff pol 1 ..) will exclude variables
@c like substituting them to be zero.
@c 
@c @end defun

@c THIS FUNCTION DOESN'T SEEM TO BE APPROPRIATE IN USER-LEVEL DOCUMENTATION
@c PRESERVE THIS DESCRIPTION PENDING FURTHER DECISION
@c @defun new-disrep (poly)
@c 
@c From Lisp this returns the general Maxima format for an arg which is
@c in st-rat form:
@c 
@c @example
@c (displa(new-disrep (setq me (st-rat #$x^2*u+y+1$))))
@c 
@c        2
@c y + u x  + 1
@c @end example
@c 
@c @end defun

@c -----------------------------------------------------------------------------
@anchor{all_dotsimp_denoms}
@defvr {Option variable} all_dotsimp_denoms
Default value: @code{false}

When @code{all_dotsimp_denoms} is a list, the denominators encountered by
@mref{dotsimp} are appended to the list.  @code{all_dotsimp_denoms} may be
initialized to an empty list @code{[]} before calling @code{dotsimp}.

By default, denominators are not collected by @code{dotsimp}.
@end defvr

@c --- End of file affine.de.texi ----------------------------------------------

