Glossary: Precisely what do you mean by...


Backward Compatibility
Circuit and Cable Numbering Schemes
Command Files
Data Structure
Data Structure Document
Development Release
Official Release
Post-Release
Programmer Manual
Run Header
SNOMAN
SNOMAN Version Number
Software Cycle
Software Units (SUs)
Titles Bank
Titles Files
Update Files
User Manual
Validity Range
ZEBRA



Glossary: SNOMAN

SNOMAN is the SNO Monte carlo and ANalysis program.

For further information see:-

Glossary: User Manual

Contains a general description of the code, including a general overview of the many packages (EXTRACT, ZEBRA, CERNLIB, PAW) which the program requires. There are also descriptions of the major groups of routines which make up the program (Event generation, Photon Transport, etc.). The User's Manual also contains instructions for obtaining and running the program, which hopefully will allow the user to get SNOMAN running at their institution. These will all hopefully be kept updated as the project progresses. The first-time user and anyone uncertain about how to proceed should probably consult these documents first.

The User Manual can be found in the directory:-

.../snoman/n_nn/doc/user
and a zipped postscript version in:-

.../snoman/n_nn/doc/user_manual.ps.gz

It is also available in HTML form

Glossary: Software Units (SUs)

The SNOMAN code is not a single monlith; instead it is divided into a series of Software Units each of which have their own initialisation, execution and termination routines.

For further information see:-

Glossary: Data Structure Document

The Data Structure Document gives an overview of the SNOMAN Data Structure Note that the section on showing how it might be accessed has been moved to the section "Writing Code to Access the Structure" of the chapter "Adding Code to SNOMAN" of the User Manual

The Data Structure Document can be found in the file:-

.../snoman/n_nn/doc/banks/data_structure.tex

For further information see:-

Glossary: Command Files

Command Files are files containing a series of one or more SNOMAN commands. They can be nested i.e. one command file can invoke others. They provide a convenient way of issuing standard sets of commands to SNOMAN.

For further information see:-

Glossary: Titles Files

Titles Files are files containing one or more Titles Bank in ASCII format.

Glossary: Data Structure

The Data Structure is the main internal data within SNOMAN. FORTRAN 77 has no data structuring capability, so SNOMAN uses the CERN memory manager ZEBRA. ZEBRA supports a set of named and numbered banks that are connected into a simple tree using structural links. Any number of additional links, called reference links, can be added to connect any banks together to expression any required relationship.

For further information see:-

Glossary: Programmer Manual

Contains a set of documents relating to the desired procedure for changes to be made to SNOMAN. These outline the code management procedures which we will try to follow to minimize confusion. They also show the progammer what files must be changed in order to modify the code, and how to add new banks.

The Programmer Manual can be found in the directory:-

.../snoman/n_nn/doc/programmer
and a zipped postscript version in:-

.../snoman/n_nn/doc/programmer_manual.ps.gz

It is also available in HTML form

Glossary: Titles Bank

Titles Banks are banks of information that:-

For further information see:-

Glossary: ZEBRA

ZEBRA is a memory manager prackage written at CERN. It can be used in conjunction with a FORTRAN program to create linked data structures.

For further information see:-

Glossary: Validity Range

Some Titles Banks describe detector data. As the detector changes with time, so the data has to change with time. This is achieved by having multiple versions of the bank, each with a date time validity range. One of the functions of the Constants Management system is to ensure the right version is selected for each event.

For further information see:-

Glossary: Software Cycle

The development of a release of SNOMAN goes throught the following phases:- If you look at the first line of the SNOMAN log file, you take tell exactly what the release is from the Version Number

At any time all 3 versions are available and then you have to decide Which version of SNOMAN do I want?

Glossary: Development Release

Development Releases have Version Numbers of the form n.nn80, n.nn81, n.nn82 ... e.g. 30081. They increment each time there is a new development release or a backward incompatible change to the data. In the latter case the increment allows EIO detect and reformat the old data.

The Development Release is the first phase in the Software Cycle. During development, releases may be made to help in the development. In particular they may be made to:-

People will be free to build non-standard development release versions. If they do so then, when the program runs, it will:-

Development releases to not have the same level of support as an Official Release . In particular:-

During development, bugs found or fixed are reported to the software list and recorded in the file:- 

      ../snoman/n_nn/doc/release/dev_bugs.doc
If they apply to the previous release then the may be made available to those who wish to run with a Post-Release version of the previous release.

See also FAQ: Which version of SNOMAN do I want?

Glossary: Official Release

Official Releases have Version Numbers of the form n.nn00, n.nn01, n.nn02 ... e.g. 30001.

The Official Release is the second phase in the Software Cycle. At an appropriate time, the version of SNOMAN is frozen, all documenation is brought up to date, and a release is made. If serious problems come to light in the next few weeks, something that can happen when people start using it in anger of a number of different platforms!, then the code is fixed and updates copied into the special directory:-

../snoman/n_nn/bug_fixes so that there is no need to copy the full release again. The fixes are also added to the standard directories so that getting and installing a fresh copy will include them.

After that, the code is frozen and is NOT changed again. Permanent data sets can be made safe in the knowledge that the code that produced them can always be recovered. However, for some, the need to install bug fixes, that arrive too late to be part of the official release, outweigh the need for stability. For these people, Post-Release versions can be made.

See also FAQ: Which version of SNOMAN do I want?

Glossary: Post-Release

Post-Releases have Version Numbers of the form n.nn50, n.nn51, n.nn52 ... e.g. 30051.

The Post-Release is the last phase in the Software Cycle. After an Official Release has been frozen, it will NOT be changed again. However, for some, the need to install bug fixes, that arrive too late to be part of the official release, outweigh the need for stability. The Post-release version is provided for these people.

Post-release fixes go into the directory:-

../snoman/n_nn/post_release People will be free to build non-standard post-release versions by combining this directory with the standard directories. If they do so then, when the program runs, it will:-

The file:-

../snoman/n_nn/doc/release/dev_bugs.doc in the next, Development Release , will indicate if the fix has also be provided for the previous version, and hence will be in the post-release directory. Support for post-release versions will be strictly limited:-

See also FAQ: Which version of SNOMAN do I want?

Glossary: Run Header

The Run Header is a special data structure, present at the start of every run of real data, that holds information that is global to the entire run that follows. If a file contains multiple runs, there will be multiple headers. Run Headers are processed in the following way:- This scheme ensures that Run Headers are transmitted through SNOMAN; they appear on the output file if they were present on the input file. The copy kept in division 2 is available to any code that requires it at any point throught the run.

SNOMAN Version Number

The first line of the SNOMAN log file gives the base and current SNOMAN version numbers. For example:- SNOMAN version 3.02/3.0184 Means that the base version is 3.02 but the current version is 3.0184. Version numbers are 5 digit numbers of the form:- 
  n.nnbb

  where  n.nn is a base version number  e.g. 3.02

         bb   is a subversion number:-

              00            Official Release 
              01,02,03 ... For bug fixes to the  Official Release 
              50,51,52 ... For bug fixes to the  Post-Release  
              80,81,82 ...   Development Release
For development releases the base version will be the next offical release version. So the way to read 3.02/3.0184 is that it is a development release on the migration between 3.01 and 3.02. Other examples:- SNOMAN version 3.02/3.0201 First bug fix of the Official release 3.02 SNOMAN version 3.02/3.0252 Third bug fix of the Post-Release 3.02

Backward Compatibility

Since SNOMAN Version Number 2.08 we have tried, when changing the Data Structure to retain the ability to read the old structure. When old data is detected by Event I/O Support it calls the appropriate reformating routines. Of course, the reformatting may be less than perfect; if the new version of a bank has additional data there is nothing that can be done beyond ensuring that the bank is the right size. For details about how old versions of the data structure are converted see EIO_I_REFORMAT

Circuit and Cable Numbering Schemes

Signals from all PMTs together with additional calibration source signals, get fed into 19 crates of electronics, each with 16 cards of 32 channels. This gives a total of 9728 circuits, each with its own DAQ Circuit Number and Logical Circuit Number . Cables to these channels are identified both by a Cable Barcode and by a Cable Label These schemes, and the relationships between them and the Crate, Card and Channel Numbers are the subjects of this entry in the glossary.

Crate, Card and Channel Numbers

Within SNOMAN we use logical numbers i.e. a numbering scheme that starts at zero:-

Crate There are 19 crates numbered 0 .. 18.
Card There 16 cards numbered 0 .. 15. Viewed from the back of the crate (i.e. where the cables come in), card 0 is the leftmost and card 15 the rightmost.
Channel There 32 channels numbered 0 .. 31. Channel 0 is the bottom channel and 31 the top.

The use of the term 'logical' is an attempt to minimise the confusion between those people who think it natural to number from 0 and those who always thought that numbering started at 1. The idea is that if people get into the habit of talking about, for example, "logical channel 5 in logical card 2 of logical crate 10", it will make the listener stop and think!

DAQ Circuit Number (or CCC)

DAQ Circuit Numbers are defined by the relationship:- DAQ_Circuit_Number = 1024 * logical_card + 32 * logical_crate + logical_channel

DAQ Circuit Numbers are often referred to as CCC (card/crate/channel). It is these numbers that are used by the DAQ and in the event structure PIF and PMT banks.

Logical Circuit Number (or LCN)

Logical Circuit Numbers are defined by the relationship:- Logical_Circuit_Number = 512 * logical_crate + 32 * logical_card + logical_channel

They contain the same information as the DAQ Circuit Numbers, its just that the crate and card fields are interchanged. The term "logical" is justified as the field ordering reflects priority. The DAQ Circuit Numbering scheme has gaps, corresponding to the missing crates (logical numbers 19 to 31), but the logical circuit numbers do not have this disadvantage. For this reason, titles banks that have electronic calibration data that has to be accessed by circuit number e.g. the Q1AV bank, are stored by Logical Circuit Number. Although the mapping from DAQ Circuit Number to Logical Circuit Number is trivial, the conversion routine map_ccc_lcn is provided for completeness.

Cable Barcode

Each cable has a barcode of form Exxx where xxx is a 3 letter code ( AAA through ZZZ ). The routine map_ccc_cable_barcode provides a mapping between DAQ Circuit Number and the barcode.

Cable Label

Each cable has a human readable label of form:- X.Y.zz

where:-

Due to changes made in the cabling layout after the original design was completed, there is a departure this scheme for crates D,N,R,S:-

There is a second, temporary, departure due changes from the original design:-

Although the cables are correctly labelled, the Queens PMT Database will not be updated while the build is in progress, to avoid the risk of confusion. The routines map_ccc_cable_label and map_cable_label_ccc provides a mapping between cable labels and DAQ Circuit Numbers but do not allow for the temporary departure mentioned above as this should only be applied when reading the Queens database.

Update Files

Sometimes updates to an official or development release are issued. Updates are not a complete release, they simply contain the files that have changed since the last release. Update files typically have the following file name convention:- ver_update_dd_mmm.tar.gz e.g. 3_0180_08_jul.tar.gz where:- ver = version on which update is based dd_mmm = day and month of update The code directory of an update contains the file:- update_log.doc which gives the range of dates used to select files. If more than one update is issued between releases each will contain everything since the last official or development release; so at most one update file is needed - it is never necessary to apply a succession of them.

Note: The only purpose of update files is to keep people right up to date with changes to the code. However, these are not releases, just intermediate stages in development - there will be no change in version number. No attempt will be made to keep copies of these stages nor are any promises made about the documentation! You have been warned!

Warning: These updates files are often built on VMS machines and the tar files they produce are sometimes terminated oddly. If, while unpacking, you get a message something like:-

tar: - : This doesn't look like a tar archive tar: - : Skipping to next file... tar: Ready for volume 2 tar: Type "go" when ready to proceed (or "q" to abort): just quit, the complete file has been unpacked.

On UNIX, the tools have been modified to make installing updates as painless as possible. For details about installing update files see:- 

    $SNO_TOOLS/install.doc