Debian Codegraph @

doc/guide.html

raw
1 <?xml version="1.0" encoding="iso-8859-1"?>
2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
3 "DTD/xhtml1-transitional.dtd">
4 <html xmlns="http://www.w3.org/1999/xhtml">
5 <head>
6 <link rel="stylesheet" type="text/css" href="html.css" />
7 <title>JAS project users guide</title>
8 </head>
9 <body class="main">
10 <h1>Interactive scripting guide</h1>
11
12 <p>
13 This document contains first information on how-to use the interactive
14 scripting of the JAS project. It can be used via the Java Python
15 interpreter <code>jython</code>, or the Java Ruby interpreter
16 <code>jruby</code> or the jruby Android App <code>Ruboto-IRB</code>.
17 <br />
18 The usage of JAS as an ordinary Java library, adding
19 <code>jas.jar</code> to the classpath and creating and using objects
20 from JAS classes, is introduced in the <a href="design.html">API
21 guide</a>.
22 </p>
23
24 <p>
25 JAS can be started with the script "<code>jas</code>" in the JAS home
26 directory. By default the JRuby interactive shell ist used. For the
27 Jython shell use "<code>jas -py</code>". When started from a desktop,
28 like <a href="http://www.mathlibre.org" target="new">MathLibre</a>,
29 the shells will look as in the following picture. The upper right
30 terminal shows a Jython shell and the lower left terminal shows a JRuby
31 shell.
32 </p>
33
34 <p align="center">
35 <img src="../images/mathlibre-jas-py-rb_deb.png" width="90%"
36 alt="JAS in MathLibre" />
37 <br />&nbsp;
38 <br />
39 <b>JAS jython and jruby interface in MathLibre</b>
40 </p>
41
42
43 <h3>Getting started</h3>
44
45 <p><a name="express"></a>
46 As first example we will discus how to compute a Groebner base with
47 <code>jruby</code>. The jruby script will be placed into a file, e.g.
48 <a href="../examples/getstart-gb.rb"><code>getstart-gb.rb</code></a>.
49 This script file is executed by calling
50 </p>
51 <pre>
52 jruby getstart-gb.rb
53 </pre>
54 <p>
55 If you start <code>jruby</code> (or <code>jas -rb</code>) without a
56 file name, then an interactive shell is opened and you can type
57 commands and expressions as desired.
58 The script file first imports the desired mathematical classes from
59 the <code>jas.rb</code> script which does all interfacing to the Java
60 library. For the Rdoc of it see <a href="jruby/index.html"
61 target="jruby">here</a>.
62 </p>
63 <pre>
64 require "examples/jas"
65 </pre>
66 <p>
67 In our case we need <code>PolyRing</code> to define an appropriate polynomial ring
68 and later <code>Ideal</code> to define sets of polynomials and have methods to
69 compute Groebner bases.
70 <code>PolyRing</code> takes arguments for required definitions
71 of the polynomial ring: the type of the coefficient ring, the names of
72 the used variables and the desired term order.
73 </p>
74 <pre>
75 r = PolyRing.new( QQ(), "B,S,T,Z,P,W", PolyRing.lex)
76 </pre>
77 <p>
78 The ring definition is stored in the variable <code>r</code> for later use.
79 The string <code>"QQ()"</code> defines the coefficient ring
80 to be the rational numbers,
81 the polynomial ring consists of the variables <code>B, S, T, Z, P, W</code>
82 and the term order <code>PolyRing.lex</code> means a lexicographic term order.
83 For some historical reason the term order orders the variables as
84 <code>B &lt; S &lt; T &lt; Z &lt; P &lt; W</code> and not the other way.
85 I.e. the highest or largest variable is always on the right of the list of
86 variables not on the left as in some other algebra systems.
87 With
88 </p>
89 <pre>
90 puts "PolyRing: " + r.to_s
91 </pre>
92 <p>
93 you can print out the ring definition.
94 <code>r.to_s</code> is the usual Ruby way of producing string representations
95 of objects, which in our case calls the respective Java method
96 <code>toScript()</code> of the JAS object. It produces
97 </p>
98 <pre>
99 PolyRing: PolyRing.new(QQ(),"B,S,T,Z,P,W",PolyRing.lex)
100 </pre>
101 <p>
102 i.e. the same expression as defined above. In general the string from
103 <code>r.to_s</code> of an JAS object can be used via cut-and-past as
104 new input.
105 Next we need to enter the generating polynomials for the ideal.
106 We do this in three steps,
107 first define the Ruby variables for the polynomial ring,
108 next define the polynomials
109 and then the creation of the ideal using the ring definition from before
110 and the polynomial list.
111 </p>
112 <pre>
113 one,B,S,T,Z,P,W = r.gens()
114 </pre>
115 Small letter variables for polynomials are defined automatically but
116 because of Ruby handling capital letter variables as constant they
117 must be defined by hand. The method <code>r.gens()</code> returns a list
118 of all generators (variables and values) of the polynomial ring.
119 <pre>
120 ff = [
121 45 * P + 35 * S - 165 * B - 36,
122 35 * P + 40 * Z + 25 * T - 27 * S,
123 15 * W + 25 * S * P + 30 * Z - 18 * T - 165 * B**2,
124 - 9 * W + 15 * T * P + 20 * S * Z,
125 P * W + 2 * T * Z - 11 * B**3,
126 99 * W - 11 * B * S + 3 * B**2,
127 B**2 + 33/50 * B + 2673/10000
128 ];
129 </pre>
130 <p>
131 The polynomial list can be generated by any means Ruby allows for
132 polynomial expressions.
133 In our example we use Ruby brackets <code>[ ... ]</code> for the creation of the list.
134 The polynomials in the list are delimited by commas, and may be enclosed in parentheses.
135 The syntax for polynomials is the Ruby expression syntax including
136 literals from the coefficient ring <code>QQ()</code>, variables and
137 operators <code>+, -, *, **</code> (for summation, subtraction, multiplication,
138 and exponentiation).
139 The ideal is then defined with
140 </p>
141 <pre>
142 f = r.ideal( "", ff )
143 </pre>
144 <p>
145 It is contained the the polynomial ring <code>r</code> by construction and
146 consists of the polynomials from the list <code>ff</code>, the first
147 parameter is the empty string. Ideals can be printed with
148 </p>
149 <pre>
150 puts "Ideal: " + f.to_s
151 </pre>
152 <p>
153 In this example it produces the following output.
154 </p>
155 <pre>
156 Ideal: SimIdeal.new(PolyRing.new(QQ(),"B,S,T,Z,P,W",PolyRing.lex),
157 "",[( B**2 + 33/50 * B + 2673/10000 ),
158 ( 45 * P + 35 * S - 165 * B - 36 ),
159 ( 35 * P + 40 * Z + 25 * T - 27 * S ),
160 ( 15 * W + 25 * S * P + 30 * Z - 18 * T - 165 * B**2 ),
161 ( ( -9 ) * W + 15 * T * P + 20 * S * Z ),
162 ( 99 * W - 11 * B * S + 3 * B**2 ),
163 ( P * W + 2 * T * Z - 11 * B**3 )])
164 </pre>
165 <p>
166 The polynomial terms are now sorted with respect to the lexicographical
167 term order. The highest term is first in a polynomial.
168 Also the polynomials are sorted with respect to the term order, but
169 with smallest polynomial first in the list.
170 Finaly we can go to the computation of the Groebner basis of this ideal.
171 </p>
172 <pre>
173 g = f.GB()
174 </pre>
175 <p>
176 The ideal <code>f</code> has a method <code>GB()</code> which
177 computes the Groebner base. The computed Groebner base is stored
178 in the variable <code>g</code> which is also an ideal.
179 It can be printed in the same was as the ideal <code>f</code>
180 </p>
181 <pre>
182 puts "Groebner base: " + g.to_s
183 </pre>
184 <p>
185 The output first shows the output from calling the <code>GB()</code> method
186 and the the ideal basis.
187 </p>
188 <pre>
189 sequential(field) GB executed in 37 ms
190
191 Groebner base: SimIdeal.new(PolyRing.new(QQ(),"B,S,T,Z,P,W",PolyRing.lex),
192 "",[( B**2 + 33/50 * B + 2673/10000 ),
193 ( S - 5/2 * B - 9/200 ),
194 ( T - 37/15 * B + 27/250 ),
195 ( Z + 49/36 * B + 1143/2000 ),
196 ( P - 31/18 * B - 153/200 ),
197 ( W + 19/120 * B + 1323/20000 )])
198 </pre>
199 <p>The Groebner base was computed with the sequential algorithm or
200 polynomial rings over fields in 37 ms and consists of six
201 polynomials. The polynomials are now monic, i.e. the leading
202 coefficient is 1 and omitted during print out. This concludes the
203 first getting started section.
204 </p>
205
206
207 <h3>Overview of Ruby and Python classes and methods in jas.rb and jas.py</h3>
208
209 <p>
210 The jruby and the jython interface to the JAS library constain the
211 following classes. The class and method names are almost identical,
212 except where name clashes with scripting language occur,
213 e.g. <code>Ideal</code> in jython, but <code>SimIdeal</code> in jruby.
214 The class constructors in Ruby are used with the <code>.new()</code>
215 method and in Python the class name is use like a function name. For
216 example the construction of a polynomial ring is done in Ruby by
217 <code>PolyRing.new(...)</code> and in Python by
218 <code>PolyRing(...)</code>.
219 For the Rdoc of them see <a href="jruby/index.html" target="jruby">here</a> and
220 for the Epydoc of them see <a href="jython/index.html" target="jython">here</a>.
221 </p>
222 <ul>
223 <li><p><code>PolyRing</code>, <code>Ideal</code>/<code>SimIdeal</code>
224 and <code>ParamIdeal</code> <br />
225 define polynomial rings, ideals and ideals over rings with coefficient parameters.
226 <br />
227 <code>Ideal</code> has methods for sequential, parallel and distributed
228 Groebner bases computation, for example
229 <code>GB()</code>, <code>isGB()</code>,
230 <code>parGB()</code>, <code>distGB()</code>,
231 <code>NF()</code> and <code>intersect()</code>.
232 <br />
233 <code>ParamIdeal</code> has methods for comprehensive
234 Groebner bases computation, for example
235 <code>CGB()</code>, <code>CGBsystem()</code>, <code>regularGB()</code>,
236 </p>
237 </li>
238 <li><p><code>SolvPolyRing</code> and <code>SolvableIdeal</code>/<code>SolvIdeal</code> <br />
239 define solvable polynomial rings and left, right and two-sided ideals.<br />
240 <code>SolvableIdeal</code> has methods for left, right and two-sided
241 Groebner bases computation, e.g.
242 <code>leftGB()</code>, <code>rightGB()</code>, <code>twosidedGB()</code>,
243 <code>intersect()</code>.
244 </p>
245 </li>
246 <li><p><code>Module</code> and <code>SubModule</code> <br />
247 define modules over polynomial rings and sub modules. <br />
248 <code>Module</code> has a method for sequential Groebner bases computation,
249 e.g. <code>GB()</code>.
250 </p>
251 </li>
252 <li><p><code>SolvableModule</code> and <code>SolvableSubModule</code> <br />
253 define modules over solvable polynomial rings and sub modules. <br />
254 <code>SolvableModule</code> has methods for left, right and two-sided
255 Groebner bases computation, e.g.
256 <code>leftGB()</code>, <code>rightGB()</code>, <code>twosidedGB()</code>.
257 </p>
258 </li>
259 </ul>
260
261 <p>
262 Ruby has support for rational numbers, so a literal, like
263 <code>2/3</code>, is recognized as rational number 2/3. Python has no
264 support for rational number literals and <code>2/3</code> is
265 recognized as interger division, resulting in the integer
266 <code>0</code> (zero). To allow rational numbers in JAS, the Python
267 tuple or list notation must be used to express rational numbers, so
268 <code>(2,3)</code> is recognized as rational number 2/3.
269 </p>
270
271 <p>
272 For example in the construction of Legendre polynomials a
273 rational number <code>r = 1/n</code> appears.
274 As tuple literal it is written <code>(1,n)</code> and
275 as list literal it can be written as <code>[1,n]</code>.
276 </p>
277 <pre>
278 p = (2*n-1) * x * P[n-1] - (n-1) * P[n-2];
279 r = (1,n); # no rational numbers in Python, use tuple notation
280 p = r * p;
281 </pre>
282 <p>
283 In the same way complex rational numbers can be written as nested
284 tuples. For example <code>1/n + 1/2 i</code> can be written as
285 <code>((1,n),(1,2))</code>. If the second list element is omited it is
286 asumed to be one as rational number and zero as complex number. To
287 avoid ambiguities use a trailing comma, as in <code>((1,2),)</code>.
288 <!--
289 In this case it can however not be written as tuple,
290 since one nesting level would be removed as expression parenthesis.
291 If the tuples or lists contain more than 2 elements, the rest is
292 silently ignored.
293 For example <code>1/n</code> as complex number can be written as
294 <code>[(1,n)]</code> (but not as <code>((1,n))</code>).
295 Different nesting levels are allowed, i.e.
296 <code>((1,n),2)</code> or <code>(0,(1,n))</code> are legal.
297 </p>
298 <p>In case the types (nesting levels) of operands do not match,
299 for example when adding a rational to a complex number
300 (low level) class cast errors will be thrown.
301 For example in <code>(1,n) + (0,(1,n))</code> the exception
302 <code>edu.jas.arith.BigComplex cannot be cast to edu.jas.arith.BigRational</code>
303 will be thrown.
304 </p>
305 <p>Further examples can be found in the jython files
306 <a href="../examples/polynomial.py" target="jython"><code>polynomial.py</code></a>,
307 <a href="../examples/legendre.py" target="jython"><code>legendre.py</code></a>,
308 <a href="../examples/hermite.py" target="jython"><code>hermite.py</code></a> or
309 <a href="../examples/chebyshev.py" target="jython"><code>chebyshev.py</code></a>.
310 -->
311 </p>
312
313 <hr />
314
315 <h3>Overview of some mathematical capabilities of JAS</h3>
316
317 <p>
318 In this section we summarize some mathematical constructions which are
319 possible with JAS: real root computation, power series and
320 non-commutative polynomial rings.
321 </p>
322
323
324 <h4>Real roots of zero dimensional ideals</h4>
325
326 <p>Besides the computation of Gr&ouml;bner bases JAS is able to use them
327 to solve various other problems. In this sub-section we present the
328 computation of real roots of systems of (algebraic) equations. When
329 the system of equations has only finitely many real roots, such
330 systems define so called zero dimensional ideals, they can be computed
331 (using jython) as follows.
332 </p>
333 <pre>
334 r = PolyRing(QQ(),"x,y,z",PolyRing.lex);
335 print "Ring: " + str(r);
336 print;
337
338 [one,x,y,z] = r.gens(); # is also automatic
339
340 f1 = (x**2 - 5)*(x**2 - 3)**2;
341 f2 = y**2 - 3;
342 f3 = z**3 - x * y;
343
344 F = r.ideal( list=[f1,f2,f3] );
345
346 R = F.realRoots();
347 F.realRootsPrint()
348 </pre>
349 <p>
350 In the above example we compute the real roots of the equations
351 defined by the polynomials <code>f1, f2, f3</code>. First we define
352 the polynomial ring and then construct the ideal <code>F</code> from
353 the given polynomials. The method <code>F.realRoots()</code> computes
354 the real roots and method <code>F.realRootsPrint()</code> prints a
355 decimal approximation of tuples of real roots. The output of the last
356 method call looks as follows.
357 </p>
358 <pre>
359 [-1.7320508076809346675872802734375, -1.7320508076809346675872802734375, 1.4422495705075562000274658203125]
360 [1.7320508076809346675872802734375, 1.7320508076809346675872802734375, 1.4422495705075562000274658203125]
361
362 [1.7320508076809346675872802734375, -1.7320508076809346675872802734375, -1.4422495705075562000274658203125]
363 [-1.7320508076809346675872802734375, 1.7320508076809346675872802734375, -1.4422495705075562000274658203125]
364
365 [0.50401716955821029841899871826171875, 2.236067977384664118289947509765625, -1.7320508076809346675872802734375, -1.5704178023152053356170654296875]
366 [-0.50401716955821029841899871826171875, -2.236067977384664118289947509765625, 1.7320508076809346675872802734375, -1.5704178023152053356170654296875]
367 [-3.96811878503649495542049407958984375, -2.236067977384664118289947509765625, -1.7320508076809346675872802734375, 1.5704178023152053356170654296875]
368 [3.96811878503649495542049407958984375, 2.236067977384664118289947509765625, 1.7320508076809346675872802734375, 1.5704178023152053356170654296875]
369 </pre>
370 <p>
371 The roots in the tuples <code>[-1.732..., -1.732..., 1.442...]</code> correspond to the roots in
372 the variables <code>[x, y, z]</code>. The last four tuples have four
373 entries <code>[0.504..., 2.236..., -1.732..., -1.570...]</code>, where the first entry
374 stems from an internal field extension, which was needed to correctly
375 identify the roots of the ideal and are to be ignored. That is the
376 tuple <code>[2.236..., -1.732..., -1.570...]</code> without the first entry is
377 a real root of the ideal. That is, the decimal approximation of the
378 real roots are the following 8 tuples.
379 </p>
380 <pre>
381 [-1.73205..., -1.73205..., 1.44224...]
382 [ 1.73205..., 1.73205..., 1.44224...]
383
384 [ 1.73205..., -1.73205..., -1.44224...]
385 [-1.73205..., 1.73205..., -1.44224...]
386
387 [ 2.23606..., -1.73205..., -1.57041...]
388 [-2.23606..., 1.73205..., -1.57041...]
389 [-2.23606..., -1.73205..., 1.57041...]
390 [ 2.23606..., 1.73205..., 1.57041...]
391 </pre>
392 <p>More details and further examples can be found in the jython file
393 <a href="../examples/0dim_real_roots.py" target="jython"><code>0dim_real_roots.py</code></a>.
394 </p>
395
396
397 <h4>Power series</h4>
398
399 <p>Univariate power series can be constructed via the
400 <code>SeriesRing</code> class and an multivariate power series with
401 the <code>MultiSeriesRing</code> class. There are short cut methods
402 <code>PS(coeff, name, truncate, function)</code> and
403 <code>MPS(coeff, names, truncate, function)</code> to construct a
404 power series with a given coefficient generator '<code>function</code>'.
405
406 In the following example (using jython) we create a new power series ring
407 <code>pr</code> in the variable <code>y</code> over the rational numbers.
408 The creation of power series is done in the same way as
409 polynomials are created. There are additional methods like
410 <code>r.exp()</code> or <code>r.sin()</code> to create the
411 exponential power series or the power series for the sinus function.
412 </p>
413 <pre>
414 pr = SeriesRing("Q(y)");
415 print "pr:", pr;
416
417 one = pr.one();
418 r1 = pr.random(4);
419 r2 = pr.random(4);
420
421 print "one:", one;
422 print "r1:", r1;
423 print "r2:", r2;
424
425 r4 = r1 * r2 + one;
426 e = pr.exp();
427 r5 = r1 * r2 + e;
428
429 print "e:", e;
430 print "r4:", r4;
431 print "r5:", r5;
432 </pre>
433 <p>Once power series are created, for example
434 <code>r1, r2, e</code> above, it is possible to use
435 arithmetic operators to built expressions of power series like
436 '<code>r1 * r2 + one</code>' or '<code>r1 * r2 + e</code>'.
437 </p>
438 <pre>
439 pr: PS(QQ(),"y",11)
440
441 one: 1
442 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
443
444 r2: - (9,16) * y + (5,6) * y**3 + (2,3) * y**5 + (5,6) * y**9 + (5,2) * y**10
445
446 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
447 + (1,362880) * y**9 + (1,3628800) * y**10
448
449 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
450
451 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
452 + (157141,362880) * y**9 + (39236401,3628800) * y**10
453 </pre>
454 <p>
455 It is also possible to create power series by defining a generating function
456 or by defining a fixed point with respect to a map between power series.
457 </p>
458 <pre>
459 def g(a):
460 return a+a;
461 ps1 = pr.create(g);
462
463 class coeff( Coefficients ):
464 def generate(self,i):
465 ...
466 ps6 = pr.create( clazz=coeff( pr.ring.coFac ) );
467
468 class cosmap( PowerSeriesMap ):
469 def map(self,ps):
470 ...
471 ps8 = pr.fixPoint( cosmap( pr.ring.coFac ) );
472 </pre>
473 <p>More details and further examples can be found in the jython file
474 <a href="../examples/powerseries.py" target="jython"><code>powerseries.py</code></a> and
475 <a href="../examples/powerseries_multi.py" target="jython"><code>powerseries_multi.py</code></a>
476 and their Ruby counter parts.
477 </p>
478
479
480 <h4>Solvable polynomial rings</h4>
481
482 <p>
483 Solvable polynomial rings are non commutative polynomial rings
484 where the non commutativity is expressed by commutator relations.
485 Commutator relations are stored in a data structure called relation table.
486 In the definition of a solvable polynomial ring this relation table must be
487 defined. E.g the definition for the ring of a solvable polynomial ring (in jruby) is
488 </p>
489 <pre>
490 require "examples/jas"
491 # WA_32 solvable polynomial example
492
493 p = PolyRing.new(QQ(),"a,b,e1,e2,e3");
494 relations = [e3, e1, e1*e3 - e1,
495 e3, e2, e2*e3 - e2];
496
497 puts "relations: = " + relations.join(", ") { |r| r.to_s };
498
499 relations: = e3, e1, ( e1 * e3 - e1 ), e3, e2, ( e2 * e3 - e2 )
500 </pre>
501 <p>
502 The relation table must be build from triples of (commutative) polynomials.
503 A triple <code>p1, p2, p3</code> is interpreted as non commutative
504 multiplication relation <code>p1 .*. p2 = p3</code>.
505 <code>p1</code> and <code>p2</code> must be a single term, single variable
506 polynomials. The term order must be choosen such that
507 leadingTerm(<code>p1 p2</code>) equals leadingTerm(<code>p3</code>)
508 and <code>p1 &gt; p2</code> for each triple.
509 The polynomial <code>p3</code> is in commutative form,
510 i.e. multiplication operators occuring in it are commutative.
511 Variables for which there are no commutator relations are assumed to
512 commute with each other and with all other variables,
513 e.g. the variables <code>a, b</code> in the example.
514 </p>
515 <pre>
516 rp = SolvPolyRing.new(QQ(), "a,b,e1,e2,e3", PolyRing.lex, relations);
517 puts "SolvPolyRing: " + rp.to_s;
518
519 puts "gens = " + rp.gens().join(", ") { |r| r.to_s };
520 one,a,b,e1,e2,e3 = rp.gens();
521
522 f1 = e1 * e3**3 + e2**10 - a;
523 f2 = e1**3 * e2**2 + e3;
524 f3 = e3**3 + e3**2 - b;
525
526 F = [ f1, f2, f3 ];
527 puts "F = " + F.join(", ") { |r| r.to_s };
528
529 I = rp.ideal( "", F );
530 puts "SolvableIdeal: " + I.to_s;
531 </pre>
532 <p>
533 After the definition of the variables <code>e1, e2, e3</code> as non-commutative
534 as elements of the ring <code>rp</code>,
535 the expressions for the polynomials <code>f1, f2, f3</code> use non-cummutative multiplication
536 with the <code>*</code> operator.
537 </p>
538
539 <p>A complete example is contained in the jRuby script
540 <a href="../examples/solvablepolynomial.rb"><code>solvablepolynomial.rb</code></a>.
541 Running the script computes a left, right and twosided Groebner base
542 for the following ideal <code>I</code> generated by the polynomial list <code>F</code>.
543 </p>
544 <pre>
545 ring is associative
546 SolvPolyRing: SolvPolyRing.new(QQ(),"a,b,e1,e2,e3",PolyRing.lex,rel=[e3, e2, ( e2 * e3 - e2 ), e3, e1, ( e1 * e3 - e1 )])
547
548 gens = 1, a, b, e1, e2, e3
549 F = ( e1 * e3**3 + e2**10 - a ), ( e3 + e1**3 * e2**2 ), ( e3**3 + e3**2 - b )
550
551 SolvableIdeal: SolvIdeal.new(SolvPolyRing.new(QQ(),"a,b,e1,e2,e3",PolyRing.lex,
552 rel=[e3, e2, ( e2 * e3 - e2 ), e3, e1, ( e1 * e3 - e1 )]),
553 "",[( e3 + e1**3 * e2**2 ), ( e3**3 + e3**2 - b ), ( e1 * e3**3 + e2**10 - a )])
554 </pre>
555 <p>The left Groebner base is
556 </p>
557 <pre>
558 sequential(field|nocom) leftGB executed in 29 ms
559
560 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 )]),
561 "",[a, b, e1**3 * e2**2, e2**10, e3])
562 </pre>
563 <p>the twosided Groebner base is
564 </p>
565 <pre>
566 sequential(field|nocom) twosidedGB executed in 28 ms
567 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 )]),
568 "",[a, b, e1, e2, e3])
569 </pre>
570 <p>and the right Groebner base is
571 </p>
572 <pre>
573 sequential(field|nocom) rightGB executed in 16 ms
574 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 )]),
575 "",[a, b, e1, e2**10, e3])
576 </pre>
577
578
579 <hr />
580
581 <h3>Using the internal polynomial parser</h3>
582
583 <p>
584 The internal polynomial parser has a simpler syntax than the Ruby or
585 Python expression syntax. For example the multiplication operator <code>*</code>
586 can be omitted and <code>^</code> can be used for exponentiation <code>**</code>.
587 Moreover, <code>2/3</code> will work for rational numbers also in Python.
588 </p>
589 <p>
590 An example using the internal polynomial parser will be discused in the following.
591 The jython script is be placed into a file, e.g.
592 <a href="../examples/getstart.py"><code>getstart.py</code></a>.
593 This script file is executed by calling
594 </p>
595 <pre>
596 jython getstart.py
597 </pre>
598 <p>
599 If you start <code>jython</code> (or <code>jas -py</code>) without a
600 file name, then an interactive shell is opened and you can type
601 commands and expressions as desired.
602 The script file first imports the desired mathematical classes from
603 the <code>jas.py</code> script which does all interfacing to the Java
604 library. For the Epydoc of it see <a href="jython/index.html"
605 target="jython">here</a>.
606 </p>
607 <pre>
608 from jas import Ring, Ideal
609 </pre>
610 <p>
611 In our case we need <code>Ring</code> to define an appropriate polynomial ring
612 and <code>Ideal</code> to define sets of polynomials and have methods to
613 compute Groebner bases.
614 <code>Ring</code> takes a string argument which contains required definitions
615 of the polynomial ring: the type of the coefficient ring, the names of
616 the used variables and the desired term order.
617 </p>
618 <pre>
619 r = Ring( "Rat(B,S,T,Z,P,W) L" );
620 </pre>
621 <p>
622 The ring definition is stored in the variable <code>r</code> for later use.
623 The string <code>"Rat(B,S,T,Z,P,W) L"</code> defines the coefficient ring
624 to be the rational numbers <code>Rat</code>,
625 the polynomial ring consists of the variables <code>B, S, T, Z, P, W</code>
626 and the term order <code>L</code> means a lexicographic term order.
627 For some historical reason the term order orders the variables as
628 <code>B &lt; S &lt; T &lt; Z &lt; P &lt; W</code> and not the other way.
629 I.e. the highest or largest variable is always on the right of the list of
630 variables not on the left as in some other algebra systems.
631 With
632 </p>
633 <pre>
634 print "Ring: " + str(r);
635 </pre>
636 <p>
637 you can print out the ring definition.
638 <code>str(r)</code> is the usual Python way of producing string representations
639 of objects, which in our case calls the respective Java method
640 <code>toString()</code> of the JAS ring object. It produces
641 </p>
642 <pre>
643 Ring: BigRational(B, S, T, Z, P, W) INVLEX
644 </pre>
645 <p>
646 i.e. the coefficients are from the jas class <code>BigRational</code>
647 and the term order is <code>INVLEX</code>
648 (<code>INV</code> because the largest variable is on the right).
649 Next we need to enter the generating polynomials for the ideal.
650 We do this in two steps, first define a Python string with the polynomials
651 and then the creation of the ideal using the ring definition from before
652 and the polynomial string.
653 </p>
654 <pre>
655 ps = """
656 (
657 ( 45 P + 35 S - 165 B - 36 ),
658 ( 35 P + 40 Z + 25 T - 27 S ),
659 ( 15 W + 25 S P + 30 Z - 18 T - 165 B**2 ),
660 ( - 9 W + 15 T P + 20 S Z ),
661 ( P W + 2 T Z - 11 B**3 ),
662 ( 99 W - 11 B S + 3 B**2 ),
663 ( B**2 + 33/50 B + 2673/10000 )
664 )
665 """;
666 </pre>
667 <p>
668 The polynomial string can be generated by any means Python allows for
669 string manipulation.
670 In our example we use Python multiline strings, which are delimited by
671 triple quotes <code>""" ... """</code>.
672 The list of polynomials is delimited by parenthesis <code>( ... )</code>,
673 as well as every polynomial is delimited by parenthesis, e.g.
674 <code>( B**2 + 33/50 B + 2673/10000 )</code>.
675 The polynomials are separated by commas.
676 The syntax for polynomials is a sequence of monimals consisting
677 of coefficients and terms (as products of powers of variables).
678 The terms can optionally be written with multiplication sign,
679 i.e. <code>25 S P</code> can be written <code>25*S*P</code>.
680 Variable names must be delimited by white space or some operator,
681 i.e. you can not write <code>25 SP</code> because <code>SP</code>
682 is not a listed variable name in the polynomial ring definition.
683 Coefficients may not contain white space, i.e. the <code>/</code>
684 separating the nominator from the denominator may not be surrounded
685 by spaces, i.e. writing <code>33 / 50</code> is not allowed.
686 Powers of variables can be written with <code>**</code> or <code>^</code>,
687 i.e. the square of <code>B</code> is written as <code>B**2</code>
688 or <code>B^2</code>.
689 The ideal is the defined with
690 </p>
691 <pre>
692 f = Ideal( r, ps );
693 </pre>
694 <p>
695 The ideal is contained the the polynomial ring <code>r</code>
696 and consists of the polynomials from the string <code>ps</code>.
697 Ideals can be printed with
698 </p>
699 <pre>
700 print "Ideal: " + str(f);
701 </pre>
702 <p>
703 In this example it produces the following output.
704 </p>
705 <pre>
706 Ideal: BigRational(B, S, T, Z, P, W) INVLEX
707 (
708 ( B^2 + 33/50 B + 2673/10000 ),
709 ( 45 P + 35 S - 165 B - 36 ),
710 ( 35 P + 40 Z + 25 T - 27 S ),
711 ( 15 W + 25 S * P + 30 Z - 18 T - 165 B^2 ),
712 ( -9 W + 15 T * P + 20 S * Z ),
713 ( 99 W - 11 B * S + 3 B^2 ),
714 ( P * W + 2 T * Z - 11 B^3 )
715 )
716 </pre>
717 <p>
718 The polynomial terms are now sorted with respect to the lexicographical
719 term order. The highest term is first in a polynomial.
720 Also the polynomials are sorted with respect to the term order, but
721 with smallest polynomial first in the list.
722 Finaly we can go to the computation of the Groebner basis of this ideal.
723 </p>
724 <pre>
725 g = f.GB();
726 </pre>
727 <p>
728 The ideal <code>f</code> has a method <code>GB()</code> which
729 computes the Groebner base. The computed Groebner base is stored
730 in the variable <code>g</code> which is also an ideal.
731 It can be printed in the same way as the ideal <code>f</code>
732 </p>
733 <pre>
734 print "Groebner base:", g;
735 </pre>
736 <p>
737 The output first shows the output from calling the <code>GB()</code> method
738 and the the ideal basis.
739 </p>
740 <pre>
741 sequential executed in 136 ms
742
743 Groebner base: BigRational(B, S, T, Z, P, W) INVLEX
744 (
745 ( B^2 + 33/50 B + 2673/10000 ),
746 ( S - 5/2 B - 9/200 ),
747 ( T - 37/15 B + 27/250 ),
748 ( Z + 49/36 B + 1143/2000 ),
749 ( P - 31/18 B - 153/200 ),
750 ( W + 19/120 B + 1323/20000 )
751 )
752 </pre>
753 <p>I.e. the Groebner base was computed in 135 ms and consists
754 of six polynomials. The polynomials are now monic,
755 i.e. the leading coefficient is 1 and omitted during print out.
756 This concludes the getting started section.
757 </p>
758
759
760 <h4>Solvable polynomial rings and the internal parser</h4>
761
762 <p>
763 Solvable polynomial rings are non commutative polynomial rings
764 where the non commutativity is expressed by commutator relations.
765 Commutator relations are stored in a data structure called relation table.
766 In the definition of a solvable polynomial ring this relation table must be
767 defined. E.g the definition for the ring of a solvable polynomial ring is
768 </p>
769 <pre>
770 Rat(a,b,e1,e2,e3) L
771 RelationTable
772 (
773 ( e3 ), ( e1 ), ( e1 e3 - e1 ),
774 ( e3 ), ( e2 ), ( e2 e3 - e2 )
775 )
776 </pre>
777 <p>
778 The relation table must be build from triples of (commutative) polynomials.
779 A triple <code>p1, p2, p3</code> is interpreted as non commutative
780 multiplication relation <code>p1 .*. p2 = p3</code>.
781 Currently <code>p1</code> and <code>p2</code> must be single term, single variable
782 polynomials. The term order must be choosen such that
783 leadingTerm(<code>p1 p2</code>) equals leadingTerm(<code>p3</code>)
784 and <code>p1 &gt; p2</code> for each triple.
785 Polynomial <code>p3</code> must be in commutative form,
786 i.e. multiplication operators occuring in it are commutative.
787 Variables for which there are no commutator relations are assumed to
788 commute with each other and with all other variables,
789 e.g. the variables <code>a, b</code> in the example.
790 Polynomials in the generating set of an ideal are also assumed to be
791 in commutative form. If you need non-commutative multiplication
792 in the polynomial expresions, please use the jython or jruby interface,
793 as discussed above.
794 </p>
795
796 <p>A complete example is contained in the Python script
797 <a href="../examples/solvable.py"><code>solvable.py</code></a>.
798 Running the script computes a left, right and twosided Groebner base
799 for the following ideal
800 </p>
801 <pre>
802 (
803 ( e1 e3^3 + e2^10 - a ),
804 ( e1^3 e2^2 + e3 ),
805 ( e3^3 + e3^2 - b )
806 )
807 </pre>
808 <p>The left Groebner base is
809 </p>
810 <pre>
811 (
812 ( a ), ( b ),
813 ( e1^3 * e2^2 ), ( e2^10 ), ( e3 )
814 )
815 </pre>
816 <p>the twosided Groebner base is
817 </p>
818 <pre>
819 (
820 ( a ), ( b ), ( e1 ), ( e2 ), ( e3 )
821 )
822 </pre>
823 <p>and the right Groebner base is
824 </p>
825 <pre>
826 (
827 ( a ), ( b ), ( e1 ), ( e2^10 ), ( e3 )
828 )
829 </pre>
830
831 <p>A module example is in
832 <a href="../examples/armbruster.py"><code>armbruster.py</code></a>
833 and a solvable module example is in
834 <a href="../examples/solvablemodule.py"><code>solvablemodule.py</code></a>.
835 </p>
836
837
838 <hr />
839
840 <h3>Overview of JAS Android App</h3>
841
842 <p style="color: red">
843 The App has been developed for JAS version 2.5 on Android 5 and is
844 not working on current Android versions (since 2019).
845 </p>
846
847 <p>
848 The JAS application uses the Ruboto-IRB Android application. Ruboto
849 provides an jruby scripting interpreter together with an editor
850 application. The Ruboto App is enhanced with the JAS jruby interface
851 and the JAS Java classes.
852 </p>
853
854 <p>For the Android app the main screen with the "trinks.rb" example and its output looks as follows.
855 </p>
856 <p><a href="../images/device-2012-11-18-jas-trinks.png" ><img src="../images/device-2012-11-18-jas-trinks-thumb.png" /></a> &nbsp;
857 <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;
858 <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>
859 </p>
860
861 <p>
862 The JAS jruby interface on Android has the
863 same functionality as the general JAS jruby scripting interface (only
864 some functionality of the power series is not avaliable).
865 </p>
866
867
868 <!--
869 <h3>Some internals of jas.py</h3>
870 -->
871
872
873 <!--
874 <li><p><code></code><code></code>
875 </p>
876 </li>
877
878 <pre>
879 </pre>
880
881 <p>
882 </p>
883 <pre>
884 </pre>
885 -->
886
887 <hr />
888 <address><a href="mailto:kredel@[email protected]">Heinz Kredel</a></address>
889 <p>
890 <!-- Created: Sun Feb 19 15:49:14 CET 2006 -->
891 <!-- hhmts start -->
892 Last modified: Mon Feb 28 10:39:28 CET 2022
893 <!-- hhmts end -->
894 </p>
895 <!--p align="right" >
896 $Id$
897 </p-->
898 </body>
899 </html>