LHEF

The lhef library is a rust library to read and write files in the LesHouchesEvents format. It can be used to just read the common blocks specified by the standard, but is flexible enough to also handle the additional information that is allowed by the standard. This can be done either by reading them as Strings or by parsing them into custom data structures. Reading common blocks has been tested for event files generated by MG5_aMC@NLO and HELAC_NLO. Specialized data structures for the reweighting information written by HELAC_NLO are included.

Usage examples

Reading a file and ignoring all extra information:

use lhef::ReadLhe;
use lhef::plain::LheFile;

let lhe = LheFile::read_lhe_from_file(&"events.lhe").unwrap();

// Energy of beam 1
let beam_1_energy = lhe.init.beam_1_energy;

// pz of the 4rd particle in the 7th event
let pz = lhe.events[6].particles[3].momentum.pz;

Reading a file generated including extra information as strings:

Specialized data structures for e.g. Madgraph do not exist, but the additional information stored in the event files written by it can still be extracted as strings:

use lhef::ReadLhe;
use lhef::string::{LheFile, EventExtra};

let lhe = LheFile::read_lhe_from_file(&"events.lhe").unwrap();

// extra information of the 5th event
let EventExtra(ref extra) = lhe.events[4].extra;

Reading a file generated by HELAC-NLO

This library comes with a module containing special data structures for the additional information contained in event files generated by HELAC-NLO. Therefore event files generated by HELAC can be read directly into the appropriate structures:

use lhef::ReadLhe;
use lhef::helac::LheFileRS;

let lhe = LheFileRS::read_lhe_from_file(&"events.lhe").unwrap();

// x1 of the 5th event
let extra = lhe.events[4].extra.pdf.x1;

Supported file types

This library comes with three specialization modules to handle extra information contained in event files:

plain

The plain module allows to read lhe files without taking any extra information into account. The [plain::LheFile] struct contains only the information that is guaranteed to be present in all lhe files. The extra fields on the file, init and event objects are still present, but only return dummy objects that do not contain any information. The comment and the header are also dummy objects.

string

The string module allows to read lhe files and keeping all the extra information in the files as unparsed strings. The comment and the header are kept as strings, without the start and end tags. All extra information has leading and trailing whitespace removed. Whitespace (including linebreaks) within the strings is conserved.

helac

The helac module contains specialized structs that the extra information contained in lhe files generated by HELAC-NLO is parsed into. The comment is kept as a string, and since HELAC lhe files do not contain a header, the header is a dummy object.

Adding support for new file types

To add new file types, you need to add types that implement the ReadLhe and WriteLhe traits for the additional information stored in the file type. The type signature of the read_from_lhe function of the ReadLhe trait means that you should use nom to parse your type. Your implementations need to parse the opening and end tags for comments (<!-- and -->) and the header (<header> and </header>) respectively, but must leave the tags for the init section and for events alone. With these implementations you can then use LheFileGeneric with your types to read and write lhe files.

Limitations

Currently this crate has several limitations:

• All tags in the lhe files are treated as case sensitive. This means that a file containing an <EVENT> tag instead of <event> can not be parsed.
• Files must follow the structure outlined in the lhe paper, i.e. additional information stored in the file in locations not specified in the paper will break the parser.
• In particular, additional xml style comments except the one comment allowed by the spec will break the parser.
• Attributes on any tag, with the exeption of the version attribute on the <LesHouchesEvent> tag, are not supported yet.

The only one of these limitations that clearly violates the lhe specification is the last one, so this will be fixed in a future update. However, so far I never encountered a program that actually does generate any attribute in these tags.