Getting started¶
This tutorial takes you from a CMS file to an event in your browser. Follow the steps in order.
You will:
- get the
embercommand; - turn a file into a bundle with
ember; - open the bundle in the viewer;
- look around the event;
- share it.
The CMS site is not set up yet.
emberwrites the bundle on your machine, and you open it in the viewer at https://marriot-evd.web.cern.ch. Your browser reads the file from your disk: nothing is uploaded. Links to your own bundles need a site that holds them, which is planned (Hosting). See Status.
Only want to look? Open https://marriot-evd.web.cern.ch and sign on with your CERN account. It opens one of its
data sets: ttbar events at 0 and 200 pile-up, HGCal cassette tests and test beam. Then go to
step 4. Or drop golden/v6_1event.ember from the repository on the page: it is one
simulated event.
What you need¶
- A CMSSW release for Phase 2 or Run 3, and
cmsenvin it, for a reconstruction file or a MiniAOD.emberwrites its cmsRun configuration from the modules that this release has. Use the release that made your file, or a newer one of the same cycle.emberwas tested with the integration build CMSSW_20_1_X_2026-11-17-2300. In an older release, the tables whose modules it lacks are left out, and the configuration says which. - Python 3.9 or later with numpy and uproot.
cmsenvgives you all three. A NanoAOD file needs nothing else. - A CERN account, to open the viewer at https://marriot-evd.web.cern.ch (it is behind the CERN single sign-on).
Optional: more in your bundles. Two CMSSW branches, not merged yet, add the hits of each cluster and the truth graph. Add them to your CMSSW area with
git cms-merge-topicand build.emberuses them when it finds them. See Get every table: the CMSSW branches.
Step 1: Get the ember command¶
ember is a single file. It runs in any CMSSW environment, with nothing to install. Choose one way to get it.
From a clone of the repository (works anywhere):
git clone https://github.com/mmarriot/ember.git
python3 ember/tools/build_zipapp.py ~/bin/ember
This writes the file ~/bin/ember. If ~/bin is not in your PATH, call it as ~/bin/ember, or add ~/bin to your
PATH.
With pip (outside CMSSW, or in a Python virtual environment):
python3 -m pip install git+https://github.com/mmarriot/ember.git
Check that it works:
$ ember --version
ember 0.2.0
If it fails:
command not found: the command is not in yourPATH. Give its full path, for example~/bin/ember --version. Afterpip installoutside a virtual environment,emberis usually in~/.local/bin.No module named 'numpy'(or'uproot'): this Python lacks a package that Ember needs. Runcmsenvfirst.
Step 2: Turn a file into a bundle¶
Run ember on your file, after cmsenv. Here it is a Phase-2 step3 file of 20 ttbar events without pile-up:
$ ember step3.root
step3.root: CMSSW EDM (RECO, AOD or MiniAOD) from CMSSW_20_1_X_2026-11-12-2300, 20 events
making the NanoAOD of the first 10 with cmsRun
geometry ExtendedRun4D104 (from the file's geometry files)
conditions 201X_mcRun4_realistic_v1 (the file's global tag, ...)
era Phase2C22I13M9 (this release's default for ExtendedRun4D104; the file does not record its era)
left out: the hits of clusters: this release has no CaloClusterHitsTableProducer, ...
left out: this release has no TruthGraphFlatTableProducer, TruthGraphHitFlatTableProducer (the truth tables: ...)
running cmsRun ember_cfg.py (--config FILE.py keeps it)
NanoAOD made in 29 s
profile phase2 (chosen for the tables of ember_nano.root)
29 tables, 8 relations, 29 display layers
10 events, 4 MB, 0 s
wrote step3.ember
to see it, drop it on https://marriot-evd.web.cern.ch (your browser reads the file; nothing is uploaded)
What happened:
emberfound the geometry, conditions and era that the file was made with, and printed them.- It wrote a cmsRun configuration,
ember_cfg.py, from the modules of your release: the tables of the hits, clusters, tracksters, tracks and physics objects that the file has. It lists what it left out, here the hits of each cluster and the truth tables, which need CMSSW branches until they are merged. Add--config mine_cfg.pyto keep the configuration, to read it or to run it again withcmsRun. - It ran the configuration on the first 10 events, in a temporary folder.
- It converted the NanoAOD into a bundle, with the profile that draws most of it, and wrote
step3.emberin the current folder. Ask for more events with--max-events 50, or for all with--max-events 0.
The cmsRun job takes about 20 s to start, then 0.6 s per event without pile-up, or 0.7 s per event at 200 pile-up,
with 4 threads (-j 8 gives it 8). A NanoAOD file is converted directly, with no CMSSW job, in a few seconds.
Which files work, and what each one gives, is in Which files work. If ember cannot
tell the geometry, or your file was made with other settings, see
Convert a step3 file.
If it fails, ember prints one line that starts with ember:. The most common ones:
| message | what to do |
|---|---|
this is a CMSSW reconstruction file: ... so run cmsenv in a release first |
Run cmsenv in a CMSSW release for Phase 2 or Run 3, then try again. |
... failed in the CMSSW environment: run cmsenv in this shell ... |
This shell's python3 or PATH is not the release's (for example an LCG view sourced after cmsenv). Run cmsenv again. |
FILE: cannot tell which geometry it was made with (...) |
Give the geometry, for example --geometry D110. |
the export job failed (exit code N); ... |
The cmsRun job failed. Its last lines follow, and the log and the configuration are kept in the files named. A wrong era or wrong conditions end here: give --era and --conditions. |
FILE: none of the profiles phase2, run3, nano, hgcal, cms draws its tables (it has: ...) |
ember does not know this kind of NanoAOD. See Profiles. |
Every message, and what to do about it, is in The ember command.
Step 3: Open the bundle¶
- If you ran
emberon another machine (lxplus, for example), copy the bundle to the computer where your browser is:scp <your login>@lxplus.cern.ch:path/to/step3.ember . - Open https://marriot-evd.web.cern.ch, and sign on with your CERN account.
- Drop
step3.emberon the page. Or open the data set chooser (the button at the left of the top bar) and click Open a local file… at its bottom.
Your browser reads the file where it is. It is not uploaded. Any copy of the viewer does the same, also one that you run yourself (Look at a bundle without the site).
Step 4: Look at the event¶
You see the first event of the bundle. Press ? at any time for the viewer's own help. Now try these five things:
- Move around. Drag to rotate, scroll to zoom, and right-drag to pan. Press
1,2,3or4for the 3D, front, side and ρ–z views. Use the Look at bar at the top (or pressD) to show one part of the detector: Physics, Tracker, Calo, HGCal, Muons, or All. PressHometo see everything again. - Go through the events. Press
→and←. Or type an event number in the Event… box. PressPfor a tour: the viewer builds up the event step by step, from the collision point outwards and from hits to physics objects, with a caption for each step. - Click an object, for example a jet, a track, a cluster or a hit. Its card opens on the right. The card shows
what the object is part of, and what it is made of, down to the hits. Press
↓and↑to draw one step of this chain at a time. Click a name in the card to look at that object. PressEscto go back. - Compare with the simulation, when the bundle has truth. Press
Tto colour everything by the simulated particle it comes from. Select an object and pressXto jump to its truth match, andXagain to come back. The card says how good the match is, as purity and completeness. Select a particle to see, detector by detector, where its energy went: in the reco object matched to it, in others, or in none. Truth explains these words. - Hide what you do not need. In the side panel, each kind of object shows its cut, for example "pT ≥ 30 GeV". Click the cut to change it with a slider. Click only on a heading to show that kind alone. Click the count on a row to list its largest objects.
All the controls are described in Viewer.
Step 5: Share it¶
A bundle on your disk has no link. To show it to a colleague, send them the file (on EOS or CERNBox, for example). They open it the same way, in step 3.
Links that open the same event, the same selected object and the same view work for bundles that a site holds: the data sets of https://marriot-evd.web.cern.ch, and your own bundles once the planned CMS site exists. The share button at the top right copies such a link, and lists what it opens. For a local file, it says that the file has no link.
What next¶
- How-to guides: which files work, convert a step3 file, choose events, name your bundle, get the cluster hits and the truth.
- Questions and problems: what new users run into.
- Viewer: every control, the side panel, colours and the selection's card.
- The
embercommand: every option and message.