Introduction

Pals-cpp is the parser library for PALS accelerator lattice files. It uses rapidyaml https://github.com/biojppm/rapidyaml to read lattices into memory and provides additional capabilities like printing to console, writing to files, and searching for elements. One major component is performing lattice expansion following the PALS specifications:

1. The lattice to be expanded can be specified by the user. If none is specified, the one in the last use: lattice_name statement will be expanded. If none exists, the last lattice in the file is expanded.
2. Content from other files can be brought into scope using include: filename
3. Elements that inherit parameters from other elements will have those properties brought into scope.
4. Beamlines in a lattice with a repeat: count will have their contents repeated count times in the lattice.
5. Elements in a lattice defined outside of it will have their definitions brought it.
6. Fork elements will create new branches in the lattice to their destination branch.

Usage

First, to build, run the following in the root directory:

cmake -S . -B build 
cmake --build build

This builds libyaml_c_wrapper.dylib, a shared object library that can interface with other languages.

It also builds an executable at build/example_rw containing examples for how to use the library to read lattice files, perform basic manipulations, and write to the lattice back to a file. To see the output, navigate to the build directory and run

./example_rw

The program get_lattices will create a struct containing three lattices:

• original is a map containing the base lattice as well as any lattices included in the base lattice.
• included is the base lattice but with all included files substituted in.
• expanded is the base lattice after lattice expansion has been performed. Specify the lattice file with the first argument to the function. On default, the lattice specified by the last use statement will be used, and if no use statement exists, the lattice lattice in the file will be used. An optional flag -lat lattice_name can be used to specify the lattice to expand, which has greatest priority. For example, in the build directory, run

./get_lattices ex.pals.yaml -lat lat2

Developer Notes

YAMLTreeHandle wraps ryml::Tree into C objects so they can be part of a shared object library to interface with other languages. ryml::Trees are stored in memory simply as arrays. ryml::NodeRef acts as a simple wrapper around nodes, which are just indices in the tree array. Trees are obtained by parsing C++ std::string, and values are simply pointers to locations in the string. Therefore, the string must be kept in memory as long as the tree is in use.

Most of the relevant ryml code for reference is contained in /build/_deps/rapidyaml-src/src/c4/yml/tree.hpp

Documentation generated by Doxygen. Run in the root directory

doxygen Doxyfile

To build the test, in the root directory run

ctest --test-dir build --output-on-failure

To run a specific test, run

ctest --test-dir build -R "Test Name"

To Do

Update test cases Search by kind