* How to compile.

* Tree layout
  - UAPNode, etc.
  - standard node names at base of tree: UAP_root, etc.

* Syntax for Bmad, mad-8 and mad-x trees. 

%------------------------------------------------------------------------------
\section{UAP\_root and children}

In the following \vn{"MAD"} will be used to represent either \vn{Bmad}, 
\vn{MAD8} and/or \vn{MADX}.


Information in UAP is stored in a tree structure. When a lattice is
read-in, expanded, or otherwise handled, The root node of this tree
structure is called
\begin{example}
  <UAP_root>
\end{example}
A child of the \vnb{UAP_root} node corresponds to a particular input
representation, AML representation, or the expanded lattice
representation. The current list of possible children is:
\begin{example}
  <Bmad_representation>
  <MAD8_representaiton>
  <MADX_representation>
  <AML_representation>
  <expanded_lattice>
\end{example}
The attributes of the \vnb{X_representation} children are
\begin{example}
  source_language = "name"
  file_name = "name"
\end{example}
The \vn{source_language} is the language of the source of the
information. For example, if a MADX lattice file is read-in then the
\vn{source_language} will be \vn{"MADX"} and the
\vnb{X_representation} will be \vnb{MADX_representation}.  If an
\vnb{AML_representation} tree is converted to a
\vnb{MAD8_representation} tree then the \vn{source_language} is
\vn{"AML"}.

On input from a file, \vn{file_name} is the name of the input file.
When writting to a file, \vn{file_name} is used as the output file
name.

%------------------------------------------------------------------------------

\section{Expanded Lattice Representation}

The children of \vnb{expanded_lattice} are:
  <control_list>   // List of controllers.
  <global>
  <machine>        // There can be multiple <machine> children.
\end{example}

The \vnb{machine} node will have children:
\begin{example}
  <tracking_lattice>
  <master_list>
  <beam>
  <lattice>
\end{example}


%------------------------------------------------------------------------------

\section{X Representations}

A lattice element represented in an MAD lattice file:
\begin{example}
  ele_name: ele_class {, this_attribute = this_value} 
\end{example}
will be represented in the MAD representation tree in the form:
\begin{example}
  <element name = "ele_name" class = "ele_class" {this_attribute = "this_value"} />
\end{example}
An attribute using a default, that is an attribute without a
corresponding \vn{"= value"}, is represented in the MAD representation
tree with a empty (\vn{""}) value string.  For example an element
defined in a MADX file with
\begin{example}
  q1: quad, l = 10, tilt; // a quad
\end{example}
will be represented as
\begin{example}
  <element name = "q1" class = "quadrupole" l = "10" tilt = "" comment = "a quad" />
\end{example}
Notice that the class name in the MAD representation is not an abbreviation even though
the input file uses one. If an element inherits attributes from another element then
\vn{inherit} is used in place of \vn{class}. For example, a Bmad element definition:
\begin{example}
  q2: q1, type = "my type"
\end{example}
translates to
\begin{example}
  <element name = "q2" inherit = "q1 type = "my type" />
\end{example}

parameters of the form
\begin{example}
  param_class {, this_param = this_value} 
\end{example}
are translated to
\begin{example}
  <param_class {this_param = "this_value"} />  
\end{example}

For example
\begin{example}
  beam, energy = 5.2
\end{example}
translates to 
\begin{example}
  <beam energy = "5.2" />
\end{example}



There are a number of exceptions: In Bmad, a taylor element:
\begin{example}
  t: taylor, l = 3.9, {4: 2.73, 0 0 1 0 0 2}, {1: 1.04, 1 0 0 0 0 0}
\end{example}
would be translated to
\begin{example}
  <element name = "t" class = "taylor" l = "3.9">
    <term i_out = "4" coef = "2.73" exp = "0 0 1 0 0 2" />
    <term i_out = "1" coef = "1.04" exp = "1 0 0 0 0 0" />
  </element>
\end{example}


* For example, k1 and k2 attributes in a bend are translated to <multipole> children
  and not <quadrupole> and <sextupole>.


* Sequence elements:
    ele_name: class_name, at = real, ...  
    ele_name: ref_ele, at = real, ...    
    class_name, at = real            
    seq_name, at = real

    <element name = "ele_name" class = "class_name" at = "real" ... />
    <element name = "ele_name" inherit = "ele_rep" at = "real" ... />
    <element ref = "class_name" at = "real"  />
    <sequence ref = "seq_name" at = "real" />


* expanded_lattice layout
  - A machine lattice list is the children of tracking_lattice
  - How superimpose, multipass, control, guirder are handled.
  - s-calculation done
  - expression evaluation
  - master_list: multipass and superimpose
  - control_list: controllers and guirder.
  - rank: multipass_slave, super_slave, multipass_lord, super_lord.
  - Controller may only control the dphi attribute of a multipass lcavity or rfcavity.
  
  - DELTA controllers have an old_value attribute to keep track of changes.

* restrictions on AML for conversion to MAD-8, MAD-X and Bmad.
  - Restrictions of element types: sol_quad.
  - Restrictions on superposition/sectors.
  - MAD: beambeam xma, yma: if comming from aml must put orientation inside beambeam.

* Classes and methods: UAPNode, etc.
  - doxygen

* Example programs

* How file names are used when creating lattice files
  ModifyIncludedFileNames method to change the file names.

* AML_rep to expanded_lattice conversion
  - length_chord to length conversion in expanded_lattice.
  - design + err converted to value in expanded_lattice.

* sequences:
  -- class or subsequence name must already be defined.


----------------------------------------------------------------------

<multipole> is used to indicate perturbation fields.

Changing element values:
  qf: quad, k1 = 0.2
  qf, k1 = 0.19   ! redefinition

----------------------------------------------------------------------
MADX

Beam, sequence = ""

For all elements:
  apertype = "type", aperture={param1, param2, ...}

apertype    #parameters
CIRCLE        1
ELLIPSE       2
RECTANGLE     2
LHCSCREEN     3
MARGUERITE    3
RECTELLIPSE   4
RACETRACK     3
FILENAME      0

bend:         k0, k0s !! do not implement this now!
quadrupole:   k1s
sextupole:    k2s
octupole:     k3s
multipole:    knl = {kn1, kn2, ...}
              ksl = {ks1, ks2, ks3, ...}
elsecarator:  ex, ey (no e)

