Reconstruction of the Beam Spot

Complete: 4
Detailed Review status


  • Francisco Yumiceva


The beam spot is the luminous region produced by the collisions of proton beams. The position and spread of the beam spot needs to be measured precisely because of the following reasons:

  • Important input for physics e.g. b-tagging, lifetime, etc.
  • For patter recognition (input for HLT and offline reconstruction).
  • Extraction of the tracking impact parameter resolution.
  • Quick check of global alignment.
  • Provide feedback to accelerator groups.
  • Beam monitor.

The algorithm used to calculated the transverse beam position is the so called d0-phi algorithm. This is a robust and fast χ2 fit which just needs 1000 good tracks to reach micron precision. Using a Log-Likelihood fit, the beam width can be extracted using 20000 good tracks. A more detail description can be found in the CMS Note 2007/021.

Access to the beam spot data

The beam spot data is stored in RECO, AOD, and PAT datasets. This collection can be accessed from an analyzer in CMSSW as follows:

#include "DataFormats/BeamSpot/interface/BeamSpot.h"

// within the analyze()
reco::BeamSpot beamSpot;
edm::Handle<reco::BeamSpot> beamSpotHandle;
iEvent.getByLabel("offlineBeamSpot", beamSpotHandle);

if ( beamSpotHandle.isValid() )
    beamSpot = *beamSpotHandle;

} else
      << "No beam spot available from EventSetup \n";

double x0 = beamSpot.x0();
double y0 = beamSpot.y0();
double z0 = beamSpot.z0();
double sigmaz = beamSpot.sigmaZ();
double dxdz = beamSpot.dxdz();
double BeamWidth = beamSpot.BeamWidth();
// print the beam spot object
// cout << beamSpot << endl;

// look at BeamSpot.h in DataFormats package 
// for a complete list of member functions for
// the beam spot object

The full list of member functions available in the beam spot object can be found in the [[][reference manual].

Using the beam spot to correct the track impact parameter

The default impact parameter parameter of tracks are give with respect to the center of the Tracker (0,0,0). The impact parameter should be correct by the beam line offset before is used for analysis. The correction can be done either with respect to the primary vertex or with respect to the beam spot. The former can be done by using the tracking tools in the package IPTools. The later is done as follows:

// please see above for definition of beamSpot object
// reco::BeamSpot beamSpot;
// reco::TrackRef Track;

math::XYZPoint point(beamSpot.x0(),beamSpot.y0(), beamSpot.z0());
double d0 = -1.* Track->dxy(point);
double d0sigma = sqrt( Track->d0Error() * Track->d0Error() + beamSpot.BeamWidth()*beamSpot.BeamWidth() );

Status of the Beam spot in MC samples

Simulation of the beam spot

The generated particles have the production vertex at the origin (0,0,0) of the coordinate system. Therefore, to simulate a realistic luminous region the vertices of the generated particles are smeared by a Gaussian distribution in Z, and by the accelerator beta function for the transverse plane. In the case of the presence of beams with a crossing angle, the momentum of the particles are also corrected by a Lorentz boost.

The vertex smearing (and Lorentz boost) should be included in the simulation sequence by calling one of the vertex smearing modules available in "Configuration/StandardSequences", for example:


The following configuration files are available for several beam conditions:


The values of the parameters for each beam condition can be found in the file "IOMC/EventVertexGenerators/python/". In addition to the vertex smearing by the beta function, there are options to smear the vertices by a flat or Gaussian distributions, see the "IOMC/EventVertexGenerators" package for more details.

Reconstruction of the beam spot

In order to provide a beam spot data in MC samples, we first generate and reconstruct a QCD sample with a given beam conditions. Then, the beam spot analysis code is run to fit the data and extract the beam spot position, spread, and errors. Finally, the beam spot data is loaded into the conditions database so when the reconstruction is run, the beam spot data is copied from the database to the event and it is stored in RECO as an EDM collection.

(need to fix this) Get beam position from the event

Since 170pre4, the beam spot data is available in the event. Skip to step 3 to learn how to access the beam spot data in this case.

In releases < 170pre4 for example in 168, you can get the beam spot from the event after the following steps:

1. Get recent version of beam spot producer:

addpkg RecoVertex/BeamSpotProducer
2. Enable beam spot Producer. In your analysis configuration cfg file by adding the following line
include "RecoVertex/BeamSpotProducer/data/BeamSpotSimpleGaussian.cff  // for official samples
// or use one of the following for the test samples (see above):
// BeamSpotEarlyCollision.cff, BeamSpotNominalCollision.cff, BeamSpotNominalCollision1.cff,
// BeamSpotNominalCollision2.cff, BeamSpotNominalCollision3.cff, BeamSpotNominalCollision4.cff

If you have your own beam spot in a sqlite file or in the DB, you can modify the cff file above to read your beam spot with the respective tag name.

3. In your analyzer include the beam spot data format and get the data:

#include "DataFormats/BeamSpot/interface/BeamSpot.h"

reco::BeamSpot vertexBeamSpot;
edm::Handle<reco::BeamSpot> recoBeamSpotHandle;
vertexBeamSpot = *recoBeamSpotHandle;

4. Access the reco::BeamSpot member functions, see the reference manual

5. An example to read the Beam Spot data from the DB and save it as EDCollection in a root file is given in the following cfg file:


Get beam position from the database

Packages needed for releases 1.3.X and 1.4.X:

cvs co -r V00-00-00 CondCore/BeamSpotPlugins
cvs co -r V00-00-01 CondFormats/BeamSpotObjects
cvs co -r V02-01-01 CondFormats/DataRecord
cvs co -r V00-00-05 RecoVertex/BeamSpotProducer
cvs co -r V00-00-03 DataFormats/BeamSpot

Packages needed for releases 1.5.0pre2:

cvs co -r V00-00-05 RecoVertex/BeamSpotProducer
cvs co -r V00-00-04 DataFormats/BeamSpot

Currently, the beam spot information in the DB can be accessed through a sqlite file. The files needed to run this example can be downloaded here: BeamSpot.db and conddbcatalog.xml

Add the following includes and lines in your code to access the data:

#include "FWCore/Framework/interface/ESHandle.h"
#include "FWCore/Framework/interface/EventSetup.h"
#include "FWCore/Framework/interface/IOVSyncValue.h"
#include "CondFormats/DataRecord/interface/BeamSpotObjectsRcd.h"
#include "CondFormats/BeamSpotObjects/interface/BeamSpotObjects.h"

BeamSpotFromDB::analyze(const edm::Event& iEvent, const edm::EventSetup& iSetup)
        edm::ESHandle< BeamSpotObjects > beamhandle;
        const BeamSpotObjects *mybeamspot = beamhandle.product();

        std::cout << *mybeamspot << std::endl;
Look at the BeamSpotObjects class for more information about how to get all the parameters.

In your configuration file, add the following lines:

include "CondCore/DBCommon/data/CondDBCommon.cfi"
  replace CondDBCommon.connect = "sqlite_file:BeamSpot.db"    
  replace CondDBCommon.catalog = "file:conddbcatalog.xml"
  es_source = PoolDBESSource { 
    using CondDBCommon
    VPSet toGet = { 
          { string record = "BeamSpotObjectsRcd" string tag = "SimpleGaussian" } 

Determination of beam position using an EDAnalyzer

In this section, we describe how to calculate the beam spot parameters using a set of good tracks. To reach a precision in the order of microns, it is necessary to loop over several events in a sample to collect at least 1000 good tracks.

1. Install CMSSW release 1_6_8. Please see Setting up your Computing Environment

2. Checkout packages:

addpkg RecoVertex/BeamSpotProducer
4. Run over some events. In this example, we run over CSA07 QCD events:
cd RecoVertex/BeamSpotProducer/test
edit analysis_d0_phi.cfg:
[-> in PoolSource add a dataset, for example ->] '/store/mc/2007/7/11/CSA07-QCD_Pt_80_120-2027/0001/0001F088-9832-DC11-A133-000423DCF6B8.root' 
[-> comment out the input file ->] #include "RecoVertex/BeamSpotProducer/test/NominalCollision4.cff"
now run cmsRun:
cmsRun analyze_d0_phi.cfg
The relevant output is the following:
calculating beam spot...
 we will use 7390 good tracks out of 28994
 number of tracks used: 0
 number of tracks used: 7390
 number of tracks used: 7390
 number of tracks used: 7390
 number of tracks used: 7390
 number of tracks used: 7390
 number of tracks used: 7390
 number of tracks used: 7384
 number of tracks used: 7373
 number of tracks used: 7359
 number of tracks used: 7337
 number of tracks used: 7301
 number of tracks used: 7244
 number of tracks used: 7189
 number of tracks used: 7129
 number of tracks used: 7013
 number of tracks used: 6787
 number of tracks used: 6382
 number of tracks used: 5665
 number of tracks used: 4615
 total number of iterations = 19
BSFitter: default fit does not extract beam width, assigning a width of zero.
            Calculated Beam Spot

   X0 = 0.000137297 +/- 8.54651e-05 [cm]
   Y0 = 1.45161e-05 +/- 8.72648e-05 [cm]
   Z0 = 0.178271 +/- 0.762762 [cm]
 Sigma Z0 = 4.69784 +/- 0.577968 [cm]
 dxdz = 3.60997e-06 +/- 1.61885e-05 [radians]
 dydz = -5.41738e-05 +/- 1.6445e-05 [radians]
 Beam Width = 0 +/- 0 [cm]

This sample was generated at (0,0,0) with no crossing-angles, a RMS bunch length in Z of 5.3 cm and the average transverse beam width is of 15 microns. The beam width can be extracted using the log likelihood fit implemented in this package which requires more tracks and a tighten track quality criteria.

5. Track quality cuts can be modified via the framework, see the configuration file


Use different beam conditions during reconstruction

Below is a recipe to change the beam conditions before reconstruction:

1. Create a text file with a new beam position. This can be done by hand or running the Beam Spot analyzer over a private sample. For example, the beam spot analyzer create a text file with the results of the fit:

[cmslpc06] test > more EarlyCollision.txt
X 0.0323201
Y -0.000137265
Z 0.110321
sigmaZ 3.83198
dxdz 5.58847e-06
dydz -1.97724e-05
BeamWidthX 45.9e-4
BeamWidthY 45.9e-4
Cov(0,j) 7.68449e-10 1.61892e-11 0 0 0 0 0 
Cov(1,j) 1.61892e-11 7.75067e-10 0 0 0 0 0 
Cov(2,j) 0 0 0.137499 0 0 0 0 
Cov(3,j) 0 0 0 0.0972715 0 0 0 
Cov(4,j) 0 0 0 0 5.43189e-11 1.16835e-12 0 
Cov(5,j) 0 0 0 0 1.16835e-12 5.41043e-11 0
Cov(6,j) 0 0 0 0 0 0 4e-08
emittanceX 7.03e-08
emittanceY 7.03e-08
betaStar 300.0

You can modify the file by hand if you just want to change some of the values.

2. Create a sqlite file to be loaded during reconstruction:

addpkg RecoVertex/BeamSpotProducer

In this package, edit the file called "BeamSpotProducer/test/" to create a sqlite file. The new conditions that you will produce need to have a tag name. Change the following line to the name of the new condition, for example:

tag = cms.string('Early10TeVCollision_3p8cm_v4_mc_IDEAL')

The tag name is used in step 3. The filename of the output file is given by this line:

process.CondDBCommon.connect = "sqlite_file:EarlyCollision.db"

Now run cmsRun to create the sqlite file "EarlyCollision.db"


"cmsRun" can be used to check that "EarlyCollision.db" contains the desired parameters.

3. Load new conditions. In your reconstruction configuration file, you need to overwrite the global tag with the following lines:

process.BeamSpotDBSource = cms.ESSource("PoolDBESSource",
       toGet = cms.VPSet(cms.PSet(
       record = cms.string('BeamSpotObjectsRcd'),
       tag = cms.string('Early10TeVCollision_OVERWRITE'))),
       connect = cms.string('sqlite_file:EarlyCollision.db')
process.es_prefer_beamspot = cms.ESPrefer("PoolDBESSource","BeamSpotDBSource")

Notice that you need to copy "EarlyCollision.db" to the same directory where the configuration file lives.

4. Validation. Check that the new beam spot data is available in the beam spot collection "offlineBeamSpot". This step confirms that the default beam parameters have been overwritten. Collection name for example: "Events/recoBeamSpot_offlineBeamSpot_RECO/recoBeamSpot_offlineBeamSpot_RECO.obj"

Online Beam Spot

In preparation.

Upload new beam spot conditions

Action items

  • Beam spot monitoring: * Implement a fast DQM monitoring after HTL which run the full tracking reconstruction by lumi blocks and calculate the beam position. * Implement a DQM monitoring in the in AlCaReco skims. * Displays for the CMS control room of the beam position by the Tracker and by the LHC BPMs.
  • Online beam spot: * Can we run the d0-phi method in the HLT? * Can we use the primary vertex finding in the HLT to estimate the beam position?
  • Feedback the beam spot position to the LHC.
  • Offline beam spot:
    • We are assuming that the beam width is the same in X and Y, we could change the code to take into account the possibility of different beam widths in X and Y.
    • Compare d0-phi method against the primary vertex finding method.

Review status

Reviewer/Editor and Date (copy from screen) Comments
KatiLassilaPerini - 13 Jan 2009 moved from wb to swguide
FranciscoYumiceva - 10 Feb 2007 first version of page

Responsible: FranciscoYumiceva
Last reviewed by: FranciscoYumiceva - 1 Feb 2008

Topic attachments
I Attachment HistorySorted ascending Action Size Date Who Comment
PNGpng 75511ce7f520a4d76f51938f35e05981.png   manage 0.3 K 2007-02-10 - 22:08 UnknownUser  
Unknown file formatdb BeamSpot.db r1 manage 48.0 K 2007-04-03 - 06:00 FranciscoYumiceva sqlite file with beam spot parameters
XMLxml conddbcatalog.xml r1 manage 0.3 K 2007-04-24 - 17:10 FranciscoYumiceva  

This topic: CMSPublic > CMSCommunicationsGroup > CMSCommunicationsProjects > WebHome > SWGuide > WorkBook > SWGuideFindingBeamSpot
Topic revision: r42 - 2009-06-10 - FranciscoYumiceva
This site is powered by the TWiki collaboration platform Powered by PerlCopyright & 2008-2020 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
or Ideas, requests, problems regarding TWiki? use Discourse or Send feedback