Guidelines for SolarSoft Providers

Guidelines for SolarSoft Providers

Below are a set of guidelines for contributing software and data to SolarSoft. They are only suggestions, but is is hoped that following them will help contributors to maintain their part of the tree, and simplify SolarSoft for users.

Software

Software should be modular, i.e. split into reasonable sized chinks of code with identified purposes. As far as possible, these should be stored as individual routines in suitably named sub-directories. The only exceptions are blocks of closely coupled routine, e.g. those related to accessing a catalogue, or servicing a widget, where grouping the routines together makes it easier to make changes. In such cases, all the routines should have the same identifying prefix.

One thing that has to be done when a new branch is incorporated into the SolarSoft tree is to check for naming conflicts, that is whether a routine of the same name already exists within the tree. If conflicts are found, they must be eliminated otherwise the behaviour of the software would depend on which branches are present in a user's path, and their order. Routines that are instrument specific should include the name of the instrument. Thus, a routine to decompress the counts telemetered down from the instrument should be called xxx_decompress.pro (where xxx is the instrument identifier, e.g. sxt, cds, etc.) and not just decompress.pro.

Each routine, or block of routines should have document header that conforms to the guidelines in the IDL manuals. In particular, the name, purpose, calling sequence with an explanation of the variable, and history of the routine should be contained within the ";+" and ";-" delimiters of the document header.

Sub-directory Structure

The Yohkoh instruments and several of the SoHO instruments have been a part of SolarSoft for some time. Experience has shown that SolarSoft works best if an instrument tree is divided into a number of sub-directories with well identified functions. Many are possible, but suggested sub-directories are:

/doc

This sub-directory contains information on how to analyse the instrument data, and the meaning and use of and calibration and other ancillary files.

/idl

The /idl sub-directory contains the software used to calibrate and analyse the instrument data. It is important that extraneous material should not be included in this branch. Sub-directories under /idl are included in the path used by IDL and unnecessary directories will slow IDL down. Ideally the number of sub-directories should be kept to a minimum, and unnecessary depths of sub-directories should be avoided.

Contributed routines should be held in identified sub-directories. These should contain only software, and not unnecessary data files.

/calibration

This sub-directory contains files related to the instrument calibration. It is better if only simple, small calibration files are stored within th SolarSoft tree. Other, larger files that change with time are best stored in the /sdb tree - these could include dark current files, flat-field files, etc. Storing the information as a number of files allows users to copy only those files they need to analyse the observation they are interested in (software already exists that allows this). Seperating these files from the instrument branch ensures that the tar files used to install an instrument in the SolarSoft tree remains a reasonable length.

/catalogue

For a short duration experiment, it is possible to include the catalogue or observing log within the instrument branch of the SolarSoft tree. However, for instruments that observe over a long interval the catalogue is best stored under the /sdb tree. It is beneficial if the catalogue is split into files that cover a week, a month, or a number of months - whichever is easiest so long as the length of the file(s) remains a reasonable length. Again, splitting the file(s) allows user to copy the file(s) that covers the interval they are interested in, rather than having to copy the whole catalogue. Also, if the tree containing the catalogue is being mirrored by other sites, only the most recent file(s) need to be copied if an extra observation is added, rather than the whole, mission long catalogue.

/data

This directory should be used for any other small data files that are useful for data analysis, but are neither catalogue or calibration files.

R.D. Bentley, S.L. Freeland
5-May-1998