Quick Start

Estimated reading time: 4 minutes

Prepare the CEPC Software

There are several methods to use CEPC software.

  • Use CVMFS. This is the recommended way to use CEPC software because of simplicity. Here the CEPC software are centrally installed on CVMFS server. There is nothing to do if you are going to use it on lxslc6, or you need to install the CVMFS client to mount them on the local machine.
  • Full installation. This will install all the packages of CEPC software by compiling from the source. It is able to deploy the full CEPC software on your local PC.
  • Use docker image. It is similar with the CVMFS method except that the CVMFS client and configuration are integrated in the docker image.

You can choose one or more methods for your situation. For a full installation, you can fully control where you would like to put them, e.g., on a shared file system. For the CVMFS method, you do not need to install each version for every new release. But be sure that the CVMFS clients are installed on all the machines running CEPC software. The docker image could be the most convenient way for personal use.

Setup CEPC Software Environment

Here we use the CEPC software on CVMFS as example.

Once there are available CEPC softwares installed, you can start to use them. Make sure the software_root in file ~/.cepcenv.conf is properly set before next steps.

Initialize CEPCEnv first:

source /cvmfs/cepc.ihep.ac.cn/software/cepcenv/setup.sh

List all installed CEPC software versions:

$ cepcenv ls
(Software root: "/cvmfs/cepc.ihep.ac.cn/software/cepcsoft")

Select the CEPC software version you would like to use:

cepcenv use 0.1.0

You can also set it as a default version. The default version will be automatically selected when CEPCEnv initialization is done.

cepcenv use --default 0.1.0

Then the CEPC software environment should be correctly configured. Try some commands to verify:

echo $Arbor_HOME
gcc --version
root -b

Test CEPC Software

Download the test example from http://cepcgit.ihep.ac.cn/cepcsoft/TestExample. Replace the USERNAME with yours on CEPC Gitlab.

git clone http://USERNAME@cepcgit.ihep.ac.cn/cepcsoft/TestExample.git
cd TestExample

This will run simulation and reconstruction, then draw the total mass distribution. The output files could be found in the output directory.


Before starting simulation, the generator file should be prepared. The existing samples could be found according to this page.

Consider the TestExample from the last section, the sim directory contains scripts for doing full simulation with Mokka.

There are two files simu.macro and event.macro. simu.macro is the main script for describing the simulation details.

/Mokka/init/BatchMode true
/Mokka/init/printLevel 2
/Mokka/init/detectorModel CEPC_v4

/Mokka/init/user consult
/Mokka/init/dbPasswd consult

/Mokka/init/lcioFilename ../output/nnh_e2e2_sim.slcio
/Mokka/init/initialMacroFile event.macro

/Mokka/init/lcioDetailedShowerMode true
/Mokka/init/userInitBool WriteCompleteHepEvt true
/Mokka/init/lcioWriteMode WRITE_NEW
/Mokka/init/lcioStoreCalHitPosition true
/Mokka/init/lcioDetailedTRKHitMode TPCCollection

/Mokka/init/randomSeed 10000000

The output slcio file location should be put in the line starting with /Mokka/init/lcioFilename. There is also a necessary file event.macro whose name is specified on the line /Mokka/init/initialMacroFile:

/generator/generator ../stdhep/nnh_e2e2.e0.p0.00001.stdhep
/run/beamOn 10

This file includes the input generator file location and the event number which will be simulated.

In order to get the total number of the stdhep file, use the lcio_event_counter command:

lcio_event_counter nnh_e2e2.e0.p0.00001.stdhep

Run the full simulation with the following command:

Mokka simu.macro

There is also a file GearOutput.xml generated which includes the detector parameters. This file will be used in the reconstruction step.


Also from the TestExample, the rec directory includes the script reco.xml for reconstruction. This is a Marlin steer file.

The input slcio file from the simulation step:

  <parameter name="LCIOInputFiles">

The reconstruction event number:

<parameter name="MaxRecordNumber" value="-1"/>

Here -1 means all the events from input file.

The output reconstructed slcio file location:

<processor name="MyLCIOOutputProcessor" type="LCIOOutputProcessor">
  <parameter name="LCIOOutputFile" type="string" >

Run the reconstruction with Marlin:

Marlin reco.xml

Event Display

The event could be displayed using Druid optionally with the detector geometry.

Druid nnh_e2e2_rec.slcio

Please refer to the detailed usage of Druid.


The analysis package includes a Marlin processor in order to access the ArborPFOs collection from reconstructed slcio file.

For a detailed example, please see vvHmumu.