Skip to content

PALS: Base Structure & Version #152

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ax3l wants to merge 11 commits into
base: main
Choose a base branch
from
+68 −31
Open

PALS: Base Structure & Version #152

Show file tree
Hide file tree
Changes from 8 commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
3e7622f
PALS: Base Structure & Version
ax3l Jan 7, 2026
aee82f4
Readability: Add 2 Spaces
ax3l Jan 21, 2026
2254bd1
Section: lattice -> elements
ax3l Jan 21, 2026
454270b
Update Written Standard
ax3l Jan 22, 2026
9658e1a
Simplify Wording
ax3l Jan 28, 2026
f4907fd
Clarify that lattice elements include commands
ax3l Jan 28, 2026
af3b1f2
Add `Example:`
ax3l Jan 28, 2026
da2ef1f
elements -> lattices
ax3l Jan 28, 2026
df5136f
Use magic-element-name Approach
ax3l Jan 28, 2026
431c408
fix typo
ax3l Jan 28, 2026
1dd0800
Include: Move Down
ax3l Jan 28, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
54 changes: 29 additions & 25 deletions examples/fodo.pals.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,32 +9,36 @@
# - definition of a FODO channel that:
# - repeats a line (fodo_cell) three times
#
- drift1:
kind: Drift
length: 0.25
PALS:
Copy link
Member Author

@ax3l ax3l Jan 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Claude:
image

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.

Copy link
Member Author

@ax3l ax3l Jan 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

image image

Copy link
Member Author

@ax3l ax3l Jan 21, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member Author

@ax3l ax3l Jan 28, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member Author

@ax3l ax3l Jan 28, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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:
          - ...

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

- quad1:
kind: Quadrupole
MagneticMultipoleP:
Bn1: 1.0
length: 1.0

- fodo_cell:
kind: BeamLine
line:
- drift1
- quad1
- drift2:
elements:
- drift1:
kind: Drift
length: 0.5
- quad2:
inherit: quad1
length: 0.25

- quad1:
kind: Quadrupole
MagneticMultipoleP:
Bn1: -1.0
- drift1

- fodo_channel:
kind: BeamLine
line:
Bn1: 1.0
length: 1.0

- fodo_cell:
repeat: 3
kind: BeamLine
line:
- drift1
- quad1
- drift2:
kind: Drift
length: 0.5
- quad2:
inherit: quad1
MagneticMultipoleP:
Bn1: -1.0
- drift1

- fodo_channel:
kind: BeamLine
line:
- fodo_cell:
repeat: 3
54 changes: 43 additions & 11 deletions source/conventions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -83,7 +83,49 @@ associated standards, there are packages that implement translation between latt
representational internal format defined by the package.

While the standard itself is language agnostic, this document that describes the standard
needs to use some syntax and this syntax is based upon YAML. Non-YAML syntax used here is:
needs to use some syntax and this syntax is based upon YAML.

%---------------------------------------------------------------------------------------------------
(s:includefiles)=
## PALS Root Object

The root of the PALS schema is given by this dictionary:
```{code} YAML
PALS:
version: null # version schema: defined later

lattices:
- ... # a list of lattice elements and commands
```

%---------------------------------------------------------------------------------------------------
(s:includefiles)=
## Include Lattice Files

A lattice file can include other lattices (elements and commands) using an include statement.

Example:
```{code} YAML
PALS:
version: null # version schema: defined later

include:
Copy link
Member

@DavidSagan DavidSagan Jan 28, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member Author

@ax3l ax3l Jan 28, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

@DavidSagan DavidSagan Jan 28, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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'?

Copy link
Member Author

@ax3l ax3l Jan 28, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member Author

@ax3l ax3l Jan 28, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@DavidSagan take a look now

Copy link
Member

@DavidSagan DavidSagan Jan 28, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

@DavidSagan DavidSagan Jan 28, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member Author

@ax3l ax3l Jan 28, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member Author

@ax3l ax3l Jan 28, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

- "./base-lattice.pals.yaml"
- "./extra-lattice.pals.yaml"

lattices:
# the elements and commands of base-lattice.pals.yaml
# the elements and commands of extra-lattice.pals.yaml
- ... # a list of additional lattice elements and commands
```
where the include file names above are examples.
Includes simplify insert the `lattices` block of the `include` file(s) first.

%---------------------------------------------------------------------------------------------------
(s:matching)=
## Matching Syntax

Non-YAML syntax used here is:

1. The {math}`N^{th}` item in a list is referred to using square brackets enclosing the index: `[N]`.
For example:
Expand Down Expand Up @@ -140,16 +182,6 @@ All parameters are optional unless explicitly stated otherwise.
Optional real or integer parameters have a default value of zero unless otherwise stated.
Optional string parameters have a default value of blank unless otherwise stated.

%---------------------------------------------------------------------------------------------------
(s:includefiles)=
## Include Files

A lattice file can include other lattice files using an include statement.
```{code} yaml
include: <file-name>
```
where `<file-name>` is the name of the file to be included.

%---------------------------------------------------------------------------------------------------
(s:names)=
## Names
Expand Down