Programmers manual for the Nonius python library

This manual is meant for users that want to program their own scripts to control the KappaCCD, and also to help us at Nonius when we feel lost in the 10s of thousands of lines of code in the python library. It focuses on the non-GUI part of the code.

At this moment, this manual is about 48% complete. We're working on it.

What is python?

In the past, crystallographic software has been largely written in Fortran, and more recently also in C. With the development of the "collect" software, Nonius has broken with this tradition, and has embraced a very modern VHLL (Very High Level Language).

The use of such a language has a number of advantages:

• A lot of programming time can be saved because the low-level issues like memory allocation are taken care of by the language implementation.

• No need to develop an interactive extension language: the interpreter of the VHLL is perfectly suitable for that.

• Loads and loads of standardized modules exist for e.g. image manipulation and GUI development but also for Fourier transformations and solving systems of equations. All these modules can be easily linked together.

Many of these VHLL's are in use right now. To name a few: Tcl, Perl and Java.

Tcl and Perl have the problem that they were developed before the object oriented paradigm broke. Object orientation has been added at a later stage to these two languages, but the scars of the early days are clearly visible.

Java is a highly hyped language that looks a bit like C++. It has the big advantage that there is a lot of commercial push for it, but in practice there are lots of problems and support might be slower than for a really "free" language.

Nonius has chosen to use Python. On the Python Website we can find:

Python is an interpreted, interactive, object-oriented
programming language. It is often compared to Tcl, Perl,
Scheme or Java.
Python combines remarkable power with very clear
syntax.  It has modules, classes, exceptions, very high
level dynamic data types, and dynamic typing. There are
interfaces to many system calls and libraries, as well
as to various windowing systems (X11, Motif, Tk, Mac,
MFC). New built-in modules are easily written in in C
or C++. Python is also usable as an extension language
for applications that need a programmable interface.

The very clear syntax, and the object oriented design make this a very scaleable language: it is no problem to manage tasks from a 5 line script to a 60,000 line project like the "collect" program suite.

There is a very good tutorial to start learning python. You will feel that you can read python sources like your native language almost immediately...

In addition to the standard python interpreter, the Nonius software uses:

Tkinter

Python interface to the Tk widgetset.

Pmw

Python megawidgets (extension to the Tk widgets).

NumPy

Numerical python (modules to handle large arrays efficiently).

PIL

Python Imaging Library.

PyXML

Python library for XML data file handling.

PyOpenGL

Python bindings to the OpenGL 3D library.

Scientific Python

Some Scientific extensions to the python library.

Introduction to the Nonius Python library

The library has been implemented in a number of Python "packages". By far not all of the modules in these packages are described in this programmers manual, but most are mentioned here.

hwdriver

This package contains high-level and low-level drivers to the hardware interface. For the KappaCCD, the low-level interface is a Command Line Interface (CLI) to the SERVER program. There are different compatible high-level interfaces, which are described in this manual.

goniometer

This package contains classes to control goniometer positions (including calculations, rotations, and conversions), goniometer scans (including simulations), and some other operations that are supported by the KappaCCD hardware (for use in a graphical user interface).

experiment

This package contains a unit cell class (including cell reduction and standardization), crystal structure symmetry classes, corrections for distortion and unreliable pixels, information about the chemical elements, peak-search routines, and a few other modules.

filetype

This package contains interfaces to different file types. Most of the code is for handling KCD image files, but some support is there for the SPE file format. If this package is properly used, support for other file formats is transparent for the programmer.

interface

The interface package contains low-level interfaces to programs (mostly) outside of the collect suite that can be called from python code. Different modules exist to run some of the programs, and to read and interpret output files. Important interfaces are e.g. to run "DENZO-SMN", to control a "netscape" process, to send E-mail, to compress/uncompress files, and to read a "Denzo .X" file.

strategy

This package controls the generation of data collection strategies.

misc

This package contains a number of low level routines.

gui

Contains some generally applicable classes to make a Graphical User Interface (proxy classes and editor classes), and the specific modules that make up the collect program.

display

Contains the specific modules that make up the ndisp program.

There are a number of modules that are not in a package. Most of these can only be used as programs (scripts) for a single task (e.g. cifin, makesav), and are not as such part of the "library". The only one of the package-less modules to be described in the programmers manual is "projtls".

Making and running your own scripts

If you are creating your own scripts that use the Nonius python library, you need to let the python interpreter know that you want to use the Nonius library. For this goal there is a shell script called "npyrun".

A normal python program would be run using the command python script.py. If your script requires the Nonius library, you can use npyrun script.py instead. "npyrun" will tell the python interpreter where the Nonius library is before executing your program.

If you want to be able to run myprog arg1 arg2 instead of npyrun myprog.py arg1 arg2, you can make a shell script like:

#!/bin/sh
exec npyrun /home/me/nonius/myprog.py "$@"

Examples

The modules in the /usr/local/nonius/app/examples directory are available as source code. These can be used as a basis to build your own code.