3. Run Card Structure#
An Achilles simulation is steered by a set of options. These options enable the user to run Achilles in various ways to study the different physics choices in the code.
The options have to be specified in a run card which by default is named run.yml residing in the current
working directory. If you want to use a different run card, it can be passed into the Achilles executable
as the first positional argument (achilles <input_file>).
All of the configurations options are written in the YAML format. The different sections in the run card are described below, along with the currently available options, and references to the physics where appropriate.
Warning
Achilles is still in beta development, and the options are subject to change before the v1.0 release of Achilles.
3.1. Including External Files#
Any value in the run card can be replaced by the contents of a separate YAML file using the
custom !include tag:
SomeKey: !include "path/to/file.yml"
When Achilles loads the run card it replaces every !include scalar with the fully parsed
contents of the referenced file. The path is resolved relative to the Achilles data search
paths (first in the current working directory, then the environment variable ACHILLES_PATH, and finally the install location); absolute paths are also accepted. Included files are
processed recursively, so an included file may itself contain further !include tags.
The !include tag is particularly useful for sharing nucleus definitions, cascade
interaction tables, form factor files, and option defaults across multiple run cards without
duplicating their contents. The pre-supplied defaults under data/default/ make
extensive use of this mechanism:
Nuclei:
- Nucleus: !include "data/default/12C.yml"
Cascade:
Interactions: !include "data/default/VirtResInteractions.yml"
Options: !include "data/default/OptionDefaults.yml"
3.2. Main Settings#
The first section in the run card is the Main section. This section contains information about the basic options for running Achilles. These include:
NEvents(integer): Number of unweighted events to generateHardCuts(boolean): Flag to turn on / off cuts at the hard scattering levelEventCuts(boolean): [deprecated] Handles cuts to be applied after all simulation stepsRunDecays(boolean): Decay particles that are unstable longer than the typical cascade time scale, such as tau leptons (requires Sherpa to be linked)Output(YAML Node): Parameters determining how events are written out to fileFormat(string): Format of file to be written out. Current supported options are:NuHepMC(default),HepMC([deprecated]), andAchilles.Name(string): File path from the current working directory to write the events out toZipped(boolean): Flag to determine if the output should be written compressed using the gzip library or not.
Additional discussion on the output formats are discussed in detail in the Output Formats section.
Example:
Main:
NEvents: 50000
HardCuts: true
RunDecays: false
Output:
Format: NuHepMC
Name: achilles.hepmc
Zipped: true
3.3. Processes#
The processes section is where the set of incoming and outgoing leptons are listed. Each line in this section denotes a process to calculate. Achilles will combine this information with the list of nuclear models to consider listed in NuclearModels.
An example setup for running both neutral current and charged current is given below:
Processes:
- Leptons: [14, [14]]
- Leptons: [14, [13]]
The above code block can be broken down as follows. First is the YAML node giving the name of the section
in this case Processes. It is followed by a YAML list item. Each list item is described first by
denoting that it is describing the leptons in the process, and then followed by a list of two elements.
The first item is the PID for the incoming lepton. The second item is a list of all outgoing leptons.
Note
In order to handle processes with final states beyond single leptons, Achilles needs to be compiled with Sherpa support to handle the n-body final state phase space.
The allowed values for the leptons are any that are defined in the model using the standard Particle Data Group Particle Identification Codes (PID) numbering scheme. This section is designed to be flexible enough to define arbitrary processes that the user would be interested in studying through the use of the Achilles event generator. The extension to Beyond the Standard Model particles is also supported in this section through the use of the Sherpa interface. For details on defining the physics model to be used, please see the discussion in Sherpa Options.
3.4. Beams#
The Beams section defines the energy distribution(s) of the incoming beam particle(s).
Each entry in the list specifies a single beam via its PDG PID and a Beam Params
sub-node that selects the beam type and its parameters.
Beams:
- Beam:
PID: 14
Beam Params:
Type: Monochromatic
Energy: 1000
Multiple entries are allowed when running with more than one beam species simultaneously; however, all beams must share the same energy range.
3.4.1. Beam Params types#
Monochromatic
A fixed-energy beam. All events use exactly the specified energy.
Beam Params:
Type: Monochromatic
Energy: 1108 # beam energy in MeV
Key |
Description |
|---|---|
|
Beam energy in MeV. |
Spectrum
A beam whose energy is sampled from a flux histogram read from a data file. The file
format is auto-detected from its header line; supported formats are Achilles,
MiniBooNE, and T2K (ND280).
Beam Params:
Type: Spectrum
Histogram: flux/my_flux.txt
Alternatively, a flux histogram stored in a HepData YAML file can be used:
Beam Params:
Type: Spectrum
HepData: flux/my_flux.yaml
If Achilles is compiled with ROOT support, a ROOT histogram can be specified:
Beam Params:
Type: Spectrum
ROOTHist:
File: my_flux.root # resolved under flux/ directory
Key |
Description |
|---|---|
|
Path to a text-format flux histogram. The file format ( |
|
Path to a HepData YAML file containing the flux histogram. |
|
Sub-node with a |
FlatFlux
A beam with a uniform (flat) energy distribution between MinEnergy and MaxEnergy.
Beam Params:
Type: FlatFlux
MinEnergy: 200 # MeV
MaxEnergy: 2000 # MeV
Key |
Description |
|---|---|
|
Minimum beam energy in MeV. |
|
Maximum beam energy in MeV. |
3.5. Cascade#
The Cascade section controls the intranuclear cascade (INC) that propagates the
hadronic final-state particles through the nucleus after the hard interaction.
Cascade:
Run: false
Interactions: !include "data/default/VirtResInteractions.yml"
Step: 0.04
Probability: Cylinder
InMedium: None
PotentialProp: false
Algorithm: Base
Key |
Description |
|---|---|
|
Boolean. Set to |
|
List of interaction model definitions used during the cascade. Typically
provided via |
|
Step size for particle propagation through the nucleus in fm. Smaller values
increase accuracy at the cost of computation time. Default: |
|
Model used to compute the interaction probability at each step. Accepted
values: |
|
In-medium correction applied to particle kinematics during propagation.
Accepted values: |
|
Boolean. When |
|
Cascade algorithm. Accepted values: |
3.5.1. Interaction Models#
The Interactions list specifies which hadronic interaction models are active
during the cascade. Each entry requires a Name and an Options sub-node.
NucleonNucleon
Nucleon–nucleon rescattering.
- Name: NucleonNucleon
Options:
Mode: GiBUU
ResonanceMode: Decay
ExpSup: 0.0
Option |
Description |
|---|---|
|
Cross-section parametrisation. Currently only |
|
Treatment of resonances produced during NN scattering. |
|
Exponential suppression factor. Set to |
DeltaInteraction
Delta resonance interactions (used together with ResonanceMode: Propagate).
- Name: DeltaInteraction
Options:
Mode: GiBUU
SWaveAbsorption: true
ExpSup: 0.0
Option |
Description |
|---|---|
|
Cross-section parametrisation. Currently only |
|
Boolean. Enable s-wave pion absorption via the Delta using the Oset model. |
|
Exponential suppression factor. Set to |
PionInteraction
Pion rescattering and absorption.
- Name: PionInteraction
Options:
HardScatter:
Name: MesonBaryonInteraction
Options:
Absorption:
Name: PionAbsorptionOneStep
Options:
ConstantInteraction
Assigns a fixed cross section to specified two-body initial states. For example, can be used to give zero-cross-section placeholders to hyperon and photon channels:
- Name: ConstantInteraction
Options:
InitialStates:
- Incoming: [22, 2112]
Outgoing:
- Outgoing: [22, 2112]
CrossSection: 0
Each entry under InitialStates maps a pair of incoming PIDs to one or more
outgoing channels, each with a constant CrossSection in mb.
3.6. NuclearModels#
The NuclearModels section is a list of nuclear model configurations. Achilles
evaluates every listed model for each process defined in Processes, so multiple
models can be run simultaneously within a single job.
Each entry begins with a NuclearModel: key whose sub-node contains at minimum a
Model field identifying the model type, along with model-specific options described
below. The full list of available models loaded into Achilles can be displayed by running
with the option --display-nuc-models.
NuclearModels:
- NuclearModel:
Model: QESpectral
SpectralP: data/Spectral_Functions/pke12p_tot.data
SpectralN: data/Spectral_Functions/pke12n_tot.data
FormFactorFile: "FormFactors.yml"
Ward: None
- NuclearModel:
Model: FortranModel
Name: RES_Spectral_Func
ConfigFile: data/info_C12_pke.data
FormFactorFile: "FormFactors.yml"
Ward: None
3.6.1. Common fields#
The following fields are shared by all model types:
Key |
Description |
|---|---|
|
Model type identifier. Built-in values: |
|
Path to a YAML file defining the form factor parametrisations. See
|
|
Ward–Takahashi identity gauge correction applied to the computed hadronic
current. Accepted values: |
3.6.2. QESpectral#
Quasi-elastic scattering computed with a nucleon spectral function.
NuclearModel:
Model: QESpectral
SpectralP: data/Spectral_Functions/pke12p_tot.data
SpectralN: data/Spectral_Functions/pke12n_tot.data
FormFactorFile: "FormFactors.yml"
Ward: None
Key |
Description |
|---|---|
|
Path to the proton spectral function data file. |
|
Path to the neutron spectral function data file. |
3.6.3. HyperonSpectral#
Hyperon production computed with a nucleon spectral function. The configuration keys
are identical to QESpectral:
NuclearModel:
Model: HyperonSpectral
SpectralP: data/pke12_tot.data
SpectralN: data/pke12_tot.data
FormFactorFile: "FormFactors.yml"
Ward: None
3.6.4. FortranModel#
A nuclear model implemented in Fortran and loaded through the Fortran interface.
NuclearModel:
Model: FortranModel
Name: RES_Spectral_Func
ConfigFile: data/info_C12_pke.data
FormFactorFile: "FormFactors.yml"
Ward: None
Key |
Description |
|---|---|
|
Name of the registered Fortran model to instantiate (must match the name
passed to |
|
Path to the model configuration file passed verbatim to the Fortran |
|
Path to a YAML file whose |
3.6.5. FormFactorFile format#
The form factor YAML file (e.g. data/default/FormFactors.yml) has two parts.
The first part maps each form factor category to its parametrisation name:
vector: Kelly
axial: AxialZExpansion
coherent: Helm
resonancevector: ResonanceVectorDummy
resonanceaxial: ResonanceAxialDummy
mecvector: MesonExchangeVector
mecaxial: MesonExchangeAxial
hyperon: Hyperon
The second part provides the parameter values for each named parametrisation. The
available parametrisations for the vector form factors include Kelly, BBBA,
ArringtonHill, and VectorDipole; for the axial form factor AxialZExpansion
and AxialDipole are supported; for coherent scattering Helm and Lovato
are available. Each parametrisation section must supply the numeric parameters listed
in the corresponding form factor implementation.
3.7. Nuclei#
The Nuclei section is a list of target nuclei to simulate. Each entry is a
Nucleus: node that can be written inline or loaded from a file with !include.
The pre-supplied nucleus files are located in data/default/.
Nuclei:
- Nucleus: !include "data/default/12C.yml"
Currently provided nucleus files: 1H.yml, 1N.yml, 12C.yml, 16O.yml,
40Ar.yml.
3.7.1. Nucleus fields#
Name: 12C
Binding: 8.6 # MeV
Fermi Momentum: 225 # MeV
Density:
ProtonFile: data/densities/c12.prova.txt
NeutronFile: data/densities/c12.prova.txt
FilePotential: data/realOP_12C_EDAI.dat
Function: configuration
Configs: data/configurations/QMC_configs.out.gz
FermiGas:
Type: Local
Correlated: false
SRCfraction: 0.2
LambdaSRC: 2.75
Params: []
Potential:
Name: Schroedinger
r0: 0.16
Mode: 3
Key |
Description |
|---|---|
|
Human-readable nucleus identifier (e.g. |
|
Average binding energy per nucleon in MeV. |
|
Fermi momentum in MeV. |
Density sub-node
Key |
Description |
|---|---|
|
Path to the proton density profile data file. |
|
Path to the neutron density profile data file. |
|
Path to the real optical potential data file. |
|
Density function type. Use |
|
Path to the nucleon configuration file (gzip-compressed). Required when
|
FermiGas sub-node
Key |
Description |
|---|---|
|
Fermi gas model type. Currently |
|
Boolean. Enable short-range correlation (SRC) corrections. |
|
Fraction of nucleons assigned to the SRC component. |
|
SRC momentum cut-off scale in GeV. |
|
List of additional model-specific parameters (may be empty). |
Potential sub-node
Key |
Description |
|---|---|
|
Potential model. Accepted values: |
|
Nuclear saturation density in fm-3. Typical value: |
|
Integer mode flag passed to the potential implementation. |
3.8. HardCuts#
The HardCuts section defines kinematic selection cuts applied to the hard-scattering
final state before event weighting. Cuts are only active when HardCuts: true is set
in Main Settings. Each entry in the list specifies one cut:
HardCuts:
- Type: AngleTheta
PIDs: 11
range: [36.5, 38.5]
Key |
Description |
|---|---|
|
Cut type. |
|
PDG PID of the particle to which the cut is applied. A single integer or a list of integers is accepted. |
|
Two-element list |
For a list of all implemented cuts, a user can run Achilles with the option --display-cuts.
3.9. Options#
The Options section controls the numerical integration and unweighting settings.
It is most conveniently loaded from a shared defaults file:
Options: !include "data/default/OptionDefaults.yml"
The full inline form is:
Options:
Initialize:
Seed: 12345678
Accuracy: 1.0e-2
Unweighting:
Name: Percentile
percentile: 99
Initialize sub-node
Key |
Description |
|---|---|
|
Integer seed for the random number generator. Use different seeds to obtain statistically independent runs. Setting to -1 results in using a different seed each run. |
|
Target relative integration accuracy for the adaptive Monte Carlo integration. Smaller values require more function evaluations. |
Unweighting sub-node
Key |
Description |
|---|---|
|
Unweighting algorithm. |
|
Percentile (0–100) used to set the maximum weight when |
3.10. Backend#
The Backend section selects the cross-section calculation backend.
Backend:
Name: Default
Options: []
Key |
Description |
|---|---|
|
Backend identifier. |
|
Backend-specific options passed as a YAML sequence. The |
3.11. Sherpa Options#
When the Sherpa or BSM backend is selected, Achilles requires a top-level
SherpaOptions section. This is most conveniently provided via !include:
SherpaOptions: !include "data/default/SherpaOptions.yml"
The inline form is:
SherpaOptions:
Model: SMnu
ParamCard: parameters.dat
Key |
Description |
|---|---|
|
Sherpa model identifier. |
|
Path to the Sherpa parameter card file that sets coupling constants and particle masses for the selected model. |
3.12. Output Formats#
The output format is set by the Format key in the Output sub-node of
Main Settings.
NuHepMCThe recommended output format. Events are written in the NuHepMC convention on top of the HepMC3 library. NuHepMC files are readable by standard HepMC3 analysis tools and carry neutrino-experiment-specific metadata. Compressed output (
Zipped: true) uses gzip.HepMC(deprecated)Plain HepMC3 format without NuHepMC metadata. Retained for backward compatibility.
AchillesNative Achilles binary format. This is a compact representation intended for internal debugging and post-processing within the Achilles framework.