PALS: Base Structure & Version

[ax3l]

This updates the PALS root structure further, as discussed in August 2025. It also adds a version attribute (schema TBD, e.g., calver or semver) to start on #125.

Checklist

• update example
• discuss and agree on example update, then
• can be a later PR: agree on versioning scheme (semver or calver or other) for PALS standard, then
• update standard documentation: New subsection in Introduction

Changes

Adds a root level PALS key, which helps to group:

• lattice elements (list)
• version attribute
• a potential (global) config dictionary (later, in brainstorming so far)
• combine with other dictionaries in YAML and JSON and XML files, as needed (for usability)

[ax3l]

Discussed today: Start with PALS: or - PALS:?

Claude:

I personally also find the extra nesting to get a bit excessive if we start with a list. When we import into each other, we would anyway do it in the lattice: ... list.

[ax3l]

[ax3l]

Discussed with @DavidSagan : We would combine files and use immediate evaluation / sets like this later on:

PALS:
  version: null  # later, we will put the version of the PALS standard here

  imports:
    - "first.pals.yaml"  # adds elements to the beginning of "lattice: ..."
    - "second.pals.yaml"  # adds more elements (to the end of) "lattice: ..."

  elements:
    # elements from first.pals.yaml
    # elements from second.pals.yaml

    - another_drift:
        kind: Drift
        length: 0.25   

    - set: "..."  # can manipulate all elements

first.pals.yaml and second.pals.yaml would use the same schema (PALS: version: elements: ...).
We can later on allow to sub-select a beamline in imports:, e.g., first.pals.yaml:FODO for a named BeamLine only.

[ax3l]

Rolled somehow back today, now includes use a "magic element name" like the set command:

Discussed with @DavidSagan : We would combine files and use immediate evaluation / sets like this later on:

PALS:
  version: null  # later, we will put the version of the PALS standard here

  lattices:
    - include: "first.pals.yaml"  # adds elements & commands
    - include: "second.pals.yaml"  # adds more elements & commands

    - another_drift:
        kind: Drift
        length: 0.25   

    - set: "..."  # can manipulate all elements

first.pals.yaml and second.pals.yaml would use the same schema (PALS: version: lattices: ...).
We can later on allow to sub-select a beamline in imports:, e.g., first.pals.yaml:FODO for a named BeamLine only.

[ax3l]

My personal preference is to call this group elements:.

I do not think it is confusing if elements includes a list of elements and commands like include/set, and it is quite descriptive (vs. writing "nodes" or "objects" or "list").

PALS:
  version: null  # later, we will put the version of the PALS standard here

  elements:
    - include: "first.pals.yaml"  # adds elements & commands

    - another_drift:
        kind: Drift
        length: 0.25   

    - set: "..."  # can manipulate all elements

    - include: "second.pals.yaml"  # adds more elements & commands

    - my_lattice:
        kind: Lattice
        branches:
          - ...

[ax3l]

@DavidSagan I checked this quickly and it would be cleaner to keep without the list at the root level.
Thread: #152 (comment)

[ax3l]

Thanks! We agreed on the example, I will finalize the PR by updating also the Introduction section of the written standard.

[ax3l]

Updated the written standard now, too! :)

[ax3l]

@DavidSagan just an update that I added the docs as well. Let us know if good to merge :)

[DavidSagan]

The information in the include file may be anything and not restricted to a "lattice". EG: a bunch of set commands.

[DavidSagan]

Also order is important so this needs to be -include.

[ax3l]

That is not correct. The elements inside include need to be sorted and thus use a list (with -), the outer key include itself does not:
It is not relevant if the key include inside the PALS group comes before/after version/lattice/other keys.

[DavidSagan]

I think what this boils down to is that your vision of what include does is different from mine. PALS can have both. Since there is already documentation for my version of include why don't you call your version `using'?

[ax3l]

What you want is a floating reserved element name include that includes the file somewhere in the lattices: list. This PR does not do that, but we can do that as well.

To me those are two different ways to include, I have no strong preference over one or the other. Will update.

[ax3l]

@DavidSagan take a look now

[DavidSagan]

Part of the problem here is that you are using the word element for a YAML key but element can also refer to
a lattice element (quadrupole, etc.) which is what I thought you were referring to. I would suggest using the word key here to avoid ambiguity.

[DavidSagan]

Also this PR removes the include definition already in place. This definition obviously needs elaboration but I do want to keep it since this is different from what you envision. Suggestion: Keep the existing include section in the documentation and have the PR add your section with a different name.

[ax3l]

Include: same section & usage now, I just moved it up. Moving it down again, since it seems to confuse that I moved the section to be grouped more logically.

[ax3l]

The element(s) key would just be the group where we put all elements/lattices/commands in. Thus, there would be no real ambiguity, it is just a descriptive namespace.