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

@node Introduction to Affine, Functions and Variables for Affine, Affine, Affine
@section Introduction to Affine

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

@opencatbox
@category{Polynomials} @category{Groebner bases} @category{Share packages} @category{Package affine}
@closecatbox


@node Functions and Variables for Affine,  , Introduction to Affine, Affine
@section Functions and Variables for Affine

@anchor{fast_linsolve}
@deffn {Function} fast_linsolve ([@var{expr_1}, ..., @var{expr_m}], [@var{x_1}, ..., @var{x_n}])
Solves the simultaneous linear equations @var{expr_1}, ..., @var{expr_m}
for the variables @var{x_1}, ..., @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}, ..., @var{a_n} are all free of @var{x_1}, ..., @var{x_n}.

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

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

@opencatbox
@category{Package affine}
@closecatbox
@end deffn

@anchor{grobner_basis}
@deffn {Function} grobner_basis ([@var{expr_1}, ..., @var{expr_m}])
Returns a Groebner basis for the equations @var{expr_1}, ..., @var{expr_m}.
The function @code{polysimp} can then
be used to simplify other functions relative to the equations.

@example
grobner_basis ([3*x^2+1, y*x])$

polysimp (y^2*x + x^3*9 + 2) ==> -3*x + 2
@end example

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

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

@opencatbox
@category{Package affine}
@closecatbox
@end deffn

@c NEEDS CLARIFICATION IN A SERIOUS WAY
@anchor{set_up_dot_simplifications}
@deffn {Function} set_up_dot_simplifications @
@fname{set_up_dot_simplifications} (@var{eqns}, @var{check_through_degree}) @
@fname{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 @code{nc_degree}.   This in turn is influenced by
the weights of individual variables.

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

@opencatbox
@category{Package affine}
@closecatbox
@end deffn

@anchor{declare_weights}
@deffn {Function} declare_weights (@var{x_1}, @var{w_1}, ..., @var{x_n}, @var{w_n})
Assigns weights @var{w_1}, ..., @var{w_n} to @var{x_1}, ..., @var{x_n}, respectively.
These are the weights used in computing @code{nc_degree}.

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

@opencatbox
@category{Package affine}
@closecatbox
@end deffn

@anchor{nc_degree}
@deffn {Function} nc_degree (@var{p})
Returns the degree of a noncommutative polynomial @var{p}.  See @code{declare_weights}.

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

@opencatbox
@category{Package affine}
@closecatbox
@end deffn

@c NEEDS CLARIFICATION -- TO WHICH EQUATIONS DOES THIS DESCRIPTION REFER ??
@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.

@opencatbox
@category{Package affine}
@closecatbox
@end deffn

@anchor{fast_central_elements}
@deffn {Function} fast_central_elements ([@var{x_1}, ..., @var{x_n}], @var{n})
If @code{set_up_dot_simplifications} has been previously done, finds the central polynomials
in the variables @var{x_1}, ..., @var{x_n} in the given degree, @var{n}.

For example:
@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.

@opencatbox
@category{Package affine}
@closecatbox
@end deffn

@c THIS IS NOT AT ALL CLEAR
@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 @code{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.

@opencatbox
@category{Package affine}
@closecatbox
@end deffn

@anchor{mono}
@deffn {Function} mono ([@var{x_1}, ..., @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}, ..., @var{x_n}.

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

@opencatbox
@category{Package affine}
@closecatbox
@end deffn

@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.

@opencatbox
@category{Package affine}
@closecatbox
@end deffn

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

Makes a list of the coefficients of the noncommutative polynomials @var{p_1}, ..., @var{p_n}
of the noncommutative monomials @var{m_1}, ..., @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.

@opencatbox
@category{Package affine}
@closecatbox
@end deffn

@anchor{list_nc_monomials}
@deffn {Function} list_nc_monomials @
@fname{list_nc_monomials} ([@var{p_1}, ..., @var{p_n}]) @
@fname{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}, ..., @var{p_n}.

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

@opencatbox
@category{Package affine}
@closecatbox
@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

@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 @code{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}.

@opencatbox
@category{Package affine}
@closecatbox

@end defvr



