Debian Codegraph @

doc/download.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 Download</title>
8 </head>
9 <body class="main">
10 <h1>Download, installation and unit tests</h1>
11
12
13 <h2>Download jar-files or clone repository</h2>
14
15 <ul>
16 <li><p>This is JAS version: <strong>@VERSION@</strong>,
17 subversion revision: <strong>@SVNREV@</strong> (export at @SVNDATE@).
18 </p>
19 </li>
20 <li><p>The JAS classes jar-file
21 <a href="../@VERSION@.@[email protected]">@VERSION@.@[email protected]</a>
22 can be used the same way as any other Java archive during
23 compilation and execution of your Java programs.
24 It is compiled using Java 11 from OpenJDK.
25 The bytecode is dual licenced also under the Apache 2.0 licence
26 to allow usage in Android projects.
27 <br />
28 The source code is in
29 <a href="../@VERSION@.@[email protected]">@VERSION@.@[email protected]</a>
30 current version should compile on Java 8 and 11 (aka Java 1.8 and 1.11).
31 (right click on the link and chose "save link as")
32 <br />
33 The Javadoc API documentation is in
34 <a href="../@VERSION@.@[email protected]">@VERSION@.@[email protected]</a>
35 for current version.
36 </p>
37 </li>
38 <li><p>A JAS Maven compatible repository is at
39 <a href="http://krum.rz.uni-mannheim.de/maven-repository/" target="new"
40 >http://krum.rz.uni-mannheim.de/maven-repository/</a> and at
41 <a href="https://repo1.maven.org/maven2/de/uni-mannheim/rz/krum/" target="new"
42 >https://repo1.maven.org/maven2/de/uni-mannheim/rz/krum/</a>. <br />
43 groupId: <code>de.uni-mannheim.rz.krum</code>, artifactId: <code>jas</code>,
44 version (for example): <code>2.7.@SVNREV@</code>.
45 </p>
46 <!--
47 http://krum.rz.uni-mannheim.de/maven-repository/de/uni-mannheim/rz/krum/jas/
48 http://central.maven.org/maven2/de/uni-mannheim/rz/krum/jas/
49 -->
50 </li>
51 <li><p>The JAS Git repository is available with
52 </p>
53 <pre>
54 git clone http://krum.rz.uni-mannheim.de/jas.git jas
55 </pre>
56 <p>or from GitHub</p>
57 <pre>
58 git clone https://github.com/kredel/java-algebra-system jas
59 </pre>
60 </li>
61 <li><p>Required libraries:
62 <br />
63 <a href="../../lib/log4j-api.jar">lib/log4j-api.jar</a>,
64 <a href="../../lib/log4j-core.jar">lib/log4j-core.jar</a>
65 (from Apache Log4j version 2.17.1),
66 <br />
67 <a href="../../lib/junit-4.12.jar">lib/junit-4.12.jar</a>,
68 <a href="../../lib/hamcrest-core-1.3.jar">lib/hamcrest-core-1.3.jar</a>
69 (from Junit 4),
70 <br />
71 In case you already have these jars, just ensure they are in the
72 correct location (e.g. <code>../lib/</code>) or in the class path or accessible via Maven.
73 </p>
74 <p>
75 The jar libraries can be downloaded from the above links or
76 with the Ivy "resolve" target of ant, or the Maven dependencies,
77 when installing the JAS source code.
78 </p>
79 </li>
80 <li><p>Optional libraries and files:
81 </p>
82 <ul>
83 <li>There is a <a href="http://www.docker.com" target="deb">docker</a> specification to create
84 a docker image containing a runnable JAS in <a href="Dockerfile">Dockerfile</a>.
85 </li>
86 <li>A Debian package <a href="http://packages.debian.org/de/sid/libjas-java" target="deb">libjas-java</a>,
87 <br />
88 an inofficial Debian package which can be used with MathLibre
89 <a href="../@DEBVERSION@.@[email protected]" target="deb">@DEBVERSION@.@[email protected]</a>,
90 <br />
91 and an Ubuntu package
92 <a href="http://packages.ubuntu.com/search?keywords=libjas-java" target="deb">libjas-java</a>
93 are also avalilable.
94 </li>
95 <li><a href="../jas-mpj.jar">jas-mpj.jar</a> <br /> This JAR contains
96 implementations of distributed Gr&ouml;bner bases using the
97 MPJ middle-ware (MPI Java). It requires an MPJ implementation such as
98 <a href="http://mpj-express.org/" target="mpj" >MPJ Express</a> or
99 <a href="http://fastmpj.com/" target="mpj" >FastMPJ</a>.
100 <br />
101 The Javadocs can be found <a href="../mpj/index.html" target="api">here</a>.
102 </li>
103 <li><a href="../jas-mpi.jar">jas-mpi.jar</a> <br /> This JAR contains
104 implementations of distributed Gr&ouml;bner bases using the
105 Open-MPI middle-ware (with Java support). It requires an MPI implementation
106 such as <a href="http://www.open-mpi.org/" target="mpi" >Open-MPI</a>.
107 <br />
108 The Javadocs can be found <a href="mpi/index.html" target="api">here</a>.
109 </li>
110 <li><a href="../jas-meditor.jar">jas-meditor.jar</a>
111 <br />
112 This JAR contains the interface for JAS as an meditor engine,
113 see <a href="http://jscl-meditor.sourceforge.net/" target="rela">jscl-meditor</a>.
114 <br />
115 Sample script to call meditor with the JAS engine
116 <a href="../meditor/meditor">meditor</a>.
117 </li>
118 <li><a href="../jlinalg_adapter.jar">jlinalg_adapter.jar</a>
119 <br />
120 This JAR contains an adapter for JAS to the linear algebra library
121 <a href="http://jlinalg.sourceforge.net/" target="rela">JLinAlg</a> version 0.6.
122 <br />
123 The Javadocs can be found <a href="../jlinalg_adapter/index.html" target="api">here</a>.
124 </li>
125 <li><a href="../commons-math_adapter-bin.jar">commons-math_adapter-bin.jar</a>
126 <br />
127 This JAR contains an adapter for JAS to the Apache Commons Math 3.3
128 linear algebra library
129 <a href="http://commons.apache.org/math/" target="rela">Commons-Math</a>
130 version 3.3.
131 </li>
132 <li><a href="../jas-jython.jar">jas-jython.jar</a>
133 <br />
134 This JAR contains a scripting interface to use the
135 <a href="http://www.jython.org/" target="rela">jython</a>
136 interpreter with JAS.
137 </li>
138 <li>Android JAS App
139 <a href="http://krum.rz.uni-mannheim.de/ruboto-irb-jas-release.apk">Ruboto-IRB_with_JAS</a>.
140 <br />
141 You must allow &quot;installation from untrusted sources&quot;.
142 <br />
143 The JAS App uses its JRuby scripting interface and runs within the Ruby IRB Android App
144 <a href="http://ruboto.org/">Ruboto</a>.
145 </li>
146 </ul>
147 <p>&nbsp;</p>
148 </li>
149 <li><p>For latest developments see <a href="jas-log.html">JAS Weblog</a>
150 and the <a href="git_change.log" target="top">Git change log</a>.
151 </p>
152 </li>
153 </ul>
154
155
156 <h2>Installation</h2>
157
158 <ul>
159 <li><p>Add the JAS jar-file and the other required jar-files
160 to the classpath. Start using it in your applications.
161 For example
162 </p>
163 <pre>
164 javac -classpath log4j-api-2.17.1.jar:log4j-core-2.17.1.jar:junit.jar:jas.jar:. -d . src/edu/jas/application/Examples.java
165
166 java -classpath log4j-api-2.17.1.jar:log4j-core-2.17.1.jar:junit.jar:jas.jar:. edu.jas.application.Examples
167 </pre>
168
169 <p>Make sure that you use the actual jars as described above, for example
170 <code>log4j-api-2.17.1.jar:log4j-core-2.17.1.jar:junit-4.12.jar:hamcrest-core-1.3.jar</code>
171 </p>
172
173 </li>
174 <li><p>If you want to develop with JAS, then extract the
175 jar-file in a new directory
176 <code>jar -xvf jas-[version]-src.jar</code>
177 </p>
178 </li>
179 <li><p>JAS is currently developed for Java 11 (OpenJDK).
180 It may eventually not compile under Java 8 (OpenJDK 1.8).
181 It will <b>no more</b> compile under Java 6 (OpenJDK 1.6)
182 or older versions.
183 </p>
184 </li>
185 <li><p>Among the extracted files, there is an Ant build script
186 <code>build.xml</code>
187 and also a Gnu make file
188 <code>Makefile</code>.
189 <br />
190 To use Ant, you must edit the <code>build.xml</code> file and
191 adjust the <code>lib</code> property to point to the directory
192 where you downloaded the jar files.
193 Also be sure to use the correct JDK version, e.g. via setting the
194 <code>JAVA_HOME</code> environment variable.
195 <br />
196 To use the Gnu make file, you must edit the <code>Makefile</code>
197 and adjust the <code>JDK</code> and the <code>LIBPATH</code> variables.
198 </p>
199 </li>
200 <li><p>Most useful Ant targets:
201 <br />
202 <code>ant resolve</code> fetch the required libraries (log4j2, junit) with Ivy,
203 <br />
204 <code>ant compile</code> changed Java files are compiled,
205 <br />
206 <code>ant recompile</code> all Java files are compiled,
207 <br />
208 <code>ant test</code> run all JUnit tests,
209 <br />
210 <code>ant run -Dclass=edu.jas.'package'.'class'</code> run the respective class,
211 <br />
212 <code>ant clean</code> remove backup files,
213 <br />
214 <code>ant distclean</code> remove all class files,
215 <br />
216 <code>ant doc</code> create the Javadocs.
217 </p>
218 </li>
219 <li><p>Most useful make-file targets:
220 <br />
221 <code>make "class"</code> run the <code>main()</code> method of the class,
222 <br />
223 e.g. <code>make edu.jas.poly.Examples</code> run
224 the class <code>Examples</code>.
225 </p>
226 </li>
227 </ul>
228
229
230 <h2>Unit tests with JUnit</h2>
231 <ul>
232 <li><p>Unit tests can be run with the "test" target for ant, e.g.
233 <code>ant test</code>
234 </p>
235 </li>
236 <li><p>The output of the unit tests is collected in the directory
237 <code>test</code> for inspection.
238 </p>
239 </li>
240 <li><p>The test units work mainly with generated random polynomials.
241 The parameters are choosen such that the resulting Groebner bases
242 are not to hard to compute.
243 However some random polynomials may be to big and the running time
244 may occasionally be several minutes (but not hours).
245 <br />
246 On the other hand random polynomials may sometimes be zero or one.
247 If such input does not make sense the test will fail. I.e. some
248 tests will fail from time to time, but not for repeated execution
249 of the test. So if a test fails rerun the test a few times.
250 </p>
251 </li>
252 </ul>
253
254
255 <h2><a name="docu">Documentation</a></h2>
256
257 <ul>
258 <li><p>The JAS documentation is contained in the jar files
259 <code>jas-[version]-src.jar</code> and <code>jas-[version]-doc.jar</code>.
260 Extract the jar files and start exploring with any browser
261 from the <code>index.html</code> file in the main directory.
262 </p>
263 </li>
264 <li><p>The JAS javadoc API documents and the jython documents
265 can also be browsed online:
266 <a href="api/index.html" target="api">API Javadocs</a>,
267 <a href="jython/index.html" target="jython">Epydoc of jas.py</a> and
268 <a href="jruby/index.html" target="jruby">Rdoc of jas.rb</a>.
269 </p>
270 </li>
271 <li><p><a href="../README" target="main" >README</a> and licencing:
272 <a href="COPYING.jas" target="gpl" >COPYING.jas</a> (GPL)
273 or
274 <a href="COPYING.lgpl.jas" target="gpl" >COPYING.lgpl.jas</a> (LGPL)
275 </p>
276 </li>
277 </ul>
278
279
280 <h2><a name="log">Logging</a></h2>
281
282 <ul>
283 <li><p>JAS uses <a href="https://en.wikipedia.org/wiki/Log4j">Apache Log4j</a>
284 to track progress in computations and
285 inform about problematic or erroneous program states.
286 Since JAS 2.6 it uses <b>Log4j 2.x</b>.
287 </p>
288 </li>
289 <li><p>The configuration is in file <code>log4j2.properties</code>.
290 Per deault the logging level is at <b>ERROR</b> so that only minimal
291 logs are produced.
292 To obtain more detailed information or store the logs to files,
293 please configure the desired properties in the above file.
294 </p>
295 <p>This configuration file is no more contained in the binary jars
296 <code>jas-bin.jar</code> or <code>jas-[version].jar</code> to allow
297 usage of other compatible logging frameworks.
298 </p>
299 <p>The old configuration of Log4j version 1 via
300 <code>BasicConfigurator.configure()</code> is no more supported.
301 </p>
302 </li>
303 <!--li><p>In case you can not use Apache log4j for some reason, there is an
304 adaptor package <a href="../mylog.jar">mylog.jar</a>
305 which delegates all logging calls to native Java logging.
306 </p>
307 <p>For Android there is the adaptor package <a href="../droidlog.jar">droidlog.jar</a>
308 which delegates all logging calls to native Android logging.
309 </p>
310 </li-->
311 </ul>
312
313
314 <h2><a name="eclipse">Usage</a> with the Eclipse IDE</h2>
315
316 <p>The JAS source distribution can also be compiled and used from the
317 Eclipse integrated development environment.
318 </p>
319
320 <p>Instructions to install the JAS source:</p>
321 <ol>
322 <li>Download the JAS source jar and unpack to some directory,
323 or git clone the repository to some directory
324 </li>
325 <li>Download the Log4j2 and the Junit jar files
326 </li>
327 <li>Start eclipse
328 </li>
329 <li>Create a new project from "existing source"
330 </li>
331 <li>Specify the source directory <code>src</code> contained the directory from 1.
332 </li>
333 <li>Add the jars from 2. to the project libraries as "external JARs"
334 </li>
335 <li>Create a new project or use your default project
336 </li>
337 <li>In the project properties add as "required project"
338 the JAS project from 4.
339 </li>
340 </ol>
341
342 <p>Instructions to install the JAS binary:</p>
343 <ol>
344 <li>Download the JAS binary jar file
345 </li>
346 <li>Download the Log4j2 and the Junit jar files
347 </li>
348 <li>Start eclipse
349 </li>
350 <li>In your projects properties add the jar files
351 from 1. and 2. to the project libraries as "external JARs"
352 </li>
353 </ol>
354
355
356 <p>Create and edit a sample java programm which uses the JAS API.
357 E.g. the following sample computes the first ten Legendre polynomials.
358 </p>
359 <pre>
360 import java.util.List;
361 import java.util.ArrayList;
362
363 import edu.jas.arith.BigRational;
364 import edu.jas.poly.GenPolynomial;
365 import edu.jas.poly.GenPolynomialRing;
366
367 public class mytests {
368
369 public static void main(String[] args) {
370 BigRational fac = new BigRational();
371 String[] var = new String[]{ "x" };
372 GenPolynomialRing&lt;BigRational&gt; ring
373 = new GenPolynomialRing&lt;BigRational&gt;(fac,1,var);
374
375 int n = 10;
376 List&lt;GenPolynomial&lt;BigRational&gt;&gt; P
377 = new ArrayList&lt;GenPolynomial&lt;BigRational&gt;&gt;(n);
378 GenPolynomial&lt;BigRational&gt; t, one, x, xc;
379 BigRational n21, nn;
380
381 one = ring.getONE();
382 x = ring.univariate(0);
383
384 P.add( one );
385 P.add( x );
386 for ( int i = 2; i &lt; n; i++ ) {
387 n21 = new BigRational( 2*i-1 );
388 xc = x.multiply( n21 );
389 t = xc.multiply( P.get(i-1) ); // (2n-1) x P[n-1]
390 nn = new BigRational( i-1 );
391 xc = P.get(i-2).multiply( nn ); // (n-1) P[n-2]
392 t = t.subtract( xc );
393 nn = new BigRational(1,i);
394 t = t.multiply( nn ); // 1/n t
395 P.add( t );
396 }
397 for ( int i = 0; i &lt; n; i++ ) {
398 System.out.println("P["+i+"] = " + P.get(i) );
399 }
400 }
401 }
402 </pre>
403
404
405 <h2>Using the <a name="jython">Jython</a> interpreter</h2>
406
407 <ul>
408 <!--li><p>Set up your <code>.jythonrc</code> file, e.g. see the sample code in
409 <a href="../sample.jythonrc" target="py">sample.jythonrc</a>.
410 </p>
411 </li-->
412 <li><p>Be sure you have downloaded the above libraries
413 <code>log4j-api.jar, log4j-core.jar, junit-4.12.jar, hamcrest-core-1.3.jar</code>,
414 and <code>jas*-bin.jar</code>.
415 JAS-@VERSION@ is using and has been tested with Jython 2.7.0.
416 </p>
417 </li>
418 <li><p>The main file to interface to the JAS library is
419 <a href="../examples/jas.py" target="py">jas.py</a>.
420 It must be imported by other Python files.
421 HTML documents of the interface can be found
422 <a href="jython/index.html" target="jython">here</a>.
423 </p>
424 </li>
425 <!--li><p>If jython cannot find the JAS classes, try to put the jas.jar also
426 into the CLASSPATH or unpack the jar into the directory you are
427 starting jython (also to get the correct version of .py files).
428 </p>
429 </li-->
430 <li><p>Start using JAS, e.g.
431 </p>
432 <pre>
433 jython -J-cp log4j-api.jar:log4j-core.jar:junit-4.12.jar:hamcrest-core-1.3.jar:. examples/trinks.py
434 </pre>
435 <p>The
436 <a href="../examples/trinks.py" target="py">examples/trinks.py</a>
437 contains an Groebner base example named after its proposer Mr. Trinks.
438 The file runs a sequential, a parallel and a distributed version
439 of the Groebner base algorithms.
440 </p>
441 </li>
442 <li><p>For further discussion of the JAS jython interface
443 see
444 <a href="guide.html" target="main">User guide</a>.
445 </p>
446 </li>
447 </ul>
448
449
450 <h2>Using the <a name="jruby">JRuby</a> interpreter</h2>
451
452 <ul>
453 <li><p>Be sure you have downloaded the above libraries
454 <code>log4j-api.jar, log4j-core.jar, junit-4.12.jar, hamcrest-core-1.3.jar</code>,
455 and <code>jas*-bin.jar</code>.
456 JAS-@VERSION@ is using and has been tested with JRuby 1.7.23 (Ruby 1.9.3 compatible)
457 </p>
458 </li>
459 <li><p>The main file to interface to the JAS library is
460 <a href="../examples/jas.rb" target="rb">jas.rb</a>.
461 It must be required by other Ruby files.
462 HTML documents of the interface can be found
463 <a href="jruby/index.html" target="jruby">here</a>.
464 </p>
465 </li>
466 <li><p>Start using JAS, e.g.
467 </p>
468 <pre>
469 jruby -J-cp log4j-api.jar:log4j-core.jar:junit-4.12.jar:hamcrest-core-1.3.jar:. examples/trinks.rb
470 </pre>
471 <p>The
472 <a href="../examples/trinks.rb" target="rb">examples/trinks.rb</a>
473 contains an Groebner base example named after its proposer Mr. Trinks.
474 The file runs a sequential, a parallel and a distributed version
475 of the Groebner base algorithms.
476 </p>
477 </li>
478 <li><p>For further discussion of the JAS scripting interface
479 see
480 <a href="guide.html" target="main">User guide</a>.
481 </p>
482 </li>
483 </ul>
484
485
486 <h2>Using the <a name="ruboto-irb-jas">Ruboto-IRB-JAS</a> Android application</h2>
487
488 <p style="color: red">
489 The App has been developed for JAS version 2.5 on Android 5 and is
490 not working on current Android versions (since 2019).
491 </p>
492
493 <ul>
494 <li><p>Be sure you have installed the above Android application package
495 <code>ruboto-irb-jas-release.apk</code>.
496 It contains all required libraries and scripts.
497 JAS-2.5 has been tested with Android 2.3 and 4.1 and is using
498 JRuby 1.6.4 (Ruby 1.8.7 &amp; 1.9.2 compatible)
499 </p>
500 </li>
501 <li><p>The JAS app uses the Ruby IRB <a href="http://ruboto.org/">Ruboto</a> for Android.
502 This is just a Ruby interpreter running on Android together with a text editor.
503 So all JAS JRuby scripts can be run in this environment.
504 The JAS Java programs are included in compiled and transformed Dalvik "dex" format.
505 Up to now, no functional problems have been encountered, i.e. all JAS Java code runs.
506 However, due to limitations in CPU speed and memory on mobile phones or tablets
507 eventually not all examples and problems will execute.
508 In 2012, comparison of a two year old Android tablet (1 GHz, 0.5 GB)
509 and a three year old PC (3 GHz, 4 GB) show that the examples run
510 about 5 times slower than on the PC.
511 </p>
512 </li>
513 <li><p>The main Ruboto screen with the "trinks.rb" example and its output looks as follows.
514 Also the arbitrary precision numbers arithmetic works on Android.
515 </p>
516 <p><a href="../images/device-2012-11-18-jas-trinks.png" ><img src="../images/device-2012-11-18-jas-trinks-thumb.png" alt="screen shot" /></a> &nbsp;
517 <a href="../images/device-2012-11-18-jas-trinks-out.png" ><img src="../images/device-2012-11-18-jas-trinks-out-thumb.png" alt="screen shot"/></a> &nbsp;
518 <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" alt="screen shot"/></a>
519 </p>
520 <p>The list of examples can be accessed via the "scripts" button.
521 </p>
522 <p><a href="../images/device-2012-11-18-jas-examples.png" ><img src="../images/device-2012-11-18-jas-examples-thumb.png" alt="screen shot"/></a>
523 </p>
524 </li>
525 <li><p>For further discussion of the JAS scripting interface
526 see
527 <a href="guide.html" target="main">User guide</a>.
528 </p>
529 </li>
530 </ul>
531
532 <hr />
533 <address><a name="contact"
534 href="mailto:kredel@[email protected]">Heinz Kredel</a>
535 </address>
536 <p>
537 <!-- Created: Sat Mar 19 21:44:14 CET 2005 -->
538 <!-- hhmts start -->
539 Last modified: Mon May 30 10:33:32 CEST 2022
540 <!-- hhmts end -->
541 </p>
542 <!--p align="right" >
543 $Id$
544 </p-->
545 </body>
546 </html>