Merge pull request #16 from DavidSagan/dcs16/002

Start work on the standard.

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

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.