Download, installation and unit tests

Download jar-files or clone repository

This is JAS version: jas-2.7, subversion revision: 200 (export at 2023-07-04).
The JAS classes jar-file jas-2.7.200-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 jas-2.7.200-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 jas-2.7.200-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.200.

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 jas-java_2.7.200-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:

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

Instructions to install the JAS binary:

Download the JAS binary jar file
Download the Log4j2 and the Junit jar files
Start eclipse
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-jas-2.7 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-jas-2.7 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.

Heinz Kredel

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