From 3e7622f65ea84cf39c05f7c5d1ddf16e58e83d7b Mon Sep 17 00:00:00 2001 From: Axel Huebl Date: Wed, 7 Jan 2026 11:12:20 -0800 Subject: [PATCH 01/11] PALS: Base Structure & Version 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 close #125. --- examples/fodo.pals.yaml | 56 ++++++++++++++++++++++------------------- 1 file changed, 30 insertions(+), 26 deletions(-) diff --git a/examples/fodo.pals.yaml b/examples/fodo.pals.yaml index 80932be..c2f5a4b 100644 --- a/examples/fodo.pals.yaml +++ b/examples/fodo.pals.yaml @@ -9,32 +9,36 @@ # - definition of a FODO channel that: # - repeats a line (fodo_cell) three times # -- drift1: - kind: Drift - length: 0.25 +PALS: + version: null # later, we will put the version of the PALS standard here -- quad1: - kind: Quadrupole - MagneticMultipoleP: - Bn1: 1.0 - length: 1.0 + lattice: + - drift1: + kind: Drift + length: 0.25 -- fodo_cell: - kind: BeamLine - line: - - drift1 - - quad1 - - drift2: - kind: Drift - length: 0.5 - - quad2: - inherit: quad1 - MagneticMultipoleP: - Bn1: -1.0 - - drift1 + - quad1: + kind: Quadrupole + MagneticMultipoleP: + Bn1: 1.0 + length: 1.0 -- fodo_channel: - kind: BeamLine - line: - - fodo_cell: - repeat: 3 + - fodo_cell: + 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 From aee82f4a194517445dce0e91a6c5b8feca8fa2c1 Mon Sep 17 00:00:00 2001 From: Axel Huebl Date: Wed, 21 Jan 2026 08:44:08 -0800 Subject: [PATCH 02/11] Readability: Add 2 Spaces --- examples/fodo.pals.yaml | 54 ++++++++++++++++++++--------------------- 1 file changed, 27 insertions(+), 27 deletions(-) diff --git a/examples/fodo.pals.yaml b/examples/fodo.pals.yaml index c2f5a4b..321ceb9 100644 --- a/examples/fodo.pals.yaml +++ b/examples/fodo.pals.yaml @@ -13,32 +13,32 @@ PALS: version: null # later, we will put the version of the PALS standard here lattice: - - drift1: - kind: Drift - length: 0.25 - - - quad1: - kind: Quadrupole - MagneticMultipoleP: - Bn1: 1.0 - length: 1.0 - - - fodo_cell: - kind: BeamLine - line: - - drift1 - - quad1 - - drift2: - kind: Drift - length: 0.5 - - quad2: - inherit: quad1 - MagneticMultipoleP: - Bn1: -1.0 - - drift1 - - - fodo_channel: - kind: BeamLine - line: + - drift1: + kind: Drift + length: 0.25 + + - quad1: + kind: Quadrupole + MagneticMultipoleP: + Bn1: 1.0 + length: 1.0 + + - fodo_cell: + 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 From 2254bd13487eea50cd7d90735c1a7fcb26e56b12 Mon Sep 17 00:00:00 2001 From: Axel Huebl Date: Wed, 21 Jan 2026 09:08:52 -0800 Subject: [PATCH 03/11] Section: lattice -> elements --- examples/fodo.pals.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/examples/fodo.pals.yaml b/examples/fodo.pals.yaml index 321ceb9..505cb43 100644 --- a/examples/fodo.pals.yaml +++ b/examples/fodo.pals.yaml @@ -12,7 +12,7 @@ PALS: version: null # later, we will put the version of the PALS standard here - lattice: + elements: - drift1: kind: Drift length: 0.25 From 454270b521f198809f37ea3dccf985da730aea3c Mon Sep 17 00:00:00 2001 From: Axel Huebl Date: Wed, 21 Jan 2026 21:22:26 -0800 Subject: [PATCH 04/11] Update Written Standard --- source/conventions.md | 52 ++++++++++++++++++++++++++++++++++--------- 1 file changed, 41 insertions(+), 11 deletions(-) diff --git a/source/conventions.md b/source/conventions.md index ff93f86..aaaa1f3 100644 --- a/source/conventions.md +++ b/source/conventions.md @@ -83,7 +83,47 @@ 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 + + elements: + - ... # a list of lattice elements +``` + +%--------------------------------------------------------------------------------------------------- +(s:includefiles)= +## Include Lattice Files + +A lattice file can include other lattices using an include statement. +```{code} YAML +PALS: + version: null # version schema: defined later + + include: + - "./base-lattice.pals.yaml" + - "./extra-lattice.pals.yaml" + + elements: + # the elements of base-lattice.pals.yaml + # the elemetns of extra-lattice.pals.yaml + - ... # a list of additional lattice elements +``` +where the include file names above are examples. +Includes add the `elements` of the referenced file(s), prepending them before the elements of the current file. + +%--------------------------------------------------------------------------------------------------- +(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: @@ -140,16 +180,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: -``` -where `` is the name of the file to be included. - %--------------------------------------------------------------------------------------------------- (s:names)= ## Names From 9658e1ace5b18bcc9e210a28d0f3c23aa57041a4 Mon Sep 17 00:00:00 2001 From: Axel Huebl Date: Wed, 28 Jan 2026 09:31:16 -0800 Subject: [PATCH 05/11] Simplify Wording --- source/conventions.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/conventions.md b/source/conventions.md index aaaa1f3..37689a0 100644 --- a/source/conventions.md +++ b/source/conventions.md @@ -113,11 +113,11 @@ PALS: elements: # the elements of base-lattice.pals.yaml - # the elemetns of extra-lattice.pals.yaml + # the elements of extra-lattice.pals.yaml - ... # a list of additional lattice elements ``` where the include file names above are examples. -Includes add the `elements` of the referenced file(s), prepending them before the elements of the current file. +Includes simplify insert the `elements` of the `include` file(s), prepending them before the elements of the current file. %--------------------------------------------------------------------------------------------------- (s:matching)= From f4907fd59ece9f0d19cdcf175fd42805f9cbee0e Mon Sep 17 00:00:00 2001 From: Axel Huebl Date: Wed, 28 Jan 2026 09:39:21 -0800 Subject: [PATCH 06/11] Clarify that lattice elements include commands --- source/conventions.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/source/conventions.md b/source/conventions.md index 37689a0..b0fae82 100644 --- a/source/conventions.md +++ b/source/conventions.md @@ -102,7 +102,7 @@ PALS: (s:includefiles)= ## Include Lattice Files -A lattice file can include other lattices using an include statement. +A lattice file can include other lattices (elements and commands) using an include statement. ```{code} YAML PALS: version: null # version schema: defined later @@ -112,12 +112,12 @@ PALS: - "./extra-lattice.pals.yaml" elements: - # the elements of base-lattice.pals.yaml - # the elements of extra-lattice.pals.yaml + # the elements and commands of base-lattice.pals.yaml + # the elements and commands of extra-lattice.pals.yaml - ... # a list of additional lattice elements ``` where the include file names above are examples. -Includes simplify insert the `elements` of the `include` file(s), prepending them before the elements of the current file. +Includes simplify insert the `elements` block of the `include` file(s), prepending them before the elements and commands of the current file. %--------------------------------------------------------------------------------------------------- (s:matching)= From af3b1f27ff6ac99234e28fa052867db7e3fdee85 Mon Sep 17 00:00:00 2001 From: Axel Huebl Date: Wed, 28 Jan 2026 09:40:01 -0800 Subject: [PATCH 07/11] Add `Example:` --- source/conventions.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/source/conventions.md b/source/conventions.md index b0fae82..f7f2319 100644 --- a/source/conventions.md +++ b/source/conventions.md @@ -103,6 +103,8 @@ PALS: ## 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 From da2ef1fd5fa76ecc8d7a8ed58813aaea2984ed63 Mon Sep 17 00:00:00 2001 From: Axel Huebl Date: Wed, 28 Jan 2026 09:51:15 -0800 Subject: [PATCH 08/11] elements -> lattices --- source/conventions.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/source/conventions.md b/source/conventions.md index f7f2319..4248827 100644 --- a/source/conventions.md +++ b/source/conventions.md @@ -94,8 +94,8 @@ The root of the PALS schema is given by this dictionary: PALS: version: null # version schema: defined later - elements: - - ... # a list of lattice elements + lattices: + - ... # a list of lattice elements and commands ``` %--------------------------------------------------------------------------------------------------- @@ -113,13 +113,13 @@ PALS: - "./base-lattice.pals.yaml" - "./extra-lattice.pals.yaml" - elements: + 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 + - ... # a list of additional lattice elements and commands ``` where the include file names above are examples. -Includes simplify insert the `elements` block of the `include` file(s), prepending them before the elements and commands of the current file. +Includes simplify insert the `lattices` block of the `include` file(s) first. %--------------------------------------------------------------------------------------------------- (s:matching)= From df5136f2a7faf76bc0588bff58a02aeea33419c7 Mon Sep 17 00:00:00 2001 From: Axel Huebl Date: Wed, 28 Jan 2026 13:38:32 -0800 Subject: [PATCH 09/11] Use magic-element-name Approach Magic element name without type, like `set`. --- source/conventions.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/source/conventions.md b/source/conventions.md index 4248827..97afca4 100644 --- a/source/conventions.md +++ b/source/conventions.md @@ -109,17 +109,16 @@ Example: PALS: version: null # version schema: defined later - include: - - "./base-lattice.pals.yaml" - - "./extra-lattice.pals.yaml" - lattices: # the elements and commands of base-lattice.pals.yaml + - include: "./base-lattice.pals.yaml" # the elements and commands of extra-lattice.pals.yaml - - ... # a list of additional lattice elements and commands + - include: "./base-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. +Includes simplify insert the `lattices` block of the `include` file(s). %--------------------------------------------------------------------------------------------------- (s:matching)= From 431c40819ee2f63488c6bb1cf87c59c64e756ed9 Mon Sep 17 00:00:00 2001 From: Axel Huebl Date: Wed, 28 Jan 2026 15:25:54 -0800 Subject: [PATCH 10/11] fix typo --- source/conventions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/conventions.md b/source/conventions.md index 97afca4..cc7f77e 100644 --- a/source/conventions.md +++ b/source/conventions.md @@ -118,7 +118,7 @@ PALS: - ... ``` where the include file names above are examples. -Includes simplify insert the `lattices` block of the `include` file(s). +Includes simply insert the `lattices` block of the `include` file(s). %--------------------------------------------------------------------------------------------------- (s:matching)= From 1dd08001bf30b70d02482ad5628c5fd77cc15532 Mon Sep 17 00:00:00 2001 From: Axel Huebl Date: Wed, 28 Jan 2026 15:39:55 -0800 Subject: [PATCH 11/11] Include: Move Down Avoid confusion. --- examples/fodo.pals.yaml | 2 +- source/conventions.md | 48 +++++++++++++++++++++-------------------- 2 files changed, 26 insertions(+), 24 deletions(-) diff --git a/examples/fodo.pals.yaml b/examples/fodo.pals.yaml index 505cb43..f8a84c0 100644 --- a/examples/fodo.pals.yaml +++ b/examples/fodo.pals.yaml @@ -12,7 +12,7 @@ PALS: version: null # later, we will put the version of the PALS standard here - elements: + lattices: - drift1: kind: Drift length: 0.25 diff --git a/source/conventions.md b/source/conventions.md index cc7f77e..1856170 100644 --- a/source/conventions.md +++ b/source/conventions.md @@ -86,7 +86,7 @@ While the standard itself is language agnostic, this document that describes the needs to use some syntax and this syntax is based upon YAML. %--------------------------------------------------------------------------------------------------- -(s:includefiles)= +(s:palsroot)= ## PALS Root Object The root of the PALS schema is given by this dictionary: @@ -98,28 +98,6 @@ PALS: - ... # 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 - - lattices: - # the elements and commands of base-lattice.pals.yaml - - include: "./base-lattice.pals.yaml" - # the elements and commands of extra-lattice.pals.yaml - - include: "./base-lattice.pals.yaml" - # a list of additional lattice elements and commands - - ... -``` -where the include file names above are examples. -Includes simply insert the `lattices` block of the `include` file(s). - %--------------------------------------------------------------------------------------------------- (s:matching)= ## Matching Syntax @@ -181,6 +159,30 @@ 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 Lattice Files + +A lattice file can include other lattices (elements and commands) using an include statement. + +Example: +```{code} YAML +PALS: + # ... + + lattices: + # the elements and commands of base-lattice.pals.yaml + - include: "./base-lattice.pals.yaml" + + # the elements and commands of extra-lattice.pals.yaml + - include: "./base-lattice.pals.yaml" + + # a list of additional lattice elements and commands + - ... +``` +where the include file names above are examples. +Includes simply insert the `lattices` block of the `include` file(s). + %--------------------------------------------------------------------------------------------------- (s:names)= ## Names