Remove expand_lattice command and introduce post_expansion.

source/definitions.md

@@ -78,6 +78,4 @@ An important concept is [`lattice expansion`](#s:lattice.expand) and `branch exp
 Branch expansion is the process, starting from the `root` `BeamLine`
 of a branch, of constructing the ordered list of lattice elements contained in that branch.
 `Lattice expansion` involves branch expansion along with things like
-calculating the reference energy for all elements. Lattice expansion by default occurs
-at the end when the PALS file has been read or when there is a [`expand_lattice`](#s:expand.lat)
-command.
+calculating the reference energy for all elements.

source/fundamentals.md

@@ -15,11 +15,14 @@ PALS:
   load:                     # [list] Files to load. See the "Load Files" section.
   notes:                    # [list] Optional notes of interest.
   phase_space_coordinates:  # [enum] Type of phase space coordinates 
+  post_expansion:           # [list] Post-expansion setup. 
   reminders:                # [list] Optional reminder messages to be printed when file is read.
   version:                  # [string] Version of the PALS schema used in this file
 ```
 The difference between `notes` and `reminders` is that reminder messages are meant to be 
 printed (or otherwise communicated to the user) every time the file is read.
+The set of node types that can be used under the `post_expansion` node is the same as the
+`facility` node except for lattice and `use` nodes.
 
 Example:
 ```{code} YAML
@@ -57,6 +60,48 @@ to be outside of the PALS standard and will be ignored by a PALS parser.
 PALS file `authors` are optional, but recommended to enable data provenance and contacts.
 Per author, the `name` is required; the `orcid`, `affiliation` and `email` fields are optional.
 
+%---------------------------------------------------------------------------------------------------
+(s:facility)=
+## `facility` and `post_expansion`
+
+Constructing the lattice can be divided into two phases. 
+The first, "pre-expansion", phase basically involves defining lattice elements, controllers, 
+beam lines, etc., and ends with [lattice expansion](#s:lattice.expand).
+The second, "post-expansion", phase basically involves making modifications to the expanded lattice. 
+Essentially, the information needed for the pre-expansion phase is put in the `facility` sub-node
+of `PALS` and the information for the post-expansion phase is put in the `post_expansion` sub-node.
+Example:
+```{code} yaml
+PALS:
+  facility:
+    - q1:
+        kind: Quadrupole
+        MagneticMultipoleP:
+          Kn1L: 0.375
+
+    - bline:
+        kind: Beamline
+        line:
+          - q1:
+              repeat: 3
+
+    - lat:
+        kind: Lattice
+        branches: bline
+
+  post_expansion:
+    - set:
+        parameter: q1>MagneticMultipoleP.Kn1L
+        value: PARAMETER * (1 + 1e-4*random_gauss())
+```
+In this example, the expanded lattice has three elements named `q1`. 
+To add a random error to each of these, the lattice has to be expanded before a `set` command is used,
+and this is accomplished by placing a `set` command under the `post_expansion` node.
+If the `set` command had appeared in the `facility` node, and not in the `post_expansion` node, then
+when the set command is executed, the set would be applied to the value of `Kn1L` in the definition
+of `q1`. In this case, the result would be that all three of the `q1` elements in the expanded lattice would
+have the same value of `Kn1L`.
+
 %---------------------------------------------------------------------------------------------------
 (s:parameters)=
 ## Parameters

source/lattice-construction.md

@@ -52,7 +52,7 @@ element, this element is dropped from the branch line. The one exception that a
 element must be at the start of a branch is if there is a `Fork` element forking to the beginning of the
 branch and `ForkP.propagete_reference` of the fork element is `true`. In this case, a `BeginningEle`
 element is not needed to set the beginning reference parameters of the branch but the first element
-must be an element that can be pointed to by a `Fork` element ([](#:forking)).
+must be an element that can be pointed to by a `Fork` element ([](#s:forking)).
 
 After a branch is expanded, a `Placeholder` element will be placed at the end to hold
 the final floor position and reference parameters (energy, species, etc.).
@@ -84,14 +84,7 @@ The steps used for lattice expansion are:
 * Start with the root PALS file and construct a tree that contains all `include` and `load` trees.
 This is the base tree for the lattice expansion.
 
-* Divide the `facility` list into two lists: The first list, called the "pre-expansion list"
-is everything that comes before an `expand_lattice` node. The second list, 
-called the "post-expansion" list is everything that comes after the `expand_lattice` node. 
-Both lists preserve the order from the initial list.
-The post-expansion list will be empty if there is no `expand_lattice` node. 
-The post-expansion list is ignored until after the branches have been expanded.
-
-* Go through the pre-expansion list in order and node-by-node evaluate any expressions and execute any `set` commands.
+* Go through the `facility` list in order and node-by-node evaluate any expressions and execute any `set` commands.
 There is no distinction here between delayed evaluation and immediate evaluation [expressions](#s:expressions). 
 Both are evaluated. Controllers are ignored here.
 
@@ -140,14 +133,14 @@ new beamlines and branch expansion is performed on these new lines.
 The new branches may themselves have `Fork` elements that fork to new beamlines
 and this process is repeated until there are no new branches to be created.
 
-* Apply the `ABSOLUTE` `Controllers` from the pre-expansion list.
+* Apply the `ABSOLUTE` `Controllers` from the `facility` list.
 `RELATIVE` `Controllers` are not involved in lattice expansion.
 
 * For each branch, element-by-element, starting at the beginning, the reference parameters (energy, 
 species, time, etc.) are calculated along with dependent parameters (EG multipole `Ks1` if `Bs1`
 has been set), floor positions, and s-positions.
 
-* Using the post-expansion list, node-by-node from the list beginning, 
+* Using the `post_expansion` list, node-by-node from the list beginning, 
 evaluate any expressions and execute any `set` commands. Controllers are ignored here.
 
 * Apply `ABSOLUTE` `Controllers` from both lists. 
@@ -252,49 +245,5 @@ is the last lattice. This default can be overridden by a `use` statement. Exampl
 - use: lat1
 ```
 
-%---------------------------------------------------------------------------------------------------
-(s:expand.lat)=
-## expand_lattice Statement
-
-By default, [lattice expansion](#s:expansion.intro) happens at the end when a PALS file has been read.
-Lattice expansion can be triggered before this if there is an `expand_lattice` statement.
-This statement must be a child of the `facility` node. Triggering lattice expansion is necessary
-when reference to the expanded lattice is needed. For example:
-```{code} yaml
-facility:
-  - q1:
-      kind: Quadrupole
-      MagneticMultipoleP:
-        Kn1L: 0.375
-
-  - bline:
-      kind: Beamline
-      line:
-        - q1:
-            repeat: 3
-
-  - lat:
-      kind: Lattice
-      branches: bline
-
-  - expand_lattice
-
-  - set:
-      parameter: lat>>q1>MagneticMultipoleP.Kn1L
-      value: parameter * (1 + 1e-4*random_gauss())
-```
-In this example, the expanded lattice has three elements named `q1`. 
-To add a random error to each of these, the lattice has to be expanded before a `set` command is used.
-
-If the `expand_lattice` command is removed from the above example, the three `q1` elements of `lat` have
-not yet been instantiated and the set command as written cannot be done. When there is no
-`expand_lattice` statement, trying to set the `Kn1L` parameter in the `q1` element definition as in:
-```{code} yaml
-  - set 
-      parameter: q1>MagneticMultipoleP.Kn1L
-      value: parameter * (1 + 1e-4*random_gauss())
-```
-will be successful but without `expand_lattice`, the set targets the single `q1` definition, 
-so `random_gauss()` is evaluated only once and all three expanded copies inherit that one value.
 
 

source/lattice-elements.md

@@ -39,7 +39,8 @@ crab1:
     voltage: 1.0e6
 ```
 
-Lattice element definitions may only be placed as a child node of the [`facility`](#s:palsroot) node
+Lattice element definitions may only be placed as a child node of the [`facility`](#s:palsroot)
+or [`post_expansion`](#s:palsroot) nodes, 
 or "in place" in a `line` within a [`BeamLine`](#s:beamline.components). Example:
 ```{code} yaml
 PALS: