File: guide.html

package info (click to toggle)
jas 2.7.200-1
links: PTS, VCS
area: main
in suites: forky, sid, trixie
size: 15,732 kB
sloc: java: 164,370; python: 14,882; ruby: 14,509; xml: 583; makefile: 545; sh: 349
file content (899 lines) | stat: -rw-r--r-- 32,864 bytes
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <link rel="stylesheet" type="text/css" href="html.css" />
    <title>JAS project users guide</title>
  </head>
  <body class="main">
    <h1>Interactive scripting guide</h1>

<p>
This document contains first information on how-to use the interactive
scripting of the JAS project.  It can be used via the Java Python
interpreter <code>jython</code>, or the Java Ruby interpreter
<code>jruby</code> or the jruby Android App <code>Ruboto-IRB</code>.
<br />
The usage of JAS as an ordinary Java library, adding
<code>jas.jar</code> to the classpath and creating and using objects
from JAS classes, is introduced in the <a href="design.html">API
guide</a>.
</p>

<p>
JAS can be started with the script "<code>jas</code>" in the JAS home
directory. By default the JRuby interactive shell ist used. For the
Jython shell use "<code>jas -py</code>". When started from a desktop,
like <a href="http://www.mathlibre.org" target="new">MathLibre</a>,
the shells will look as in the following picture. The upper right
terminal shows a Jython shell and the lower left terminal shows a JRuby
shell.
</p>

<p align="center">
<img src="../images/mathlibre-jas-py-rb_deb.png" width="90%" 
     alt="JAS in MathLibre" />
<br />&nbsp;
<br />
<b>JAS jython and jruby interface in MathLibre</b>
</p>


<h3>Getting started</h3>

<p><a name="express"></a>
As first example we will discus how to compute a Groebner base with
<code>jruby</code>. The jruby script will be placed into a file, e.g.
<a href="../examples/getstart-gb.rb"><code>getstart-gb.rb</code></a>. 
This script file is executed by calling
</p>
<pre>
  jruby getstart-gb.rb
</pre>
<p>
If you start <code>jruby</code> (or <code>jas -rb</code>) without a
file name, then an interactive shell is opened and you can type
commands and expressions as desired.
The script file first imports the desired mathematical classes from
the <code>jas.rb</code> script which does all interfacing to the Java
library.  For the Rdoc of it see <a href="jruby/index.html"
target="jruby">here</a>.
</p>
<pre>
  require "examples/jas"
</pre>
<p>
In our case we need <code>PolyRing</code> to define an appropriate polynomial ring
and later <code>Ideal</code> to define sets of polynomials and have methods to 
compute Groebner bases. 
<code>PolyRing</code> takes arguments for required definitions 
of the polynomial ring: the type of the coefficient ring, the names of 
the used variables and the desired term order.
</p>
<pre>
  r = PolyRing.new( QQ(), "B,S,T,Z,P,W", PolyRing.lex)
</pre>
<p>
The ring definition is stored in the variable <code>r</code> for later use.
The string <code>"QQ()"</code> defines the coefficient ring 
to be the rational numbers,
the polynomial ring consists of the variables <code>B, S, T, Z, P, W</code>
and the term order <code>PolyRing.lex</code> means a lexicographic term order.
For some historical reason the term order orders the variables as 
<code>B &lt; S &lt; T &lt; Z &lt; P &lt; W</code> and not the other way. 
I.e. the highest or largest variable is always on the right of the list of
variables not on the left as in some other algebra systems.
With 
</p>
<pre>
  puts "PolyRing: " + r.to_s
</pre>
<p>
you can print out the ring definition. 
<code>r.to_s</code> is the usual Ruby way of producing string representations
of objects, which in our case calls the respective Java method 
<code>toScript()</code> of the JAS object. It produces
</p>
<pre>
  PolyRing: PolyRing.new(QQ(),"B,S,T,Z,P,W",PolyRing.lex)
</pre>
<p>
i.e. the same expression as defined above. In general the string from
<code>r.to_s</code> of an JAS object can be used via cut-and-past as
new input.
Next we need to enter the generating polynomials for the ideal. 
We do this in three steps, 
first define the Ruby variables for the polynomial ring,
next define the polynomials
and then the creation of the ideal using the ring definition from before 
and the polynomial list.
</p>
<pre>
  one,B,S,T,Z,P,W = r.gens()
</pre>
Small letter variables for polynomials are defined automatically but
because of Ruby handling capital letter variables as constant they
must be defined by hand. The method <code>r.gens()</code> returns a list 
of all generators (variables and values) of the polynomial ring.
<pre>
ff = [
 45 * P + 35 * S - 165 * B - 36, 
 35 * P + 40 * Z + 25 * T - 27 * S, 
 15 * W + 25 * S * P + 30 * Z - 18 * T - 165 * B**2, 
 - 9 * W + 15 * T * P + 20 * S * Z, 
 P * W + 2 * T * Z - 11 * B**3, 
 99 * W - 11 * B * S + 3 * B**2,
 B**2 + 33/50 * B + 2673/10000
];
</pre>
<p>
The polynomial list can be generated by any means Ruby allows for 
polynomial expressions. 
In our example we use Ruby brackets <code>[ ... ]</code> for the creation of the list.
The polynomials in the list are delimited by commas, and may be enclosed in parentheses.
The syntax for polynomials is the Ruby expression syntax including
literals from the coefficient ring <code>QQ()</code>, variables and
operators <code>+, -, *, **</code> (for summation, subtraction, multiplication, 
and exponentiation).
The ideal is then defined with
</p>
<pre>
  f = r.ideal( "", ff )
</pre>
<p>
It is contained the the polynomial ring <code>r</code> by construction and
consists of the polynomials from the list <code>ff</code>, the first
parameter is the empty string.  Ideals can be printed with
</p>
<pre>
  puts "Ideal: " + f.to_s
</pre>
<p>
In this example it produces the following output.
</p>
<pre>
Ideal: SimIdeal.new(PolyRing.new(QQ(),"B,S,T,Z,P,W",PolyRing.lex),
       "",[( B**2 + 33/50 * B + 2673/10000 ), 
           ( 45 * P + 35 * S - 165 * B - 36 ), 
           ( 35 * P + 40 * Z + 25 * T - 27 * S ), 
           ( 15 * W + 25 * S * P + 30 * Z - 18 * T - 165 * B**2 ), 
           ( ( -9 ) * W + 15 * T * P + 20 * S * Z ), 
           ( 99 * W - 11 * B * S + 3 * B**2 ), 
           ( P * W + 2 * T * Z - 11 * B**3 )])
</pre>
<p>
The polynomial terms are now sorted with respect to the lexicographical 
term order. The highest term is first in a polynomial.
Also the polynomials are sorted with respect to the term order, but
with smallest polynomial first in the list.
Finaly we can go to the computation of the Groebner basis of this ideal.
</p>
<pre>
  g = f.GB()
</pre>
<p>
The ideal <code>f</code> has a method <code>GB()</code> which 
computes the Groebner base. The computed Groebner base is stored
in the variable <code>g</code> which is also an ideal.
It can be printed in the same was as the ideal <code>f</code>
</p>
<pre>
  puts "Groebner base: " + g.to_s
</pre>
<p>
The output first shows the output from calling the <code>GB()</code> method
and the the ideal basis.
</p>
<pre>
sequential(field) GB executed in 37 ms

Groebner base: SimIdeal.new(PolyRing.new(QQ(),"B,S,T,Z,P,W",PolyRing.lex),
               "",[( B**2 + 33/50 * B + 2673/10000 ), 
                   ( S - 5/2 * B - 9/200 ), 
                   ( T - 37/15 * B + 27/250 ), 
                   ( Z + 49/36 * B + 1143/2000 ), 
                   ( P - 31/18 * B - 153/200 ), 
                   ( W + 19/120 * B + 1323/20000 )])
</pre>
<p>The Groebner base was computed with the sequential algorithm or
polynomial rings over fields in 37 ms and consists of six
polynomials. The polynomials are now monic, i.e. the leading
coefficient is 1 and omitted during print out.  This concludes the
first getting started section.
</p>


<h3>Overview of Ruby and Python classes and methods in jas.rb and jas.py</h3>

<p>
The jruby and the jython interface to the JAS library constain the
following classes. The class and method names are almost identical,
except where name clashes with scripting language occur,
e.g. <code>Ideal</code> in jython, but <code>SimIdeal</code> in jruby.
The class constructors in Ruby are used with the <code>.new()</code>
method and in Python the class name is use like a function name. For
example the construction of a polynomial ring is done in Ruby by
<code>PolyRing.new(...)</code> and in Python by
<code>PolyRing(...)</code>.
For the Rdoc of them see <a href="jruby/index.html" target="jruby">here</a> and
for the Epydoc of them see <a href="jython/index.html" target="jython">here</a>.
</p>
<ul>
<li><p><code>PolyRing</code>, <code>Ideal</code>/<code>SimIdeal</code> 
    and <code>ParamIdeal</code> <br />
    define polynomial rings, ideals and ideals over rings with coefficient parameters. 
    <br />
    <code>Ideal</code> has methods for sequential, parallel and distributed 
    Groebner bases computation, for example 
    <code>GB()</code>, <code>isGB()</code>,
    <code>parGB()</code>,  <code>distGB()</code>,  
    <code>NF()</code> and  <code>intersect()</code>.
    <br />
    <code>ParamIdeal</code> has methods for comprehensive  
    Groebner bases computation, for example
    <code>CGB()</code>,  <code>CGBsystem()</code>,  <code>regularGB()</code>,  
    </p>
</li>
<li><p><code>SolvPolyRing</code> and <code>SolvableIdeal</code>/<code>SolvIdeal</code> <br />
    define solvable polynomial rings and left, right and two-sided ideals.<br />
    <code>SolvableIdeal</code> has methods for left, right and two-sided
    Groebner bases computation, e.g.
    <code>leftGB()</code>,  <code>rightGB()</code>,  <code>twosidedGB()</code>,  
    <code>intersect()</code>.
    </p>
</li>
<li><p><code>Module</code> and <code>SubModule</code> <br />
    define modules over polynomial rings and sub modules. <br />
    <code>Module</code> has a method for sequential Groebner bases computation, 
    e.g. <code>GB()</code>.  
    </p>
</li>
<li><p><code>SolvableModule</code> and <code>SolvableSubModule</code> <br />
    define modules over solvable polynomial rings and sub modules. <br />
    <code>SolvableModule</code> has methods for left, right and two-sided
    Groebner bases computation, e.g.
    <code>leftGB()</code>, <code>rightGB()</code>, <code>twosidedGB()</code>.
    </p>
</li>
</ul>

<p>
Ruby has support for rational numbers, so a literal, like
<code>2/3</code>, is recognized as rational number 2/3. Python has no
support for rational number literals and <code>2/3</code> is
recognized as interger division, resulting in the integer
<code>0</code> (zero). To allow rational numbers in JAS, the Python
tuple or list notation must be used to express rational numbers, so 
<code>(2,3)</code> is recognized as rational number 2/3.
</p>

<p>
For example in the construction of Legendre polynomials a 
rational number <code>r = 1/n</code> appears.
As tuple literal it is written <code>(1,n)</code> and 
as list literal it can be written as <code>[1,n]</code>.
</p>
<pre>
  p = (2*n-1) * x * P[n-1] - (n-1) * P[n-2];
  r = (1,n); # no rational numbers in Python, use tuple notation
  p = r * p; 
</pre>
<p>
In the same way complex rational numbers can be written as nested
tuples.  For example <code>1/n + 1/2 i</code> can be written as
<code>((1,n),(1,2))</code>. If the second list element is omited it is
asumed to be one as rational number and zero as complex number. To
avoid ambiguities use a trailing comma, as in <code>((1,2),)</code>.
<!--
In this case it can however not be written as tuple, 
since one nesting level would be removed as expression parenthesis.
If the tuples or lists contain more than 2 elements, the rest is 
silently ignored.
For example <code>1/n</code> as complex number can be written as
<code>[(1,n)]</code> (but not as <code>((1,n))</code>). 
Different nesting levels are allowed, i.e.
<code>((1,n),2)</code> or <code>(0,(1,n))</code> are legal.
</p>
<p>In case the types (nesting levels) of operands do not match, 
for example when adding a rational to a complex number 
(low level) class cast errors will be thrown.
For example in <code>(1,n) + (0,(1,n))</code> the exception 
<code>edu.jas.arith.BigComplex cannot be cast to edu.jas.arith.BigRational</code> 
will be thrown.
</p>
<p>Further examples can be found in the jython files
<a href="../examples/polynomial.py" target="jython"><code>polynomial.py</code></a>,
<a href="../examples/legendre.py" target="jython"><code>legendre.py</code></a>,
<a href="../examples/hermite.py" target="jython"><code>hermite.py</code></a> or
<a href="../examples/chebyshev.py" target="jython"><code>chebyshev.py</code></a>.
-->
</p>

<hr />

<h3>Overview of some mathematical capabilities of JAS</h3>

<p>
In this section we summarize some mathematical constructions which are
possible with JAS: real root computation, power series and
non-commutative polynomial rings.
</p>


<h4>Real roots of zero dimensional ideals</h4>

<p>Besides the computation of Gr&ouml;bner bases JAS is able to use them
to solve various other problems. In this sub-section we present the
computation of real roots of systems of (algebraic) equations. When
the system of equations has only finitely many real roots, such
systems define so called zero dimensional ideals, they can be computed
(using jython) as follows. 
</p>
<pre>
  r = PolyRing(QQ(),"x,y,z",PolyRing.lex);
  print "Ring: " + str(r);
  print;

  [one,x,y,z] = r.gens(); # is also automatic

  f1 = (x**2 - 5)*(x**2 - 3)**2;
  f2 = y**2 - 3;
  f3 = z**3 - x * y;

  F = r.ideal( list=[f1,f2,f3] );

  R = F.realRoots();
  F.realRootsPrint()
</pre>
<p>
In the above example we compute the real roots of the equations
defined by the polynomials <code>f1, f2, f3</code>. First we define
the polynomial ring and then construct the ideal <code>F</code> from
the given polynomials. The method <code>F.realRoots()</code> computes
the real roots and method <code>F.realRootsPrint()</code> prints a
decimal approximation of tuples of real roots. The output of the last
method call looks as follows.
</p>
<pre>
[-1.7320508076809346675872802734375, -1.7320508076809346675872802734375, 1.4422495705075562000274658203125]
[1.7320508076809346675872802734375, 1.7320508076809346675872802734375, 1.4422495705075562000274658203125]

[1.7320508076809346675872802734375, -1.7320508076809346675872802734375, -1.4422495705075562000274658203125]
[-1.7320508076809346675872802734375, 1.7320508076809346675872802734375, -1.4422495705075562000274658203125]

[0.50401716955821029841899871826171875, 2.236067977384664118289947509765625, -1.7320508076809346675872802734375, -1.5704178023152053356170654296875]
[-0.50401716955821029841899871826171875, -2.236067977384664118289947509765625, 1.7320508076809346675872802734375, -1.5704178023152053356170654296875]
[-3.96811878503649495542049407958984375, -2.236067977384664118289947509765625, -1.7320508076809346675872802734375, 1.5704178023152053356170654296875]
[3.96811878503649495542049407958984375, 2.236067977384664118289947509765625, 1.7320508076809346675872802734375, 1.5704178023152053356170654296875]
</pre>
<p>
The roots in the tuples <code>[-1.732..., -1.732..., 1.442...]</code> correspond to the roots in
the variables <code>[x, y, z]</code>.  The last four tuples have four
entries <code>[0.504..., 2.236..., -1.732..., -1.570...]</code>, where the first entry
stems from an internal field extension, which was needed to correctly
identify the roots of the ideal and are to be ignored. That is the
tuple <code>[2.236..., -1.732..., -1.570...]</code> without the first entry is
a real root of the ideal.  That is, the decimal approximation of the
real roots are the following 8 tuples.
</p>
<pre>
  [-1.73205..., -1.73205...,  1.44224...]
  [ 1.73205...,  1.73205...,  1.44224...]

  [ 1.73205..., -1.73205..., -1.44224...]
  [-1.73205...,  1.73205..., -1.44224...]

  [ 2.23606..., -1.73205..., -1.57041...]
  [-2.23606...,  1.73205..., -1.57041...]
  [-2.23606..., -1.73205...,  1.57041...]
  [ 2.23606...,  1.73205...,  1.57041...]
</pre>
<p>More details and further examples can be found in the jython file
<a href="../examples/0dim_real_roots.py" target="jython"><code>0dim_real_roots.py</code></a>.
</p>


<h4>Power series</h4>

<p>Univariate power series can be constructed via the
<code>SeriesRing</code> class and an multivariate power series with
the <code>MultiSeriesRing</code> class. There are short cut methods
<code>PS(coeff, name, truncate, function)</code> and 
<code>MPS(coeff, names, truncate, function)</code> to construct a 
power series with a given coefficient generator '<code>function</code>'.

In the following example (using jython) we create a new power series ring 
<code>pr</code> in the variable <code>y</code> over the rational numbers.
The creation of power series is done in the same way as 
polynomials are created. There are additional methods like 
<code>r.exp()</code> or <code>r.sin()</code> to create the 
exponential power series or the power series for the sinus function.
</p>
<pre>
  pr = SeriesRing("Q(y)");
  print "pr:", pr;

  one = pr.one();
  r1 = pr.random(4);
  r2 = pr.random(4);

  print "one:", one;
  print "r1:", r1;
  print "r2:", r2;

  r4 = r1 * r2 + one;
  e = pr.exp();
  r5 = r1 * r2 + e;

  print "e:", e;
  print "r4:", r4;
  print "r5:", r5;
</pre>
<p>Once power series are created, for example 
<code>r1, r2, e</code> above, it is possible to use 
arithmetic operators to built expressions of power series like
'<code>r1 * r2 + one</code>' or '<code>r1 * r2 + e</code>'.
</p>
<pre>
pr: PS(QQ(),"y",11)

one: 1
r1:  (13,5) - (14,5) * y**3 - y**4 + 14 * y**5 - (12,7) * y**6 - 4 * y**7 - (9,14) * y**8 + 3 * y**9 + (1,15) * y**10

r2:  - (9,16) * y + (5,6) * y**3 + (2,3) * y**5 + (5,6) * y**9 + (5,2) * y**10

e: 1 + y + (1,2) * y**2 + (1,6) * y**3 + (1,24) * y**4 + (1,120) * y**5 + (1,720) * y**6 + (1,5040) * y**7 + (1,40320) * y**8 
   + (1,362880) * y**9 + (1,3628800) * y**10

r4: 1 - (117,80) * y + (13,6) * y**3 + (63,40) * y**4 + (551,240) * y**5 - (245,24) * y**6 + (11,84) * y**7 + (241,20) * y**8 + (97,224) * y**9 + (173,16) * y**10

r5: 1 - (37,80) * y + (1,2) * y**2 + (7,3) * y**3 + (97,60) * y**4 + (553,240) * y**5 - (7349,720) * y**6 + (661,5040) * y**7 + (485857,40320) * y**8 
    + (157141,362880) * y**9 + (39236401,3628800) * y**10
</pre>
<p>
It is also possible to create power series by defining a generating function 
or by defining a fixed point with respect to a map between power series. 
</p>
<pre>
  def g(a):
      return a+a;
  ps1 = pr.create(g);

  class coeff( Coefficients ):
      def generate(self,i):
          ...
  ps6 = pr.create( clazz=coeff( pr.ring.coFac ) );

  class cosmap( PowerSeriesMap ):
      def map(self,ps):
          ...
  ps8 = pr.fixPoint( cosmap( pr.ring.coFac ) );
</pre>
<p>More details and further examples can be found in the jython file
<a href="../examples/powerseries.py" target="jython"><code>powerseries.py</code></a> and
<a href="../examples/powerseries_multi.py" target="jython"><code>powerseries_multi.py</code></a>
and their Ruby counter parts.
</p>


<h4>Solvable polynomial rings</h4>

<p>
Solvable polynomial rings are non commutative polynomial rings 
where the non commutativity is expressed by commutator relations.
Commutator relations are stored in a data structure called relation table.
In the definition of a solvable polynomial ring this relation table must be 
defined. E.g the definition for the ring of a solvable polynomial ring (in jruby) is
</p>
<pre>
  require "examples/jas"
  # WA_32 solvable polynomial example

  p = PolyRing.new(QQ(),"a,b,e1,e2,e3");
  relations = [e3, e1, e1*e3 - e1,
               e3, e2, e2*e3 - e2];

  puts "relations: = " + relations.join(", ") { |r| r.to_s };

relations: = e3, e1, ( e1 * e3 - e1 ), e3, e2, ( e2 * e3 - e2 )
</pre>
<p>
The relation table must be build from triples of (commutative) polynomials.
A triple <code>p1, p2, p3</code> is interpreted as non commutative 
multiplication relation <code>p1 .*. p2 = p3</code>. 
<code>p1</code> and <code>p2</code> must be a single term, single variable
polynomials. The term order must be choosen such that 
leadingTerm(<code>p1 p2</code>) equals leadingTerm(<code>p3</code>)
and <code>p1 &gt; p2</code> for each triple.
The polynomial <code>p3</code> is in commutative form, 
i.e. multiplication operators occuring in it are commutative.
Variables for which there are no commutator relations are assumed to 
commute with each other and with all other variables, 
e.g. the variables <code>a, b</code> in the example.
</p>
<pre>
  rp = SolvPolyRing.new(QQ(), "a,b,e1,e2,e3", PolyRing.lex, relations);
  puts "SolvPolyRing: " + rp.to_s;

  puts "gens = " + rp.gens().join(", ") { |r| r.to_s };
  one,a,b,e1,e2,e3 = rp.gens();

  f1 = e1 * e3**3 + e2**10 - a;
  f2 = e1**3 * e2**2 + e3;
  f3 = e3**3 + e3**2 - b;

  F = [ f1, f2, f3 ];
  puts "F = " + F.join(", ") { |r| r.to_s };

  I = rp.ideal( "", F );
  puts "SolvableIdeal: " + I.to_s;
</pre>
<p>
After the definition of the variables <code>e1, e2, e3</code> as non-commutative 
as elements of the ring <code>rp</code>, 
the expressions for the polynomials <code>f1, f2, f3</code> use non-cummutative multiplication 
with the <code>*</code> operator.
</p>

<p>A complete example is contained in the jRuby script 
<a href="../examples/solvablepolynomial.rb"><code>solvablepolynomial.rb</code></a>.
Running the script computes a left, right and twosided Groebner base
for the following ideal <code>I</code> generated by the polynomial list <code>F</code>.
</p>
<pre>
ring is associative
SolvPolyRing: SolvPolyRing.new(QQ(),"a,b,e1,e2,e3",PolyRing.lex,rel=[e3, e2, ( e2 * e3 - e2 ), e3, e1, ( e1 * e3 - e1 )])

gens = 1, a, b, e1, e2, e3
F = ( e1 * e3**3 + e2**10 - a ), ( e3 + e1**3 * e2**2 ), ( e3**3 + e3**2 - b )

SolvableIdeal: SolvIdeal.new(SolvPolyRing.new(QQ(),"a,b,e1,e2,e3",PolyRing.lex,
                      rel=[e3, e2,  ( e2 * e3 - e2 ), e3, e1,  ( e1 * e3 - e1 )]),
                  "",[( e3 + e1**3 * e2**2 ), ( e3**3 + e3**2 - b ), ( e1 * e3**3 + e2**10 - a )])
</pre>
<p>The left Groebner base is
</p>
<pre>
sequential(field|nocom) leftGB executed in 29 ms

seq left GB: SolvIdeal.new(SolvPolyRing.new(QQ(),"a,b,e1,e2,e3",PolyRing.lex,rel=[e3, e2,  ( e2 * e3 - e2 ), e3, e1,  ( e1 * e3 - e1 )]),
             "",[a, b, e1**3 * e2**2, e2**10, e3])
</pre>
<p>the twosided Groebner base is
</p>
<pre>
sequential(field|nocom) twosidedGB executed in 28 ms
seq twosided GB: SolvIdeal.new(SolvPolyRing.new(QQ(),"a,b,e1,e2,e3",PolyRing.lex,rel=[e3, e2,  ( e2 * e3 - e2 ), e3, e1,  ( e1 * e3 - e1 )]),
                 "",[a, b, e1, e2, e3])
</pre>
<p>and the right Groebner base is
</p>
<pre>
sequential(field|nocom) rightGB executed in 16 ms
seq right GB: SolvIdeal.new(SolvPolyRing.new(QQ(),"a,b,e1,e2,e3",PolyRing.lex,rel=[e3, e2,  ( e2 * e3 - e2 ), e3, e1,  ( e1 * e3 - e1 )]),
              "",[a, b, e1, e2**10, e3])
</pre>


<hr />

<h3>Using the internal polynomial parser</h3>

<p>
The internal polynomial parser has a simpler syntax than the Ruby or
Python expression syntax. For example the multiplication operator <code>*</code>
can be omitted and <code>^</code> can be used for exponentiation <code>**</code>.
Moreover, <code>2/3</code> will work for rational numbers also in Python.
</p>
<p>
An example using the internal polynomial parser will be discused in the following.
The jython script is be placed into a file, e.g.
<a href="../examples/getstart.py"><code>getstart.py</code></a>. 
This script file is executed by calling
</p>
<pre>
  jython getstart.py
</pre>
<p>
If you start <code>jython</code> (or <code>jas -py</code>) without a
file name, then an interactive shell is opened and you can type
commands and expressions as desired.
The script file first imports the desired mathematical classes from
the <code>jas.py</code> script which does all interfacing to the Java
library.  For the Epydoc of it see <a href="jython/index.html"
target="jython">here</a>.
</p>
<pre>
  from jas import Ring, Ideal
</pre>
<p>
In our case we need <code>Ring</code> to define an appropriate polynomial ring
and <code>Ideal</code> to define sets of polynomials and have methods to 
compute Groebner bases. 
<code>Ring</code> takes a string argument which contains required definitions 
of the polynomial ring: the type of the coefficient ring, the names of 
the used variables and the desired term order.
</p>
<pre>
  r = Ring( "Rat(B,S,T,Z,P,W) L" );
</pre>
<p>
The ring definition is stored in the variable <code>r</code> for later use.
The string <code>"Rat(B,S,T,Z,P,W) L"</code> defines the coefficient ring 
to be the rational numbers <code>Rat</code>,
the polynomial ring consists of the variables <code>B, S, T, Z, P, W</code>
and the term order <code>L</code> means a lexicographic term order.
For some historical reason the term order orders the variables as 
<code>B &lt; S &lt; T &lt; Z &lt; P &lt; W</code> and not the other way. 
I.e. the highest or largest variable is always on the right of the list of
variables not on the left as in some other algebra systems.
With 
</p>
<pre>
  print "Ring: " + str(r);
</pre>
<p>
you can print out the ring definition. 
<code>str(r)</code> is the usual Python way of producing string representations
of objects, which in our case calls the respective Java method 
<code>toString()</code> of the JAS ring object. It produces
</p>
<pre>
Ring: BigRational(B, S, T, Z, P, W) INVLEX
</pre>
<p>
i.e. the coefficients are from the jas class <code>BigRational</code>
and the term order is <code>INVLEX</code> 
(<code>INV</code> because the largest variable is on the right).
Next we need to enter the generating polynomials for the ideal. 
We do this in two steps, first define a Python string with the polynomials 
and then the creation of the ideal using the ring definition from before 
and the polynomial string.
</p>
<pre>
ps = """
( 
 ( 45 P + 35 S - 165 B - 36 ), 
 ( 35 P + 40 Z + 25 T - 27 S ), 
 ( 15 W + 25 S P + 30 Z - 18 T - 165 B**2 ), 
 ( - 9 W + 15 T P + 20 S Z ), 
 ( P W + 2 T Z - 11 B**3 ), 
 ( 99 W - 11 B S + 3 B**2 ),
 ( B**2 + 33/50 B + 2673/10000 )
) 
""";
</pre>
<p>
The polynomial string can be generated by any means Python allows for 
string manipulation. 
In our example we use Python multiline strings, which are delimited by 
triple quotes <code>""" ... """</code>.
The list of polynomials is delimited by parenthesis <code>( ... )</code>,
as well as every polynomial is delimited by parenthesis, e.g.
<code>( B**2 + 33/50 B + 2673/10000 )</code>.
The polynomials are separated by commas.
The syntax for polynomials is a sequence of monimals consisting 
of coefficients and terms (as products of powers of variables).
The terms can optionally be written with multiplication sign,  
i.e. <code>25 S P</code> can be written <code>25*S*P</code>. 
Variable names must be delimited by white space or some operator,
i.e. you can not write <code>25 SP</code> because <code>SP</code>
is not a listed variable name in the polynomial ring definition.
Coefficients may not contain white space, i.e. the <code>/</code>
separating the nominator from the denominator may not be surrounded 
by spaces, i.e. writing <code>33 / 50</code> is not allowed.
Powers of variables can be written with <code>**</code> or <code>^</code>,
i.e. the square of <code>B</code> is written as <code>B**2</code>
or <code>B^2</code>.
The ideal is the defined with
</p>
<pre>
  f = Ideal( r, ps );
</pre>
<p>
The ideal is contained the the polynomial ring <code>r</code>
and consists of the polynomials from the string <code>ps</code>.
Ideals can be printed with
</p>
<pre>
  print "Ideal: " + str(f);
</pre>
<p>
In this example it produces the following output.
</p>
<pre>
Ideal: BigRational(B, S, T, Z, P, W) INVLEX
(
( B^2 + 33/50 B + 2673/10000  ),
( 45 P + 35 S - 165 B - 36  ),
( 35 P + 40 Z + 25 T - 27 S ),
( 15 W + 25 S * P + 30 Z - 18 T - 165 B^2 ),
( -9 W + 15 T * P + 20 S * Z ),
( 99 W - 11 B * S + 3 B^2 ),
( P * W + 2 T * Z - 11 B^3 )
)
</pre>
<p>
The polynomial terms are now sorted with respect to the lexicographical 
term order. The highest term is first in a polynomial.
Also the polynomials are sorted with respect to the term order, but
with smallest polynomial first in the list.
Finaly we can go to the computation of the Groebner basis of this ideal.
</p>
<pre>
  g = f.GB();
</pre>
<p>
The ideal <code>f</code> has a method <code>GB()</code> which 
computes the Groebner base. The computed Groebner base is stored
in the variable <code>g</code> which is also an ideal.
It can be printed in the same way as the ideal <code>f</code>
</p>
<pre>
  print "Groebner base:", g;
</pre>
<p>
The output first shows the output from calling the <code>GB()</code> method
and the the ideal basis.
</p>
<pre>
sequential executed in 136 ms

Groebner base: BigRational(B, S, T, Z, P, W) INVLEX
(
( B^2 + 33/50 B + 2673/10000  ),
( S - 5/2 B - 9/200  ),
( T - 37/15 B + 27/250  ),
( Z + 49/36 B + 1143/2000  ),
( P - 31/18 B - 153/200  ),
( W + 19/120 B + 1323/20000  )
)
</pre>
<p>I.e. the Groebner base was computed in 135 ms and consists 
of six polynomials. The polynomials are now monic, 
i.e. the leading coefficient is 1 and omitted during print out.
This concludes the getting started section.
</p>


<h4>Solvable polynomial rings and the internal parser</h4>

<p>
Solvable polynomial rings are non commutative polynomial rings 
where the non commutativity is expressed by commutator relations.
Commutator relations are stored in a data structure called relation table.
In the definition of a solvable polynomial ring this relation table must be 
defined. E.g the definition for the ring of a solvable polynomial ring is
</p>
<pre>
Rat(a,b,e1,e2,e3) L
RelationTable
(
 ( e3 ), ( e1 ), ( e1 e3 - e1 ),
 ( e3 ), ( e2 ), ( e2 e3 - e2 )
)
</pre>
<p>
The relation table must be build from triples of (commutative) polynomials.
A triple <code>p1, p2, p3</code> is interpreted as non commutative 
multiplication relation <code>p1 .*. p2 = p3</code>. 
Currently <code>p1</code> and <code>p2</code> must be single term, single variable
polynomials. The term order must be choosen such that 
leadingTerm(<code>p1 p2</code>) equals leadingTerm(<code>p3</code>)
and <code>p1 &gt; p2</code> for each triple.
Polynomial <code>p3</code> must be in commutative form, 
i.e. multiplication operators occuring in it are commutative.
Variables for which there are no commutator relations are assumed to 
commute with each other and with all other variables, 
e.g. the variables <code>a, b</code> in the example.
Polynomials in the generating set of an ideal are also assumed to be 
in commutative form. If you need non-commutative multiplication 
in the polynomial expresions, please use the jython or jruby interface, 
as discussed above.
</p>

<p>A complete example is contained in the Python script 
<a href="../examples/solvable.py"><code>solvable.py</code></a>.
Running the script computes a left, right and twosided Groebner base
for the following ideal
</p>
<pre>
(
 ( e1 e3^3 + e2^10 - a ),
 ( e1^3 e2^2 + e3 ),
 ( e3^3 + e3^2 - b )
)
</pre>
<p>The left Groebner base is
</p>
<pre>
(
 ( a ), ( b ),
 ( e1^3 * e2^2 ), ( e2^10 ), ( e3 )
)
</pre>
<p>the twosided Groebner base is
</p>
<pre>
(
 ( a ), ( b ), ( e1 ), ( e2 ), ( e3 )
)
</pre>
<p>and the right Groebner base is
</p>
<pre>
(
 ( a ), ( b ), ( e1 ), ( e2^10 ), ( e3 )
)
</pre>

<p>A module example is in 
<a href="../examples/armbruster.py"><code>armbruster.py</code></a> 
and a solvable module example is in
<a href="../examples/solvablemodule.py"><code>solvablemodule.py</code></a>.
</p>


<hr />

<h3>Overview of JAS Android App</h3>

<p style="color: red">
The App has been developed for JAS version 2.5 on Android 5 and is
not working on current Android versions (since 2019).
</p>

<p>
The JAS application uses the Ruboto-IRB Android application. Ruboto
provides an jruby scripting interpreter together with an editor
application. The Ruboto App is enhanced with the JAS jruby interface
and the JAS Java classes.
</p>

<p>For the Android app the main screen with the "trinks.rb" example and its output looks as follows.
</p>
<p><a href="../images/device-2012-11-18-jas-trinks.png" ><img src="../images/device-2012-11-18-jas-trinks-thumb.png" /></a> &nbsp;
   <a href="../images/device-2012-11-18-jas-trinks-out.png" ><img src="../images/device-2012-11-18-jas-trinks-out-thumb.png" /></a> &nbsp;
   <a href="../images/device-2012-11-18-jas-trinks-out-big.png" ><img src="../images/device-2012-11-18-jas-trinks-out-big-thumb.png" /></a>
</p>

<p>
The JAS jruby interface on Android has the
same functionality as the general JAS jruby scripting interface (only
some functionality of the power series is not avaliable).
</p>


<!--
<h3>Some internals of jas.py</h3>
--> 


<!--
<li><p><code></code><code></code>
    </p>
</li>

<pre>
</pre>

<p>
</p>
<pre>
</pre>
-->

<hr />
<address><a href="mailto:kredel@at@rz.uni-mannheim.de">Heinz Kredel</a></address>
<p>
<!-- Created: Sun Feb 19 15:49:14 CET 2006 -->
<!-- hhmts start -->
Last modified: Mon Feb 28 10:39:28 CET 2022
<!-- hhmts end -->
</p>
<!--p align="right" >
$Id$
</p-->
  </body>
</html>