From 4a9e8b2b1f7e5e0d17d0f3ec7c4f7afddf50a7a7 Mon Sep 17 00:00:00 2001 From: David Sagan Date: Thu, 6 Aug 2026 14:22:59 -0400 Subject: [PATCH 1/5] Remove `expand_lattice` command and introduce `post_expansion`. --- source/definitions.md | 4 +-- source/fundamentals.md | 45 +++++++++++++++++++++++++- source/lattice-construction.md | 59 +++------------------------------- source/lattice-elements.md | 3 +- 4 files changed, 51 insertions(+), 60 deletions(-) diff --git a/source/definitions.md b/source/definitions.md index 6ce5cf21..319906ec 100644 --- a/source/definitions.md +++ b/source/definitions.md @@ -78,6 +78,4 @@ An important concept is [`lattice expansion`](#s:lattice.expand) and `branch exp Branch expansion is the process, starting from the `root` `BeamLine` of a branch, of constructing the ordered list of lattice elements contained in that branch. `Lattice expansion` involves branch expansion along with things like -calculating the reference energy for all elements. Lattice expansion by default occurs -at the end when the PALS file has been read or when there is a [`expand_lattice`](#s:expand.lat) -command. +calculating the reference energy for all elements. diff --git a/source/fundamentals.md b/source/fundamentals.md index d6d19ecb..09662544 100644 --- a/source/fundamentals.md +++ b/source/fundamentals.md @@ -13,7 +13,8 @@ PALS: notes: # [list] Optional notes of interest. reminders: # [list] Optional reminder messages to be printed when file is read. extension_labels: # [Dict] Optional extensions to PALS that the standard shall ignore. - facility: # [list] lattice elements, beamlines, lattices, parameter set commands, etc. + facility: # [list] Lattice elements, beamlines, lattices, parameter set commands, etc. + post_expansion: # [list] Set commands, etc. for post-expansion setup. ``` The difference between `notes` and `reminders` is that reminder messages are meant to be printed (or otherwise communicated to the user) every time the file is read. @@ -54,6 +55,48 @@ to be outside of the PALS standard and will be ignored by a PALS parser. PALS file `authors` are optional, but recommended to enable data provenance and contacts. Per author, the `name` is required; the `orcid`, `affiliation` and `email` fields are optional. +%--------------------------------------------------------------------------------------------------- +(s:facility)= +## `facility` and `post_expansion` + +The [lattice expansion](#s:lattice.expand) performed by a PALS parser can be divided into +two phases. The first "expansion" phase basically involves constructing the ordered lists +of lattice elements contained in all the branches of a lattice. The second "post-expansion" +phase basically involves making modifications to the expanded lattice. +Essentially, the information needed to to the expansion phase is put in the `facility` sub-node +of `PALS` and the information for the post-expansion work is put in the `post_expansion` sub-node. +Example: +```{code} yaml +PALS + facility: + - q1: + kind: Quadrupole + MagneticMultipoleP: + Kn1L: 0.375 + + - bline: + kind: Beamline + line: + - q1: + repeat: 3 + + - lat: + kind: Lattice + branches: bline + + post_expansion: + - set: + parameter: q1>MagneticMultipoleP.Kn1L + value: PARAMETER * (1 + 1e-4*random_gauss()) +``` +In this example, the expanded lattice has three elements named `q1`. +To add a random error to each of these, the lattice has to be expanded before a `set` command is used, +and this is accomplished by placing a `set` command under the `post_expansion` node. +If the `set` command had appeared in the `facility` node, and not in the `post_expansion` node, then +when the set command is executed, the set would be applied to the value of `Kn1L` in the definition +of `q1`. In this case, result would be that all three of the `q1` elements in the expanded lattice would +have the same value of `Kn1L`. + %--------------------------------------------------------------------------------------------------- (s:parameters)= ## Parameters diff --git a/source/lattice-construction.md b/source/lattice-construction.md index c0f1aca7..46acbebb 100644 --- a/source/lattice-construction.md +++ b/source/lattice-construction.md @@ -52,7 +52,7 @@ element, this element is dropped from the branch line. The one exception that a element must be at the start of a branch is if there is a `Fork` element forking to the beginning of the branch and `ForkP.propagete_reference` of the fork element is `true`. In this case, a `BeginningEle` element is not needed to set the beginning reference parameters of the branch but the first element -must be an element that can be pointed to by a `Fork` element ([](#:forking)). +must be an element that can be pointed to by a `Fork` element ([](#s:forking)). After a branch is expanded, a `Placeholder` element will be placed at the end to hold the final floor position and reference parameters (energy, species, etc.). @@ -84,14 +84,7 @@ The steps used for lattice expansion are: * Start with the root PALS file and construct a tree that contains all `include` and `load` trees. This is the base tree for the lattice expansion. -* Divide the `facility` list into two lists: The first list, called the "pre-expansion list" -is everything that comes before an `expand_lattice` node. The second list, -called the "post-expansion" list is everything that comes after the `expand_lattice` node. -Both lists preserve the order from the initial list. -The post-expansion list will be empty if there is no `expand_lattice` node. -The post-expansion list is ignored until after the branches have been expanded. - -* Go through the pre-expansion list in order and node-by-node evaluate any expressions and execute any `set` commands. +* Go through the `facility` list in order and node-by-node evaluate any expressions and execute any `set` commands. There is no distinction here between delayed evaluation and immediate evaluation [expressions](#s:expressions). Both are evaluated. Controllers are ignored here. @@ -140,14 +133,14 @@ new beamlines and branch expansion is performed on these new lines. The new branches may themselves have `Fork` elements that fork to new beamlines and this process is repeated until there are no new branches to be created. -* Apply the `ABSOLUTE` `Controllers` from the pre-expansion list. +* Apply the `ABSOLUTE` `Controllers` from the `facility` list. `RELATIVE` `Controllers` are not involved in lattice expansion. * For each branch, element-by-element, starting at the beginning, the reference parameters (energy, species, time, etc.) are calculated along with dependent parameters (EG multipole `Ks1` if `Bs1` has been set), floor positions, and s-positions. -* Using the post-expansion list, node-by-node from the list beginning, +* Using the `post_expansion` list, node-by-node from the list beginning, evaluate any expressions and execute any `set` commands. Controllers are ignored here. * Apply `ABSOLUTE` `Controllers` from both lists. @@ -252,49 +245,5 @@ is the last lattice. This default can be overridden by a `use` statement. Exampl - use: lat1 ``` -%--------------------------------------------------------------------------------------------------- -(s:expand.lat)= -## expand_lattice Statement - -By default, [lattice expansion](#s:expansion.intro) happens at the end when a PALS file has been read. -Lattice expansion can be triggered before this if there is an `expand_lattice` statement. -This statement must be a child of the `facility` node. Triggering lattice expansion is necessary -when reference to the expanded lattice is needed. For example: -```{code} yaml -facility: - - q1: - kind: Quadrupole - MagneticMultipoleP: - Kn1L: 0.375 - - - bline: - kind: Beamline - line: - - q1: - repeat: 3 - - - lat: - kind: Lattice - branches: bline - - - expand_lattice - - - set: - parameter: lat>>q1>MagneticMultipoleP.Kn1L - value: parameter * (1 + 1e-4*random_gauss()) -``` -In this example, the expanded lattice has three elements named `q1`. -To add a random error to each of these, the lattice has to be expanded before a `set` command is used. - -If the `expand_lattice` command is removed from the above example, the three `q1` elements of `lat` have -not yet been instantiated and the set command as written cannot be done. When there is no -`expand_lattice` statement, trying to set the `Kn1L` parameter in the `q1` element definition as in: -```{code} yaml - - set - parameter: q1>MagneticMultipoleP.Kn1L - value: parameter * (1 + 1e-4*random_gauss()) -``` -will be successful but without `expand_lattice`, the set targets the single `q1` definition, -so `random_gauss()` is evaluated only once and all three expanded copies inherit that one value. diff --git a/source/lattice-elements.md b/source/lattice-elements.md index 071900e2..2d2b7b80 100644 --- a/source/lattice-elements.md +++ b/source/lattice-elements.md @@ -39,7 +39,8 @@ crab1: voltage: 1.0e6 ``` -Lattice element definitions may only be placed as a child node of the [`facility`](#s:palsroot) node +Lattice element definitions may only be placed as a child node of the [`facility`](#s:palsroot) +or [`post_expansion`](#s:palsroot) nodes, or "in place" in a `line` within a [`BeamLine`](#s:beamline.components). Example: ```{code} yaml PALS: From 57dcb4b5358226558752d8ef074ae6e54c965786 Mon Sep 17 00:00:00 2001 From: David Sagan Date: Mon, 10 Aug 2026 21:34:00 -0400 Subject: [PATCH 2/5] Fix expansion text in fundamentals.md. --- source/fundamentals.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/source/fundamentals.md b/source/fundamentals.md index 09662544..0565cbd3 100644 --- a/source/fundamentals.md +++ b/source/fundamentals.md @@ -59,12 +59,12 @@ Per author, the `name` is required; the `orcid`, `affiliation` and `email` field (s:facility)= ## `facility` and `post_expansion` -The [lattice expansion](#s:lattice.expand) performed by a PALS parser can be divided into -two phases. The first "expansion" phase basically involves constructing the ordered lists -of lattice elements contained in all the branches of a lattice. The second "post-expansion" -phase basically involves making modifications to the expanded lattice. -Essentially, the information needed to to the expansion phase is put in the `facility` sub-node -of `PALS` and the information for the post-expansion work is put in the `post_expansion` sub-node. +Constructing the lattice can be divided into two phases. +The first, "pre-expansion", phase basically involves defining lattice elements, controllers, +beam lines, etc., and ends with [lattice expansion](#s:lattice.expand). +The second, "post-expansion", phase basically involves making modifications to the expanded lattice. +Essentially, the information needed for the pre-expansion phase is put in the `facility` sub-node +of `PALS` and the information for the post-expansion phase is put in the `post_expansion` sub-node. Example: ```{code} yaml PALS From c42d52c608113bd444365ed13ddbf92d9c13a17c Mon Sep 17 00:00:00 2001 From: David Sagan Date: Mon, 10 Aug 2026 21:43:33 -0400 Subject: [PATCH 3/5] more. --- source/fundamentals.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/source/fundamentals.md b/source/fundamentals.md index 0565cbd3..c06a62e0 100644 --- a/source/fundamentals.md +++ b/source/fundamentals.md @@ -13,11 +13,13 @@ PALS: notes: # [list] Optional notes of interest. reminders: # [list] Optional reminder messages to be printed when file is read. extension_labels: # [Dict] Optional extensions to PALS that the standard shall ignore. - facility: # [list] Lattice elements, beamlines, lattices, parameter set commands, etc. - post_expansion: # [list] Set commands, etc. for post-expansion setup. + facility: # [list] Lattice elements, beamlines, lattices, set and use commands. + post_expansion: # [list] Post-expansion setup. ``` The difference between `notes` and `reminders` is that reminder messages are meant to be printed (or otherwise communicated to the user) every time the file is read. +The set of node types that can be used under the `post_expansion` node is the same as the +`facility` node except for lattice and `use` nodes. Example: ```{code} YAML @@ -67,7 +69,7 @@ Essentially, the information needed for the pre-expansion phase is put in the `f of `PALS` and the information for the post-expansion phase is put in the `post_expansion` sub-node. Example: ```{code} yaml -PALS +PALS: facility: - q1: kind: Quadrupole @@ -94,7 +96,7 @@ To add a random error to each of these, the lattice has to be expanded before a and this is accomplished by placing a `set` command under the `post_expansion` node. If the `set` command had appeared in the `facility` node, and not in the `post_expansion` node, then when the set command is executed, the set would be applied to the value of `Kn1L` in the definition -of `q1`. In this case, result would be that all three of the `q1` elements in the expanded lattice would +of `q1`. In this case, the result would be that all three of the `q1` elements in the expanded lattice would have the same value of `Kn1L`. %--------------------------------------------------------------------------------------------------- From 67ee704e17b3dcaa56ef3fa94448cef1ae73f472 Mon Sep 17 00:00:00 2001 From: David Sagan Date: Tue, 25 Aug 2026 01:32:45 -0400 Subject: [PATCH 4/5] correction. --- source/fundamentals.md | 8 +------- 1 file changed, 1 insertion(+), 7 deletions(-) diff --git a/source/fundamentals.md b/source/fundamentals.md index 76e0d31d..95e6c10e 100644 --- a/source/fundamentals.md +++ b/source/fundamentals.md @@ -8,13 +8,6 @@ The root of the PALS schema is given by a `PALS` node. Possible subnodes are: ```{code} YAML PALS: - version: # [string] Version of the PALS schema used in this file - authors: # [list] Optional authors associated with this file - notes: # [list] Optional notes of interest. - reminders: # [list] Optional reminder messages to be printed when file is read. - extension_labels: # [Dict] Optional extensions to PALS that the standard shall ignore. - facility: # [list] Lattice elements, beamlines, lattices, set and use commands. - post_expansion: # [list] Post-expansion setup. authors: # [list] Authors associated with this file extension_labels: # [Dict] Optional extensions to PALS that the standard shall ignore. facility: # [list] lattice elements, beamlines, lattices, parameter set commands, etc. @@ -22,6 +15,7 @@ PALS: load: # [list] Files to load. See the "Load Files" section. notes: # [list] Optional notes of interest. phase_space_coordinates: # [enum] Type of phase space coordinates + post_expansion: # [list] Post-expansion setup. reminders: # [list] Optional reminder messages to be printed when file is read. version: # [string] Version of the PALS schema used in this file ``` From 5c1beefd6258e99d140f48d7ae7750e3659195cf Mon Sep 17 00:00:00 2001 From: David Sagan Date: Mon, 31 Aug 2026 15:25:09 -0400 Subject: [PATCH 5/5] EZoni suggested changes. --- source/fundamentals.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/source/fundamentals.md b/source/fundamentals.md index 95e6c10e..1c33d6e3 100644 --- a/source/fundamentals.md +++ b/source/fundamentals.md @@ -15,14 +15,12 @@ PALS: load: # [list] Files to load. See the "Load Files" section. notes: # [list] Optional notes of interest. phase_space_coordinates: # [enum] Type of phase space coordinates - post_expansion: # [list] Post-expansion setup. + post_expansion: # [list] Optional post-expansion setup. reminders: # [list] Optional reminder messages to be printed when file is read. version: # [string] Version of the PALS schema used in this file ``` The difference between `notes` and `reminders` is that reminder messages are meant to be printed (or otherwise communicated to the user) every time the file is read. -The set of node types that can be used under the `post_expansion` node is the same as the -`facility` node except for lattice and `use` nodes. Example: ```{code} YAML @@ -102,6 +100,9 @@ when the set command is executed, the set would be applied to the value of `Kn1L of `q1`. In this case, the result would be that all three of the `q1` elements in the expanded lattice would have the same value of `Kn1L`. +The set of node types that can be used under the `post_expansion` node is the same as the +`facility` node except for `lattice` and `use` nodes. + %--------------------------------------------------------------------------------------------------- (s:parameters)= ## Parameters