diff --git a/standard/element_parameter.md b/standard/element_parameter.md new file mode 100644 index 0000000..2c8515a --- /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 `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, `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). diff --git a/standard/standard.md b/standard/standard.md new file mode 100644 index 0000000..39adf4c --- /dev/null +++ b/standard/standard.md @@ -0,0 +1,81 @@ +# 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 grammar to implemement the ALS schema. Rather, there are associated +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. + +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 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). +By convention, element names in ALS will be upper camel case. + + +## Lattice Branches + +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. + +## 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.