doc/info/Affine.texi

   1 @c end concepts Affine
   2 @menu
   3 * Introduction to Affine::
   4 * Functions and Variables for Affine::
   5 @end menu
   6
   7 @node Introduction to Affine, Functions and Variables for Affine, Package affine, Package affine
   8 @section Introduction to Affine
   9
  10 @code{affine} is a package to work with groups of polynomials.
  11
  12 @opencatbox{Categories:}
  13 @category{Polynomials}
  14 @category{Groebner bases}
  15 @category{Share packages}
  16 @category{Package affine}
  17 @closecatbox
  18
  19
  20 @node Functions and Variables for Affine,  , Introduction to Affine, Package affine
  21 @section Functions and Variables for Affine
  22
  23 @anchor{fast_linsolve}
  24 @deffn {Function} fast_linsolve ([@var{expr_1}, @dots{}, @var{expr_m}], [@var{x_1}, @dots{}, @var{x_n}])
  25 Solves the simultaneous linear equations @var{expr_1}, @dots{}, @var{expr_m}
  26 for the variables @var{x_1}, @dots{}, @var{x_n}.
  27 Each @var{expr_i} may be an equation or a general expression;
  28 if given as a general expression, it is treated as an equation of the form @code{@var{expr_i} = 0}.
  29
  30 The return value is a list of equations of the form
  31 @code{[@var{x_1} = @var{a_1}, @dots{}, @var{x_n} = @var{a_n}]}
  32 where @var{a_1}, @dots{}, @var{a_n} are all free of @var{x_1}, @dots{}, @var{x_n}.
  33
  34 @code{fast_linsolve} is faster than @code{linsolve} for system of equations which
  35 are sparse.
  36
  37 @code{load("affine")} loads this function.
  38
  39 @opencatbox{Categories:}
  40 @category{Package affine}
  41 @closecatbox
  42 @end deffn
  43
  44 @anchor{grobner_basis}
  45 @deffn {Function} grobner_basis ([@var{expr_1}, @dots{}, @var{expr_m}])
  46 Returns a Groebner basis for the equations @var{expr_1}, @dots{}, @var{expr_m}.
  47 The function @code{polysimp} can then
  48 be used to simplify other functions relative to the equations.
  49
  50 @example
  51 grobner_basis ([3*x^2+1, y*x])$
  52
  53 polysimp (y^2*x + x^3*9 + 2) ==> -3*x + 2
  54 @end example
  55
  56 @code{polysimp(f)} yields 0 if and only if @var{f} is in the ideal generated by
  57 @var{expr_1}, @dots{}, @var{expr_m}, that is,
  58 if and only if @var{f} is a polynomial combination of the elements of
  59 @var{expr_1}, @dots{}, @var{expr_m}.
  60
  61 @code{load("affine")} loads this function.
  62
  63 @opencatbox{Categories:}
  64 @category{Package affine}
  65 @closecatbox
  66 @end deffn
  67
  68 @c NEEDS CLARIFICATION IN A SERIOUS WAY
  69 @anchor{set_up_dot_simplifications}
  70 @deffn {Function} set_up_dot_simplifications @
  71 @fname{set_up_dot_simplifications} (@var{eqns}, @var{check_through_degree}) @
  72 @fname{set_up_dot_simplifications} (@var{eqns})
  73
  74 The @var{eqns} are polynomial equations in non commutative variables.
  75 The value of @code{current_variables} is the
  76 list of variables used for computing degrees.  The equations must be
  77 homogeneous, in order for the procedure to terminate.
  78
  79 If you have checked overlapping simplifications in @code{dot_simplifications}
  80 above the degree of @var{f}, then the following is true:
  81 @code{dotsimp (@var{f})} yields 0 if and only if @var{f} is in the
  82 ideal generated by the equations, i.e.,
  83 if and only if @var{f} is a polynomial combination
  84 of the elements of the equations.
  85
  86 The degree is that returned by @code{nc_degree}.   This in turn is influenced by
  87 the weights of individual variables.
  88
  89 @code{load("affine")} loads this function.
  90
  91 @opencatbox{Categories:}
  92 @category{Package affine}
  93 @closecatbox
  94 @end deffn
  95
  96 @anchor{declare_weights}
  97 @deffn {Function} declare_weights (@var{x_1}, @var{w_1}, @dots{}, @var{x_n}, @var{w_n})
  98 Assigns weights @var{w_1}, @dots{}, @var{w_n} to @var{x_1}, @dots{}, @var{x_n}, respectively.
  99 These are the weights used in computing @code{nc_degree}.
 100
 101 @code{load("affine")} loads this function.
 102
 103 @opencatbox{Categories:}
 104 @category{Package affine}
 105 @closecatbox
 106 @end deffn
 107
 108 @anchor{nc_degree}
 109 @deffn {Function} nc_degree (@var{p})
 110 Returns the degree of a noncommutative polynomial @var{p}.  See @code{declare_weights}.
 111
 112 @code{load("affine")} loads this function.
 113
 114 @opencatbox{Categories:}
 115 @category{Package affine}
 116 @closecatbox
 117 @end deffn
 118
 119 @c NEEDS CLARIFICATION -- TO WHICH EQUATIONS DOES THIS DESCRIPTION REFER ??
 120 @anchor{dotsimp}
 121 @deffn {Function} dotsimp (@var{f})
 122 Returns 0 if and only if @var{f} is in the ideal generated by the equations, i.e.,
 123 if and only if @var{f} is a polynomial combination of the elements of the equations.
 124
 125 @code{load("affine")} loads this function.
 126
 127 @opencatbox{Categories:}
 128 @category{Package affine}
 129 @closecatbox
 130 @end deffn
 131
 132 @anchor{fast_central_elements}
 133 @deffn {Function} fast_central_elements ([@var{x_1}, @dots{}, @var{x_n}], @var{n})
 134 If @code{set_up_dot_simplifications} has been previously done, finds the central polynomials
 135 in the variables @var{x_1}, @dots{}, @var{x_n} in the given degree, @var{n}.
 136
 137 For example:
 138 @example
 139 set_up_dot_simplifications ([y.x + x.y], 3);
 140 fast_central_elements ([x, y], 2);
 141 [y.y, x.x];
 142 @end example
 143
 144 @code{load("affine")} loads this function.
 145
 146 @opencatbox{Categories:}
 147 @category{Package affine}
 148 @closecatbox
 149 @end deffn
 150
 151 @c THIS IS NOT AT ALL CLEAR
 152 @anchor{check_overlaps}
 153 @deffn {Function} check_overlaps (@var{n}, @var{add_to_simps})
 154 Checks the overlaps thru degree @var{n},
 155 making sure that you have sufficient simplification rules in each
 156 degree, for @code{dotsimp} to work correctly.  This process can be speeded
 157 up if you know before hand what the dimension of the space of monomials is.
 158 If it is of finite global dimension, then @code{hilbert} should be used.  If you
 159 don't know the monomial dimensions, do not specify a @code{rank_function}.
 160 An optional third argument @code{reset}, @code{false} says don't bother to query
 161 about resetting things.
 162
 163 @code{load("affine")} loads this function.
 164
 165 @opencatbox{Categories:}
 166 @category{Package affine}
 167 @closecatbox
 168 @end deffn
 169
 170 @anchor{mono}
 171 @deffn {Function} mono ([@var{x_1}, @dots{}, @var{x_n}], @var{n})
 172 Returns the list of independent
 173 monomials relative to the current dot simplifications of degree @var{n}
 174 in the variables @var{x_1}, @dots{}, @var{x_n}.
 175
 176 @code{load("affine")} loads this function.
 177
 178 @opencatbox{Categories:}
 179 @category{Package affine}
 180 @closecatbox
 181 @end deffn
 182
 183 @anchor{monomial_dimensions}
 184 @deffn {Function} monomial_dimensions (@var{n})
 185 Compute the Hilbert series through degree @var{n} for the current algebra.
 186
 187 @code{load("affine")} loads this function.
 188
 189 @opencatbox{Categories:}
 190 @category{Package affine}
 191 @closecatbox
 192 @end deffn
 193
 194 @anchor{extract_linear_equations}
 195 @deffn {Function} extract_linear_equations ([@var{p_1}, @dots{}, @var{p_n}], [@var{m_1}, @dots{}, @var{m_n}])
 196
 197 Makes a list of the coefficients of the noncommutative polynomials @var{p_1}, @dots{}, @var{p_n}
 198 of the noncommutative monomials @var{m_1}, @dots{}, @var{m_n}.
 199 The coefficients should be scalars.   Use @code{list_nc_monomials} to build the list of
 200 monomials.
 201
 202 @code{load("affine")} loads this function.
 203
 204 @opencatbox{Categories:}
 205 @category{Package affine}
 206 @closecatbox
 207 @end deffn
 208
 209 @anchor{list_nc_monomials}
 210 @deffn {Function} list_nc_monomials @
 211 @fname{list_nc_monomials} ([@var{p_1}, @dots{}, @var{p_n}]) @
 212 @fname{list_nc_monomials} (@var{p})
 213
 214 Returns a list of the non commutative monomials occurring in a polynomial @var{p}
 215 or a list of polynomials @var{p_1}, @dots{}, @var{p_n}.
 216
 217 @code{load("affine")} loads this function.
 218
 219 @opencatbox{Categories:}
 220 @category{Package affine}
 221 @closecatbox
 222 @end deffn
 223
 224 @c THIS FUNCTION DOESN'T SEEM TO BE APPROPRIATE IN USER-LEVEL DOCUMENTATION
 225 @c PRESERVE THIS DESCRIPTION PENDING FURTHER DECISION
 226 @c @defun pcoeff (poly monom [variables-to-exclude-from-cof (list-variables monom)])
 227 @c
 228 @c This function is called from Lisp level, and uses internal poly format.
 229 @c @example
 230 @c
 231 @c CL-MAXIMA>>(setq me (st-rat #$x^2*u+y+1$))
 232 @c (#:Y 1 1 0 (#:X 2 (#:U 1 1) 0 1))
 233 @c
 234 @c CL-MAXIMA>>(pcoeff me (st-rat #$x^2$))
 235 @c (#:U 1 1)
 236 @c @end example
 237 @c @noindent
 238 @c
 239 @c Rule: if a variable appears in monom it must be to the exact power,
 240 @c and if it is in variables to exclude it may not appear unless it was
 241 @c in monom to the exact power.  (pcoeff pol 1 ..) will exclude variables
 242 @c like substituting them to be zero.
 243 @c
 244 @c @end defun
 245
 246 @c THIS FUNCTION DOESN'T SEEM TO BE APPROPRIATE IN USER-LEVEL DOCUMENTATION
 247 @c PRESERVE THIS DESCRIPTION PENDING FURTHER DECISION
 248 @c @defun new-disrep (poly)
 249 @c
 250 @c From Lisp this returns the general Maxima format for an arg which is
 251 @c in st-rat form:
 252 @c
 253 @c @example
 254 @c (displa(new-disrep (setq me (st-rat #$x^2*u+y+1$))))
 255 @c
 256 @c        2
 257 @c y + u x  + 1
 258 @c @end example
 259 @c
 260 @c @end defun
 261
 262 @anchor{all_dotsimp_denoms}
 263 @defvr {Option variable} all_dotsimp_denoms
 264 Default value: @code{false}
 265
 266 When @code{all_dotsimp_denoms} is a list,
 267 the denominators encountered by @code{dotsimp} are appended to the list.
 268 @code{all_dotsimp_denoms} may be initialized to an empty list @code{[]}
 269 before calling @code{dotsimp}.
 270
 271 By default, denominators are not collected by @code{dotsimp}.
 272
 273 @opencatbox{Categories:}
 274 @category{Package affine}
 275 @closecatbox
 276
 277 @end defvr
 278
 279
 280