CLHEP 2000 Agreements

CLHEP Workshop at Fermilab
June 29 - 30, 2000
Consensus and Agreements

Several points were agreed to at the CLHEP workshop at Fermilab held June 29-30, 2000. Although these were presented at the end of the workshop as a sequence of 29 individual items, here some overlapping items have been combined, and the agreements are grouped into several categories:

A brief synopsis of the agreements:
  1. All CLHEP packages must work on all CLHEP platforms.
  2. Packages which fail on a CLHEP platform can be made available as Non-CLHEP packages. CLHEP packages must not depend on these.
  3. CLHEP will make early announcements of package intentions to the general CLHEP mailing list.
  4. CLHEP editors/developers are allowed to use the cvs repository as a code management tool for development. Changelogs for packages do not start till the first release
  5. CLHEP needs some sort of automated documentation tool. In preparation for that, we can start moving to a standardized header comment format.
  6. CHLEP will maintain a package dependency tree, will keep it accurate, and will strictly adhere to the implications of this dependency tree.
  7. The central test directory will contain a single test corresponding to each package. Each CLHEP package will have a test subdirectory, containing the remaining test programs.
  8. The central CLHEP doc area will have a ps or pdf version of key documentation for each package. Each package area will have a doc subdirectory, to contain html and/or tex sources for documentation.
  9. Except for classes which already have adequate methods to capture and restore state, each class header will have will provide access to its internals by declaring a friend method named xxxOpen.
  10. The Alist, String, Hist, Classdoc, and Compbinations packages, will not be present in the next CLHEP release.
  11. The Utilities package will go away. Instead of having a catch-all Utilities packages, CLHEP will be amenable to including several fairly small distinct packages.
  12. It was implied that the Tools package will similarly go away.
  13. Minor additions but no massive modifications of Geometry package.
  14. We need to converge on understanding the relationships amongsts the vector-like classes in various packages, before contemplating a new package introducing another form of vector.
  15. Somebody will be added to the editor list with co-responsibility for support of the Matrix package.
  16. The GenericFunctions package (Joe Boudreau as editor) is accepted.
  17. Tokenizer, parser, FFread, and DLopen codes will be grouped into packages and accepted.
  18. An expression evaluator will be accepted as a new package (with E.T. as editor).
  19. Although CLHEP is looking for an automated documentation tool for internal use, it is not intended that this become available to the users as a package.
  20. ZOOM Exceptions The ZOOM exceptions package is accepted into CLHEP (M. Fischler as editor). However, other CLHEP packages are not at this time permitted to depend on Exceptions.
  21. The ZOOM ISOcxx Portability package wil be included in CLHEP (W. Brown as editor). Other CLHEP packages are free to use ISOcxx or not.
  22. The features of the ZOOM PhysicsVectors package which are missing in CLHEP Vectors will be incorporated into the CLHEP classes.
  23. Work by ZOOM in the Matrix area, on enhancements and optimizations driven will go into the CLHEP Matrix package.
  24. HepMC classes including their container for particles and vertices will be utilized in the context of StdHepC++.
  25. StdHepC++ will provide a common Particle Data Table entry class.

The following items of agreement were reached at the CLHEP workshop:

    General Policy Issues

  1. All CLHEP packages must work on all CLHEP platforms

      2. CLHEP is to be a Common Library for HEP.

      If a specific platform has a deficiency (with respect to the C++ standard) that will not permit some CLHEP package to work, the editors will choose among the following actions:

      1. Most desirable is to strengthen the CLHEP portability and configuration tools so as to remedy the deficiency.
      2. If this cannot be done, but the feature utilizing the deficient construct can instead be re-implemented in a way that does work on all CLHEP platforms, this fix shuld be made.
      3. If the feature cannot be implemented, but it is not fundamental to the package, consider removing that capability from the package.

        If the package fundamentally requires the deficient construct, and the deficiency cannot be resolved in one of the above desirable ways, then one of two less pleasant choices will be selected:

      4. Remove the package from CLHEP.
          The possibility of making available packages which are not formally part of CLHEP becuase they fail on one or more platforms is discussed next.
      5. Remove that platform from the list of official CLHEP platforms.
          Putting a platform onto a "DOESN'T WORK" list is not a step to be taken lightly.

  2. Non-CLHEP packages

      3. Packages which the editors agree should be in CLHEP but are not presently because they fail on one or more CLHEP platforms may be packaged in the CLHEP cvs repository and made available in releases. However, some rules must be followed regarding these "Uncommon" Library for HEP packages:
      1. We must clearly state that this package is not part of the real CLHEP, and indicate which platforms it will not work on.
      2. No CLHEP package may depend on any of these "Non-CLHEP" packages.

  3. Early announcements of package intentions

      4. We will use the general CLHEP mailing list to inform the community of intentions to incorporate a new package or to begin developing a new package which we then intend to incorporate. This is intended as a "flag in the air" mechanism to avoid duplication of effort and clashes with other development efforts.
        We must announce ASAP the set of intended new products agreed at this workshop.

  4. Use of the CLHEP cvs repository

      5. CLHEP editors/developers are allowed to use the cvs repository as a code management tool for development.
      1. We will provide world read access to these sources via cvsweb.
      2. We do not guarantee compilablity of all code in the head of the repository at any given instant. That is the purpose of releases.
      3. The change log for a product does not start till the first CLHEP release of that product.
          Thus if there is considerable activity before release, to make the package work under various conditions, this early activity will not pollute the eventual change log.

  5. Automated doucumentation tool

      6. CLHEP needs some sort of automated documentation tool. In preparation for that, we can start moving to a standardized header comment format. We will get some information from Babar, who is already doing that at some level.
        The existance of an automated tool does not imply that all documentation must be produced in that manner. In particular, User's Guides and tutuorials are usually best produced by hand.

    Organization of CLHEP and its Packages

  6. Dependency Tree

      7. CHLEP will maintain a package dependency tree, will keep it accurate, and will strictly adhere to the implications of this dependency tree.
      1. When a new package is proposed and accepted, its dependencies must be specified.
      2. Introducing an interpackage dependency where there was none is considered a decision on the same level as adding or removing a package, and is a matter for serious consideration by the editors. Except in extraordinary circumstances, this should be avoided, as it has real potential for fouling up users who are relying on the dependency structure.
      3. The resolution of the current conflict, in which Matrix and Random each have reason to depend on the other package is:
        • The dependency of Matrix on Random will be removed, by eliminating the constructor that creates a matrix filled with random numbers.
        • The Random package may continue to depend on Matrix (to get the HepMatrix and HepVector classes for the multivariate distributions).
        • However, it is strongly recommended that an that dependency by obviated, and that Random not depend on other packages.
        • An adjunct package, RandomObjects , can hold methods that inherently involve random operations and other CLHEP class.
            The RandomObjects class would contain the multivariate (vector) distributions, and would also replace the fucntionallity of the random-filled-Matrix that is excised from Matrix.

  7. Test areas

      8. This represents a cleaning up of the test directory:
      CLHEP will have the central test directory it currently has, but in addition, each package will have a test subdirectory.
      1. There will be one test corresponding to each package in the central test directory. The purpose of these is for installers to verify that the package works at some basic level on their system.
        • This test should take no more than a few minutes to run and be amenable to automated checking of correctness, by comparison with a provided out.save file and/or by returning zero to indicate correct operation.
        • The test will be named packageTest, for example, MatrixTest.
        • In rare cases, it may be appropriate to have a small number of central tests beyond just the one. These would be named packageTest2, and so forth.
      2. The test subdirectory for each package can have many other test programs, including validation of correctness, feature coverage tests, a regression suite, timing test programs, tests to tickle and investigate specific bugs, and so forth. Package editors are encouraged to keep such tests with the package, in the cvs repository. However, building the package is a distinct operation from building all these "lower" tests.
      3. Lower tests (in the individual package test subdirectories) need not be compilable or runnable on all platforms.
        (The tests in the central test directory must compile and run on all CLHEP platforms.)

  8. Doc directories

      9. Each package area will have a doc subdirectory, to contain html and/or tex sources for documentation (also possibly flat-text technical maintenance notes).
      The central doc area will have a ps or pdf version of key documentation for each package, which may be supplied or built in an automated manner.

  9. Support for saving and restoring full states of objects

      10. Except for classes which already have adequate methods to capture and restore the state of a given instance, each class will have the collowing lines of code in its public area:
        class xxxOpen;
        friend class xxxOpen;
      where xxx is the name of the class. This provides a way for somebody to write methods that get at the full public and private state.
        Bob Jacobsen will write up a paragraph explaining the workings and benefits of this arrangement.

    Obsolete Packages

  10. Removal of packages in next release

      11. The following CLHEP packages, which in the past have been deprecated, will not be present in the next CLHEP release and will be removed from the cvs repository (other than in the attic):
      • Alist
      • String
      • Hist
          (Has been in complete dis-use for some time already.)
      • Classdoc
          See agreement about documentation.
      • Combinations
          Combinations, which uses Alist, had not been working anyway, and would have to be seriously revamped if it were retained. If there is need for a Combinations package, it may be re-constituted in the future.

  11. The Utilities package will go away

      12. The Utilites package will become empty, and assumedly will then be eliminated (though we did not state that it would definitely be removed by the next release). Instead of having a catch-all Utilities packages, CLHEP will be amenable to including several fairly small distinct packages.

  12. Implication that Tools package will go away

      13. Although Tools was not listed in the "packages to be removed" discussion, an implication of the way we are doing dependencies is that this package, as a catchall for classes with awkward dependencies, will go away.
      In some cases, instead of adding classes to Tools, small new packages will be introduced.

    Issues Concerning Current Packages

  13. Minor additions but no massive modifications of Geometry package

    1. CLHEP does not anticipate extensive modifications or enhancements of the Geometry package at this time (that is, at least till after the next CLHEP release).
    2. A method will be added to Geometry to extract rotation, reflection and scale of a transformation.
    3. We will look at the extensions made by Phoenix, with the intention of pulling these back into the official CLHEP Geometry package.

  14. Various kinds of vectors in CLHEP

      15. Bob Jacobsen will draft a first approximation at explaining the relationships among the vector-like classes in CLHEP's Geometry and Vector packages.
        This understanding needs to converge before we can consider a new package introducing another form of vector (e.g., template-specialized vectors of two and three dimensions using floats and doubles).
      We will not introduce a new package involving yet another form of vector at this time (that is, at least till after the next CLHEP release.

  15. Matrix development

      16. Somebody will be added to the editor list with co-responsibility for support of the Matrix package.

    New Packages

  16. GenericFunctions

      17. The GenericFunctions package (Joe Boudreau as editor) is accepted.
        First version should start with single-variable functions, so as to be able to consider user comments when developing the potentially trickier mulit-variable features.

  17. Tokenizer, parser, and related functionallity

      18. Evegeni has code in the following areas:
      1. Tokenizer
      2. Regular Expression parser
      3. FFread substitute
          That is, reading lines in the format keyword value(s) and plaing the values in the right variables.
      4. Shared library DLopen (dynamic libraries)
      It is agreed that these will be accepted into CLHEP. It is agreeed that theses shuld not be a single package. The grouping into 2 or more packages is left for Evegeni's consideration.

  18. Expression Evaluator

      19. Evegeni has an expression evaluator, which will be accepted as a new package (with E.T. as editor). He will incorporate any improvements found by exploring the similar class used in Babar.

  19. No user-intended documentation package

      20. Although CLHEP is looking for an automated documentation tool for internal use, it is not intended (at this time) that this become available to the users as a CLHEP package.

  20. ZOOM Exceptions

      21. The ZOOM exceptions package is accepted into CLHEP as Exceptions (M. Fischler as editor). However, other CLHEP packages (coming in from ZOOM or elsewhere) are not at this time permitted to depend on Exceptions.

  21. ISOcxx Portability

      22. ZOOM's ISOcxx Portability package wil be included in CLHEP (W. Brown as editor).
      1. ISOcxx will not necessarily be used by every CLHEP package.
      2. ISOcxx.h is permitted to be included (be not mandated to be included) in other CLHEP headers.
      3. (Once ISOcxx is in place) other CLHEP packages will be allowed to depend on ISOcxx. Proper note must be made in the dependency tree.
      4. In CLHEP, ISOcxx.h will be included from "CLHEP/ISOcxx/ISOcxx.h".
          This implies that the package build will put a file into the package area itself. This has implications concerning distribution by read-only CD. CLHEP can accept these implications.
      5. Possibly, ISOcxx will need to be enhanced to be allow one to say "always assume this include is present when evaluating for defects." This, and perhaps other accomodations, should reduce the chances of clashes among attempts to remedy defects.
      6. Exceptions will depend on ISOcxx. Before the next CLHEP release, ISOcxx must be brought into proper enough shape that Exceptions can use it without kludge, or else the incorporation of Exceptions will be delayed till after the next release.

    Coordination with ZOOM Packages

  22. Merge of ZOOM PhysicsVectors into CLHEP Vectors package

    1. Rather than having each PhysicsVectors class (e.g. SpaceVector) inherit from the corresponding CLHEP Vectors class (e.g. Hep3Vector) we will augment the CLHEP Vectors class interfaces to provide the additional ZOOM PhysicsVectors functionallity.
      • This represents a change in intentions relative to a CLHEP editors list decision of a while ago, and supercedes that decision.
      • The point is a general philosophy, applicable beyond just the Vector package:
          If a specific funtionallity belongs with a concept, we should put it in the header of the class that embodies that concept, even though that causes the header to be larger.
          We should not use inheritance in this situation.
    2. It was agreed that even if the interface were to expand by three times as much in the header file, this approach will still be the one we take.
        Of course, when doing the merge judgement will be used to excise any feature whose "bloat" exceeds its likely value.
    3. Classes which are part of the ZOOM package but have no analogue in the current Vector package (e.g. UnitVector and PlaneVector) will be added, with names following the pattern used in CLHEP Vector.
    4. There may be a set of classes with the old ZOOM names (for back compatibility) but these would be trivial derivatives (by typedef) of the CLHEP classes.
    5. In cases of confliciting conventions, we will choose one and document the choice.
      • If there are conflicting actual usages, the current CLHEP convention will be used.
      • If there is a copnvention in use in ZOOM and no corresponding convention in the CLHEP package, ZOOM's choice will be used.
      • Unnecessary flexibility, such as providing a choice of metric signs, will be excised.
    6. The CLHEP Vector package, even after PhysicsVectors is incorporated, will not depend on the Exceptions package, nor will it use the C++ exceptions mechanism.

  23. Effort to focus on CLHEP Matrix rather than ZOOM LinearAlgebra

      24. Work by ZOOM in the Matrix area, on enhancements and optimizations driven by the needs of FNAL users, will go into the CLHEP Matrix package.

      This does not imply that ZOOM is dropping its LinearAlgebra package. However:

      • Enhancements in ZOOM LinearAlgebra will be limited to very specific features needed by specific Run II developers.
      • ZOOM will also either place those enhancements into CLHEP Matrix, or help somebody working on behalf of the Matrix editor to do so.

    Particle and Event Classes

  24. Utilize HepMC classes in context of StdHepC++

      25. The StdHepC++ package, when moving toward a better-organized structure for events, will make use of the particle and "intrusive container" classes in use in HepMC.
      1. The GeneratorEvent container scheme, where the particle class will contain "pointers" to associated vertices and the vertex class contains a list of particles, is accepted.
      2. The names Particle and Vertex are deemed too likely to conflict with experiments' class names (even with namespace protection). Instead we will use SimParticle and SimVertex.
      3. The HepMC effort will maintain the GeneratorEvent and related classes. If minor adjustments and enhancements are needed for purposes of the StdHepC++ package, these will be incorporated.

  25. Particle Data Table entry class

      26. There will be a class representing the Particle Data Table entries for a particle. (The name PDTentry was suggested but not necessarily agreed.) This class will be developed and maintained by the StdHepC++ editor (L. Garren). It will include ways to map from various id's (e.g., Lund ID) into a pointer to an entry in the table.
      • StdHepC++ will of course use this class.
      • HepMC will also move in the direction of using this class as its format for holding PDT data.