MINOS Offline Software Requirements (v 09/15/00 )



Table of Contents



1 Introduction

2 General Offline Requirements 3 Event Display 4 Reconstruction 5 Simulations 6 Detector Information 7 Data Base

8 Framework

1 Introduction

This document lists the requirements for all of the MINOS offline packages. The order the packages are listed roughly correspondes to the order of their dependency; packages listed first depend on packages listsed after them. This roughly coresponds to the order of importance of the package to the "physicist programmer". The requirements for the offline system as a whole are listed first.

The requirements for each package are subdivided into labeled categories in the order of importance. For example:

A2: Requirements should be listed in this format (1)
Is the second requirement in section A and is of primary importance. (This format is not yet uniform across all sections).

Each package is listed with the e-mail address for the coordinator of that package. If you have comments or suggestions for additional requirements please e-mail the package coordinator. The document is maintained and edited by messier@huhepl.harvard.edu. Please send general comments there.


2 General Offline Requirements

Contact: gmeig@slac.stanford.edu

These are the requirements for the MINOS offline system taken as a whole.

2.1 Documentation

  • D1: The framework should be well documented and easy to learn. (1)
  • D2: The framework should be easy to maintain. (1)
  • D3: Code revisions should be tracked and recorded; it should always be possible to recover the source code used to generate a physics result.

    2.2 Performance

  • P1: To keep pace with the data, the reconstruction should be able to handle roughly 100 events in 20 CPU seconds. This correponds to 10 CPU's processing 100 events in the time between spills.
  • P2: The required Monte Carlo simulations for physics analysis should take no more than one month to generate, track, and reconstruct. (1)
  • P3: Reconstruction jobs should be easy to move from site to site. For example, it should be possible to run simple reconstruction jobs on a laptop computer that is not connected to a network.

  • 3 Event Display

    Contact: "George Irwin" gmieg@slac.stanford.edu

    3.1 User Interface

  • Interface through menus and buttons with keyboard accelerations. Most common display manipulations should be buttons; less common actions should be in menus.
  • Ability to define macros.
  • Should have run/event search mechanism
  • Should allow user to apply ntuple cuts on events before they are displayed
  • Supply online help

    3.2 I/O

  • Should accept data from both online and offline data streams
  • Should allow user to save selected events to separate file

    3.3 Visualization

  • Support multiple geometries including near detector, far detector, (calibration module and Soudan II??) events using a similar interface and be able to change from one to the other on the fly
  • Allow events to be displayed in multiple projections including:
  • Ability to rotate and zoom views.
  • Views should be rendered optionally as wire-frame and solids.
  • Views should be rendered using multiple graphics drivers.
  • Ability to display graphics remotely.
  • Ability to add custom views
  • Provide drawing tools to allow text, arrows, lines etc. to be added to the display
  • Allow for generation of conference-quality hard copies in various formats including .ps, .eps and .pdf.

    3.4 Event Information and Data

  • Display detector response in both time and charge mode.
  • View detector response in text/table format
  • Allow for display of reconstruction information including: in both graphical and text/table formats.
  • Allow for display of Monte Carlo information in both graphical and text/table formats
  • Allow display of common event and user histograms
  • Provide hooks to allow for special user draw and analysis routines

    3.5 Analysis

  • Ability to drive reconstruction with altered parameters and hits.

  • 4 Reconstruction

    4.1 User Requirements

  • These need to be supplied as part of a coordination effort with currently non-existent analysis groups.

    4.2 Functional Requirements

  • Packages envisioned to partially fulfill anticipated framework requirements to support reconstruction activities include:

  • 4.3 Candidate Model

    Contact: "George Irwin" gmieg@slac.stanford.edu

    4.4 Candidate Definition

  • Any reconstructed object:

    4.5 Requirements for Candidate classes

    1. Encapsulate attributes of reconstructed objects.
    2. Provide mechanism to Set and Get reconstructed object attributes.
    3. Allow co-existence of multiple versions of the same Candidate type.
      • Calculated by different Algorithms.
      • Calculated by different invocations of the same Algorithm, perhaps with different Algorithm parameters or for differing event input.
    4. Facilitate ones ability to understand or to rebuild a Candidate object based on history information recorded in each instance of a Candidate object.
    5. Ability to write out Candidate objects to persistent store.
    6. Ability to retrieve Candidate objects from persistent store.
    7. Provision for making a transient modification to an existing Candidate object, from either a transient or permanent source, without perturbing other users of the same Candidate object, either within or outside of the same analysis process or "thread" where the modification is made.
    8. Ability to commit a modified transient object to permanent store.
    9. Machinery to define and test "equality" or "overlap" of Candidates.
    10. Automatic deletion of unneeded Candidate objects from memory.
    11. A concrete Candidate object must be sufficiently configured at creation that the Candidate is mechanically functional. This insurance should not depend on user invocation of a separate initialization method subsequent to Candidate creation.

    4.6 Proposed Strategies to Achieve Requirements

  • (adapted in part from Babar BtaCandidate classes)

  • 4.7 Algorithm Support

    Contact: "George Irwin" gmieg@slac.stanford.edu

    4.8 Algorithm Definition

  • A class which contains the code to calculate or modify the attributes of a Candidate object, including the "daughter" list.

    4.9 Requirements for Algorithm classes

    1. Algorithm must be configurable with default parameter set (from database, e.g.), but allow user to reset parameters dynamically.
    2. Algorithm identifier and configuration parameters must be captured by each Candidate object for its history record.
    3. Algorithm objects must be managed to prevent memory leaks.

    4.10 Proposed Strategies to Achieve Requirements

    1. Concrete Algorithm object is "stateless". (It may contain limited "intrinsic state" which is integral to the Algorithm or expensive to reconfigure.)
    2. Concrete Algorithm object gets its configuration parameters from an AlgConfig object which encapsulates Algorithm "extrinsic state". The user can override parameter settings in the AlgConfig object dynamically.
    3. Concrete Algorithm object and AlgConfig object are packaged in an AlgHandle object which is passed to the constructor of a concrete Candidate object.
    4. Concrete Candidate constructor runs the Algorithm and logs the concrete Algorithm ID and AlgConfig information.
    5. Concrete Algorithm objects are instantiated and owned by an AlgFactory, which loans them out pre-packaged with AlgConfig in an AlgHandle.

  • 5 Simulations


    5.1 Detector Simulation


    5.2 Neutrino Generator

    Contact: gallag@hep.umn.edu

    NEUGEN will be a neutrino scattering application. One common use shall be as a reliable, modular, comprehensively tested event generator for use in Monte Carlo simulations. It will be able to provide additional information related to neutrino scattering in a user-friendly fashion.

    5.2.1 General Requirements

  • G1: The physics should be correct. (1)
  • G2: NEUGEN will generate neutrino interactions of all flavors over the energy range 10 MeV - 100 GeV. (1)
  • G3: All relevant (known) reactions in the energy range of interest will be included. (1)
  • G4: The physics content of the generator should be accessible. (1)
  • G5: Will serve as the event generator for MINOS simulations using beam and atmospheric neutrinos. (1)
  • G6: Will be MINOS-independent, should not have dependencies on any MINOS packages. (2)
  • G7: Where possible, shall attempt to reuse classes developed for other large HEP applications (particle, cross section classes?). (3)

    5.2.2 Functional Requirements

  • F1: Black-box use will be encouraged / supported - defaults for parameters will be "best values". It should be apparent when the generator is running in non-default mode. (1)
  • F2: Should be capable of running in standalone mode for fast MC simulations, without geometry packages, etc... (2)
  • F3: Users should be able to examine cross sections for specific processes. (2)
  • F4: Users can determine uncertainty on cross sections (3).

    5.2.3 User Interface Requirements

  • U1: Should provide an easy user interface to control selection of physics models and parameters. (1)
  • U2: Users should be able to determine the physics process responsible for any given event. (1)
  • U3: Users should be able to replace packages with their own. (2)

    5.2.4 Error Handling Requirements

  • E1: All error and warning messages must be intelligible and traceable. (1)
  • E2: Error messages should provide enough information about te state of the system at the occurrence of the fault that the condition is easily reproduced. (2)

    5.2.5 Output Requirements

  • O1: The version and settings of the generator shall be recorded with the data for each run. (2)
  • O2: Event generation should be reproducible given the same initial configuration. (3)
  • O3: Shall provide distributions of important kinematic variables at the end of each run or other information summarizing the run as a whole (#s of NC, CC events, ...). (3)

    5.2.6 Validation Requirements

    All models will be: Documented, Verified, Fully Implemented
  • V1: Documented: A description of the underlying physics will be required. (3)
  • V2: Verified: All models incorporated into the generator shall have their output compared to data where available to determine the optimum settings for running in default mode. (1)
  • V3: Fully Implemented: Events can be generated using this model, users have control over all adjustable parameters. (1)
  • V4: All information related to the validation or verification of the package should be contained within the package. (2)

    5.2.7 Constraints

  • C1: Shall use ROOT as the framework. (1)
  • C2: Shall run on every system where MINOS code will be supported. (1)
  • C3: Shall run quickly (to be specified). (1)

  • 5.3 Neutrino Flux Tables

    Contact: messier@huhepl.harvard.edu

    This package will provide an interface for users who want to know the neutrino flux in the regions inside, and surrounding the MINOS detectors.

    5.3.1 General

  • G1: The calculation of the total and differential flux should reproduce the beam simulations to a few parts in 10^4 as to be neglible compared to the target of 2% near/far uncertainty. (1)
  • G2: The interface should be the same for all flux tables and the same for both detectors. (1)
  • The interface to the user should use a consistent reference frame. ie. xyz-axes relative to the detector coordinate system. (1)
  • G3: The tables provided should include: (1)
  • G4: There should be interfaces for: (2)

  • 5.4 Beam Line Simulation

    Contact: messier@huhepl.harvard.edu

    5.4.1 General

  • G1: Provide an detailed, accurate, fast, and efficient GEANT simulation of the NuMI beam line
  • G2: Allow for variations of critical variables (positions, alignments, currents, etc.) and provide an easy way for users to input these or to have them read from a data base.
  • G3: Allow simulation of actual integrated run conditions (horn positions, currents etc.)

    5.4.2 Output

  • O1: Output should be in ntuple format O2: For each neutrino, output data should include: (1)

    5.4.3 Beam Monitoring

  • BM1: Provide a run mode useful for tests of beam monitor performance including: (1)
  • BM2: Provide a simulation of monitor chambers which can be turned on/off depending on the application (1)

  • 6 Detector Information


    6.1 Magnetic Field

    Contact: costas@fnal.gov

  • The B field classes should reproduce the FEA calculation with an accuracy of a few parts in 10000.

  • 6.2 Unified Geometry Layered Interface: Ugli

    Contact: rhatcher@SLAC.Stanford.EDU
  • Support mechanism for building and managing simultaneous versions of the geometry at one time.

  • Build a geometry native to the simulations framework (e.g. GEANT3 or GEANT4). At least for GEANT3 there must be a mechanism that regenerates this as reference changes from one version to another since GEANT3 is only capable of managing a single geometry at a time.

  • Build a geometry compatible with the event display package (i.e. ROOT).

  • For a given (x,y,z) given in a global coordinate system determine the material type.

  • Translate between local (e.g. strip) and global (detector) coordinate systems.

  • Provide information about the detector's configuration:

  • Provide support for navigation and collections of hits, digits which are grouped hierarchically into collections by strips, planes, detector subsections (supermodules) and finally the detector as a whole. While the geometry package doesn't actually do the work it should provide a natural means of helping to organize the information.

  • Provide access (navigational only?) to related information such as fiber tail and clear connector lengths; MUX associations (fiber   «  pixel  «  tube).

  • Given a position return the distance to the nearest surface (change of material).

  • Future: Given a position and direction find the distance to the next surface (change of material).


  • 7 Data Base

    Contact: border@mnhepw.hep.umn.edu

    Please see the data base www pages:

    and in particular the use case page:

    8 Framework


    8.1 Job Control Shell

    Contact: messier@huhepl.harvard.edu

    The Job Control shell will provide a framework for analyzing data. It will provide an interface to the resources provided by the MINOS framework and to offline reconstruction and calibation modules, allowing these modules to be organized into analysis "jobs".

    8.1.1 General

  • G1: The job control shell should work identically on near and far detector data. (1)

    8.1.2 Job Configuration

  • C1: The shell will provide an interface to configure framework packages, including: (1)
  • C2: The shell will provide an interface to specify the modules to be used in the job and their order. (1)
  • C2: The shell will provide an interface to configure analysis/reconstruction modules (1)
  • C3: The shell will provide notification of major state changes, including: or the equivalent (ie. whatever defines a "run").
  • C4: The shell will provide access to or the equivalent (ie. whatever defines an "event?"). Modules will have separate entry points for methods that require read-only access to the data as well as methods that need to alter the data.(1) C5: The shell will provide access to other module-specific entry points. (2)
  • 8.1.3 User interface

  • U1: Jobs should be able to run batch mode. (1)
  • U2: Jobs should be able to run interactive mode (1)
  • U3: Options should be settable from either the command line or input macro file. (1)
  • U4: Options should include: (1)
  • U5: The job control shell will supply a GUI interface (2)

    8.1.4 Input/Output

  • IO1: Allow events that pass all entry points to be written to files. (1)
  • IO2: Allow output files to be split according to run number or the number of events written. (2)
  • IO4: Allow for partial output of events (2)
  • IO3: Provide an end-of-run summary of the events processed by each entry point and other job statistics (CPU time, etc.) (2)

  • 8.2 Data Distribution (Dispatcher) Requirements

    Contact: schubert@hep.umn.edu

    The Data Distribution package will handle the distribution of data from the online data sources to client applications. The client applications will be able to subscribe to certain subsets of data through an interface provided by the Data Distribution package.
    This document is a preliminary attempt to list the Data Distribution system requirements. I have used Hugh Gallagher's Neugen requirements list as a guide.

    8.2.1 General Requirements

  • G1: Distributes data from near-online data files to client applications.(1)
  • G2: Provides user-friendly interface to client for accessing data.(1)
  • G3: Use other HEP event servers as models in design where applicable. (3)

    8.2.2 Functional Requirements

  • F1: Clients will be able to subscribe to certain subsets of data. (1)
  • F2: Clients will be serviced at different priority where applicable. (2)
  • F3: The Server will have access to the data written by the DAQ to disk soon after it is written and before the data file has been closed.(1)
  • F4: Data transfer over the internet is supported, so that clients can be remote from the data sources. (1)

    8.2.3 User Interface Requirements

  • U1: Client interface to data should be user-friendly and machine-independent. (1)

    8.2.4 Error Handling Requirements

  • E1: All error and warning messages must be intelligible and traceable.(1)

    8.2.5 Validation and Documentation Requirements

  • V1: The data distribution code will be tested in a simulated environment before use in the detector environment. (1)
  • V2: A "User Manual" describing it's use along with documentation of the client interface will be provided. (1)

    8.2.6 Constraints

  • C1: Must support ROOT data format (1)
  • C2: Client code should run on every system where MINOS code is supported. (1)
  • C3: Server code should run be written in Posix standard to run on Linux/UNIX operating systems. (2)
  • C4: Server code must be fast enough to keep up with the data generator. (1)

  • 8.3 Navigation and Relationship Lattice: Nav and Lat

    Contact: n.west1@physics.oxford.ac.uk

    Requirements for a generic navigation model are to some extent open ended. Beyond the essential requirements, the purpose of the model is to support algorithm development, and this is done in part by recognizing common patterns of use which are then generalized and formalized into the model. So the requirements are divided into 3 categories:-

    Requirements can be further subdivided by the type of user:- Unless indicated to the contrary, requirements are those of the End User.

    8.3.1 Essential Requirements

    Henceforth the term Iteration refers both to:-

    8.3.2 Important Requirements

    8.3.3 Potential Requirements


    8.4 Message Service

    Contact: messier@huhepl.harvard.edu

    8.4.1 General

  • G1: The interface should be comparable and as easy to use as cout and cerr (1)
  • G2: Allow print thresholds to be set on a package-by-package basis (1)
  • G3: Perform with comparable speed as cout and cerr (2)
  • G4: Handle un-printed messages as quickly as possible (2)
  • G5: Allow routing of messages to one or multiple output streams (2)
  • G6: Allow output streams to be concatenated at the end of jobs (2)

    8.4.2 Formatting

  • F1: Provide convenient formatting of numerical output (1)
  • F2: Allow messages to be tagged with: in such a way that this additional information can be turned on/off by the user on a package by package basis (1)