Previous Up Next
Creative Commons License
This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.

Appendix C How to Use the Software

This is information about Open Source Software project Moebinv [211], see its Webpage1 for updates.

It is easier to use the MoebInv package than ever. The simplest options are:

  1. Download precompiled GUI for your OS. The GUI has self-contained help system, please use it for further advise.
  2. Work with Jupyter notebooks at your Web-browser. You can access these at either: Once you started a Jupyter notebook you can skip to Section C.3 for introduction.

The third possibility is live DVD (ISO image), its installation is explained in Section C.2. You can skip to Section C.3 if you are not using this route. The live DVD/ISO images are derived from several open-source projects, notably Debian GNU–Linux [309], GiNaC library of symbolic calculations [21], Asymptote [126] and many others. Thus, our work is distributed under the GNU General Public License (GPL) 3.0 [112].

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 [186]. A newer version of ISO is now included as an auxiliary file to the same paper, see the subdirectory:

http://arxiv.org/src/cs/0512073v11/anc

Also, an updated versions (v3.5.8) of the ISO image for amd64 architecture is uploaded to clouds:

https://tinyurl.com/rvhyyv2
https://drive.google.com/file/d/1I3XT91pfXY2BbZbxSOXJLfVvthSb4hkb/view?usp=sharing

.

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 C.1, C.2.1 and C.2.2.

C.1 Viewing Colour Graphics

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.

C.2 Installation of CAS

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 amd64 (or i386 for previous versions up to v3.0) 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.

C.2.1 Booting from the DVD Disk

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 C.2.2.

It is difficult to give an exact list of hardware requirements for DVD booting, but your computer must be based on the amd64 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 C.3.


Figure C.1: Initial screens of software start up. First, DVD boot menu; second, IDE screen after the booting.

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 [13] 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 C.1.

C.2.2 Running a Linux Emulator

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 amd64 architecture. I would recommend VirtualBox [271]—a free, open-source program which works well on many existing platforms. There are many alternatives (including open-source), for example: Qemu [31], Open Virtual Machine [272] 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 C.3. Some tips to improve your experience with emulations are described in the detailed electronic manual.

C.2.3 Recompiling the CAS on Your OS

The core of our software is a C++ library which is based on GiNaC [21]—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 [186] through LATEX.

Our interactive tool is based on pyGiNaC [50]—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 [307], 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.

C.3 Using the CAS and Computer Exercises

Once you have booted to the GUI with the open CAS window as described in Subsections C.2.1 or C.2.2, a window with Pyzo (an integrated development environment—IDE)) shall start. The left frame is an editor for your code, some exercises from the book will appear there. Top right frame is a IPython shell, where your code will be executed. Bottom left frame presents the files tree.


Figure C.2: IPython shell.

Pyzo has a modern graphical user interface (GUI) and a detailed help system, thus we do not need to describe its work here. On the other hand, if a user wish to work with IPython shell alone (see Fig. C.2), he may start the shall from

Main Menu→Accessories→CAS moebinv (ipython).

The presentation below will be given in terms of IPython shell, an interactions with Pyzo is even more intuitive.

Initially, 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 IPython prompt (e.g. the top right frame of Pyzo):

In [2]: !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.

C.3.1 Warming Up

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 [280]. Our CAS was loaded with many predefined objects—see Section C.5. Let us see what C is, for example:

In [3]: print C
------> print(C)
[cycle2D object]

In [4]: 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 [5]: 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 kml2n2—the determinant of the FSCc 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 13, remembering that the point P and cycle C are already defined. In fact, all statements and exercises marked by the symbol Mouse on the margins are already present on the DVD. For example, to access the proof of Theorem 13, type the following at the prompt:

In [6]: %ed ex.4.13.py

Here, the special %ed instructs the external editor jed to visit the file ex.13.py. This file is a Python script containing the same lines as the proof of Theorem 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 [6]: %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 Mouse in the margin. For example, for Exercise 22, open file ex.22.py. However, the next mouse sign marks the item 1, thus you need to visit file ex.1.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.

C.3.2 Drawing Cycles

You can visualise cycles instantly. First, we open an Asymptote instance and define a picture size:

In [7]: A=asy()
Asymptote session is open.  Available methods are:
    help(), size(int), draw(str), fill(str), clip(str), ...

In [8]: A.size(100)

Then, we define a cycle with centre (0,1) and σ-radius 2:

In [9]: Cn=cycle2D([0,1],e,2)

In [10]: 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 [11]: A.send(cycle2D(Cn.subs(sign==-1)).asy_string())

In [12]: A.send(cycle2D(Cn.subs(sign==0)).asy_string())

In [13]: A.send(cycle2D(Cn.subs(sign==1)).asy_string())

In [14]: A.shipout("cycles")

In [15]: 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.

C.3.3 Library figure

There is a high-level library figure, which allows to describe ensembles of cycles through various relations between elements. Let us start from the example. First, we create an empty figure F with the elliptic geometry, given by the diagonal matrix (

  −10
0−1

):

$ from figure import *
$ F=figure([-1,-1])

Every (even “empty”) figure comes with two predefined cycles: the real line and infinity. Since they will be used later, we get an access to them:

$ RL=F.get_real_line()
$ inf=F.get_infinity()

We can add new cycles to the figure explicitly specifying their parameters. For example, for k=1, l=3, n=2, m=12:

$ A=F.add_cycle(cycle2D(1,[3,2],12),"A")

A point (zero-radius cycle) can be specified by its coordinates (coordinates of its centre):

$ B=F.add_point([0,1],"B")

Now we use the main feature of this library and add a new cycles c through its relations to existing members of the figure F:

$ c=F.add_cycle_rel([is_orthogonal(A),is_orthogonal(B),\
$ is_orthogonal(RL)],"c")

Cycle c will be orthogonal to cycle A, passes through point B (that is orthogonal to the zero-radius cycle representin B), and orthogonal to the real line. The last condition characterises a line in the Lobachevsky half-plane. We can add a straight line requesting its orthogonality to the infinity. For example:

$ d=F.add_cycle_rel([is_orthogonal(A),is_orthogonal(B),\
$ is_orthogonal(inf)],"d")

We may want to find parameters of automatically calculated cycles c and d:

$ print F.string()

This produces an output, showing parameters of all cycles together with their mutual relations:

infty: {(0, [[0,0]]~infty, 1), -2} --> (d);  <-- ()
R: {(0, [[0,1]]~R, 0), -1} --> (c);  <-- ()
A: {(1, [[3,2]]~A, 12), 0} --> (c,d);  <-- ()
B: {(1, [[0,1]]~B, 1), 0} --> (c,d);  <-- (B/o,infty|d,B-(0)|o,B-(1)|o)
c: {(6/11, [[1,0]]~c, -6/11), 1} --> ();  <-- (A|o,B|o,R|o)
d: {(0, [[-1/6,1/2]]~d, 1), 1} --> ();  <-- (A|o,B|o,infty|o)
B-(0): {(0, [[1,0]]~B-(0), 0), -3} --> (B);  <-- ()
B-(1): {(0, [[0,1]]~B-(1), 2), -3} --> (B);  <-- ()

Note, two cycles B-(0) and B-(1) were automatially created as "invisible" parents of cycle (point) B.

Finally, we may want to see the drawing:

$ F.asy_write(300,-1.5,5,-5,5,"figure-example")

This creates an encapsulated PostScript file figure-example.eps, which is shown on Fig. C.3. See [211] for further documentation of figure library. Examples include symbolic calculations and automatic theorem proving.


Figure C.3: Example of figure library usage.

C.3.4 Further Usage

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 1 and 2.

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.

C.4 Library for Cycles

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.

constructors
There are two main forms of cycle2D constructors:
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 r2
In both cases, we use a metric defined by a Clifford unit e.
operations
Cycles can be added (+), subtracted (-) or multiplied by a scalar (method exmul()). A simplification is done by normal() and substitution by subs(). Coefficients of cycles can be normalised by the methods normalize() (k-normalisation), normalize_det() and normalize_norm().
evaluations
For a given cycle, we can make the following evaluations: hdet()—determinant of its (hypercomplex) FSCc matrix, radius_sq()—square of the radius, val()—value of a cycle at a point, which is the power of the point to the cycle.
similarities
There are the following methods for building cycle similarities: sl2_similarity(), matrix_similarity() and cycle_similarity() with an element of SL2(ℝ), a matrix or another cycle, respectively.
checks
There are several checks for cycles, which return GiNaC relations. The latter may be converted to Boolean values if no variables are presented within them. The checks for a single cycle are: is_linear(), is_normalized() and passing(), the latter requires a parameter (point). For two cycles, they are is_orthogonal() and is_f_orthogonal().
specialisation
Having a cycle defined through several variables, we may try to specialise it to satisfy some further conditions. If these conditions are linear with respect to the cycle’s variables, this can be achieved through the very useful method subject_to(). For example, for the above defined cycle C, we can find
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 13 for an application.
specific
There are the following methods specific to two dimensions: focus(), focal_length()—evaluation of a cycle’s focus and focal length and roots()—finding intersection points with a vertical or horizontal line. For a generic line, use method line_intersect() instead.
drawing
For visualisation through Asymptote, you can use various methods: asy_draw(), asy_path() and asy_string(). They allow you to define the bounding box, colour and style of the cycle’s drawing. See the examples or full documentation for details of usage.

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.

C.5 Predefined Objects at Initialisation

For convenience, we predefine many GiNaC objects which may be helpful. Here is a brief indication of the most-used:

realsymbol.
a, b, c, d: elements of SL2(ℝ) matrix.
u, v, u1, v1, u2, v2: coordinates of points.
r, r1, r2: radii.
k, l, n, m, k1, l1, n1, m1: components of cycles.
sign, sign1, sign2, sign3, sign4: signatures of various metrics.
s, s1, s2, s3: s parameters of FSCc matrices.
x, y, t: spare to use.
varidx.
mu, nu, rho, tau: two-dimensional (in vector formalism) or one-dimensional indexes for Clifford units.
matrix.
M, M1, M2, M3: diagonal 2× 2 matrices with entries −1 and i-th sign on their diagonal.
sign_mat, sign_mat1, sign_mat2: similar matrices with i-th s instead of sign.
clifford_unit.
e, es, er, et: Clifford units with metrics derived from matrices M, M1, M2, M3, respectively.
cycle2D.
The following cycles are predefined:
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.


1
site search by freefind advanced

Last modified: October 28, 2024.
Previous Up Next