The information on this page is woefully out-of-date, and much of it is now incorrect. Please visit the UACalc_CLI GitHub repository for the latest information.
These notes explain how to set up the Jython interpreter as a command line interface to UACalc, and then give a few examples that show how to import and use UACalc classes on the command line. (A separate set of notes describes how to configure the Eclipse IDE so that it’s easy to import UACalc packages in Java and Python programs.)
Jython is an implementation of the Python programming language written to run in the Java Runtime Environment (JRE). If you use Jython, your Python programs can import and make use of any Java library.
The Universal Algebra Calculator (UACalc) is powerful software for studying and experimenting with general (universal) algebras. It is written entirely in Java and it has a very nice, user friendly graphical user interface (gui). The UACalc lacks a command line interface (cli), and for some tasks we might prefer a cli over a gui.
A common scenario is the following: we wish to construct a large collection of algebras and, iterating over this collection, use some functionality provided by UACalc to search for a counterexample to some conjecture. One solution would be to write a Java program to do this, since we can access the opensource Java classes and methods provided by UACalc. Although Java is a nice language that makes programming relatively painless, it is still time consuming to write a decent, correct Java program. For fast prototyping and experimentation, it would be nice to have a scripting language interface to UACalc. Jython provides this.
The next section describes a few ways to install and configure a command line version of UACalc. Then we show how to import UACalc classes from the Jython command line interpreter, and then use simple Python syntax to work with the resulting UACalc objects. In another set of notes, we show how to configure the Eclipse IDE so that UACalc packages can be imported in Python programs developed in Eclipse. A similar set of notes is available for Emacs.
Installation and configuration
There are a number of ways to configure your system so that UACalc Java packages can be imported and used in your Python programs. The three methods described below assume you simply want to use the UACalc classes from the Jython command line interpreter. This is a good place to start experimenting. Alternatively, you can configure Emacs or the Eclipse IDE so that your Python programs can import UACalc packages. These alternatives are described in other UACalc notes on this website.
(There is also a front page to the Git repository, with essentially the same instructions as appear below.)
Method 1: tar file download
Assuming you already have Java installed, or you will install it yourself, this method may work for you and may be the simplest.
- Download the UACalc.tar file from: http://uacalc.org/Jython/UACalc.tar and put it in your home directory.
- Extract this tar archive into your home directory with a command like the following:
tar xvf UACalc.tar
Or, if you already have a ~/UACalc directory, you can prevent tar from overwriting files that are newer than those in the archive with `tar –keep-newer-files xvf UACalc.tar` (consider also the -w option).
Method 2: automatic setup script for Ubuntu
We are creating a setup.sh shell script to automatically install and configure a command line version of the Universal Algebra Calculator (UACalc). This includes installation of Java (if not already installed) and a standalone version of Jython.
At this point an alpha version that works on Ubuntu Linux is available. It can be installed in three easy steps given below. This has been tested on a minimal Ubuntu Linux installation (see the cloud computing notes–coming soon). If you are not using Ubuntu, you can read the comments in the setup.sh file, and do the analogous steps for your platform, or use Method 1 above.
- Download the script: setup.sh. You can use your browser to download it from the link above, OR type the following at the command line:
- Make it executable:
chmod a+x setup.sh
- Run it:
If you try these commands on an Ubuntu machine and get an error, we want to know. Please post a comment in the box below.
For more information about this script and what it does, please see the script itself (it’s well commented).
If you followed the steps in Method 2, you now have your own UACalc Git repository residing in ~/git/UACalc. (If you don’t know what this means, you can learn Git in 15 minutes!)
Our UACalc GitHub repository may be updated occasionally. To update your local version of the repository, change to the directory ~/git/UACalc and invoke the git pull command, as follows:
cd ~/git/UACalc git pull
Don’t worry, this will not overwrite changes you may have made to the files in your own repository. (But if you’ve made changes to a file that you would like to discard, do `git checkout filename`.) For some other useful Git commands, a nice list of the basics is the “no ds” guide.
Method 3: most basic command line setup
This section assumes you have already installed Java and Jython and you are using some flavor of Linux. If you are on a Mac, the following may work in the terminal, though I have not tested it. (If you are on Windows, I strongly encourage you to install Ubuntu, or login to a remote Amazon server running Ubuntu, as we will describe in another set of notes on this website.)
The steps below assume you are working in the $HOME directory. To work in a different directory, substitute the path to that directory for $HOME in the commands below.
- Use a web browser or the wget command to download the uacalc.jar file from http://uacalc.org/uacalc.jar and note the directory in which you saved the file. The steps below will assume it’s in $HOME/uacalc.jar. For example, in a terminal window enter the following two commands:
cd $HOME wget http://uacalc.org/uacalc.jar
- To start the Jython command line interpreter, enter jython:
jython Jython 2.7b1 (default:ac42d59644e9, Feb 9 2013, 15:24:52) [Java HotSpot(TM) 64-Bit Server VM (Oracle Corporation)] on java1.7.0_21 Type "help", "copyright", "credits" or "license" for more information. >>>
If you don’t see >>> (the Jython prompt), something is wrong with your Jython installation, in which case you should consult the Jython wiki documentation or consider using one of the first to methods above, which provides a standalone Jython interpreter.
- Import the Jython sys module, and set the PYTHONPATH to include uacalc.jar:
>>> import sys >>> sys.path.append("$HOME/uacalc.jar")
- Now you can already start importing parts of UACalc. For examples, see the first example in the section on importing and using UACalc packages.
Starting the Jython interpreter
If you used Methods 1 or 2 above, you should now have the following directories:
~/UACalc/Algebras ~/UACalc/Examples ~/UACalc/UACalc_CLI
(If you used Method 3 above, please skip to Example 1 in the next section.) In the third of these directories there will be startup script called uacalc. Run this script by entering it at the command line:
You should see
Starting Jython with UACalc dependencies. Please be patient... %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Welcome to the command line version of UACalc! to exit type quit() (more help coming) %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% >>>
You may wish to put a link to the uacalc start up command in your path. For example, if ~/bin is in your path, do
ln -s ~/UACalc/UACalc_CLI/uacalc ~/bin/uacalc
The file ~/UACalc/UACalc_CLI/uacalc.py has definitions used in an interactive session, and the uacalc command is just shorthand for the following:
java -jar ~/UACalc/UACalc_CLI/Jars/jython.jar -i ~/UACalc/UACalc/UACalc_CLI/uacalc.py
To get some idea of some of the basic things that are possible, look at the file ~/UACalc/Examples/AlgebraConstructionExample.py. This is an example script showing how to use Python to construct an algebra. Below are some other examples. (More will be posted soon.)
- Once you have configured Jython and started the interpreter as described above, you can import some UACalc packages.
>>> from org.uacalc import alg
- Instantiating classes is much simpler in Python than it is in Java. For example, to define the partition |0,1|2,3|,
>>> a = alg.conlat.BasicPartition("|0,1|2,3|")
It’s even easier if we import the BasicPartition class specifically:
>>> from org.uacalc.alg.conlat import BasicPartition >>> a = BasicPartition("|0,1|2,3|")
- You can do catch-all imports with the * wildcard. For instance,
>>> from org.uacalc.alg import * >>> a = conlat.BasicPartition("|0,1|2,3|")
but you should use such import statements sparingly because they cause Jython to put wrappers around every class and method in the named package.
- Once you have instantiated an object, you can invoke its toString() method by simply entering its name at the prompt:
>>> a |0,1|2,3|
Alternatively, you can print it:
>>> print a |0,1|2,3|
- To summarize some of what we’ve seen above, we go through a simple example from the beginning. (This example assumes only that you have Jython installed and have downloaded uacalc.jar. It doesn’t assume you have the uacalc script installed, so it demonstrates what you might do if you followed Method 3 above.)
~$ jython >>> import sys >>> sys.path.append("/home/username/uacalc.jar") >>> from org.uacalc.alg import * >>> a = conlat.BasicPartition("|0,1|2,3|") >>> b = conlat.BasicPartition("|0|1,2|3|") >>> a, b (|0,1|2,3|, |0|1,2|3|) >>> print a, b |0,1|2,3| |0|1,2|3| >> c, d = a, b >>> c, d (|0,1|2,3|, |0|1,2|3|) >>> compab = a.compose(b) >>> compab [[0, 0], [0, 1], [0, 2], [1, 0], [1, 1], [1, 2], [2, 1], [2, 2], [2, 3], [3, 1], [3, 2], [3, 3]] >>> parts = a, b, c, d >>> parts (|0,1|2,3|, |0|1,2|3|, |0,1|2,3|, |0|1,2|3|) >>> for p in parts: ... p.rank() ... 2 1 2 1
You can call some of the UACalc’s “hidden methods” (that don’t appear in the gui menu). For example, if you look at the UACalc javadocs, and click on CongruenceLattice on the left, you will find a method
commutator(BinaryRelation S, BinaryRelation T).
(There are also methods for the weak and strong rectangularity commutators, as well as centrality methods.)
The sample interactive session below does the following:
- Read in the algebra f3 (the reduct of the three element field to multiplication).
- Check its cardinality.
- Define theta to be the nontrivial congruence and define one to be the top.
- Check the commutator [theta,one] = zero but [one,theta] = theta.
[ralph@mahiloa:~/UACalc/UACalc_CLI]$ uacalc Starting Jython with UACalc dependencies. Please be patient... %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Welcome to the command line version of UACalc! to exit type quit() (more help coming) %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% >>> f3 = AlgebraIO.readAlgebraFile("/home/ralph/UACalc/Algebras/f3.ua") >>> f3.cardinality() 3 >>> conlat = f3.con().getUniverseList() >>> conlat [|0|1|2|, |0|1,2|, |0,1,2|] >>> theta = conlat >>> theta |0|1,2| >>> one = conlat >>> one |0,1,2| >>> f3.con().commutator(theta,one) |0|1|2| >>> f3.con().commutator(one,theta) |0|1,2| >>> quit()
So far we have seen just a few examples of UACalc classes and some of their methods. To see what other UACalc packages you can import, and to learn about their methods, consult the UACalc javadocs.