8. Examples

Some example set-ups are included in Sherpa, in the <prefix>/share/SHERPA-MC/Examples/ directory. These may be useful to new users to practice with, or as templates for creating your own Sherpa run-cards. In this section, we will look at some of the main features of these examples.

8.1. Vector boson + jets production

To change any of the following LHC examples to production at different collider energies or beam types, e.g. proton anti-proton at the Tevatron, simply change the beam settings accordingly:

BEAMS: [2212, -2212]
BEAM_ENERGIES: 980

8.1.1. W+jets production

This is an example setup for inclusive W production at hadron colliders. The inclusive process is calculated at next-to-leading order accuracy matched to the parton shower using the MC@NLO prescription detailed in [HKSS12]. The next few higher jet multiplicities, calculated at next-to-leading order as well, are merged into the inclusive sample using the MEPS@NLO method – an extension of the CKKW method to NLO – as described in [HKSS13] and [GHK+13]. Finally, even higher multiplicities, calculated at leading order, are merged on top of that. A few more things to note are detailed below the example.

# Sherpa configuration for W[lv]+Jets production

# set up beams for LHC run 2
BEAMS: 2212
BEAM_ENERGIES: 6500

# matrix-element calculation
ME_GENERATORS:
- Comix
- Amegic
- OpenLoops

# optional: use a custom jet criterion
#SHERPA_LDADD: MyJetCriterion
#JET_CRITERION: FASTJET[A:antikt,R:0.4,y:5]

# exclude tau (15) from (massless) lepton container (90)
PARTICLE_DATA:
  15:
    Massive: 1

# pp -> W[lv]+jets
PROCESSES:
- 93 93 -> 90 91 93{4}:
    Order: {QCD: 0, EW: 2}
    CKKW: 20
    # set up NLO+PS final-state multiplicities
    2->2-4:
      NLO_Mode: MC@NLO
      NLO_Order: {QCD: 1, EW: 0}
      ME_Generator: Amegic
      RS_ME_Generator: Comix
      Loop_Generator: OpenLoops
    # make integration of higher final-state multiplicities faster
    2->4-6:
      Integration_Error: 0.05

SELECTORS:
# Safety cuts to avoid PDF calls with muF < 1 GeV
- [Mass, 11, -12, 1.0, E_CMS]
- [Mass, 13, -14, 1.0, E_CMS]
- [Mass, -11, 12, 1.0, E_CMS]
- [Mass, -13, 14, 1.0, E_CMS]

Things to notice:

  • The Order in the process definition in a multi-jet merged setup defines the order of the core process (here 93 93 -> 90 91 with two electroweak couplings). The additional strong couplings for multi-jet production are implicitly understood.

  • The settings necessary for NLO accuracy are restricted to the 2->2,3,4 processes using the 2->2-4 key below the # set up NLO+PS ... comment. The example can be converted into a simple MENLOPS setup by using 2->2 instead, or into an MEPS setup by removing these lines altogether. Thus one can study the effect of incorporating higher-order matrix elements.

  • The number of additional LO jets can be varied through changing the integer within the curly braces in the Process definition, which gives the maximum number of additional partons in the matrix elements.

  • OpenLoops is used here as the provider of the one-loop matrix elements for the respective multiplicities.

  • Tau leptons are set massive in order to exclude them from the massless lepton container (90).

  • As both Comix and Amegic are specified as matrix element generators to be used, Amegic has to be specified to be used for all MC@NLO multiplicities using ME_Generator: Amegic. Additionally, we specify RS_ME_Generator: Comix such that the subtracted real-emission bit of the NLO matrix elements is calculated more efficiently with Comix instead of Amegic. This combination is currently the only one supported for NLO-matched/merged setups.

The jet criterion used to define the matrix element multiplicity in the context of multijet merging can be supplied by the user. As an example the source code file ./Examples/V_plus_Jets/LHC_WJets/My_JetCriterion.C provides such an alternative jet criterion. It can be compiled via executing cmake . in that directory. The newly created library is linked at run time using the SHERPA_LDADD flag. The new jet criterion is then evoked by JET_CRITERION.

8.1.2. Z+jets production

This is an example setup for inclusive Z production at hadron colliders. The inclusive process is calculated at next-to-leading order accuracy matched to the parton shower using the MC@NLO prescription detailed in [HKSS12]. The next few higher jet multiplicities, calculated at next-to-leading order as well, are merged into the inclusive sample using the MEPS@NLO method – an extension of the CKKW method to NLO – as described in [HKSS13] and [GHK+13]. Finally, even higher multiplicities, calculated at leading order, are merged on top of that. A few things to note are detailed below the previous W+jets production example and apply also to this example.

# Sherpa configuration for Z[ee]+Jets production

# set up beams for LHC run 2
BEAMS: 2212
BEAM_ENERGIES: 6500

# matrix-element calculation
ME_GENERATORS:
  - Comix
  - Amegic
  - OpenLoops

## OTF variations
SCALE_VARIATIONS:
  - [0.25, 0.25]
  - [1.0,  0.25]
  - [0.25, 1.0]
  - [1.0,  1.0]
  - [4.0,  1.0]
  - [1.0,  4.0]
  - [4.0,  4.0]

PDF_VARIATIONS:
  - PDF4LHC21_40_pdfas*
  - NNPDF40_nnlo_as_01180
  - MSHT20nnlo_as118
  - CT18NNLO_as_0118

# EW setup and corrections
EW_SCHEME: alphamZsW
SIN2THETAW: 0.23113
ASSOCIATED_CONTRIBUTIONS_VARIATIONS:
  - [EW]
  - [EW, LO1]
  - [EW, LO1, LO2]
  - [EW, LO1, LO2, LO3]

# speed and neg weight fraction improvements
NLO_CSS_PSMODE: 2
MC@NLO:
  RS_SCALE: METS{H_Tp2/4}

# pp -> Z[ee]+jets
PROCESSES:
- 93 93 -> 11 -11 93{5}:
    Order: {QCD: 0, EW: 2}
    CKKW: 20
    # set up NLO+PS final-state multiplicities
    2->2-4:
      NLO_Mode: MC@NLO
      NLO_Order: {QCD: 1, EW: 0}
      ME_Generator: Amegic
      RS_ME_Generator: Comix
      Loop_Generator: OpenLoops
      Associated_Contributions: [EW, LO1, LO2, LO3]
    # make integration of higher final-state multiplicities faster
    2->4-7:
      Integration_Error: 0.05
      Max_N_Quarks: 4
      Max_Epsilon: 0.01

SELECTORS:
- [Mass, 11, -11, 66, E_CMS]

8.1.3. W+bb production

This example is currently broken. Please contact the Authors for more information.

8.1.4. Zbb production

BEAMS: 2212
BEAM_ENERGIES: 6500

# general settings
EVENTS: 1M

# me generator settings
ME_GENERATORS: [Comix, Amegic, LHOLE]

HARD_DECAYS:
  Enabled: true
  Mass_Smearing: 0
  Channels:
    23,11,-11: {Status: 2}
    23,13,-13: {Status: 2}

PARTICLE_DATA:
  5:
    Massive: true
    Mass: 4.75  # consistent with MSTW 2008 nf 4 set
  23:
    Width: 0
    Stable: 0

MI_HANDLER: None
FRAGMENTATION: None
CORE_SCALE: VAR{H_T2+sqr(91.188)}
PDF_LIBRARY: MSTW08Sherpa
PDF_SET: mstw2008nlo_nf4

PROCESSES:
- 93 93 -> 23 5 -5:
    NLO_Mode: MC@NLO
    NLO_Order: {QCD: 1, EW: 0}
    ME_Generator: Amegic
    RS_ME_Generator: Comix
    Loop_Generator: LHOLE
    Order: {QCD: 2, EW: 1}

SELECTORS:
- FastjetFinder:
    Algorithm: antikt
    N: 2
    PTMin: 5.0
    DR: 0.5
    EtaMax: 5
    Nb: 2

Things to notice:

  • The matrix elements are interfaced via the Binoth Les Houches interface proposal [B+10], [A+b], External one-loop ME.

  • The Z-boson is stable in the hard matrix elements. It is decayed using the internal decay module, indicated by the settings HARD_DECAYS:Enabled: true and PARTICLE_DATA:23:Stable: 0.

  • fjcore from FastJet is used to regularize the hard cross section. We require two b-jets, indicated by Nb: 2 at the end of the FastjetFinder options.

  • Four-flavour PDF are used to comply with the calculational setup.

8.2. Jet production

8.2.1. Jet production

To change any of the following LHC examples to production at the Tevatron simply change the beam settings to

BEAMS: [2212, -2212]
BEAM_ENERGIES: 980

8.2.1.1. MC@NLO setup for dijet and inclusive jet production

This is an example setup for dijet and inclusive jet production at hadron colliders at next-to-leading order precision matched to the parton shower using the MC@NLO prescription detailed in [HKSS12] and [HS12]. A few things to note are detailed below the example.

# collider setup
BEAMS: 2212
BEAM_ENERGIES: 6500

TAGS:
  LOOPGEN: <my-loop-gen>

# settings fot ME generators
ME_GENERATORS: [Amegic, Comix, $(LOOPGEN)]

# scale definitions
MEPS:
  CORE_SCALE: VAR{0.25*H_T2}

SCALE_VARIATIONS:
  - [0.25, 0.25]
  - [1.0,  0.25]
  - [0.25, 1.0]
  - [1.0,  1.0]
  - [4.0,  1.0]
  - [1.0,  4.0]
  - [4.0,  4.0]


PROCESSES:
- 93 93 -> 93 93:
    Order: {QCD: 2, EW: 0}
    NLO_Order: {QCD: 1, EW: 0}
    NLO_Mode: MC@NLO
    ME_Generator: Amegic
    Loop_Generator: $(LOOPGEN)
    RS_ME_Generator: Comix


SELECTORS:
- FastjetFinder:
    Algorithm: antikt
    N: 1
    PTMin: 20
    DR:    0.4
- FastjetFinder:
    Algorithm: antikt
    N: 2
    PTMin: 10
    DR:    0.4

Things to notice:

  • Asymmetric cuts are implemented (relevant to the RS-piece of an MC@NLO calculation) by requiring at least two jets with pT > 10 GeV, one of which has to have pT > 20 GeV.

  • Both the factorisation and renormalisation scales are set to the above defined scale factors times a quarter of the scalar sum of the transverse momenta of all anti-kt jets (R = 0.4, pT > 20 GeV) found on the ME-level before any parton shower emission. See SCALES for details on scale setters.

  • The resummation scale, which sets the maximum scale of the additional emission to be resummed by the parton shower, is set to the above defined resummation scale factor times half of the transverse momentum of the softer of the two jets present at Born level.

  • The external generator OpenLoops provides the one-loop matrix elements.

  • The NLO_Mode is set to MC@NLO.

8.2.1.2. MEPS setup for jet production

BEAMS: 2212
BEAM_ENERGIES: 6500

PROCESSES:
- 93 93 -> 93 93 93{0}:
    Order: {QCD: 2, EW: 0}
    CKKW: 20
    Integration_Error: 0.02

SELECTORS:
- NJetFinder:
    N: 2
    PTMin: 20.0
    ETMin: 0.0
    R: 0.4
    Exp: -1

Things to notice:

  • Order is set to {QCD: 2, EW: 0}. This ensures that all final state jets are produced via the strong interaction.

  • An NJetFinder selector is used to set a resolution criterion for the two jets of the core process. This is necessary because the “CKKW” tag does not apply any cuts to the core process, but only to the extra-jet matrix elements, see Multijet merged event generation with Sherpa.

8.2.2. Jets at lepton colliders

This section contains two setups to describe jet production at LEP I, either through multijet merging at leading order accuracy or at next-to-leading order accuracy.

8.2.2.1. MEPS setup for ee->jets

This example shows a LEP set-up, with electrons and positrons colliding at a centre of mass energy of 91.2 GeV.

BEAMS: [11, -11]
BEAM_ENERGIES: 45.6

ALPHAS(MZ): 0.1188
ORDER_ALPHAS: 1

PROCESSES:
- 11 -11 -> 93 93 93{3}:
    CKKW: pow(10,-2.25/2.00)*E_CMS
    Order: {QCD: Any, EW: 2}

Things to notice:

  • The running of alpha_s is set to leading order and the value of alpha_s at the Z-mass is set.

  • Note that initial-state radiation is enabled by default. See ISR parameters on how to disable it if you want to evaluate the (unphysical) case where the energy for the incoming leptons is fixed.

8.2.2.2. MEPS@NLO setup for ee->jets

This example expands upon the above setup, elevating its description of hard jet production to next-to-leading order.

# collider setup
BEAMS: [11, -11]
BEAM_ENERGIES: 45.6

TAGS:
  # tags for process setup
  YCUT: 2.0
  # tags for ME generators
  LOOPGEN0: Internal
  LOOPGEN1: <my-loop-gen-for-3j>
  LOOPGEN2: <my-loop-gen-for-4j>
  LOOPMGEN: <my=loop-gen-for-massive-2j>

# settings for ME generators
ME_GENERATORS:
  - Comix
  - Amegic
  - $(LOOPGEN0)
  - $(LOOPGEN1)
  - $(LOOPGEN2)
  - $(LOOPMGEN)
AMEGIC: {INTEGRATOR: 4}

# model parameters
MODEL: SM
ALPHAS(MZ): 0.118
PARTICLE_DATA: {5: {Massive: true}}
HADRON_DECAYS:
  Max_Proper_Lifetime: 100

PROCESSES:
- 11 -11 -> 93 93 93{3}:
    CKKW: pow(10,-$(YCUT)/2.00)*E_CMS
    Order: {QCD: 0, EW: 2}
    RS_Enhance_Factor: 10
    2->2: { Loop_Generator: $(LOOPGEN0) }
    2->3: { Loop_Generator: $(LOOPGEN1) }
    2->4: { Loop_Generator: $(LOOPGEN2) }
    2->2-4:
      NLO_Mode: MC@NLO
      NLO_Order: {QCD: 1, EW: 0}
      ME_Generator: Amegic
      RS_ME_Generator: Comix
- 11 -11 -> 5 -5 93{3}:
    CKKW: pow(10,-$(YCUT)/2.00)*E_CMS
    Order: {QCD: 0, EW: 2}
    Loop_Generator: $(LOOPMGEN)
    RS_Enhance_Factor: 10
    2->2:
      NLO_Mode: MC@NLO
      NLO_Order: {QCD: 1, EW: 0}
      ME_Generator: Amegic
      RS_ME_Generator: Comix
- 11 -11 -> 5 5 -5 -5 93{1}:
    CKKW: pow(10,-$(YCUT)/2.00)*E_CMS
    Order: {QCD: 2, EW: 2}
    Cut_Core: 1

Things to notice:

  • the b-quark mass has been enabled for the matrix element calculation (the default is massless) because it is not negligible for LEP energies

  • the b b-bar and b b b-bar b-bar processes are specified separately because the 93 particle container contains only partons set massless in the matrix element calculation, see Particle containers.

  • model parameters can be modified in the config file; in this example, the value of alpha_s at the Z mass is set.

8.3. Higgs boson + jets production

8.3.1. H production in gluon fusion with interference effects

This is a setup for inclusive Higgs production through gluon fusion at hadron colliders. The inclusive process is calculated at next-to-leading order accuracy, including all interference effects between Higgs-boson production and the SM gg->yy background. The corresponding matrix elements are taken from [BDS02] and [DL].

# collider parameters
BEAMS: 2212
BEAM_ENERGIES: 6500

# generator parameters
EVENTS: 1M
EVENT_GENERATION_MODE: Weighted
AMEGIC: {ALLOW_MAPPING: 0}
ME_GENERATORS: [Amegic, Higgs]
SCALES: VAR{Abs2(p[2]+p[3])}

# physics parameters
PARTICLE_DATA:
  4:  {Yukawa: 1.42}
  5:  {Yukawa: 4.92}
  15: {Yukawa: 1.777}
EW_SCHEME: 3
RUN_MASS_BELOW_POLE: 1

PROCESSES:
- 93 93 -> 22 22:
    NLO_Mode: Fixed_Order
    Order: {QCD: 2, EW: 2}
    NLO_Order: {QCD: 1, EW: 0}
    Enable_MHV: 12
    Loop_Generator: Higgs
    Integrator: PS2
    RS_Integrator: PS3

SELECTORS:
- HiggsFinder:
    PT1: 40
    PT2: 30
    Eta: 2.5
    MassRange: [100, 150]
- [IsolationCut, 22, 0.4, 2, 0.025]

Things to notice:

  • This calculation is at fixed-order NLO.

  • All scales, i.e. the factorisation, renormalisation and resummation scales are set to the invariant mass of the di-photon pair.

  • Dedicated phase space generators are used by setting Integrator: PS2 and RS_Integrator: PS3, cf. Integrator.

To compute the interference contribution only, as was done in [DL], one can set HIGGS_INTERFERENCE_ONLY: 1. By default, all partonic processes are included in this simulation, however, it is sensible to disable quark initial states at the leading order. This is achieved by setting HIGGS_INTERFERENCE_MODE: 3.

One can also simulate the production of a spin-2 massive graviton in Sherpa using the same input card by setting HIGGS_INTERFERENCE_SPIN: 2. Only the massive graviton case is implemented, specifically the scenario where k_q=k_g. NLO corrections are approximated, as the gg->X->yy and qq->X->yy loop amplitudes have not been computed so far.

8.3.2. H+jets production in gluon fusion

This is an example setup for inclusive Higgs production through gluon fusion at hadron colliders used in [HKS]. The inclusive process is calculated at next-to-leading order accuracy matched to the parton shower using the MC@NLO prescription detailed in [HKSS12]. The next few higher jet multiplicities, calculated at next-to-leading order as well, are merged into the inclusive sample using the MEPS@NLO method – an extension of the CKKW method to NLO – as described in [HKSS13] and [GHK+13]. Finally, even higher multiplicities, calculated at leading order, are merged on top of that. A few things to note are detailed below the example.

# collider parameters
BEAMS: 2212
BEAM_ENERGIES: 6500

# settings for ME generators
ME_GENERATORS: [Comix, Amegic, Internal, OpenLoops]

# settings for hard decays
HARD_DECAYS:
  Enabled: true
  Channels:
    25,22,22: {Status: 2}
  Apply_Branching_Ratios: false
  Use_HO_SM_Widths: false

# model parameters
MODEL: HEFT
PARTICLE_DATA:
  25: {Mass: 125, Width: 0}

PROCESSES:
- 93 93 -> 25 93{2}:
    Order: {QCD: 2, EW: 0, HEFT: 1}
    CKKW: 30
    2->1-2: { Loop_Generator: Internal }
    2->3: { Loop_Generator: OpenLoops }
    2->1-3:
      NLO_Mode: MC@NLO
      NLO_Order: {QCD: 1, EW: 0}
      ME_Generator: Amegic
      RS_ME_Generator: Comix

Things to notice:

  • The example can be converted into a simple MENLOPS setup by replacing 2->1-3 with 2->1, or into an MEPS setup with 2->0, to study the effect of incorporating higher-order matrix elements.

  • Providers of the one-loop matrix elements for the respective multiplicities are set using Loop_Generator. For the two simplest cases Sherpa can provide it internally. Additionally, MCFM is interfaced for the H+2jet process, cf. MCFM interface.

  • To enable the Higgs to decay to a pair of photons, for example, the hard decays are invoked. For details on the hard decay handling and how to enable specific decay modes see Hard decays.

8.3.3. H+jets production in gluon fusion with finite top mass effects

This is example is similar to H+jets production in gluon fusion but with finite top quark mass taken into account as described in [B+15] for all merged jet multiplicities. Mass effects in the virtual corrections are treated in an approximate way. In case of the tree-level contributions, including real emission corrections, no approximations are made concerning the mass effects.

# collider parameters
BEAMS: 2212
BEAM_ENERGIES: 6500

# settings for ME generators
ME_GENERATORS: [Amegic, Internal, OpenLoops]

# settings for hard decays
HARD_DECAYS:
  Enabled: true
  Channels:
    25,22,22: {Status: 2}
  Apply_Branching_Ratios: false
  Use_HO_SM_Widths: false

# model parameters
MODEL: HEFT
PARTICLE_DATA:
  25: {Mass: 125, Width: 0}

# finite top mass effects
KFACTOR: GGH
OL_IGNORE_MODEL: true
OL_PARAMETERS:
  preset: 2
  allowed_libs: pph2,pphj2,pphjj2
  psp_tolerance: 1.0e-7

PROCESSES:
- 93 93 -> 25 93{1}:
    Order: {QCD: 2, EW: 0, HEFT: 1}
    CKKW: 30
    Loop_Generator: Internal
    2->1-2:
      NLO_Mode: MC@NLO
      NLO_Order: {QCD: 1, EW: 0}

Things to notice:

  • One-loop matrix elements from OpenLoops [CMP12] are used in order to correct for top mass effects. Sherpa must therefore be compiled with OpenLoops support to run this example. Also, the OpenLoops process libraries listed in the run card must be installed.

  • The maximum jet multiplicities that can be merged in this setup are limited by the availability of loop matrix elements used to correct for finite top mass effects.

  • The comments in H+jets production in gluon fusion apply here as well.

8.3.4. H+jets production in associated production

This section collects example setups for Higgs boson production in association with vector bosons

8.3.4.1. Higgs production in association with W bosons and jets

This is an example setup for Higgs boson production in association with a W boson and jets, as used in [HKP+]. It uses the MEPS@NLO method to merge pp->WH and pp->WHj at next-to-leading order accuracy and adds pp->WHjj at leading order. The Higgs boson is decayed to W-pairs and all W decay channels resulting in electrons or muons are accounted for, including those with intermediate taus.

# collider setup
BEAMS: 2212
BEAM_ENERGIES: 6500

ME_GENERATORS: [Comix, Amegic, OpenLoops]

# define custom particle container for easy process declaration
PARTICLE_CONTAINERS:
  900: {Name: W, Flavours: [24, -24]}
  901: {Name: lightflavs, Flavours: [1, -1, 2, -2, 3, -3, 4, -4, 21]}
NLO_CSS_DISALLOW_FLAVOUR: 5

# particle properties (ME widths need to be zero if external)
PARTICLE_DATA:
  24: {Width: 0}
  25: {Mass: 125.5, Width: 0}
  15: {Stable: 0, Massive: true}


# hard decays setup, specify allowed decay channels, ie.:
# h->Wenu, h->Wmunu, h->Wtaunu, W->enu, W->munu, W->taunu, tau->enunu, tau->mununu + cc
HARD_DECAYS:
  Enabled: true
  Channels:
    25,24,-12,11: {Status: 2}
    25,24,-14,13: {Status: 2}
    25,24,-16,15: {Status: 2}
    25,-24,12,-11: {Status: 2}
    25,-24,14,-13: {Status: 2}
    25,-24,16,-15: {Status: 2}
    24,12,-11: {Status: 2}
    24,14,-13: {Status: 2}
    24,16,-15: {Status: 2}
    -24,-12,11: {Status: 2}
    -24,-14,13: {Status: 2}
    -24,-16,15: {Status: 2}
    15,16,-12,11: {Status: 2}
    15,16,-14,13: {Status: 2}
    -15,-16,12,-11: {Status: 2}
    -15,-16,14,-13: {Status: 2}
  Decay_Tau: 1
  Apply_Branching_Ratios: 0

PROCESSES:
- 901 901 -> 900 25 901{2}:
    Order: {QCD: 0, EW: 2}
    CKKW: 30
    2->2-3:
      NLO_Mode: MC@NLO
      NLO_Order: {QCD: 1, EW: 0}
      ME_Generator: Amegic
      RS_ME_Generator: Comix
      Loop_Generator: OpenLoops

Things to notice:

  • Two custom particle container, cf. Particle containers, have been declared, facilitating the process declaration.

  • As the bottom quark is treated as being massless by default, a five flavour calculation is performed. The particle container ensures that no external bottom quarks, however, are considered to resolve the overlap with single top and top pair processes.

  • OpenLoops [CMP12] is used as the provider of the one-loop matrix elements.

  • To enable the decays of the Higgs, W boson and tau lepton the hard decay handler is invoked. For details on the hard decay handling and how to enable specific decay modes see Hard decays.

8.3.4.2. Higgs production in association with Z bosons and jets

This is an example setup for Higgs boson production in association with a Z boson and jets, as used in [HKP+]. It uses the MEPS@NLO method to merge pp->ZH and pp->ZHj at next-to-leading order accuracy and adds pp->ZHjj at leading order. The Higgs boson is decayed to W-pairs. All W and Z bosons are allowed to decay into electrons, muons or tau leptons. The tau leptons are then allowed to decay into all possible partonic channels, leptonic and hadronic, to allow for all possible trilepton signatures, unavoidably producing two and four lepton events as well.

# collider setup
BEAMS: 2212
BEAM_ENERGIES: 6500

ME_GENERATORS: [Comix, Amegic, OpenLoops]

# define custom particle container for easy process declaration
PARTICLE_CONTAINERS:
  901: {Name: lightflavs, Flavours: [1, -1, 2, -2, 3, -3, 4, -4, 21]}
NLO_CSS_DISALLOW_FLAVOUR: 5

# particle properties (ME widths need to be zero if external)
PARTICLE_DATA:
  23: {Width: 0}
  25: {Mass: 125.5, Width: 0}
  15: {Stable: 0, Massive: true}


# hard decays setup, specify allowed decay channels
# h->Wenu, h->Wmunu, h->Wtaunu, W->enu, W->munu, W->taunu,
# Z->ee, Z->mumu, Z->tautau, tau->any + cc
HARD_DECAYS:
  Enabled: true
  Channels:
    25,24,-12,11: {Status: 2}
    25,24,-14,13: {Status: 2}
    25,24,-16,15: {Status: 2}
    25,-24,12,-11: {Status: 2}
    25,-24,14,-13: {Status: 2}
    25,-24,16,-15: {Status: 2}
    24,12,-11: {Status: 2}
    24,14,-13: {Status: 2}
    24,16,-15: {Status: 2}
    23,15,-15: {Status: 2}
    -24,-12,11: {Status: 2}
    -24,-14,13: {Status: 2}
    -24,-16,15: {Status: 2}
    15,16,-12,11: {Status: 2}
    15,16,-14,13: {Status: 2}
    -15,-16,12,-11: {Status: 2}
    -15,-16,14,-13: {Status: 2}
    15,16,-2,1: {Status: 2}
    15,16,-4,3: {Status: 2}
    -15,-16,2,-1: {Status: 2}
    -15,-16,4,-3: {Status: 2}
  Decay_Tau: 1
  Apply_Branching_Ratios: 0

PROCESSES:
- 901 901 -> 23 25 901{2}:
    Order: {QCD: 0, EW: 2}
    CKKW: 30
    2->2-3:
      NLO_Mode: MC@NLO
      NLO_Order: {QCD: 1, EW: 0}
      ME_Generator: Amegic
      RS_ME_Generator: Comix
      Loop_Generator: OpenLoops

Things to notice:

  • A custom particle container, cf. Particle containers, has been declared, facilitating the process declaration.

  • As the bottom quark is treated as being massless by default, a five flavour calculation is performed. The particle container ensures that no external bottom quarks, however, are considered to resolve the overlap with single top and top pair processes.

  • OpenLoops [CMP12] is used as the provider of the one-loop matrix elements.

  • To enable the decays of the Higgs, W and Z bosons and tau lepton the hard decay handler is invoked. For details on the hard decay handling and how to enable specific decay modes see Hard decays.

8.3.4.3. Higgs production in association with lepton pairs

This is an example setup for Higgs boson production in association with an electron-positron pair using the MC@NLO technique. The Higgs boson is decayed to b-quark pairs. Contrary to the previous examples this setup does not use on-shell intermediate vector bosons in its matrix element calculation.

BEAMS: 2212
BEAM_ENERGIES: 6500

ME_GENERATORS: [Comix, Amegic, OpenLoops]

CORE_SCALE: VAR{Abs2(p[2]+p[3]+p[4])}

PARTICLE_DATA:
  5: {Massive: true}
  15: {Massive: true}
  25: {Stable: 0, Width: 0.0}

# hard decays setup, specify allowed decay channels h->bb
HARD_DECAYS:
  Enabled: true
  Channels:
    25 -> 5 -5: {Status: 2}
  Apply_Branching_Ratios: false

PROCESSES:
- 93 93 -> 11 -11 25:
    Order: {QCD: 0, EW: 3}
    NLO_Mode: MC@NLO
    NLO_Order: {QCD: 1, EW: 0}
    Loop_Generator: OpenLoops
    ME_Generator: Amegic
    RS_ME_Generator: Comix
    Integration_Error: 0.1

Things to notice:

  • The central scale is set to the invariant mass of the Higgs boson and the lepton pair.

  • As the bottom quark is set to be treated massively, a four flavour calculation is performed.

  • OpenLoops [CMP12] is used as the provider of the one-loop matrix elements.

  • To enable the decays of the Higgs the hard decay handler is invoked. For details on the hard decay handling and how to enable specific decay modes see Hard decays.

8.3.5. Associated t anti-t H production at the LHC

This set-up illustrates the interface to an external loop matrix element generator as well as the possibility of specifying hard decays for particles emerging from the hard interaction. The process generated is the production of a Higgs boson in association with a top quark pair from two light partons in the initial state. Each top quark decays into an (anti-)bottom quark and a W boson. The W bosons in turn decay to either quarks or leptons.

BEAMS: 2212
BEAM_ENERGIES: 6500

ME_GENERATORS: [Comix, Amegic, OpenLoops]

CORE_SCALE: VAR{sqr(175+125/2)}

PARTICLE_DATA:
  5: {Yukawa: 4.92}
  6: {Stable: 0, Width: 0.0}
  24: {Stable: 0}
  25: {Stable: 0, Width: 0.0}

# hard decays setup, specify allowed decay channels h->bb
HARD_DECAYS:
  Enabled: true
  Channels:
    25,5,-5: {Status: 2}
  Apply_Branching_Ratios: false

PROCESSES:
- 93 93 -> 25 6 -6:
    Order: {QCD: 2, EW: 1}
    NLO_Mode: MC@NLO
    NLO_Order: {QCD: 1, EW: 0}
    Loop_Generator: OpenLoops
    ME_Generator: Amegic
    RS_ME_Generator: Comix
    Integration_Error: 0.1

Things to notice:

  • The virtual matrix elements is interfaced from OpenLoops.

  • The top quarks are stable in the hard matrix elements. They are decayed using the internal decay module, indicated by the settings in the HARD_DECAYS and PARTICLE_DATA blocks.

  • Widths of top and Higgs are set to 0 for the matrix element calculation. A kinematical Breit-Wigner distribution will be imposed a-posteriori in the decay module.

  • The Yukawa coupling of the b-quark has been set to a non-zero value to allow the H->bb decay channel even despite keeping the b-quark massless for a five-flavour-scheme calculation.

  • Higgs BRs are not included in the cross section (Apply_Branching_Ratios: false) as they will be LO only and not include loop-induced decays

8.4. Top quark (pair) + jets production

8.4.1. Top quark pair production

# collider setup
BEAMS: 2212
BEAM_ENERGIES: 6500

# scales
EXCLUSIVE_CLUSTER_MODE: 1
CORE_SCALE: TTBar

# me generator settings
ME_GENERATORS: [Comix, Amegic, OpenLoops]

# decays
HARD_DECAYS:
  Enabled: true
  Channels:
    24,2,-1: {Status: 0}
    24,4,-3: {Status: 0}
    -24,-2,1: {Status: 0}
    -24,-4,3: {Status: 0}

# particle properties (width of external particles of the MEs must be zero)
PARTICLE_DATA:
  6: {Width: 0}

# on-the-fly variations
SCALE_VARIATIONS: 4.0*  # 7-point scale variations

PROCESSES:
- 93 93 -> 6 -6 93{3}:
    Order: {QCD: 2, EW: 0}
    CKKW: 20
    2->2-3:
      NLO_Mode: MC@NLO
      NLO_Order: {QCD: 1, EW: 0}
      ME_Generator: Amegic
      RS_ME_Generator: Comix
      Loop_Generator: OpenLoops
    2->5-8:
      Max_N_Quarks: 6
      Integration_Error: 0.05

Things to notice:

  • We use OpenLoops to compute the virtual corrections [CMP12].

  • We match matrix elements and parton showers using the MC@NLO technique for massive particles, as described in [HHL+13].

  • A non-default METS core scale setter is used, cf. Scale setting in multi-parton processes (METS)

  • We enable top decays through the internal decay module using HARD_DECAYS:Enabled: true

  • We calculate on-the-fly a 7-point scale variation, cf. On-the-fly event weight variations.

8.4.2. Top quark pair production incuding approximate EW corrections

# collider setup
BEAMS: 2212
BEAM_ENERGIES: 6500

# scales
EXCLUSIVE_CLUSTER_MODE: 1
CORE_SCALE: TTBar

# me generator settings
ME_GENERATORS: [Comix, Amegic, OpenLoops]

# decays
HARD_DECAYS:
  Enabled: true
  Channels:
    24,2,-1: {Status: 0}
    24,4,-3: {Status: 0}
    -24,-2,1: {Status: 0}
    -24,-4,3: {Status: 0}

# particle properties (width of external particles of the MEs must be zero)
PARTICLE_DATA:
  6: {Width: 0}

# on-the-fly variations (QCD)
SCALE_VARIATIONS: 4.0*  # 7-point scale variations

# on-the-fly variations (EWapprox)
ASSOCIATED_CONTRIBUTIONS_VARIATIONS:
- [EW]
- [EW, LO1]
- [EW, LO1, LO2]
- [EW, LO1, LO2, LO3]

OL_PARAMETERS:
  ew_renorm_scheme: 1

PROCESSES:
- 93 93 -> 6 -6 93{3}:
    Order: {QCD: 2, EW: 0}
    CKKW: 20
    2->2-3:
      NLO_Mode: MC@NLO
      NLO_Order: {QCD: 1, EW: 0}
      ME_Generator: Amegic
      RS_ME_Generator: Comix
      Loop_Generator: OpenLoops
      Associated_Contributions: [EW, LO1, LO2, LO3]
    2->5-8:
      Max_N_Quarks: 6
      Integration_Error: 0.05

Things to notice:

  • In addition to the setup in Top quark pair production we add approximate EW corrections, cf. [GLS18].

  • Please note: this setup only works with OpenLoops v.2 or later.

  • The approximate EW corrections are added as additional variations on the event weight.

8.4.3. Production of a top quark pair in association with a W-boson

# collider setup
BEAMS: 2212
BEAM_ENERGIES: 6500

# me generator settings
ME_GENERATORS: [Comix, Amegic, OpenLoops]

# settings for hard decays
HARD_DECAYS:
  Enabled: true
  Channels:
    24,2,-1: {Status: 0}
    24,4,-3: {Status: 0}
    24,16,-15: {Status: 0}

# model parameters
PARTICLE_DATA:
  6: {Width: 0}
  24: {Width: 0}

# technical parameters
EXCLUSIVE_CLUSTER_MODE: 1

PROCESSES:
- 93 93 -> 6 -6 24:
    NLO_Mode: MC@NLO
    NLO_Order: {QCD: 1, EW: 0}
    Order: {QCD: 2, EW: 1}
    ME_Generator: Amegic
    RS_ME_Generator: Comix
    Loop_Generator: OpenLoops

Things to notice:

  • Hard decays are enabled through HARD_DECAYS:Enabled: true.

  • Top quarks and W bosons are final states in the hard matrix elements, so their widths are set to zero using Width: 0 in their PARTICLE_DATA settings.

  • Certain decay channels are disabled using Status: 0 in the Channels sub-settings of the HARD_DECAYS setting.

8.5. Single-top production in the s, t and tW channel

In this section, examples for single-top production in three different channels are described. For the channel definitions and a validation of these setups, see [BSK].

8.5.1. t-channel single-top production

# SHERPA run card for t-channel single top-quark production at MC@NLO
# and N_f = 5

# collider setup
BEAMS: 2212
BEAM_ENERGIES: 6500

# me generator settings
ME_GENERATORS: [Comix, Amegic, OpenLoops]

# scales
# CORESCALE SingleTop:
#   use Mandelstam \hat{t} for s-channel 2->2 core process
CORE_SCALE: SingleTop

# disable hadronic W decays
HARD_DECAYS:
  Enabled: true
  Channels:
    24,2,-1: {Status: 0}
    24,4,-3: {Status: 0}
    -24,-2,1: {Status: 0}
    -24,-4,3: {Status: 0}

# choose EW Gmu input scheme
EW_SCHEME: 3

# required for using top-quark in ME
PARTICLE_DATA: { 6: {Width: 0} }

PROCESSES:
- 93 93 -> 6 93:
    NLO_Mode: MC@NLO
    NLO_Order: {QCD: 1, EW: 0}
    Order: {QCD: 0, EW: 2}
    ME_Generator: Amegic
    RS_ME_Generator: Comix
    Loop_Generator: OpenLoops
    Min_N_TChannels: 1  # require t-channel W

Things to notice:

  • We use OpenLoops to compute the virtual corrections [CMP12].

  • We match matrix elements and parton showers using the MC@NLO technique for massive particles, as described in [HHL+13].

  • A non-default METS core scale setter is used, cf. Scale setting in multi-parton processes (METS)

  • We enable top and W decays through the internal decay module using HARD_DECAYS:Enabled: true. The W is restricted to its leptonic decay channels.

  • By setting Min_N_TChannels: 1, only t-channel diagrams are used for the calculation

8.5.2. t-channel single-top production with N_f=4

# SHERPA run card for t-channel single top-quark production at MC@NLO
# and N_f = 4

# collider setup
BEAMS: 2212
BEAM_ENERGIES: 6500

# me generator settings
ME_GENERATORS: [Comix, Amegic, OpenLoops]

# scales
#   muR = transverse momentum of the bottom
#   muF = muQ = transverse momentum of the top
CORE_SCALE: VAR{MPerp2(p[2])}{MPerp2(p[3])}{MPerp2(p[2])}

# disable hadronic W decays
HARD_DECAYS:
  Enabled: true
  Channels:
    24,2,-1: {Status: 0}
    24,4,-3: {Status: 0}
    -24,-2,1: {Status: 0}
    -24,-4,3: {Status: 0}

# choose EW Gmu input scheme
EW_SCHEME: 3

PARTICLE_DATA:
  6: {Width: 0}  # required for using top-quark in ME
  5: {Massive: true, Mass: 4.18}  # mass as in NNPDF30_nlo_as_0118_nf_4

# configure for N_f = 4
PDF_LIBRARY: LHAPDFSherpa
PDF_SET: NNPDF30_nlo_as_0118_nf_4
ALPHAS: {USE_PDF: 1}

PROCESSES:
- 93 93 -> 6 -5 93:
    NLO_Mode: MC@NLO
    NLO_Order: {QCD: 1, EW: 0}
    Order: {QCD: 1, EW: 2}
    ME_Generator: Amegic
    RS_ME_Generator: Comix
    Loop_Generator: OpenLoops
    Min_N_TChannels: 1  # require t-channel W

Things to notice:

8.5.3. s-channel single-top production

# SHERPA run card for s-channel single top-quark production at MC@NLO
# and N_f = 5

# collider setup
BEAMS: 2212
BEAM_ENERGIES: 6500

# me generator settings
ME_GENERATORS: [Comix, Amegic, OpenLoops]

# scales
# CORESCALE SingleTop:
#   use Mandelstam \hat{s} for s-channel 2->2 core process
CORE_SCALE: SingleTop

# disable hadronic W decays
HARD_DECAYS:
  Enabled: true
  Channels:
    24,2,-1: {Status: 0}
    24,4,-3: {Status: 0}
    -24,-2,1: {Status: 0}
    -24,-4,3: {Status: 0}

# choose EW Gmu input scheme
EW_SCHEME: 3

# required for using top-quark in ME
PARTICLE_DATA: { 6: {Width: 0} }

# there is no bottom in the initial-state in s-channel production
PARTICLE_CONTAINERS:
  900: {Name: lj, Flavours: [1, -1, 2, -2, 3, -3, 4, -4, 21]}

PROCESSES:
- 900 900 -> 6 93:
    NLO_Mode: MC@NLO
    NLO_Order: {QCD: 1, EW: 0}
    Order: {QCD: 0, EW: 2}
    ME_Generator: Amegic
    RS_ME_Generator: Comix
    Loop_Generator: OpenLoops
    Max_N_TChannels: 0  # require s-channel W

Things to notice:

  • By excluding the bottom quark from the initial-state at Born level using PARTICLE_CONTAINERS, and by setting Max_N_TChannels: 0, only s-channel diagrams are used for the calculation

  • See t-channel single-top production for more comments

8.5.4. tW-channel single-top production

# SHERPA run card for tW-channel single top-quark production at MC@NLO
# and N_f = 5

# collider setup
BEAMS: 2212
BEAM_ENERGIES: 6500

# me generator settings
ME_GENERATORS: [Comix, Amegic, OpenLoops]

# scales
# mu = transverse momentum of the top
CORE_SCALE: VAR{MPerp2(p[3])}{MPerp2(p[3])}{MPerp2(p[3])}

# disable hadronic W decays
HARD_DECAYS:
  Enabled: true
  Channels:
    24,2,-1: {Status: 0}
    24,4,-3: {Status: 0}
    -24,-2,1: {Status: 0}
    -24,-4,3: {Status: 0}

# choose EW Gmu input scheme
EW_SCHEME: 3

# required for using top-quark/W-boson in ME
PARTICLE_DATA:
  6: {Width: 0}
  24: {Width: 0}

PROCESSES:
- 93 93 -> 6 -24:
    No_Decay: -6  # remove ttbar diagrams
    NLO_Mode: MC@NLO
    NLO_Order: {QCD: 1, EW: 0}
    Order: {QCD: 1, EW: 1}
    ME_Generator: Amegic
    RS_ME_Generator: Comix
    Loop_Generator: OpenLoops

Things to notice:

  • By setting No_Decay: -6, the doubly-resonant TTbar diagrams are removed. Only the singly-resonant diagrams remain as required by the definition of the channel.

  • See t-channel single-top production for more comments

8.6. Vector boson pairs + jets production

8.6.1. Dilepton, missing energy and jets production

# collider setup
BEAMS: 2212
BEAM_ENERGIES: 6500

# me generator settings
ME_GENERATORS: [Comix, Amegic, OpenLoops]
METS: { CLUSTER_MODE: 16 }

# define parton container without b-quarks to
# remove 0 processes with top contributions
PARTICLE_CONTAINERS:
  901: {Name: lightflavs, Flavours: [1, -1, 2, -2, 3, -3, 4, -4, 21]}
NLO_CSS_DISALLOW_FLAVOUR: 5

PROCESSES:
- 901 901 -> 90 91 90 91 901{3}:
    Order: {QCD: 0, EW: 4}
    CKKW: 30
    2->4-5:
      NLO_Mode: MC@NLO
      NLO_Order: {QCD: 1, EW: 0}
      ME_Generator: Amegic
      RS_ME_Generator: Comix
      Loop_Generator: OpenLoops
    2->5-7:
      Integration_Error: 0.05

SELECTORS:
- VariableSelector:
    Variable: PT
    Flavs: 90
    Ranges: [[5.0, E_CMS], [5.0, E_CMS]]
    Ordering: [PT_UP]
- [Mass, 11, -11, 10.0, E_CMS]
- [Mass, 13, -13, 10.0, E_CMS]
- [Mass, 15, -15, 10.0, E_CMS]

8.6.2. Dilepton, missing energy and jets production (gluon initiated)

# collider setup
BEAMS: 2212
BEAM_ENERGIES: 6500

# scales
CORE_SCALE: VAR{Abs2(p[2]+p[3]+p[4]+p[5])/4.0}

# me generator settings
ME_GENERATORS: [Amegic, OpenLoops]
AMEGIC: { ALLOW_MAPPING: 0 }
# the following phase space libraries have to be generated with the
# corresponding qq->llvv setup (Sherpa.tree.yaml) first;
# they will appear in Process/Amegic/lib/libProc_fsrchannels*.so
SHERPA_LDADD: [Proc_fsrchannels4, Proc_fsrchannels5]

PROCESSES:
- 93 93 -> 90 90 91 91 93{1}:
    CKKW: $(QCUT)
    Enable_MHV: 10
    Loop_Generator: OpenLoops
    2->4:
      Order: {QCD: 2, EW: 4}
      Integrator: fsrchannels4
    2->5:
      Order: {QCD: 3, EW: 4}
      Integrator: fsrchannels5
      Integration_Error: 0.02

SELECTORS:
- [Mass, 11, -11, 10.0, E_CMS]
- [Mass, 13, -13, 10.0, E_CMS]
- [Mass, 15, -15, 10.0, E_CMS]

8.6.3. Four lepton and jets production

# collider setup
BEAMS: 2212
BEAM_ENERGIES: 6500

# me generator settings
ME_GENERATORS: [Comix, Amegic, OpenLoops]
METS: { CLUSTER_MODE: 16 }

PROCESSES:
- 93 93 -> 90 90 90 90 93{3}:
    Order: {QCD: 0, EW: 4}
    CKKW: 30
    2->4-5:
      NLO_Mode: MC@NLO
      NLO_Order: {QCD: 1, EW: 0}
      ME_Generator: Amegic
      RS_ME_Generator: Comix
      Loop_Generator: OpenLoops
    2->5-7:
      Integration_Error: 0.05

SELECTORS:
- VariableSelector:
    Variable: PT
    Flavs: 90
    Ranges: [[5.0, E_CMS], [5.0, E_CMS]]
    Ordering: [PT_UP]
- [Mass, 11, -11, 10.0, E_CMS]
- [Mass, 13, -13, 10.0, E_CMS]
- [Mass, 15, -15, 10.0, E_CMS]

8.6.4. Four lepton and jets production (gluon initiated)

# collider setup
BEAMS: 2212
BEAM_ENERGIES: 6500

# scales
CORE_SCALE: VAR{Abs2(p[2]+p[3]+p[4]+p[5])/4.0}

# me generator settings
ME_GENERATORS: [Amegic, OpenLoops]
AMEGIC: { ALLOW_MAPPING: 0 }
# the following phase space libraries have to be generated with the
# corresponding qq->llll setup (Sherpa.tree.yaml) first;
# they will appear in Process/Amegic/lib/libProc_fsrchannels*.so
SHERPA_LDADD: [Proc_fsrchannels4, Proc_fsrchannels5]

PROCESSES:
- 93 93 -> 90 90 90 90 93{1}:
    CKKW: $(QCUT)
    Enable_MHV: 10
    Loop_Generator: OpenLoops
    2->4:
      Order: {QCD: 2, EW: 4}
      Integrator: fsrchannels4
    2->5:
      Order: {QCD: 3, EW: 4}
      Integrator: fsrchannels5
      Integration_Error: 0.02

SELECTORS:
- [Mass, 11, -11, 10.0, E_CMS]
- [Mass, 13, -13, 10.0, E_CMS]
- [Mass, 15, -15, 10.0, E_CMS]

8.6.5. WZ production with jets production

# collider setup
BEAMS: 2212
BEAM_ENERGIES: 6500

# scales
CORE_SCALE: VAR{Abs2(p[2]+p[3])/4.0}

# me generator settings
ME_GENERATORS: [Comix, Amegic, OpenLoops]

HARD_DECAYS:
  Enabled: true
  Channels:
    24,2,-1: {Status: 2}
    24,4,-3: {Status: 2}
    -24,-2,1: {Status: 2}
    -24,-4,3: {Status: 2}
    23,12,-12: {Status: 2}
    23,14,-14: {Status: 2}
    23,16,-16: {Status: 2}

PARTICLE_DATA:
  23: {Width: 0}
  24: {Width: 0}

PROCESSES:
- 93 93 -> 24 23 93{3}:
    Order: {QCD: 0, EW: 2}
    CKKW: 30
    2->2-3:
      NLO_Mode: MC@NLO
      NLO_Order: {QCD: 1, EW: 0}
      ME_Generator: Amegic
      RS_ME_Generator: Comix
      Loop_Generator: OpenLoops
    2->3-7:
      Integration_Error: 0.05
- 93 93 -> -24 23 93{3}:
    Order: {QCD: 0, EW: 2}
    CKKW: 30
    2->2-3:
      NLO_Mode: MC@NLO
      NLO_Order: {QCD: 1, EW: 0}
      ME_Generator: Amegic
      RS_ME_Generator: Comix
      Loop_Generator: OpenLoops
    2->3-7:
      Integration_Error: 0.05

8.6.6. Same sign dilepton, missing energy and jets production

# collider setup
BEAMS: 2212
BEAM_ENERGIES: 6500

# choose EW Gmu input scheme
EW_SCHEME: 3

# tags for process setup
TAGS:
  NJET: 1
  QCUT: 30

# scales
CORE_SCALE: VAR{Abs2(p[2]+p[3]+p[4]+p[5])}
EXCLUSIVE_CLUSTER_MODE: 1

# solves problem with dipole QED modeling
ME_QED: { CLUSTERING_THRESHOLD: 10 }

# improve integration performance
PSI: { ITMIN: 25000 }
INTEGRATION_ERROR: 0.05

PROCESSES:
- 93 93 -> 11 11 -12 -12 93 93 93{$(NJET)}:
    Order: {QCD: 0, EW: 6}
    CKKW: $(QCUT)
- 93 93 -> 13 13 -14 -14 93 93 93{$(NJET)}:
    Order: {QCD: 0, EW: 6}
    CKKW: $(QCUT)
- 93 93 -> 15 15 -16 -16 93 93 93{$(NJET)}:
    Order: {QCD: 0, EW: 6}
    CKKW: $(QCUT)
- 93 93 -> 11 13 -12 -14 93 93 93{$(NJET)}:
    Order: {QCD: 0, EW: 6}
    CKKW: $(QCUT)
- 93 93 -> 11 15 -12 -16 93 93 93{$(NJET)}:
    Order: {QCD: 0, EW: 6}
    CKKW: $(QCUT)
- 93 93 -> 13 15 -14 -16 93 93 93{$(NJET)}:
    Order: {QCD: 0, EW: 6}
    CKKW: $(QCUT)
- 93 93 -> -11 -11 12 12 93 93 93{$(NJET)}:
    Order: {QCD: 0, EW: 6}
    CKKW: $(QCUT)
- 93 93 -> -13 -13 14 14 93 93 93{$(NJET)}:
    Order: {QCD: 0, EW: 6}
    CKKW: $(QCUT)
- 93 93 -> -15 -15 16 16 93 93 93{$(NJET)}:
    Order: {QCD: 0, EW: 6}
    CKKW: $(QCUT)
- 93 93 -> -11 -13 12 14 93 93 93{$(NJET)}:
    Order: {QCD: 0, EW: 6}
    CKKW: $(QCUT)
- 93 93 -> -11 -15 12 16 93 93 93{$(NJET)}:
    Order: {QCD: 0, EW: 6}
    CKKW: $(QCUT)
- 93 93 -> -13 -15 14 16 93 93 93{$(NJET)}:
    Order: {QCD: 0, EW: 6}
    CKKW: $(QCUT)

SELECTORS:
- [PT, 90, 5.0, E_CMS]
- NJetFinder:
    N: 2
    PTMin: 15.0
    ETMin: 0.0
    R: 0.4
    Exp: -1

8.6.7. Polarized same-sign \(\mathrm{W}^+\) boson pair production in association with two jets at LO+PS

This is an example for the simulation of polarized cross sections for pure electroweak same-sign \(\mathrm{W}^+\) boson pair production in association with two jets at LO+PS.

# collider setup
BEAMS: 2212
BEAM_ENERGIES: 6500

# ME-Generator settings
ME_GENERATORS:
- Comix
COMIX_DEFAULT_GAUGE: 0

# scales
MEPS:
  CORE_SCALE: VAR{0.5*Abs2(p[2]+p[3])} 

# width 0 for the stable W bosons in the hard matrix element
# width 0 for Z boson to preserve SU(2) Ward Identities
PARTICLE_DATA:
  24: {Width: 0}
  23: {Width: 0}
WIDTH_SCHEME: Fixed

# decay channels & polarization settings
HARD_DECAYS:
  Enabled: true
  Channels:
    24,12,-11: {Status: 2}
    24,14,-13: {Status: 2}
  Pol_Cross_Section: 
   Enabled: true
   Reference_System: [Lab, COM]

# vector boson production process
PROCESSES:
- 93 93 -> 24 24 93 93:
    Order: {QCD: 0, EW: 4} 

# cuts on PROCESSES final state particles
SELECTORS:
- FastjetSelector:
    Expression: Mass(p[4]+p[5])>500 
    Algorithm: antikt
    N: 2
    PTMin: 20.0
    EtaMax: 5.0
- FastjetSelector:
    Expression: abs(Eta(p[4])-Eta(p[5]))>2.5
    Algorithm: antikt
    N: 2
    PTMin: 20.0
    EtaMax: 5.0

Things to notice:

  • The COMIX_DEFAULT_GAUGE is set to a special value to get the polarization vectors mentioned in section Simulation of polarized cross sections for intermediate particles .

  • The width of the \(\mathrm{W}^\pm\) boson is set to zero to retain gauge invariance since it is considered as stable during the hard scattering process (PROCESSES). To preserve SU(2) Ward Identities also the width of the Z boson need to be set to zero then.

  • The process is divided into the production of the vector bosons (PROCESSES) and their decays (HARD_DECAYS), all matrix elements are calculated with on-shell vector bosons (narrow-width approximation). Mass_Smearing and SPIN_CORRELATIONS are enabled per default.

8.6.8. Polarized \(\mathrm{W}^+\) Z boson pair production -pair production at nLO+PS

This is an example for the simulation of polarized cross sections for pure electroweak \(\mathrm{W}^+\) Z boson pair production at nLO+PS. The resulting unpolarized cross section contains all NLO QCD corrections while for polarized cross sections the effect of virtual corrections on the polarization fractions is neglected.

# collider setup
BEAMS: 2212
BEAM_ENERGIES: 6500

# settings matrix-element generation
ME_GENERATORS:
  - Comix
  - Amegic
  - OpenLoops
COMIX_DEFAULT_GAUGE: 0

# scale setting
SCALES: METS{0.25*sqr(80.352+91.153)}

# width 0 for the stable vector bosons in the hard matrix element
PARTICLE_DATA:
  24: 
    Width: 0
  23:
    Width: 0
WIDTH_SCHEME: Fixed

# speed and neg weight fraction improvements
NLO_CSS_PSMODE: 2

# vector boson production part pp -> WZ
PROCESSES:
# leading order
- 93 93 -> 24 23:
    Order: {QCD: 0, EW: 2}
# NLO QCD corrections
    NLO_Mode: MC@NLO
    NLO_Order: {QCD: 1, EW: 0}
    ME_Generator: Amegic
    RS_ME_Generator: Comix
    Loop_Generator: OpenLoops

# vector boson decays
HARD_DECAYS:
  Enabled: true
  Channels:
    24,12,-11: {Status: 2}
    23,13,-13: {Status: 2}
# settings for polarized cross sections 
  Pol_Cross_Section:
    Enabled: true
    Reference_System: [Lab, COM]

8.7. Event generation in the MSSM using UFO

This is an example for event generation in the MSSM using Sherpa’s UFO support. In the corresponding Example directory <prefix>/share/SHERPA-MC/Examples/UFO_MSSM/, you will find a directory MSSM that contains the UFO output for the MSSM (https://feynrules.irmp.ucl.ac.be/wiki/MSSM). To run the example, generate the model as described in UFO Model Interface by executing

$ cd <prefix>/share/SHERPA-MC/Examples/UFO_MSSM/
$ <prefix>/bin/Sherpa-generate-model MSSM

An example run card will be written to the working directory. Use this run card as a template to generate events.

8.8. Deep-inelastic scattering

8.8.1. DIS at HERA

This is an example of a setup for hadronic final states in deep-inelastic lepton-nucleon scattering at a centre-of-mass energy of 300 GeV. Corresponding measurements were carried out by the H1 and ZEUS collaborations at the HERA collider at DESY Hamburg.

# collider setup
BEAMS: [-11, 2212]
BEAM_ENERGIES: [27.5, 820]
PDF_SET: [None, Default]

# technical parameters
TAGS:
  QCUT: 5
  SDIS: 1.0
  LGEN: BlackHat
ME_GENERATORS:
  - Comix
  - Amegic
  - $(LGEN)
RESPECT_MASSIVE_FLAG: true
CSS_KIN_SCHEME: 1

# hadronization tune
PARJ:
  - [21, 0.432]
  - [41, 1.05]
  - [42, 1.0]
  - [47, 0.65]
MSTJ:
  - [11, 5]
FRAGMENTATION: Lund
DECAYMODEL: Lund

PROCESSES:
- -11 93 -> -11 93 93{4}:
    CKKW: $(QCUT)/sqrt(1.0+sqr($(QCUT)/$(SDIS))/Abs2(p[2]-p[0]))
    Order: {QCD: 0, EW: 2}
    Max_N_Quarks: 6
    Loop_Generator: $(LGEN)
    2->2-3:
      NLO_Mode: MC@NLO
      NLO_Order: {QCD: 1, EW: 0}
      ME_Generator: Amegic
      RS_ME_Generator: Comix
    2->3:
      PSI_ItMin: 25000
      Integration_Error: 0.03

SELECTORS:
- [Q2, -11, -11, 4, 1e12]

Things to notice:

  • the beams are asymmetric with the positrons at an energy of 27.5 GeV, while the protons carry 820 GeV of energy.

  • the multi-jet merging cut is set dynamically for each event, depending on the photon virtuality, see [CGH10].

  • there is a selector cut on the photon virtuality. This cut implements the experimental requirements for identifying the deep-inelastic scattering process.

8.9. Fixed-order next-to-leading order calculations

8.9.1. Production of NTuples

Root NTuples are a convenient way to store the result of cumbersome fixed-order calculations in order to perform multiple analyses. This example shows how to generate such NTuples and reweighted them in order to change factorisation and renormalisation scales. Note that in order to use this setup, Sherpa must be configured with option -DSHERPA_ENABLE_ROOT=ON, see Event output formats. If Sherpa has not been configured with Rivet analysis support, please disable the analysis using -a0 on the command line, see Command Line Options.

When using NTuples, one needs to bear in mind that every calculation involving jets in the final state is exclusive in the sense that a lower cut-off on the jet transverse momenta must be imposed. It is therefore necessary to check whether the event sample stored in the NTuple is sufficiently inclusive before using it. Similar remarks apply when photons are present in the NLO calculation or when cuts on leptons have been applied at generation level to increase efficiency. Every NTuple should therefore be accompanied by an appropriate documentation.

NTuple compression can be customized using the parameter ROOTNTUPLE_COMPRESSION, which is used to call TFile::SetCompressionSettings. For a detailed documentation of available options, see http://root.cern.ch

This example will generate NTuples for the process pp->lvj, where l is an electron or positron, and v is an electron (anti-)neutrino. We identify parton-level jets using the anti-k_T algorithm with R=0.4 [CSS08]. We require the transverse momentum of these jets to be larger than 20 GeV. No other cuts are applied at generation level.

EVENTS: 100k
EVENT_GENERATION_MODE: Weighted
TAGS:
  LGEN: BlackHat
ME_GENERATORS: [Amegic, $(LGEN)]
# Analysis (please configure with -DSHERPA_ENABLE_RIVET=ON & -DSHERPA_ENABLE_HEPMC2=ON)
ANALYSIS: Rivet
ANALYSIS_OUTPUT: Analysis/HTp/BVI/
# NTuple output (please configure with '-DSHERPA_ENABLE_ROOT=ON')
EVENT_OUTPUT: EDRoot[NTuple_B-like]
BEAMS: 2212
BEAM_ENERGIES: 3500
SCALES: VAR{sqr(sqrt(H_T2)-PPerp(p[2])-PPerp(p[3])+MPerp(p[2]+p[3]))/4}
EW_SCHEME: 0
WIDTH_SCHEME: Fixed  # sin\theta_w -> 0.23
DIPOLES: {ALPHA: 0.03}
PARTICLE_DATA:
  13: {Massive: true}
  15: {Massive: true}
PROCESSES:
# The Born piece
- 93 93 -> 90 91 93:
    Order: {QCD: 1, EW: 2}
    NLO_Order: {QCD: 1, EW: 0}
    NLO_Mode: Fixed_Order
    NLO_Part: B
# The virtual piece
- 93 93 -> 90 91 93:
    Order: {QCD: 1, EW: 2}
    NLO_Order: {QCD: 1, EW: 0}
    NLO_Mode: Fixed_Order
    NLO_Part: V
    Loop_Generator: $(LGEN)
# The integrated subtraction piece
- 93 93 -> 90 91 93:
    Order: {QCD: 1, EW: 2}
    NLO_Order: {QCD: 1, EW: 0}
    NLO_Mode: Fixed_Order
    NLO_Part: I
SELECTORS:
- FastjetFinder:
    Algorithm: antikt
    N: 1
    PTMin: 20
    ETMin: 0
    DR: 0.4
RIVET:
  --analyses: ATLAS_2012_I1083318
  USE_HEPMC_SHORT: 1
  --ignore-beams: 1

Things to notice:

  • NTuple production is enabled by EVENT_OUTPUT: Root[NTuple_B-like], see Event output formats.

  • The scale used is defined as in [BBD+09].

  • EW_SCHEME: 0 and WIDTH_SCHEME: Fixed are used to set the value of the weak mixing angle to 0.23, consistent with EW precision measurements.

  • DIPOLES:ALPHA: 0.03 is used to limit the active phase space of dipole subtractions.

  • 13:Massive: true and 15:Massive: 1 are used to limit the number of active lepton flavours to electron and positron.

  • The option USE_HEPMC_SHORT: 1 is used in the Rivet analysis section as the events produced by Sherpa are not at particle level.

8.9.1.1. NTuple production

Start Sherpa using the command line

$ Sherpa Sherpa.B-like.yaml

Sherpa will first create source code for its matrix-element calculations. This process will stop with a message instructing you to compile. Do so by running

$ ./makelibs -j4

Launch Sherpa again, using

$ Sherpa Sherpa.B-like.yaml

Sherpa will then compute the Born, virtual and integrated subtraction contribution to the NLO cross section and generate events. These events are analysed using the Rivet library and stored in a Root NTuple file called NTuple_B-like.root. We will use this NTuple later to compute an NLO uncertainty band.

The real-emission contribution, including subtraction terms, to the NLO cross section is computed using

$ Sherpa Sherpa.R-like.yaml

Events are generated, analysed by Rivet and stored in the Root NTuple file NTuple_R-like.root.

The two analyses of events with Born-like and real-emission-like kinematics need to be merged, which can be achieved using scripts like yodamerge. The result can then be plotted and displayed.

8.9.1.2. Usage of NTuples in Sherpa

Next we will compute the NLO uncertainty band using Sherpa. To this end, we make use of the Root NTuples generated in the previous steps. Note that the setup files for reweighting are almost identical to those for generating the NTuples. We have simply replaced EVENT_OUTPUT by EVENT_INPUT.

We re-evaluate the events with the scale variation as defined in the Reweight configuration files:

$ Sherpa Sherpa.Reweight.B-like.yaml
$ Sherpa Sherpa.Reweight.R-like.yaml

The contributions can again be combined using yodamerge.

8.9.2. MINLO

The following configuration file shows how to implement the MINLO procedure from [HNZ]. A few things to note are detailed below. MINLO can also be applied when reading NTuples, see Production of NTuples. In this case, the scale and K factor must be defined, see SCALES and KFACTOR.

BEAMS: 2212
BEAM_ENERGIES: 6500

EVENT_GENERATION_MODE: W
CORE_SCALE: VAR{Abs2(p[2]+p[3])+0.25*sqr(sqrt(H_T2)-PPerp(p[2])-PPerp(p[3])+PPerp(p[2]+p[3]))}

PROCESSES:
- 93 93 -> 11 -12 93:
    Scales: MINLO
    KFactor: MINLO
    ME_Generator: Amegic
    Loop_Generator: BlackHat
    Order: {QCD: 1, EW: 2}

SELECTORS:
- [Mass, 11, -12, 2, E_CMS]
- FastjetFinder:
    Algorithm: antikt
    N: 1
    PTMin: 1.0
    ETMin: 1.0
    DR: 0.4

Things to notice:

  • The R parameter of the flavour-based kT clustering algorithm can be changed using MINLO:DELTA_R.

  • Setting MINLO: {SUDAKOV_MODE: 0} defines whether to include power corrections stemming from the finite parts in the integral over branching probabilities. It defaults to 1.

  • The parameter MINLO:SUDAKOV_PRECISION defines the precision target for integration of the Sudakov exponent. It defaults to 1e-4.

8.10. Soft QCD: Minimum Bias and Cross Sections

8.10.1. Calculation of inclusive cross sections

Note that this example is not yet updated to the new YAML input format. Contact the Authors for more information.

(run){
  OUTPUT              = 2
  EVENT_TYPE          = MinimumBias
  SOFT_COLLISIONS     = Shrimps
  Shrimps_Mode        = Xsecs

  deltaY    =  1.5;
  Lambda2   =  1.7;
  beta_0^2  =  20.0;
  kappa     =  0.6;
  xi        =  0.2;
  lambda    =  0.3;
  Delta     =  0.4;
}(run)

(beam){
  BEAM_1 =  2212; BEAM_ENERGY_1 = 450.;
  BEAM_2 =  2212; BEAM_ENERGY_2 = 450.;
}(beam)

(me){
  ME_SIGNAL_GENERATOR = None
}(me)

Things to notice:

  • Inclusive cross sections (total, inelastic, low-mass single-diffractive, low-mass double-diffractive, elastic) and the elastic slope are calculated for varying centre-of-mass energies in pp collisions

  • The results are written to the file InclusiveQuantities/xsecs_total.dat and to the screen. The directory will automatically be created in the path from where Sherpa is run.

  • The parameters of the model are not very well tuned.

8.10.2. Simulation of Minimum Bias events

Contact the Authors for more information.

BEAMS: 2212
BEAM_ENERGIES: 3500

EVENT_TYPE:          MinimumBias
ME_GENERATORS:       None
SOFT_COLLISIONS:     Shrimps
Shrimps_Mode:        Inelastic
FRAGMENTATION:       Ahadic
YFS:
  MODE:              None

ANALYSIS: Rivet
ANALYSIS_OUTPUT: Shrimps

RIVET:
  --analyses: [ATLAS_2010_S8918562, ATLAS_2010_S8894728, ATLAS_2011_S8994773, ATLAS_2012_I1084540, TOTEM_2012_I1115294, CMS_2011_S8978280, CMS_2011_S9120041, CMS_2011_S9215166]

Things to notice:

  • The SHRiMPS model is not properly tuned yet – all parameters are set to very natural values, such as for example 1.0 GeV for infrared parameters.

  • Elastic scattering and low-mass diffraction are not included.

  • A large number of Minimum Bias-type analyses is enabled.

8.11. Setups for event production at B-factories

8.11.1. QCD continuum

Example setup for QCD continuum production at the Belle/KEK collider. Please note, it does not include any hadronic resonance.

# collider setup
BEAMS:  [11, -11]
BEAM_ENERGIES: [7., 4.]

# model parameters
ALPHAS(MZ): 0.1188
ORDER_ALPHAS: 1
PARTICLE_DATA:
  4: {Massive: 1}
  5: {Massive: 1}
MASSIVE_PS: 3

PROCESSES:
- 11 -11 -> 93 93:
    Order: {QCD: 0, EW: 2}
- 11 -11 -> 4 -4:
    Order: {QCD: 0, EW: 2}
- 11 -11 -> 5 -5:
    Order: {QCD: 0, EW: 2}

Things to notice:

  • Asymmetric beam energies, photon ISR is switched on per default.

  • Full mass effects of c and b quarks computed.

  • Strong coupling constant value set to 0.1188 and two loop (NLO) running.

8.11.2. Signal process

Example setup for B-hadron pair production on the Y(4S) pole.

# collider setup
BEAMS:  [11, -11]
BEAM_ENERGIES: [7., 4.]

# model parameters
ALPHAS(MZ): 0.1188
ORDER_ALPHAS: 1
PARTICLE_DATA:
  4: {Massive: 1}
  5: {Massive: 1}
MASSIVE_PS: 3
ME_GENERATORS: Internal
CORE_SCALE: VAR{sqr(91.2)}

PROCESSES:
#
# electron positron -> Y(4S) -> B+ B-
#
- 11 -11 -> 300553[a]:
    Decay: "300553[a] -> 521 -521"
    Order: {QCD: 0, EW: 0}
#
# electron positron -> Y(4S) -> B0 B0bar
#
- 11 -11 -> 300553[a]:
    Decay: "300553[a] -> 511 -511"
    Order: {QCD: 0, EW: 0}

Things to notice:

  • Same setup as QCD continuum, except for process specification.

  • Production of both B0 and B+ pairs, in due proportion.

8.11.3. Single hadron decay chains

This setup is not a collider setup, but a simulation of a hadronic decay chain.

# collider setup
BEAMS:  [11, -11]
BEAM_ENERGIES: [7., 4.]

# general settings
EVENT_TYPE: HadronDecay

# specify hadron to be decayed
DECAYER: 511

# initialise rest for Sherpa not to complain
# model parameters
SCALES: VAR{sqr(91.2)}

PROCESSES:
- 11 -11 -> 13 -13:
    Order: {QCD: 0, EW: 2}

Things to notice:

  • EVENT_TYPE is set to HadronDecay.

  • DECAYER specifies the hadron flavour initialising the decay chain.

  • A place holder process is declared such that the Sherpa framework can be initialised. That process will not be used.

8.12. Calculating matrix element values for externally given configurations

8.12.1. Computing matrix elements for individual phase space points using the Python Interface

Sherpa’s Python interface (see Python Interface) can be used to compute matrix elements for individual phase space points. Access to a designated class “MEProcess” is provided by interface to compute matrix elements as illustrated in the example script.

Please note that the process in the script must be compatible with the one specified in the Sherpa configuration file in the working directory. A random phase space point for the process of interest can be generated as shown in the example.

If AMEGIC++ is used as the matrix element generator, executing the script will result in AMEGIC++ writing out libraries and exiting. After compiling the libraries using ./makelibs, the script must be executed again in order to obtain the matrix element.

#!/usr/bin/env python
@LOADMPIFORPY@
import sys
sys.path.append('@PYLIBDIR@')
import Sherpa

# Add this to the execution arguments to prevent Sherpa from starting the cross section integration
sys.argv.append('INIT_ONLY: 2')

Generator=Sherpa.Sherpa(len(sys.argv),sys.argv)
try:
    Generator.InitializeTheRun()
    Process=Sherpa.MEProcess(Generator)

    # Incoming flavors must be added first!
    Process.AddInFlav(11);
    Process.AddInFlav(-11);
    Process.AddOutFlav(1);
    Process.AddOutFlav(-1);
    Process.Initialize();

    # First argument corresponds to particle index:
    # index 0 correspons to particle added first, index 1 is the particle added second, and so on...
    Process.SetMomentum(0, 45.6,0.,0.,45.6)
    Process.SetMomentum(1, 45.6,0.,0.,-45.6)
    Process.SetMomentum(2, 45.6,0.,45.6,0.)
    Process.SetMomentum(3, 45.6,0.,-45.6,0.)
    print('\nSquared ME: ', Process.CSMatrixElement())

    # Momentum setting via list of floats
    Process.SetMomenta([[45.6,0.,0.,45.6],
                        [45.6,0.,0.,-45.6],
                        [45.6,0.,45.6,0.],
                        [45.6,0.,-45.6,0.]])
    print('\nSquared ME: ', Process.CSMatrixElement())
    
    # Random momenta
    E_cms = 500.0
    wgt = Process.TestPoint(E_cms)
    print('\nRandom test point ')
    print('Squared ME: ', Process.CSMatrixElement(), '\n')

except Sherpa.SherpaException as exc:
    print(exc)
    exit(1)

8.12.2. Computing matrix elements for individual phase space points using the C++ Interface

Matrix elements values for user defined phase space points can also be quarried using a small C++ executable provided in Examples/API/ME2. It can be compiled using the provided Makefile. The test program is then run typing (note: the LD_LIBRARY_PATH must be set to include <Sherpa-installation>/lib/SHERPA-MC)

$ ./test <options>

where the usual options for Sherpa are passed. An example configuration file, giving both the process and the requested phase space points looks like

BEAMS: [11, -11]
BEAM_ENERGIES: 45.6

EVENTS: 0
INIT_ONLY: 2
PDF_LIBRARY: None

PROCESSES:
- 11 -11 -> 2 -2 21 21 21 21: {}

MOMENTA:
  - [
      [  11,  45.6,   0.0,   0.0,  45.6 ],
      [ -11,  45.6,   0.0,   0.0, -45.6 ],
      [  21,  10.0,   0.0,   0.0, -10.0, 1, 2 ],
      [  21,  10.0,   0.0,   0.0,  10.0, 2, 3 ],
      [  21,  10.0,  10.0,   0.0,   0.0, 3, 1 ],
      [  21,  10.0, -10.0,   0.0,   0.0, 1, 3 ],
      [   2,  25.6,   0.0,  25.6,   0.0, 3, 0 ],
      [  -2,  25.6,   0.0, -25.6,   0.0, 0, 1 ]
    ]
  - [
      [  11,  45.6,   0.0,   0.0,  45.6 ],
      [ -11,  45.6,   0.0,   0.0, -45.6 ],
      [  21,  12.0,   0.0,   0.0, -12.0, 1, 2 ],
      [  21,  12.0,   0.0,   0.0,  12.0, 2, 3 ],
      [  21,  12.0,  12.0,   0.0,   0.0, 3, 1 ],
      [  21,  12.0, -12.0,   0.0,   0.0, 1, 3 ],
      [   2,  21.6,   0.0,  21.6,   0.0, 3, 0 ],
      [  -2,  21.6,   0.0, -21.6,   0.0, 0, 1 ]
    ]
  - [
      [  11,  45.6,   0.0,   0.0,  45.6 ],
      [ -11,  45.6,   0.0,   0.0, -45.6 ],
      [  21,  14.0,   0.0,   0.0, -14.0, 1, 2 ],
      [  21,  14.0,   0.0,   0.0,  14.0, 2, 3 ],
      [  21,  14.0,  14.0,   0.0,   0.0, 3, 1 ],
      [  21,  14.0, -14.0,   0.0,   0.0, 1, 3 ],
      [   2,  17.6,   0.0,  17.6,   0.0, 3, 0 ],
      [  -2,  17.6,   0.0, -17.6,   0.0, 0, 1 ]
    ]
  - [
      [  11,  45.6,   0.0,   0.0,  45.6 ],
      [ -11,  45.6,   0.0,   0.0, -45.6 ],
      [  21,  16.0,   0.0,   0.0, -16.0, 1, 2 ],
      [  21,  16.0,   0.0,   0.0,  16.0, 2, 3 ],
      [  21,  16.0,  16.0,   0.0,   0.0, 3, 1 ],
      [  21,  16.0, -16.0,   0.0,   0.0, 1, 3 ],
      [   2,  13.6,   0.0,  13.6,   0.0, 3, 0 ],
      [  -2,  13.6,   0.0, -13.6,   0.0, 0, 1 ]
    ]

Please note that both the process and the beam specifications need to be present in order for Sherpa to initialise properly. The momenta need to be given in the proper ordering employed in Sherpa, which can be read from the process name printed on screen. For each entry the sequence is the following

[<pdg-id>, <E>, <px>, <py>, <pz>, triplet-index, antitriplet-index]

with the colour indices ranging from 1..3 for both the triplet and the antitriplet index in the colour-flow basis. The colour information is only needed if Comix is used for the calculation as Comix then also gives the squared matrix element value for this colour configuration. Otherwise, the last two arguments can be omitted. In any case, the colour-summed value is printed to screen.

8.13. Using the Python interface

8.13.1. Generate events using scripts

This example shows how to generate events with Sherpa using a Python wrapper script. For each event the weight, the number of trials and the particle information is printed to stdout. This script can be used as a basis for constructing interfaces to own analysis routines.

#!/usr/bin/env python
@LOADMPIFORPY@
import sys
sys.path.append('@PYLIBDIR@')
import Sherpa

Generator=Sherpa.Sherpa(len(sys.argv),sys.argv)
try:
    Generator.InitializeTheRun()
    Generator.InitializeTheEventHandler()
    for n in range(1,1+Generator.NumberOfEvents()):
        Generator.GenerateOneEvent()
        blobs=Generator.GetBlobList();
        print("Event",n,"{")
        ## print blobs
        print("  Weight ",blobs.GetFirst(1)["Weight"]);
        print("  Trials ",blobs.GetFirst(1)["Trials"]);
        for i in range(0,blobs.size()):
            print("  Blob",i,"{")
            ## print blobs[i];
            print("    Incoming particles")
            for j in range(0,blobs[i].NInP()):
                part=blobs[i].InPart(j)
                ## print part
                s=part.Stat()
                f=part.Flav()
                p=part.Momentum()
                print("     ",j,": ",s,f,p)
            print("    Outgoing particles")
            for j in range(0,blobs[i].NOutP()):
                part=blobs[i].OutPart(j)
                ## print part
                s=part.Stat()
                f=part.Flav()
                p=part.Momentum()
                print("     ",j,": ",s,f,p)
            print("  } Blob",i)
        print("} Event",n)
        if ((n%100)==0): print("  Event ",n)
    Generator.SummarizeRun()
        
except Sherpa.SherpaException as exc:
    exit(1)

8.13.2. Generate events with MPI using scripts

This example shows how to generate events with Sherpa using a Python wrapper script and MPI. For each event the weight, the number of trials and the particle information is send to the MPI master node and written into a single gzip’ed output file. Note that you need the mpi4py module to run this Example. Sherpa must be configured and installed using -DSHERPA_ENABLE_MPI, see MPI parallelization.

#!/usr/bin/env python
@LOADMPIFORPY@
import sys
sys.path.append('@PYLIBDIR@')
import Sherpa
import gzip

class MyParticle:
    def __init__(self,p):
        self.kfc=p.Flav().Kfcode()
        if p.Flav().IsAnti(): self.kfc=-self.kfc
        self.E=p.Momentum()[0]
        self.px=p.Momentum()[1]
        self.py=p.Momentum()[2]
        self.pz=p.Momentum()[3]
    def __str__(self):
        return (str(self.kfc)+" "+str(self.E)+" "
                +str(self.px)+" "+str(self.py)+" "+str(self.pz))

Generator=Sherpa.Sherpa(len(sys.argv),sys.argv)
try:
    Generator.InitializeTheRun()
    Generator.InitializeTheEventHandler()
    comm=MPI.COMM_WORLD
    rank=comm.Get_rank()
    size=comm.Get_size()
    if rank==0:
        outfile=gzip.GzipFile("events.gz",'w')
        for n in range(1,1+Generator.NumberOfEvents()):
            for t in range(1,size):
                weight=comm.recv(source=t,tag=t)
                trials=comm.recv(source=t,tag=2*t)
                parts=comm.recv(source=t,tag=3*t)
                outfile.write("E "+str(weight)+" "+str(trials)+"\n")
                for p in parts:
                    outfile.write(str(p)+"\n")
            if (n%100)==0: print("  Event",n)
        outfile.close()
    else:
        for n in range(1,1+Generator.NumberOfEvents()):
            Generator.GenerateOneEvent()
            blobs=Generator.GetBlobList();
            weight=blobs.GetFirst(1)["Weight"]
            trials=blobs.GetFirst(1)["Trials"]
            parts=[]
            for i in range(0,blobs.size()):
                for j in range(0,blobs[i].NOutP()):
                    part=blobs[i].OutPart(j)
                    if part.Stat()==1 and part.HasDecBlob()==0:
                        parts.append(MyParticle(part))
            comm.send(weight,dest=0,tag=rank)
            comm.send(trials,dest=0,tag=2*rank)
            comm.send(parts,dest=0,tag=3*rank)
    Generator.SummarizeRun()

except Sherpa.SherpaException as exc:
    exit(1)