PALSParserCpp is a parser library for PALS accelerator lattice files. It reads lattices into memory with rapidyaml, and lets a program navigate, modify, print and write them, and find elements and parameters by PALS name matching.
Its main job is lattice expansion as the PALS standard defines it: include and
load, inheritance, sets, expressions and controllers, branch expansion, and
bookkeeping that computes every dependent parameter (reference energy, floor
placement, s-positions, ...). parse_and_expand_PALS expands the lattice named
in the call or, if none is named, the one PALS chooses: the lattice in the last
use statement, or the last lattice defined if there is none. It returns five
trees describing the result, along with a list of the problems found.
The library has a C API, so other languages can call it. See Language interfaces.
You need CMake 3.16 or later and a C++17 compiler. CMake downloads the other dependencies itself (rapidyaml, PCRE2, Catch2 and AtomicAndPhysicalConstantsCLib). From the repository root:
cmake -S . -B build
cmake --build buildThis builds the shared library libPALSParserCpp (.dylib on macOS, .so on
Linux) along with the tests and examples. To run the tests:
ctest --test-dir build --output-on-failureBoth examples read their lattices from lattice_files/ through a relative path,
so run them from build/.
examples/example_rw.cpp shows how to use the library to read a lattice file,
make basic changes (adding and removing elements, renaming, ...), print it to
the console, and write it back to a file. It reads ex.pals.yaml and writes
expand.pals.yaml. To run it:
./example_rwexamples/print_lattices.cpp expands a lattice and prints the five trees. Its
first argument is the name of a file in lattice_files/. The optional
-lat <name> chooses the lattice to expand; without it, PALS chooses as
described above. The trees are:
original: the file as written, along with every file it reaches byincludeorload.combined: the file with each included file substituted in and each loaded file merged in.expanded: the lattice after expansion, holding only the parameters the author wrote. Its values are the final ones, so a parameter in both this tree andfull_expandedhas the same value in both.full_expanded: the same lattice with every dependent parameter computed: reference parameters, floor placement, s-positions, and the derived members of each parameter family.adjunct: the rest of the document, such as element and beamline definitions,usestatements, and any lattice that was not expanded.
To run it:
./print_lattices ex.pals.yaml -lat lat2These packages wrap the PALSParserCpp library for other languages. Each needs a PALSParserCpp checkout built beside its own; see its installation guide.
- PALSParserJ.jl (Julia). It also translates PALS lattices to Bmad, SciBmad and MAD-X.
- PALSParserPy (Python). It also translates PALS lattices to Bmad, MAD-X and Xsuite.
The full documentation — the user guide, the five-tree model, the expression evaluation rules, and the generated C API reference — is at https://pals-project.github.io/PALSParserCpp/.
Notes for working on the library itself (source layout, memory model, running the tests, measuring test coverage, building the docs) are on the Working on PALSParserCpp page.