Programming guidlines

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.

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)