From 9cf6aceb422b0a810ab7ee654490ea750cf72fc4 Mon Sep 17 00:00:00 2001 From: David Sagan Date: Tue, 3 Dec 2024 15:23:55 -0500 Subject: [PATCH 1/6] Start work on the standard. --- standard/element_parameter.md | 10 +++++ standard/standard.md | 80 +++++++++++++++++++++++++++++++++++ 2 files changed, 90 insertions(+) create mode 100644 standard/element_parameter.md create mode 100644 standard/standard.md diff --git a/standard/element_parameter.md b/standard/element_parameter.md new file mode 100644 index 0000000..a420287 --- /dev/null +++ b/standard/element_parameter.md @@ -0,0 +1,10 @@ +# Element Parameter Naming + +Lattice elements parameters are organized into **parameter groups**. All groups are organized as abstract syntax trees. +At the top level, there are the groups with names like `MagMultipoleGroup`, `ElecMultipoleGroup`, `RFGroup, `BendGroup`, `AlignmentGroup`, etc. +Group names use Upper camel case and have `Group` at the end of the name. + +A dot `.` is used as a separator between levels in a group. +For example, `BendGroup.angle`, `BendGroup.e1`, `RFGroup.frequency`, etc. Using lower case for second and lower level names is encouraged but not mandated. + +There are two element parameters that are so common that they are not grouped. These element parameters are `L` (element length) and `Name` (name of element). diff --git a/standard/standard.md b/standard/standard.md new file mode 100644 index 0000000..4a927cf --- /dev/null +++ b/standard/standard.md @@ -0,0 +1,80 @@ +# Accelerator Lattace Standard + +## Overview + +The Accelerator Lattace Standard (ALS) defines a standard for the sharing of lattice information to describe +particle accelerators and storage rings. ALS aims to promote: + + - portability between various applications and differing algorithms + - a unified open-access description for scientific data (publishing and archiving) + - a unified description for post-processing, visualization and analysis. + +ALS is able to describe the connections between various things +from the connection of injection and extraction lines connected to a storage ring to the interaction region +of colliding beam storage rings where particles are moving through magnets in opposite directions. An ALS +based lattice is able to +hold all the information about an entire machine complex from beam creation to dump lines enabling a +single lattice to be used as the basis of start-to-end simulations. + +ALS is built to be easily customizable so that custom information may be interted by a program into a lattice. +This custom information is generally not usable by other programs but can be useful when a program accesses +lattice files that it generated. + + +## What ALS Is + +ALS is a schema that defines things like the names of various lattice element types, how to organize lattice +elements into lines which beams of particles or X-rays can move through, etc. + +## What ALS Is Not + +ALS does not define any particular grammer to implemement the ALS schema. Rather, there are associated +language specific standards that define grammers for YAML, JSON, Python, etc. Along with these +associated standards, there are packages that implement translation between lattice files and a representational +internal format defined by the package. + +ALS does not define how particles are to be tracked through a lattice. ALS is for describing machines and +not for defining how to simulate particle motion. + +## Conventions + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", +"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be +interpreted as described in [RFC 2119](http://tools.ietf.org/html/rfc2119). + +All `keywords` in this standard are case-sensitive. + +## Lattice Elements + +The basic building block used to describe an accelerator is the lattice \vn{element}. Typically, +a lattice element is something physical like a bending magnet or an electrostatic +quadrupole, or a diffracting crystal. A lattice element may define a region in space +distinguished by the presense of (possibly time-varying) electromagnetic fields, +materials, apertures and other possible engineered structures. However, lattice elements +are not restricted to being something physical and may, for example, just mark a particular point in space +(EG: **Marker** elements), or may designate where beam lines intersect (**Fork** elements). +By convention, element names in ALS will be upper camel case. + + +## Lattice Branches + +A lattice **Branch** is essentially an ordered array of lattice elements. +In the simplist case, a program can track through the elements one element at a time. +However, lattice elements may overlap which will naturally complicat tracking. + +## Lattices + +A **lattice is the root structure holding the information about a +``machine``. A machine may be as simple as a line of elements (like the elements of a Linac) or +as complicated as an entire accelerator complex with multiple storage rings, Linacs, transfer +lines, etc. + +Essentially, a **lattice**, has an array of **branches** with each branch describing part of the +machine. Branches can be interconnected to form a unified whole. +Branches can be interconnected using **Fork** elements. +This is used to simulate forking beam lines such as a connections to a transfer line, dump line, or an +X-ray beam line. The **branch** from which other **branches** fork but is not forked to by any +other branch is called a **root** branch. + +A lattice may contain multiple **root branches. For example, a pair of intersecting storage +rings will generally have two root branches, one for each ring. From 943863f2845aef5a967188722a4ebf522bfbf983 Mon Sep 17 00:00:00 2001 From: David Sagan Date: Wed, 4 Dec 2024 12:14:52 -0500 Subject: [PATCH 2/6] Removed `Group` suffix from names. --- standard/element_parameter.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/standard/element_parameter.md b/standard/element_parameter.md index a420287..2c8515a 100644 --- a/standard/element_parameter.md +++ b/standard/element_parameter.md @@ -1,10 +1,10 @@ # Element Parameter Naming Lattice elements parameters are organized into **parameter groups**. All groups are organized as abstract syntax trees. -At the top level, there are the groups with names like `MagMultipoleGroup`, `ElecMultipoleGroup`, `RFGroup, `BendGroup`, `AlignmentGroup`, etc. -Group names use Upper camel case and have `Group` at the end of the name. +At the top level, there are the groups with names like `MagMultipole`, `ElecMultipole`, `RF, `Bend`, `Alignment`, etc. +Group names use Upper camel case. A dot `.` is used as a separator between levels in a group. -For example, `BendGroup.angle`, `BendGroup.e1`, `RFGroup.frequency`, etc. Using lower case for second and lower level names is encouraged but not mandated. +For example, `Bend.angle`, `Bend.e1`, `RF.frequency`, etc. Using lower case for second and lower level names is encouraged but not mandated. There are two element parameters that are so common that they are not grouped. These element parameters are `L` (element length) and `Name` (name of element). From 5ba88eca964380e2c97d9b32f6d3e8e35622b8f7 Mon Sep 17 00:00:00 2001 From: David Sagan Date: Fri, 6 Dec 2024 20:00:27 -0500 Subject: [PATCH 3/6] Update standard.md --- standard/standard.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/standard/standard.md b/standard/standard.md index 4a927cf..adc3b1c 100644 --- a/standard/standard.md +++ b/standard/standard.md @@ -58,7 +58,8 @@ By convention, element names in ALS will be upper camel case. ## Lattice Branches -A lattice **Branch** is essentially an ordered array of lattice elements. +A lattice **Branch** is essentially an ordered array of lattice elements that gives the physical +sequence to be tracked through. In the simplist case, a program can track through the elements one element at a time. However, lattice elements may overlap which will naturally complicat tracking. From 4bb63dac9eedb9335ecd1807449db984cbf8536f Mon Sep 17 00:00:00 2001 From: David Sagan Date: Wed, 11 Dec 2024 12:28:04 -0500 Subject: [PATCH 4/6] Update standard/standard.md Co-authored-by: Chad Mitchell <46825199+cemitch99@users.noreply.github.com> --- standard/standard.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/standard/standard.md b/standard/standard.md index adc3b1c..f5bb377 100644 --- a/standard/standard.md +++ b/standard/standard.md @@ -28,7 +28,7 @@ elements into lines which beams of particles or X-rays can move through, etc. ## What ALS Is Not -ALS does not define any particular grammer to implemement the ALS schema. Rather, there are associated +ALS does not define any particular grammar to implemement the ALS schema. Rather, there are associated language specific standards that define grammers for YAML, JSON, Python, etc. Along with these associated standards, there are packages that implement translation between lattice files and a representational internal format defined by the package. From 22ce6cbd79ef30470691189344fc6edb2084f614 Mon Sep 17 00:00:00 2001 From: David Sagan Date: Wed, 11 Dec 2024 12:28:32 -0500 Subject: [PATCH 5/6] Update standard/standard.md Co-authored-by: Chad Mitchell <46825199+cemitch99@users.noreply.github.com> --- standard/standard.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/standard/standard.md b/standard/standard.md index f5bb377..89445a4 100644 --- a/standard/standard.md +++ b/standard/standard.md @@ -49,7 +49,7 @@ All `keywords` in this standard are case-sensitive. The basic building block used to describe an accelerator is the lattice \vn{element}. Typically, a lattice element is something physical like a bending magnet or an electrostatic quadrupole, or a diffracting crystal. A lattice element may define a region in space -distinguished by the presense of (possibly time-varying) electromagnetic fields, +distinguished by the presence of (possibly time-varying) electromagnetic fields, materials, apertures and other possible engineered structures. However, lattice elements are not restricted to being something physical and may, for example, just mark a particular point in space (EG: **Marker** elements), or may designate where beam lines intersect (**Fork** elements). From 2453280cdcb4009f9351983432828b80c031b1dc Mon Sep 17 00:00:00 2001 From: David Sagan Date: Wed, 11 Dec 2024 13:03:41 -0500 Subject: [PATCH 6/6] Update standard/standard.md Co-authored-by: Chad Mitchell <46825199+cemitch99@users.noreply.github.com> --- standard/standard.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/standard/standard.md b/standard/standard.md index 89445a4..39adf4c 100644 --- a/standard/standard.md +++ b/standard/standard.md @@ -29,7 +29,7 @@ elements into lines which beams of particles or X-rays can move through, etc. ## What ALS Is Not ALS does not define any particular grammar to implemement the ALS schema. Rather, there are associated -language specific standards that define grammers for YAML, JSON, Python, etc. Along with these +language specific standards that define grammars for YAML, JSON, Python, etc. Along with these associated standards, there are packages that implement translation between lattice files and a representational internal format defined by the package.