Preface to the CMS Workbook

The CMS workbook is designed as a first-stop for new users and as an introduction to new developers. It is organized into Essentials (chapters 1 to 5) and Advanced Topics sections (chapters 6 to 9). It provides background information and initial instruction on accessing CMS computing resources and using the CMS software, and includes tutorials to guide you through a variety of analysis scenarios. In the twiki browser-based version, you will find links to more in-depth information.

This workbook is a continuously evolving document intended primarily for online use. This printed version is made available for the convenience of readers who prefer paper, but it should not be expected to be of "publication quality". In particular, we have made an effort to write out explicitly some links, but you will still need to refer back to the twiki version for some of them. Furthermore, we are aware of the problems with html characters which do not show properly in the printed document, we hope this can be fixed for the next prints.

We plan to review the workbook thoroughly a couple of times each year and follow each review with a mass printing. The most recent print was done in February 2008. Copies are available from the CMS User Support Coordinator Kati Lassila-Perini in building 40 (office 4-A02) at CERN.



0.1 Acknowledgements

The CMS Collaboration would particularly like to thank the original editor Anne Heavey for leading the workbook project from its creation and throughout the 2006 shut down year. She provided much of the workbooks content as well as helped to organize contributions from many experts in areas of CMS and CMSSW. Starting any large documentation project is an intimidating task - working out what to put in, how to structure it, and getting people to actually write contributions. From 2007 onwards the work of this task is easy - update, improve, expand, which is done with the help of CMS participators like you. Based at Fermilab, Anne is now involved in the OSG (Open Science Grid) project.

The initial structure and content of the CMS WorkBook was closely modeled on the ATLAS WorkBook, following the design of similar projects of BaBar and OPAL.

Many thanks to Steve Lloyd (ATLAS) for providing code, layout advice, twiki explanations and much ongoing assistance in producing the first version of the CMS workbook. Much gratitude is also due to Ed Moyse (ATLAS) for enabling the workbook (and the rest of the CMS web) to have customized left sidebars. Thanks also to Traudl Hansl-Kozanecka (ATLAS) for assistance with coding, advice and general structure. And last but not least, many thanks for the CERN twiki support and Peter Jones for the continuous support.

And a big thank you to all the CMS scientists and code developers who have provided information, written, reviewed, edited, and otherwise assisted with creating and maintaining these workbook tutorials and topics for their fellow collaborators.


Responsible: KatiLassilaPerini
Last reviewed by: Main.Scarlet Norberg- 11-Nov-2015



0.2 Using the Workbook

Complete: 5
Detailed Review status

Contents

Goals of this page

The goal of this page is to show you how to get the most out of the workbook. The reader will learn what the various symbols and links on the workbook pages mean, what type of information they link to, who to contact about a given page, and how to provide feedback to the editors.

Philosophy of the Workbook

This workbook is intended to serve as a relatively stand-alone learning tool for new CMS members. It is designed to explain how to use the CMS SoftWare (CMSSW) application to analyze data. It should serve as a comprehensive tutorial. CMS plans to keep it current throughout the lifetime of the experiment.

The workbook is an effort to which any and all CMS members are encouraged to contribute. Identified content experts are asked to contribute content, which editors then organize and edit. Readers are strongly encouraged to provide feedback to the editors in order to help them improve the flow, content, accuracy and readability of the workbook.

The editing goals of the workbook include:

  • Keep explanations brief, and provide links to supplementary information
  • In general, the supplementary info should not be needed in order to complete the workbook (as a tutorial)
  • Use a step-by-step format wherever possible
  • Include specific tutorials for the various tasks
  • Organization (table of contents) will evolve to accommodate content (form follows function).

Assumptions about your computing environment

The WorkBook instructions generally assume you're running CMS software on the CERN Public Login Linux system LXPLUS or on a remote system (with respect to CERN) that provides access to the CMS software releases and to the tools you'll need to develop your software, e.g., the CMSLPC cluster at Fermilab. In these environments, you can start work almost immediately. Local systems at other institutions may have different unix shells and different setups, and it is impossible to provide fool-proof instructions for all environments. For this reason, we invite institutions to provide information in Specific Information for Remote Sites and Institutions.

About the workbook pages

The CMS Workbook is a set of Twiki pages starting at https://twiki.cern.ch/twiki/bin/view/CMS/WorkBook. Each page states the goals for the reader, and most list informational sources used in compiling the content.

Completeness indicator

There is a progress indicator at the top of each page which gives the user a rough idea how complete the topic is from the author's and/or editor's point of view. Completeness is measured in terms of the content suitable for the Workbook, not in terms of anything and everything that could be written on the topic. The scale goes from empty (white) to complete (green) in six stages:
Complete: 0
Complete: 1
Complete: 2
Complete: 3
Complete: 4
Complete: 5

Beware that a Complete: 5 topic may need reworking periodically and may change to some level of incomplete from time to time. Each page is reviewed periodically to make sure the content is still valid.

The latest review and/or modified date should appear in the Review Status at the bottom of the page, possibly with some explanatory text. The "responsible person" for the page should also be listed under Review Status and is a good contact if you have questions specific to that page.

Left Hand Menu

On the left hand menu of each WorkBook page, there are links to all the workbook topics. In addition, you'll find links to:

  • a Glossary/Index of terms related to CMS, physics, CMSSW and GRID computing
  • a Summary of Changes page which summarizes the workbook pages in terms of modification, review dates and content.
  • a Site Map showing the pages under the workbook domain
  • a Print WkBk as PDF link for printing chapters or the whole workbook to PDF (this is a customized printing format, and is different from the "Printable" and "PDF" buttons in the standard TWiki tool bar)
  • a Contributors page which gives formatting guidelines for Workbook page writers and editors
  • the CMS User Support page
  • the Offline SW Guide containing the detailed information of all CMS software
  • the Reference Manual containing the release dependent technical documentation such as class lists, brief description of content and purpose of each package and default configuration files and sequences
  • the Online WB for instructions for shift and online work.

At the end of the left hand menu:

  • a Page Template for creating new Workbook pages
  • a Review for Printing page on which the editors keep track of the status of each page as they prepare for a mass printing, planned for a couple of times a year
  • To Do List a notepad for keeping editors and contributors informed about work in progress and areas of the CMS workbook where contributions are most urgently needed

Providing Feedback

Presently the principal workbook editors are managed by the L2 Coordinators for User Support: Marguerite Tonjes and Sudhir Malik. You may email them with questions, comments, complaints, contributions, corrections, and so on, or you may use the CMS Workbook Documentation hypernews forum at https://hypernews.cern.ch/HyperNews/CMS/get/workbook.html and send your comments to a wider audience (this is recommended). If you're not yet a member of the CMS hypernews system, follow the instructions at https://hypernews.cern.ch/HyperNews/CMS/add-member.pl to join. Then you can access the CMS Workbook forum and optionally subscribe to it to receive by email all postings to the forum. The email gateway for this forum is: hn-cms-workbook@cernNOSPAMPLEASE.ch.

In addition to a discussion area, the CMS WorkBook hypernews forum also provides a public staging area for new workbook documentation proposed by CMS users. Please post suggestions for new workbook documentation - on all aspects of CMS operations - to this hypernews forum rather than editing the workbook pages without prior agreement from a workbook editor.

For those of you who do write and/or edit Workbook pages, please follow the guidelines in WorkBookContributors. This is necessary for ensuring a standardized look and feel in the browser.

How to print WorkBook pages, chapters and the whole WorkBook

See Print WkBk as PDF for printing parts (topics or chapters) of the CMS WorkBook, or printing the whole document.


Review status

Reviewer/Editor and Date (copy from screen) Comments
MargueriteTonjes - 2 Mar 2018 updated for appropriate L2 Offline & Computing User Support people
CMSUserSupport - 18 Jan 2008 updated description of leftbar items
AnneHeavey - 14 Nov 2006 review and edits prior to end of 2006 mass printing
AnneHeavey - 20 Jun 2006 added "assumptions" section

Responsible: MargueriteTonjes
Last reviewed by: ScarletNorberg - 21-Nov-2015

Edit | Attach | Watch | Print version | History: r17 < r16 < r15 < r14 < r13 | Backlinks | Raw View | WYSIWYG | More topic actions
Topic revision: r17 - 2008-02-29 - CMSUserSupport
 
    • Cern Search Icon Cern Search
    • TWiki Search Icon TWiki Search
    • Google Search Icon Google Search

    CMSPublic All webs login

This site is powered by the TWiki collaboration platform Powered by PerlCopyright & 2008-2019 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback