4. Interfaces#
4.1. Fortran Interface#
Achilles provides a Fortran interface that allows nuclear models written in Fortran to be used directly within the C++ framework. The interface is structured in three layers:
An abstract Fortran base type (
model) that a user implements.A Fortran factory (
ModelFactory) that manages registration and instantiation of models.A set of ISO C-bound procedures (
nuclear_model_interface) that bridge Fortran to the C++FortranModelclass.
The overall flow when running a simulation is:
At startup,
FortranModel::RegisterModels()calls the FortranRegisterAll()routine, which registers every available Fortran model with the factory.When the YAML run card requests a Fortran-backed nuclear model,
FortranModelcallsCreateModelto instantiate it andInitModelto configure it from the supplied configuration file and parameter map.During event generation
FortranModeldelegates the current calculation and initial-state weighting to the Fortran model viaGetCurrentsandGetInitialStateWeight.
4.1.1. The model Abstract Type#
Defined in src/Achilles/fortran/nuclear_model.f90
Every Fortran nuclear model must extend the abstract model type and implement all of
its deferred procedures.
type, abstract :: model
contains
procedure(nm_init), deferred :: init
procedure(nm_cleanup), deferred :: cleanup
procedure(nm_mode), deferred :: mode
procedure :: frame => nm_frame
procedure(nm_name), deferred, nopass :: model_name
procedure(nm_psname), deferred :: ps_name
procedure(nm_currents), deferred :: currents
procedure(nm_init_wgt), deferred :: init_wgt
procedure(nm_inspirehep), deferred, nopass :: inspirehep
end type model
The table below describes each deferred procedure together with its signature and purpose.
Procedure |
Signature |
Description |
|---|---|---|
|
|
Load model-specific data from |
|
|
Deallocate any resources allocated during |
|
|
Return an integer identifying the nuclear interaction mode (e.g. quasi-elastic,
resonance). The value must match the |
|
|
Return an integer identifying the preferred reference frame. The default
implementation returns |
|
|
Return the unique string name used to identify this model in the run card and
factory. Must match the name passed to |
|
|
Return the name of the phase-space generator required by this model (e.g.
|
|
|
Compute the hadronic transition current. See currents Argument List below for the full argument list. |
|
|
Return the weight from the nuclear initial state (e.g. spectral function or Fermi gas distribution). See init_wgt Argument List below. |
|
|
Return the InspireHEP record identifier (e.g. |
4.1.1.1. currents Argument List#
subroutine nm_currents(self, pids_in, mom_in, nin, &
pids_out, mom_out, nout, &
pids_spect, mom_spect, nspect, &
qvec, ff, cur, nspin, nlorentz)
class(model), intent(inout) :: self
integer(c_size_t), intent(in), value :: nin, nout, nspect, nspin, nlorentz
integer(c_long), dimension(nin), intent(in) :: pids_in
integer(c_long), dimension(nout), intent(in) :: pids_out
integer(c_long), dimension(nspect), intent(in) :: pids_spect
type(fourvector), dimension(nin), intent(in) :: mom_in
type(fourvector), dimension(nout), intent(in) :: mom_out
type(fourvector), dimension(nspect), intent(in) :: mom_spect
type(fourvector), intent(in) :: qvec
type(complex_map), intent(in) :: ff
complex(c_double_complex), dimension(nlorentz, nspin), intent(out) :: cur
ff is a map from form-factor name strings to complex values, pre-evaluated at the
momentum transfer \(Q^2\). cur is filled column-by-column: cur(mu, spin) is
the \(\mu\)-th Lorentz component for spin state spin.
4.1.1.2. init_wgt Argument List#
function nm_init_wgt(self, pids_in, mom_in, nin, &
pids_spect, mom_spect, nspect, &
nproton, nneutron) result(wgt)
class(model), intent(inout) :: self
integer(c_size_t), intent(in), value :: nin, nspect, nproton, nneutron
integer(c_long), dimension(nin), intent(in) :: pids_in
integer(c_long), dimension(nspect), intent(in) :: pids_spect
type(fourvector), dimension(nin), intent(in) :: mom_in
type(fourvector), dimension(nspect), intent(in) :: mom_spect
real(c_double) :: wgt
nproton and nneutron give the proton and neutron number of the target nucleus.
The return value is the probability weight for the sampled initial-state configuration.
4.1.2. The ModelFactory Type#
Defined in src/Achilles/fortran/nuclear_model_factory.f90
ModelFactory maintains a list of named model constructors and creates model instances
on demand.
Procedure |
Description |
|---|---|
|
Initialise the factory (nullify the internal model pointer). |
|
Deallocate and nullify the stored model pointer. |
|
Register a new model. |
|
Return a pointer to a newly-created model matching |
|
Write the names of all registered models to standard output. |
4.1.3. C–Fortran Bridge (nuclear_model_interface)#
Defined in src/Achilles/fortran/nuclear_model_interface.f90
This module exposes ISO C-bound procedures consumed by the C++ FortranModel class.
Users typically do not call these directly, but must call register_all (via the C
entry point RegisterAll) to make their models visible to Achilles.
The module maintains a global ModelFactory instance (factory) and a dynamic
vector of live model instances (models). Each live model is identified by a
1-based size_t index that is returned by CreateModel and passed to every
subsequent call.
C entry point |
Description |
|---|---|
|
Register every built-in Fortran nuclear model with the factory and call
|
|
Print the names of all registered models; used by
|
|
Create a model by name. Returns |
|
Initialise model |
|
Deallocate and nullify model |
|
Deallocate a dynamically-allocated current array of length |
|
Return the nuclear interaction mode for model |
|
Return the preferred reference frame for model |
|
Return a heap-allocated C string containing the model name for model |
|
Return a heap-allocated C string containing the phase-space generator name. |
|
Compute the hadronic currents for model |
|
Return the initial-state weight from model |
|
Return a heap-allocated C string with the InspireHEP record identifier. |
4.1.4. The FortranModel C++ Class#
Declared in include/Achilles/fortran/FNuclearModel.hh,
implemented in src/Achilles/fortran/FNuclearModel.cc
FortranModel is a concrete subclass of NuclearModel that delegates all
physics to a Fortran model via the C-bound procedures above. It is registered with the
C++ nuclear model factory under the name "FortranModel".
Constructor
The constructor reads two keys from the NuclearModel section of the YAML run card:
Key |
Description |
|---|---|
|
The name of the Fortran model to instantiate (must match one of the names passed
to |
|
The Ward–Takahashi identity correction to apply to the computed currents. Accepted
values are |
|
Path to the model configuration file passed verbatim to the Fortran |
|
Path to a YAML file whose |
Overridden virtual methods
Method |
Behaviour |
|---|---|
|
Delegates to Fortran |
|
Delegates to Fortran |
|
Returns |
|
Evaluates form factors, packs particle data into flat arrays, calls Fortran
|
|
Delegates to Fortran |
|
Delegates to Fortran |
|
Delegates to Fortran |
|
Delegates to Fortran |
4.1.4.1. Ward Gauge Corrections#
After computing the hadronic current the FortranModel can enforce a gauge condition
on the Lorentz components. The choice is controlled by the Ward run-card key:
None— no correction applied.Coulomb— set the longitudinal (time-like) component to satisfy current conservation in the Coulomb gauge.Weyl— apply the Weyl (temporal) gauge condition.Landau— project out the longitudinal part in the Landau gauge.
4.1.5. Implementing a New Fortran Model#
To add a new nuclear model written in Fortran, follow these steps:
Create a Fortran module that
usesnuclear_modeland defines a concrete type thatextends(model)and implements all deferred procedures described in Fortran Interface.module my_model_mod use nuclear_model implicit none type, extends(model) :: my_model contains procedure :: init => my_init procedure :: cleanup => my_cleanup procedure :: mode => my_mode procedure :: model_name => my_name procedure :: ps_name => my_psname procedure :: currents => my_currents procedure :: init_wgt => my_init_wgt procedure :: inspirehep => my_inspirehep end type my_model contains ! ... implementations ... function build_my_model() result(ptr) class(model), pointer :: ptr allocate(my_model :: ptr) end function end module my_model_mod
Register the model in
nuclear_model_interface.f90. Add ausefor your new module and acall factory%register_model(...)line insideregister_all:use my_model_mod ! inside register_all(): call factory%register_model("MyModel", build_my_model)
Add the source file to the CMake build so it is compiled and linked.
Reference the model in the run card:
NuclearModel: Type: FortranModel Name: MyModel Ward: None ConfigFile: /path/to/config.dat
4.2. Sherpa Interface#
The Sherpa interface enables Achilles to use the Sherpa Monte Carlo event generator for Beyond the Standard Model (BSM) processes and tau lepton decays. The interface is built as an optional plugin and requires a custom version of Sherpa with UFO support (see Building Achilles for build instructions). The physics details are described in [IHocheLGR22] for BSM and [IHocheSW23] for tau lepton decays.
4.2.1. Overview#
The interface is implemented through the SherpaInterface class, which wraps the Sherpa
generator and provides several key capabilities:
Leptonic current calculations — Sherpa computes the leptonic transition currents including full spinor information for all helicity combinations.
Matrix element evaluation — differential cross sections are computed using Sherpa’s Comix matrix element generator.
Form factor extraction — nucleon form factors are read from the Sherpa model’s vertex definitions (requires a UFO 2.0 model).
Phase space channel generation — Sherpa’s combinatorics are used to automatically build efficient multi-channel integration mappings.
Tau lepton decays — after the intranuclear cascade, Sherpa handles the showering and hadronic decay of unstable particles such as the tau lepton.
4.2.2. Backend Types#
Two cross-section backends make use of the Sherpa interface:
BSMBackendUsed for BSM processes. The leptonic currents and matrix elements are both computed by Sherpa, while the hadronic side uses form factors extracted from the Sherpa model vertices.
SherpaBackendAll amplitude computations are fully delegated to Sherpa. This is the appropriate backend when the full process (both leptonic and hadronic sides) is described within the Sherpa framework.
4.2.3. Run Card Configuration#
To use the Sherpa interface, set the backend in the run card:
Backend:
Name: Sherpa # or BSM for beyond-SM physics
Sherpa-specific parameters are passed as command-line arguments. Common options include:
Option |
Description |
|---|---|
|
The particle physics model to use (default: |
|
Path to a UFO parameter card for custom models. |
|
Enable leptonic current calculations. |
|
Treat the tau lepton as massive. |
|
Allow the tau lepton to decay. |
|
Enable spin correlations in hard processes. |
|
Include spin correlations in the parton shower. |
To enable Sherpa-driven decays after the cascade (e.g. for tau lepton decay), set:
Main:
RunDecays: true
4.2.4. Limitations#
A custom version of Sherpa with UFO support is required. Contact the Achilles authors for details on obtaining it.
Form factor extraction from Sherpa model vertices requires the UFO 2.0 format.
The factorization scale is currently fixed at \(\mu^2 = 100\;\text{GeV}^2\).