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. Make sure to rebuild after making any changes to files, and before running tests. All lattice files should go in lattice_files/.

Example 1

examples/example_rw.cpp contains examples for how to use the library API to read lattice files, perform basic manipulations (adding and removing elements, renaming, etc.), print to console, and write the lattice back to a file. The example uses ex.pals.yaml and writes to expand.pals.yaml. To see the consle output, navigate to the build directory and run

./example_rw

Example 2

The program examples/print_lattices performs lattice expansion on a user-specified lattice. The first argument is the file name where the lattice is defined. It also takes an option argument using -lat lattice_name to specify a specific lattice to expand, otherwise it will choose a default (the lattice in the last use statement, or the last lattice in the file if none is present). The program will create and print 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. To see the console output, in the build directory, run

./print_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

Search by kind