# Download, installation and unit tests

## Download jar-files

- This is JAS version: jas-2.4, subversion revision: 3938 (export at 2012-05-06).

- The JAS classes jar-file jas-2.4.3938-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 7 from OpenJDK (IcedTea7).
  The source code is in jas-2.4.3938-src.zip current version should compile on Java 1.5, 1.6 and 1.7 (aka Java 5, 6 and 7). (right click on the link and chose "save link as")
  The Javadoc API documentation is in jas-2.4.3938-doc.zip for current version.

- The JAS Git repository is available with

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

- Required libraries:
  lib/log4j.jar (from Apache Log4j),
  lib/junit.jar (from Junit),
  In case you have the first two ones, just ensure they are in the correct location (e.g. `../lib/`) or they are in the class path.

  In case you can not use Apache log4j for some reason, there is an adaptor package mylog.jar which delegates all logging calls to native Java logging.

- Optional libraries and files:

  - 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.
  - commons-math_adapter.jar
    This JAR contains an adapter for JAS to the Apache Commons Math 2.0 linear algebra library Commons-Math version 2.0.
  - jas-jython.jar
    This JAR contains a scripting interface to use the jython interpreter with JAS.

- For latest developments see JAS Weblog and the Subversion 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.jar:junit.jar:jas.jar:. -d . src/edu/jas/gb/Examples.java

      java  -classpath log4j.jar:junit.jar:jas.jar:.      edu.jas.gb.Examples

- 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 6 (Sun JDK 1.6 and OpenJDK 1.6). It will compile also under Java 5 (Sun JDK 1.5), but some (concurrency) classes may not work under the Java Virtual Machine (JVM) of JRE-1.5. It seems best to disable automatic parallel computation then (see edu.jas.kern.ComputerThreads.NO_THREADS).

- 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 compile` changed Java files are compiled,
  `ant recompile` all Java files are compiled,
  `ant test` run all JUnit tests,
  `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 and epydoc of jas.py.

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

## 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
2. Download the Log4j and the Junit jar files
3. Start eclipse
4. Create a new project from "existing source"
5. Specify the plain source directory `/src` 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 Log4j 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.jar, junit.jar and jas*-bin.jar. JAS-2.4 is using and has been tested with Jython 2.5.2.

- 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 "../lib/log4j.jar:../lib/junit.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.jar, junit.jar and jas*-bin.jar. JAS-2.4 is using and has been tested with JRuby 1.6.4 (Ruby 1.8.7 & 1.9.2 compatible)

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

- Start using JAS, e.g.

      jruby -J-cp "../lib/log4j.jar:../lib/junit.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.

Last modified: Fri Mar 2 22:16:58 CET 2012