Software Companion Overview
The enclosed DVD (ISO image) with software is derived from several open-source projects, notably Debian GNU–Linux , GiNaC library of symbolic calculations , Asymptote  and many others. Thus, our work is distributed under the GNU General Public License (GPL) 3.0 .
You can download an ISO image of a Live GNU–Linux DVD with our CAS
from several locations. The initial (now outdated) version was
posted through the Data Conservancy Project
arXiv.org associated to
paper . A newer version of ISO is now included as an
auxiliary file to the same paper, see the subdirectory:
Also, an updated versions of the ISO
image is uploaded to Google Drive:
In this Appendix, we only briefly outline how to start using the enclosed DVD or ISO image. As soon as the DVD is running or the ISO image is mounted as a virtual file system, further help may be obtained on the computer screen. We also describe how to run most of the software on the disk on computers without a DVD drive at the end of Sections 1.1, 1.2.1 and 1.2.2.
The easiest part is to view colour illustrations on your computer. There are not many hardware and software demands for this task—your computer should have a DVD drive and be able to render HTML pages. The last task can be done by any web browser. If these requirements are satisfied, perform the following steps:
If your computer does not have a DVD drive (e.g. is a netbook), but you can gain brief access to a computer with a drive, then you can copy the top-level folder doc from the enclosed DVD to a portable medium, say a memory stick. Illustrations (and other documentation) can be accessed by opening the index.html file from this folder.
In a similar way, the reader can access ISO images of bootable disks, software sources and other supplementary information described below.
There are three major possibilities of using the enclosed CAS:
Method A is straightforward and can bring some performance enhancement. However, it requires hardware compatibility; in particular, you must have the so-called i386 architecture. Method B will run on a much wider set of hardware and you can use CAS from the comfort of your standard desktop. However, this may require an additional third-party programme to be installed.
WARNING: it is a general principle, that running a software within an emulator is more secure than to boot your computer in another OS. Thus we recommend using the method described in Section 1.2.2.
It is difficult to give an exact list of hardware requirements for DVD booting, but your computer must be based on the i386 architecture. If you are ready to have a try, follow these steps:
If the DVD boots but the graphic X server did not start for any reason and you have the text command prompt only, you can still use most of the CAS. This is described in the last paragraph of Section 1.3.
If your computer does not have a DVD drive you may still boot the CAS on your computer from a spare USB stick of at least 1Gb capacity. For this, use UNetbootin  or a similar tool to put an ISO image of a boot disk on the memory stick. The ISO image(s) is located at the top-level folder iso-images of the DVD and the file README in this folder describes them. You can access this folder as described in Section 1.1.
You can also use the enclosed CAS on a wide range of hardware running various operating systems, e.g. Linux, Windows, Mac OS, etc. To this end you need to install a so-called virtual machine, which can emulate i386 architecture. I would recommend VirtualBox —a free, open-source program which works well on many existing platforms. There are many alternatives (including open-source), for example: Qemu , Open Virtual Machine  and some others.
Here, we outline the procedure for VirtualBox—for other emulators you may need to make some adjustments. To use VirtualBox, follow these steps:
If you succeeded in this you may proceed to Section 1.3. Some tips to improve your experience with emulations are described in the detailed electronic manual.
The core of our software is a C++ library which is based on GiNaC —see its web page for up-to-date information. The latter can be compiled and installed on both Linux and Windows. Subsequently, our library can also be compiled on these computers from the provided sources. Then, the library can be used in your C++ programmes. See the top-level folder src on the DVD and the documentation therein. Also, the library source code (files cycle.h and cycle.cpp) is produced in the current directory if you pass the TEX file of the paper  through LATEX.
Our interactive tool is based on pyGiNaC —a Python binding for GiNaC. This may work on many flavours of Linux as well. Please note that, in order to use pyGiNaC with the recent GiNaC, you need to apply my patches to the official version. The DVD contains the whole pyGiNaC source tree which is already patched and is ready to use.
There is also a possibility to use our library interactively with swiGiNaC , which is another Python binding for GiNaC and is included in many Linux distributions. The complete sources for binding our library to swiGiNaC are in the corresponding folder of the enclosed DVD. However, swiGiNaC does not implement full functionality of our library.
Once you have booted to the GUI with the open CAS window as described in Subsections 1.2.1 or 1.2.2, you may need to configure your keyboard (if it is not a US layout). To install, for example, a Portuguese keyboard, you may type the following command at the prompt of the open window:
In : !change-xkbd pt
The keyboard will be switched and the corresponding national flag displayed at the bottom-left corner of the window. For another keyboard you need to use the international two-letter country code instead of pt in the above command. The first exclamation mark tells that the interpreter needs to pass this command to the shell.
The first few lines at the top of the CAS windows suggest several commands to receive a quick introduction or some help on the IPython interpreter. Our CAS was loaded with many predefined objects—see Section 1.5. Let us see what C is, for example:
In : print C ------> print(C) [cycle2D object] In : print C.string() ------> print(C.string()) (k, [L,n],m)
Thus, C is a two-dimensional cycle defined with the quadruple (k,l,n,m). Its determinant is:
In : print C.hdet() ------> print(C.hdet()) k*m-L**2+si*n**2
Here, si stands for σ—the signature of the point space metric. Thus, the answer reads km−l2+σ n2—the determinant of the SFSCc matrix of C. Note, that terms of the expression can appear in a different order: GiNaC does not have a predefined sorting preference in output.
As an exercise, the reader may now follow the proof of Theorem 4.13, remembering that the point P and cycle C are already defined. In fact, all statements and exercises marked by the symbol on the margins are already present on the DVD. For example, to access the proof of Theorem 4.13, type the following at the prompt:
In : %ed ex.4.13.py
Here, the special %ed instructs the external editor jed to visit the file ex.4.13.py. This file is a Python script containing the same lines as the proof of Theorem 4.13 in the book. The editor jed may be manipulated from its menu and has command keystrokes compatible with GNU Emacs. For example, to exit the editor, press Ctrl-X Ctrl-C. After that, the interactive shell executes the visited file and outputs:
In : %ed ex.4.13.py Editing... done. Executing edited code... Conjugated cycle passes the Moebius image of P: True
Thus, our statement is proven.
For any other CAS-assisted statement or exercise you can also visit the corresponding solution using its number next to the symbol in the margin. For example, for Exercise 6.22, open file ex.6.22.py. However, the next mouse sign marks the item 6.24.i, thus you need to visit file ex.6.24.i.py in this case. These files are located on a read-only file system, so to modify them you need to save them first with a new name (Ctrl-X Ctrl-W), exit the editor, and then use %ed special to edit the freshly-saved file.
You can visualise cycles instantly. First, we open an Asymptote instance and define a picture size:
In : A=asy() Asymptote session is open. Available methods are: help(), size(int), draw(str), fill(str), clip(str), ... In : A.size(100)
Then, we define a cycle with centre (0,1) and σ-radius 2:
In : Cn=cycle2D([0,1],e,2) In : print Cn.string() ------> print(Cn.string()) (1, [0,1],-2-si)
This cycle depends on a variable sign and it must be substituted with a numeric value before a visualisation becomes possible:
In : A.send(cycle2D(Cn.subs(sign==-1)).asy_string()) In : A.send(cycle2D(Cn.subs(sign==0)).asy_string()) In : A.send(cycle2D(Cn.subs(sign==1)).asy_string()) In : A.shipout("cycles") In : del(A)
By now, a separate window will have opened with cycle Cn drawn triply as a circle, parabola and hyperbola. The image is also saved in the Encapsulated Postscript (EPS) file cycles.eps in the current directory.
Note that you do not need to retype inputs 12 and 13 from scratch. Up/down arrows scroll the input history, so you can simply edit the value of sign in the input line 11. Also, since you are in Linux, the Tab key will do a completion for you whenever possible.
The interactive shell evaluates and remember all expressions, so it may sometime be useful to restart it. It can be closed by Ctrl-D and started from the Main Menu (the bottom-left corner of the screen) using Accessories → CAS pycyle. In the same menu folder, there are two items which open documentation about the library in PDF and HTML formats.
There are several batch checks which can be performed with CAS. Open a terminal window from Main Menu → Accessories → LXTerminal. Type at the command prompt:
$ cd ~/CAS/pycycle/ $ ./run-pyGiNaC.sh test_pycycle.py
A comprehensive test of the library will be performed and the end of the output will look like this:
True: sl2_clifford_list: (0) True: sl2_clifford_matrix: (0) True: jump_fnct (-1) Finished. The total number of errors is 0
Under normal circumstances, the reported total number of errors will, of course, be zero. You can also run all exercises from this book in a batch. From a new terminal window, type:
$ cd ~/CAS/pycycle/Examples/ $ ./check_all_exercises.sh
Exercises will be performed one by one with their numbers reported. Numerous graphical windows will be opened to show pencils of cycles. These windows can be closed by pressing the q key for each of them. This batch file suppresses all output from the exercises, except those containing the False string. Under normal circumstances, these are only Exercises 7.14.i and 7.14.ii.
You may also access the CAS from a command line. This may be required if the graphic X server failed to start for any reason. From the command prompt, type the following:
$ cd ~/CAS/pycycle/Examples/ $ ./run-pyGiNaC.sh
The full capacity of the CAS is also accessible from the command prompt, except for the preview of drawn cycles in a graphical window. However, EPS files can still be created with Asymptote—see shipout() method.
Our C++ library defines the class cycle to manipulate cycles of arbitrary dimension in a symbolic manner. The derived class cycle2D is tailored to manipulate two-dimensional cycles. For the purpose of the book, we briefly list here some methods for cycle2D in the pyGiNaC binding form only.
C=cycle2D(k,[l,n],m,e) # Cycle defined by a quadruple Cr=([u,v],e,r) # Cycle with center at [u,v] and radius r2In both cases, we use a metric defined by a Clifford unit e.
C2=C.subject_to([C.passing([u,v]), C.is_orthogonal(C1)])where C2 will be a generic cycle passing the point [u,v] and orthogonal to C1. See the proof of Theorem 4.13 for an application.
Further information can be obtained from electronic documentation on the enclosed DVD, an inspection of the test file CAS/pycycle/test_pycycle.py and solutions of the exercises.
For convenience, we predefine many GiNaC objects which may be helpful. Here is a brief indication of the most-used:
C=cycle2D(k,[l,n],m,e) # A generic cycle C1=cycle2D(k1,[l1,n1],m1,e)# Another generic cycle Cr=([u,v],e,r2) # Cycle with centre at [u,v] and radius r2 Cu=cycle2D(1,[0,0],1,e) # Unit cycle real_line=cycle2D(0,[0,1],0,e) Z=cycle2D([u,v], e) # Zero radius cycles at [u,v] Z1=cycle2D([u1,v1], e) # Zero radius cycles at [u1,v1] Zinf=cycle2D(0,[0,0],1,e) # Zero radius cycles at infinity
The solutions of the exercises make heavy use of these objects. Their exact definition can be found in the file CAS/pycycle/init_cycle.py from the home directory.
This document was translated from LATEX by HEVEA.