Programming guidelines

Programming guidelines

Introduction?

Introduction

FABLE is the proposed software framework for the Total Crystallography project. The Total Crystallography (TC) project has been officially accepted as a European NEST proposal. This means more resources and more programmers for FABLE. In order to make sure that the code produced by the programmers in the various collaborating institutes can function together it is important to define programming guidelines. This document is a proposal for such guidelines.

Goal?

Goal

The aim of the TC project is to produce working software which can be used online for preparing TC experiments and analysing data online, and which can be distributed to users to continue the analysis of their data at their home institute. The algorithms to be implemented will be defined by the TC team. The goal of this document is to define a common mechanism which will ensure that the code produced in the different institutes works together.

Library?

Library

In order to integrate the various codes together it is necessary that they be written as reusable modules and not as monolithic blocks of code which can only run as a standalone programs.
One obvious way to achieve this is that the code in each module be written as a library of routines. In order to be usable as a library a few basic rules must be followed :

1. The routines in each module must be callable via an application programmer's interface (API).
2. The module must not depend on any input other than that passed via the API.
3. The modules must not contain any user interface code (graphical or command line prompts).
4. A module can depend on other modules by calling them via their API
5. A module must document the function, input and output parameters of each API call.

Application_Programmer_Interfaces?

Application Programmer Interfaces

All modules will be accessed via their API's. In order to ensure API's are well defined and easily integrated into TC here are some guidelines on how to define API's :

1. give each call a name which indicates its function e.g. find_blobs()
2. use lower case for names, separate words with underscores
3. try to limit the number of input and output arguments to a minimum
4. where multiple input and/or output arguments are required use generic type arrays to pass the arguments instead of complicated structures e.g. use double my_argin[10] as opposed to struct my_argin{type1 field1; type2 field2; ...}

Testing_modules?

Testing modules

Modules need to be tested. Each module must provide a testsuite of programs which will call each of the API calls and demonstrate their functioning. The test programs can be written in Python, C++/C, Java. A good way of writing testsuites is to use the Unit Test1 framework. Implementations of the Unit Test framework exist for most common languages.

Example_code?

Example code

Examples must be provided with each module on how to use the module.

Documentation?

Documentation

All algorithms and api's must be documented. It is suggestd that the algorithms be documented outside the code (a brief description should be included in the code). API's should be documented in the code using the doxygen2 markup language. The name, function, input and output parameters must be documented.

Programming_Languages?

Programming Languages

FABLE will support a subset of commonly used programming languages. These are :

• C++/C
• Python
• Java

Other languages like Fortran must be wrapped with one of the above languages in order to be integrated in TC. Matlab is envisaged to be used for prototyping algorithms but not as part of the final product.

Graphical_User_Interface?

Graphical User Interface

One of the fundamental aims of TC is to provide users with a user-friendly interface. The graphical user interface (gui) will enable a user to analyse an entire experiment using the user interface. The user interface will call the API's or device servers (in the distributed case) or scripts. The TC gui will be written in Java using the Eclipse Rich Client Platform3 technology.

The user interface is the part of a program a user sees most. She spends most of her time in front of it and uses it to provide input and visualise output from the underlying program(s). The user interface therefore plays a major role for any program. A program is often judged by its user interface.

Golden Rule

FABLE must respect the golden rule for developing user interfaces no matter which technology is used :

SEPARATE USER INTERFACE IMPLEMENTATION FROM ALGORITHM IMPLEMENTATION

In simple terms this means do not embed scientific or any other non user interface algorithms in user interface code. Doing so mixes two different domains and makes it very difficult to reuse or refactor the code later on. Usually user interfaces change quicker than algorithms and it is essential to keep the two separate so they can evolve independantly. There are many ways of implementing the user interface. A proposal made today may be obsolete in 5 years.

Scientific Workbench

The FABLE User Interface will be based on the Workbench concept. A workbench is much more than a desktop. It provides useful tools for doing your work and manages the work being done by providing window management, sets of windows to solve specific tasks (perspectives), views, help, tutorials and mechanisms for coordinating tasks. The workbench will make the tasks of simulation, data acquisition, offline and online analysis accessible from one tool. It is proposed that the FABLE user interface be implemented using Eclipse/RCP. The reasons for doing this are outlined on the Eclipse - RCP page.

The User Interface Requirements lists the modules which need to be developed. The [Plugins] page lists the modules which are currently being developed.

Scripting?

Scripting

Scripting is a fundamental part of TC. It will be possible to analyse an entire experiment using scripts. Python will be the main scripting language.

Distributed_Computing?

Distributed Computing

The TC software will be capable of being distributed over a number of computers in order to increase performance e.g. by using a farm of computers. Distribution of tasks over multiple computers will be done using device servers. Device servers wrappers will be provided for all the modules. The wrappers will call the API's and export their functionality over the network. Data will be shared between processes via shared memory.

Data_Format?

Data Format

Propose to use Nexus with the option to read/write ImageCIF and EDF

I.2FO_Library?

I/O Library

Need an input/output library common to all modules

Database?

Database

Propose to use MySQL

Software_Sharing?

Software Sharing

All code to be stored on Sourceforge4 in CVS. A Fable project already exists. Should we use it or create a new project ? License will be GPL and LGPL

Programming_Environment?

Programming Environment

In order to develop TC software it is recommended to install the following software :

1. GNU C++/C compiler
2. Python
3. Eclipse IDE
4. C and Python eclipse plugins
5. I/O library
6. MySQL (if database option is required)
7. Matlab/Octave (if running of matlab code is required)
8. TACO and TANGO (if distributed option is required)