JAS Download

# Download, installation and unit tests

## Download jar-files or clone repository

- This is JAS version: @VERSION@, subversion revision: @SVNREV@ (export at @SVNDATE@).

- The JAS classes jar-file @VERSION@.@SVNREV@-bin.jar can be used the same way as any other Java archive during compilation and execution of your Java programs. It is compiled using Java 11 from OpenJDK. The bytecode is dual licenced also under the Apache 2.0 licence to allow usage in Android projects.
  The source code is in @VERSION@.@SVNREV@-src.zip current version should compile on Java 8 and 11 (aka Java 1.8 and 1.11). (right click on the link and chose "save link as")
  The Javadoc API documentation is in @VERSION@.@SVNREV@-doc.zip for current version.

- A JAS Maven compatible repository is at http://krum.rz.uni-mannheim.de/maven-repository/ and at https://repo1.maven.org/maven2/de/uni-mannheim/rz/krum/.
  groupId: `de.uni-mannheim.rz.krum`, artifactId: `jas`, version (for example): `2.7.@SVNREV@`.

- The JAS Git repository is available with

       git clone http://krum.rz.uni-mannheim.de/jas.git  jas

  or from GitHub

       git clone https://github.com/kredel/java-algebra-system jas

- Required libraries:
  lib/log4j-api.jar, lib/log4j-core.jar (from Apache Log4j version 2.17.1),
  lib/junit-4.12.jar, lib/hamcrest-core-1.3.jar (from Junit 4),
  In case you already have these jars, just ensure they are in the correct location (e.g. `../lib/`) or in the class path or accessible via Maven.

  The jar libraries can be downloaded from the above links or with the Ivy "resolve" target of ant, or the Maven dependencies, when installing the JAS source code.

- Optional libraries and files:

  - There is a docker specification to create a docker image containing a runnable JAS in Dockerfile.
  - A Debian package libjas-java,
    an inofficial Debian package which can be used with MathLibre @DEBVERSION@.@SVNREV@-all.deb,
    and an Ubuntu package libjas-java are also avalilable.
  - jas-mpj.jar
    This JAR contains implementations of distributed Gröbner bases using the MPJ middle-ware (MPI Java). It requires an MPJ implementation such as MPJ Express or FastMPJ.
    The Javadocs can be found here.
  - jas-mpi.jar
    This JAR contains implementations of distributed Gröbner bases using the Open-MPI middle-ware (with Java support). It requires an MPI implementation such as Open-MPI.
    The Javadocs can be found here.
  - jas-meditor.jar
    This JAR contains the interface for JAS as an meditor engine, see jscl-meditor.
    Sample script to call meditor with the JAS engine meditor.
  - jlinalg_adapter.jar
    This JAR contains an adapter for JAS to the linear algebra library JLinAlg version 0.6.
    The Javadocs can be found here.
  - commons-math_adapter-bin.jar
    This JAR contains an adapter for JAS to the Apache Commons Math 3.3 linear algebra library Commons-Math version 3.3.
  - jas-jython.jar
    This JAR contains a scripting interface to use the jython interpreter with JAS.
  - Android JAS App Ruboto-IRB_with_JAS.
    You must allow "installation from untrusted sources".
    The JAS App uses its JRuby scripting interface and runs within the Ruby IRB Android App Ruboto.

- For latest developments see JAS Weblog and the Git change log.

## Installation

- Add the JAS jar-file and the other required jar-files to the classpath. Start using it in your applications. For example

      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

      java  -classpath log4j-api-2.17.1.jar:log4j-core-2.17.1.jar:junit.jar:jas.jar:.      edu.jas.application.Examples

  Make sure that you use the actual jars as described above, for example `log4j-api-2.17.1.jar:log4j-core-2.17.1.jar:junit-4.12.jar:hamcrest-core-1.3.jar`

- If you want to develop with JAS, then extract the jar-file in a new directory `jar -xvf jas-[version]-src.jar`

- JAS is currently developed for Java 11 (OpenJDK). It may eventually not compile under Java 8 (OpenJDK 1.8). It will no more compile under Java 6 (OpenJDK 1.6) or older versions.

- Among the extracted files, there is an Ant build script `build.xml` and also a Gnu make file `Makefile`.
  To use Ant, you must edit the `build.xml` file and adjust the `lib` property to point to the directory where you downloaded the jar files. Also be sure to use the correct JDK version, e.g. via setting the `JAVA_HOME` environment variable.
  To use the Gnu make file, you must edit the `Makefile` and adjust the `JDK` and the `LIBPATH` variables.

- Most useful Ant targets:
  `ant resolve` fetch the required libraries (log4j2, junit) with Ivy,
  `ant compile` changed Java files are compiled,
  `ant recompile` all Java files are compiled,
  `ant test` run all JUnit tests,
  `ant run -Dclass=edu.jas.'package'.'class'` run the respective class,
  `ant clean` remove backup files,
  `ant distclean` remove all class files,
  `ant doc` create the Javadocs.

- Most useful make-file targets:
  `make "class"` run the `main()` method of the class,
  e.g. `make edu.jas.poly.Examples` run the class `Examples`.

## Unit tests with JUnit

- Unit tests can be run with the "test" target for ant, e.g. `ant test`

- The output of the unit tests is collected in the directory `test` for inspection.

- The test units work mainly with generated random polynomials. The parameters are choosen such that the resulting Groebner bases are not to hard to compute. However some random polynomials may be to big and the running time may occasionally be several minutes (but not hours).
  On the other hand random polynomials may sometimes be zero or one. If such input does not make sense the test will fail. I.e. some tests will fail from time to time, but not for repeated execution of the test. So if a test fails rerun the test a few times.

## Documentation

- The JAS documentation is contained in the jar files `jas-[version]-src.jar` and `jas-[version]-doc.jar`. Extract the jar files and start exploring with any browser from the `index.html` file in the main directory.

- The JAS javadoc API documents and the jython documents can also be browsed online: API Javadocs, Epydoc of jas.py and Rdoc of jas.rb.

- README and licencing: COPYING.jas (GPL) or COPYING.lgpl.jas (LGPL)

## Logging

- JAS uses Apache Log4j to track progress in computations and inform about problematic or erroneous program states. Since JAS 2.6 it uses Log4j 2.x.

- The configuration is in file `log4j2.properties`. Per deault the logging level is at ERROR so that only minimal logs are produced. To obtain more detailed information or store the logs to files, please configure the desired properties in the above file.

  This configuration file is no more contained in the binary jars `jas-bin.jar` or `jas-[version].jar` to allow usage of other compatible logging frameworks.

  The old configuration of Log4j version 1 via `BasicConfigurator.configure()` is no more supported.

## Usage with the Eclipse IDE

The JAS source distribution can also be compiled and used from the Eclipse integrated development environment.

Instructions to install the JAS source:

1. Download the JAS source jar and unpack to some directory, or git clone the repository to some directory
2. Download the Log4j2 and the Junit jar files
3. Start eclipse
4. Create a new project from "existing source"
5. Specify the source directory `src` contained the directory from 1.
6. Add the jars from 2. to the project libraries as "external JARs"
7. Create a new project or use your default project
8. In the project properties add as "required project" the JAS project from 4.

Instructions to install the JAS binary:

1. Download the JAS binary jar file
2. Download the Log4j2 and the Junit jar files
3. Start eclipse
4. In your projects properties add the jar files from 1. and 2. to the project libraries as "external JARs"

Create and edit a sample java programm which uses the JAS API. E.g. the following sample computes the first ten Legendre polynomials.

    import java.util.List;
    import java.util.ArrayList;

    import edu.jas.arith.BigRational;
    import edu.jas.poly.GenPolynomial;
    import edu.jas.poly.GenPolynomialRing;

    public class mytests {

        public static void main(String[] args) {
             BigRational fac = new BigRational();
             String[] var = new String[]{ "x" };
             GenPolynomialRing<BigRational> ring
                 = new GenPolynomialRing<BigRational>(fac,1,var);

             int n = 10;
             List<GenPolynomial<BigRational>> P
                 = new ArrayList<GenPolynomial<BigRational>>(n);
             GenPolynomial<BigRational> t, one, x, xc;
             BigRational n21, nn;

             one = ring.getONE();
             x   = ring.univariate(0);

             P.add( one );
             P.add( x );
             for ( int i = 2; i < n; i++ ) {
                 n21 = new BigRational( 2*i-1 );
                 xc = x.multiply( n21 );
                 t = xc.multiply( P.get(i-1) );  // (2n-1) x P[n-1]
                 nn = new BigRational( i-1 );
                 xc = P.get(i-2).multiply( nn ); // (n-1) P[n-2]
                 t = t.subtract( xc );
                 nn = new BigRational(1,i);
                 t = t.multiply( nn );           // 1/n t
                 P.add( t );
             }
             for ( int i = 0; i < n; i++ ) {
                 System.out.println("P["+i+"] = " + P.get(i) );
             }
        }
    }

## Using the Jython interpreter

- Be sure you have downloaded the above libraries `log4j-api.jar, log4j-core.jar, junit-4.12.jar, hamcrest-core-1.3.jar`, and `jas*-bin.jar`. JAS-@VERSION@ is using and has been tested with Jython 2.7.0.

- The main file to interface to the JAS library is jas.py. It must be imported by other Python files. HTML documents of the interface can be found here.

- Start using JAS, e.g.

       jython -J-cp log4j-api.jar:log4j-core.jar:junit-4.12.jar:hamcrest-core-1.3.jar:. examples/trinks.py

  The examples/trinks.py contains an Groebner base example named after its proposer Mr. Trinks. The file runs a sequential, a parallel and a distributed version of the Groebner base algorithms.

- For further discussion of the JAS jython interface see User guide.

## Using the JRuby interpreter

- Be sure you have downloaded the above libraries `log4j-api.jar, log4j-core.jar, junit-4.12.jar, hamcrest-core-1.3.jar`, and `jas*-bin.jar`. JAS-@VERSION@ is using and has been tested with JRuby 1.7.23 (Ruby 1.9.3 compatible)

- The main file to interface to the JAS library is jas.rb. It must be required by other Ruby files. HTML documents of the interface can be found here.

- Start using JAS, e.g.

       jruby -J-cp log4j-api.jar:log4j-core.jar:junit-4.12.jar:hamcrest-core-1.3.jar:. examples/trinks.rb

  The examples/trinks.rb contains an Groebner base example named after its proposer Mr. Trinks. The file runs a sequential, a parallel and a distributed version of the Groebner base algorithms.

- For further discussion of the JAS scripting interface see User guide.

## Using the Ruboto-IRB-JAS Android application

The App has been developed for JAS version 2.5 on Android 5 and is not working on current Android versions (since 2019).

- Be sure you have installed the above Android application package `ruboto-irb-jas-release.apk`. It contains all required libraries and scripts. JAS-2.5 has been tested with Android 2.3 and 4.1 and is using JRuby 1.6.4 (Ruby 1.8.7 & 1.9.2 compatible)

- The JAS app uses the Ruby IRB Ruboto for Android. This is just a Ruby interpreter running on Android together with a text editor. So all JAS JRuby scripts can be run in this environment. The JAS Java programs are included in compiled and transformed Dalvik "dex" format. Up to now, no functional problems have been encountered, i.e. all JAS Java code runs. However, due to limitations in CPU speed and memory on mobile phones or tablets eventually not all examples and problems will execute. In 2012, comparison of a two year old Android tablet (1 GHz, 0.5 GB) and a three year old PC (3 GHz, 4 GB) show that the examples run about 5 times slower than on the PC.

- The main Ruboto screen with the "trinks.rb" example and its output looks as follows. Also the arbitrary precision numbers arithmetic works on Android.

  The list of examples can be accessed via the "scripts" button.

- For further discussion of the JAS scripting interface see User guide.

Last modified: Mon May 30 10:33:32 CEST 2022