Tutorials#
These tutorials walk through running Achilles with the example run cards shipped in
the examples/ directory. Each tutorial explains the run card configuration, shows
how to launch the simulation, and describes the expected output.
Before starting, make sure Achilles is built and the executable is available (see Building Achilles).
Tutorial 1: Quasielastic Neutrino Scattering on Carbon#
This tutorial uses the run card examples/run_nue_12C_SF_1000.yml, which simulates
charged-current quasielastic (CCQE) electron-neutrino scattering on a 12C
target at 1 GeV using a spectral function nuclear model.
The run card#
Main:
NEvents: 10
HardCuts: false
RunDecays: false
Output:
Format: NuHepMC
Name: achilles_nue_12C_SF_1000.hepmc
Zipped: True
NEvents: Number of unweighted events to generate. Increase this for production runs (e.g. 50000).
HardCuts: No kinematic cuts are applied at the hard scattering level.
Output: Events are written in NuHepMC format, gzip-compressed.
Processes:
- Leptons: [12, [11]]
The process line defines the leptonic current: an incoming \(\nu_e\) (PID 12) producing an outgoing \(e^-\) (PID 11). This is charged-current scattering.
Beams:
- Beam:
PID: 12
Beam Params:
Type: Monochromatic
Energy: 1000
A monochromatic \(\nu_e\) beam at 1000 MeV.
Cascade:
Run: False
The intranuclear cascade is disabled. The output contains only the primary hard scattering products. See Tutorial 3 for enabling the cascade.
NuclearModels:
- NuclearModel:
Model: QESpectral
FormFactorFile: "FormFactors.yml"
SpectralP: data/Spectral_Functions/pke12p_tot.data
SpectralN: data/Spectral_Functions/pke12n_tot.data
Ward: None
The nuclear model is QESpectral – quasielastic scattering computed with proton
and neutron spectral functions for 12C. No Ward gauge correction is applied.
Nuclei:
- Nucleus:
Name: 12C
Binding: 8.6
Fermi Momentum: 225
...
The target nucleus is 12C with a binding energy of 8.6 MeV and Fermi momentum of 225 MeV. The density profile and nucleon configurations are loaded from the data files.
Running the simulation#
From the build directory:
$ ./achilles ../examples/run_nue_12C_SF_1000.yml
Achilles will:
Initialise the adaptive Monte Carlo integrator.
Run an optimisation phase to map out the phase space.
Generate the requested number of unweighted events.
Write the output to
achilles_nue_12C_SF_1000.hepmc.gz.
Progress is logged to the terminal and to achilles.log.
Expected output#
The output file achilles_nue_12C_SF_1000.hepmc.gz contains unweighted events
in NuHepMC format. Each event has:
An incoming \(\nu_e\) and a target nucleus (12C).
A primary vertex with an outgoing \(e^-\) and a knocked-out nucleon.
Spectator nucleons from the nuclear configuration.
Event weights and cross-section metadata.
Tutorial 2: Electron Scattering on Hydrogen#
This tutorial uses examples/run_electron_1H_SF_1000.yml, which simulates
electron scattering on a free proton (hydrogen) at 1 GeV. This is a simpler
configuration that serves as a good starting point for understanding the code.
Key differences from Tutorial 1#
Processes:
- Leptons: [11, [11]]
Both the incoming and outgoing leptons are electrons (PID 11). This is electromagnetic (electron) scattering rather than neutrino scattering.
Main:
HardCuts: true
HardCuts:
- Type: AngleTheta
PIDs: 11
range: [10, 90]
Hard cuts are enabled. The outgoing electron is required to have a polar angle \(\theta\) between 10 and 90 degrees. This mimics a typical electron scattering experiment acceptance.
Nuclei:
- Nucleus:
Name: 1H
The target is hydrogen (a free proton). Because there is no nuclear medium, the spectral function and Fermi gas settings have no effect – Achilles automatically treats hydrogen as a single-nucleon target.
Running the simulation#
$ ./achilles ../examples/run_electron_1H_SF_1000.yml
Expected output#
The output file achilles_electron_1000_SF_1H.hepmc.gz contains events with:
An incoming and outgoing electron.
A recoil proton.
No nuclear effects (no spectator nucleons, no cascade).
This provides a clean baseline for validating form factor implementations against known electron-proton scattering data.
Tutorial 3: Enabling the Cascade#
The intranuclear cascade (INC) propagates hadronic final-state particles through the nuclear medium, allowing them to rescatter, produce pions, or be absorbed. This tutorial shows how to modify a run card to enable the cascade.
Modifying the run card#
Starting from examples/run_nue_12C_SF_1000.yml, change the Cascade section:
Cascade:
Run: True
Interaction:
Name: GeantInteractions
GeantData: data/GeantData.hdf5
Step: 0.04
Probability: Cylinder
Setting Run: True activates the cascade. The key parameters are:
Interaction: The interaction model used during propagation.
GeantInteractionsuses tabulated nucleon-nucleon cross sections from Geant4 data.Step: The propagation step size in fm. Smaller values give higher accuracy.
Probability: The model for computing interaction probability at each step.
For more sophisticated cascade configurations using the virtual-resonance model,
see the Cascade section of the Run Card Structure documentation, which
describes the NucleonNucleon, DeltaInteraction, and PionInteraction models.
What changes in the output#
With the cascade enabled, events will contain additional vertices and particles beyond the primary interaction:
Rescattered nucleons: Nucleons that interacted with the nuclear medium during propagation, visible as cascade vertices.
Produced pions: Secondary pions created through nucleon-nucleon or Delta-resonance interactions.
Absorbed particles: Particles that were captured by the nucleus and do not appear in the final state.
The vertex status codes in the NuHepMC output distinguish primary interaction vertices from cascade vertices, making it straightforward to separate the hard scattering from final-state interactions in analysis.
Running with the cascade increases computation time per event because each hadronic particle must be propagated step-by-step through the nucleus.