diff --git a/source/beamlines.md b/source/beamlines.md index fd9f52c..4bb6cfd 100644 --- a/source/beamlines.md +++ b/source/beamlines.md @@ -367,8 +367,8 @@ to position the element within the beamline. Example: ``` In this example, the superposition places an element named `q10w` with respect to the element `markerA`. This superposition will apply to any `markerA` elements that exist in -any beamline. To restrict where the superposition is applied, the appropriate -[qualified name](#s:name.matching). For example: +any beamline. To restrict where the superposition is applied, use the appropriate +[qualified name](#s:element.matching). For example: ```{code} yaml superimpose: place: q10w diff --git a/source/conf.py b/source/conf.py index 14b2936..08788d7 100644 --- a/source/conf.py +++ b/source/conf.py @@ -6,7 +6,7 @@ # -- Project information ----------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information -project = 'Particle Accelerator Lattice Standard' +project = 'Particle Accelerator Lattice Standard (PALS)' copyright = '2025, under CC-BY 4.0 License' author = 'Jean-Luc Vay, David Sagan, Chad Mitchell, Axel Huebl, David Bruhwihler, Christopher Mayes, Eric Stern, Daniel Winklehner, Michael Ehrlichman, Martin Berz, Giovanni Iadarola, Ji Qiang, Edoardo Zoni, Laurent Deniau, et al.' @@ -29,4 +29,4 @@ # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output html_theme = 'sphinx_book_theme' -html_static_path = ['_static'] +## html_static_path = ['_static'] diff --git a/source/contributing.md b/source/contributing.md index 5503d4b..db47114 100644 --- a/source/contributing.md +++ b/source/contributing.md @@ -1,3 +1,4 @@ +(s:contribute)= # How to Contribute ## Follow these steps **only once** diff --git a/source/introduction.md b/source/conventions.md similarity index 53% rename from source/introduction.md rename to source/conventions.md index 9fb5b13..79a35c7 100644 --- a/source/introduction.md +++ b/source/conventions.md @@ -1,76 +1,15 @@ -(c:introduction)= -# Introduction +(c:conventions)= +# Conventions %--------------------------------------------------------------------------------------------------- -(s:conventions)= -## Conventions +(s:keywords)= +## Keywords -The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", +The keywords "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. - -%--------------------------------------------------------------------------------------------------- -(s:elements.intro)= -## Lattice Elements - -The basic building block used to describe an accelerator is the lattice **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 beamlines intersect (`Fork` elements). -By convention, element names in PALS will be upper camel case. - -%--------------------------------------------------------------------------------------------------- -(s:branches.intro)= -## Lattice Branches - -A lattice `branch` holds an ordered array of lattice elements -that gives the sequence of elements to be tracked through. -A branch can represent something like a storage ring, transfer line or Linac. -In the simplest case, a program can track through the elements one element at a time. -However, lattice elements may overlap which will naturally complicate tracking. - -%--------------------------------------------------------------------------------------------------- -(s:lattices.intro)= -## 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 beamlines such as a connections to a transfer line, dump line, or an -X-ray beamline. - -Besides `branches`, a lattice will hold information like details of any support girders that are -present and `multipass` information in the case where elements are transversed multiple times -as in an ERL or in opposite directions as in a colliding beam machine. - -%--------------------------------------------------------------------------------------------------- -(s:root.intro)= -## Root branch - -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. - -%--------------------------------------------------------------------------------------------------- -(s:expansion.intro)= -## Lattice Expansion - -An important concept is [`lattice expansion`](#s:lattice.expand) and `branch expansion`. -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. +All keywords in this standard are case-sensitive. %--------------------------------------------------------------------------------------------------- (s:syntax)= @@ -132,7 +71,7 @@ lattice element attribute dictionaries where having the name of the element as t enhances legibility. %--------------------------------------------------------------------------------------------------- -(s:parameters) +(s:parameters)= ## Parameters All parameters are optional unless explicitly stated otherwise. @@ -161,7 +100,7 @@ to the following: - A name can only contain alpha-numeric characters and underscores (A-Z, a-z, 0-9, and _ ) %--------------------------------------------------------------------------------------------------- -(s:name.matching)= +(s:element.matching)= ## Element Name Matching Lattice element name matching is the process of finding the set of lattice elements that @@ -177,16 +116,89 @@ The names of an element may be "qualified" by prepending a `branch` or `BeamLine using the string `">>"` as a separator. For example, `"B1>>Qaf.*"` would match to all elements in a branch or BeamLine named `"B1"` whose name begins with `"Qaf"`. -Additionally, if the match string ends with the character `"#"` followed by an integer `N`, +Element matches may be restricted to a given element kind using the notation +```{code} yaml +:: +``` +where `` is the element kind and `` is the element name. +Example: +```{code} yaml +Marker::bpm. +``` +This will match to all `Marker` elements whose name is four characters starting with `bpm`. + +If the match string ends with the character `"#"` followed by an integer `N`, this will match to the `N`{sup}`th` instance matched to in any `branch` or `BeamLine`. For example, `"Sd#3"` will match to the 3{sup}`rd` instance of all elements named -`"Sd". +`"Sd"`. Lattice elements can also be referred to by the index in which they appear in a branch with the first element having index one, etc. Branches do not get an index since the PALS standard does not mandate that the branches of a lattice be stored in an array (it could, for example, be a linked list). +Elements can be matched using a range construct which has the form +```{code} yaml +: +``` +where `` marks the beginning of the range and `` marks the end of the range. +Example: +```{code} yaml +Q1:Q2 +``` +In this example, the range matches all elements from `Q1` to `Q2` inclusive of `Q1` and `Q2`. +If `` comes before `` the range "wraps around" the branch or beamline. +For example, if `Q2` comes before `Q1` in the above example, the range matches all elements from +`Q1` to the end of the line plus all elements from the beginning of the line to `Q2`. + +Commas `,` can be used to form the union of element sets. The syntax is +```{code} yaml +, , ... , +``` +where ``, ... ` are element sets. +Example: +```{code} yaml +A, B, Q.* +``` +This will match to all elements named `A`, `B`, and all elements whose name begins with `Q`. + +Ampersands `&` can be used to form the intersection of element sets. The syntax is +```{code} yaml + & & ... & +``` +where ``, ... ` are element sets. +Example: +```{code} yaml +Marker::.* & Q1:Q2 +``` +This will match to all `Marker` elements that are in the range from `Q1` to `Q2`. + +%--------------------------------------------------------------------------------------------------- +(s:parameter.matching)= +## Element Parameter Name Matching + +For element parameters, the general syntax is +```{code} yaml +>>>.. ... .. +``` +where +```{code} yaml +: # Optional BeamLine or Branch name. + # Optional lattice element name. + # Parameter group name. +. ... . # Subgroups if they exist. + # Parameter name. +``` +Only `` and `` use PCRE2 syntax. + +Example: +```{code} yaml +Qa.*>MagneticMultipoleP.Ks2L +``` +This will match the `Ks2L` component of all elements whose name begins with `Qa`. Notice that +since only `` and `` use PCRE2 syntax, the dot separating the parameter group +and the parameter is unambiguous. + %--------------------------------------------------------------------------------------------------- (s:units)= ## Units @@ -198,6 +210,8 @@ The lattice standard uses SI except for energy which uses `eV`. * - Quantity - Units +* - charge + - fundamental charge * - length - meters * - time @@ -219,3 +233,59 @@ The lattice standard uses SI except for energy which uses `eV`. * - electric field - Volts/m ``` + +%--------------------------------------------------------------------------------------------------- +(s:constants)= +## Constants + +Constants defined by PALS: +```{code} yaml +c_light # [ m/sec] Speed of light +h_planck # [eV*sec] Planck's constant +h_bar_planck # [eV*sec] Reduced Planck's constant +r_e # [m] Classical electron radius +r_p # [m] Classical proton radius +e_charge # [Coul] Elementary charge +mu_0_vac # [eV*sec^2/m] Vacuum permeability +eps_0_vac # [1/eV*m] Permittivity of free space +classical_radius_factor # [m*eV] Classical Radius Factor: 1/(4 pi epsilon_0 c^2) +fine_structure_const # [-] Fine structure constant +n_avogadro # [-] Avogadro's constant +``` +The `classical_radius_factor` is a useful number when converting a formula that involve the classical +electron or proton radius to a formula for something other than an electron or proton. + +%--------------------------------------------------------------------------------------------------- +(s:functions)= +## Functions + +Functions defined by PALS: +```{code} yaml +sqrt(x) # Square Root +log(x) # Logarithm +exp(x) # Exponential +sin(x), cos(x) # Sine and cosine +tan(x), cot(x) # Tangent and cotangent +sinc(x) # Sin(x)/x Function +asin(x), acos(x) # Arc sine and Arc cosine +atan(x) # Arc tangent +atan2(y, x) # Arc tangent of y/x +sinh(x), cosh(x) # Hyperbolic sine and cosine +tanh(x), coth(x) # Hyperbolic tangent and cotangent +asinh(x), acosh(x) # Hyperbolic arc sine and Arc cosine +atanh(x), acoth(x) # Hyperbolic arc tangent and cotangent +abs(x) # Absolute Value +factorial(n) # Factorial +ran() # Random number between 0 and 1 +ran_gauss() # Gaussian distributed random number +ran_gauss(sig_cut) # Gaussian distributed random number +int(x) # Nearest integer with magnitude less then x +nint(x) # Nearest integer to x +sign(x) # 1 if x positive, -1 if negative, 0 if zero +floor(x) # Nearest integer less than x +ceiling(x) # Nearest integer greater than x +modulo(a, p) # a - floor(a/p) * p. Will be in range [0, p). +mass_of(A) # Mass of particle A +charge_of(A) # Charge, in units of the elementary charge, of particle A +anomalous_moment_of(A) # Anomalous magnetic moment of particle A +``` diff --git a/source/definitions.md b/source/definitions.md index 1647221..bf90ac8 100644 --- a/source/definitions.md +++ b/source/definitions.md @@ -23,3 +23,65 @@ and floor position and reference species and energy calculation. are branches that are formed due to the presence of `Fork` elements. - `Lattice element`: Basic building block of a lattice most often representing something physical like a quadrupole magnet or an RF cavity. + +%--------------------------------------------------------------------------------------------------- +(s:elements.intro)= +## Lattice Elements + +The basic building block used to describe an accelerator is the lattice **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 beamlines intersect (`Fork` elements). +By convention, element names in PALS will be upper camel case. + +%--------------------------------------------------------------------------------------------------- +(s:branches.intro)= +## Lattice Branches + +A lattice `branch` holds an ordered array of lattice elements +that gives the sequence of elements to be tracked through. +A branch can represent something like a storage ring, transfer line or Linac. +In the simplest case, a program can track through the elements one element at a time. +However, lattice elements may overlap which will naturally complicate tracking. + +%--------------------------------------------------------------------------------------------------- +(s:lattices.intro)= +## 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 beamlines such as a connections to a transfer line, dump line, or an +X-ray beamline. + +Besides `branches`, a lattice will hold information like details of any support girders that are +present and `multipass` information in the case where elements are transversed multiple times +as in an ERL or in opposite directions as in a colliding beam machine. + +%--------------------------------------------------------------------------------------------------- +(s:root.intro)= +## Root branch + +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. + +%--------------------------------------------------------------------------------------------------- +(s:expansion.intro)= +## Lattice Expansion + +An important concept is [`lattice expansion`](#s:lattice.expand) and `branch expansion`. +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. + diff --git a/source/element-kinds.md b/source/element-kinds.md index abc010d..ce0064d 100644 --- a/source/element-kinds.md +++ b/source/element-kinds.md @@ -13,6 +13,7 @@ cleo: # [string] user-defined name ``` %--------------------------------------------------------------------------------------------------- +--- (s:ackicker)= ## ACKicker Element @@ -31,6 +32,7 @@ Element parameter groups associated with this element kind are: - [**TrackingP**](#s:tracking.params): Tracking parameters. %--------------------------------------------------------------------------------------------------- +--- (s:beambeam)= ## BeamBeam Element @@ -401,7 +403,7 @@ tracking through a `NullEle` will never be needed. This element does not have any associated parameter groups. -For other purposes, for example, to mark reference points, [Marker](#s.marker) elements may be used. +For other purposes, for example, to mark reference points, [Marker](#s:marker) elements may be used. %--------------------------------------------------------------------------------------------------- (s:octupole)= diff --git a/source/element-parameters.md b/source/element-parameters.md index 72312ec..0c464b7 100644 --- a/source/element-parameters.md +++ b/source/element-parameters.md @@ -29,7 +29,7 @@ any of the parameter groups, that they are not grouped. These element parameters are: ```{code} yaml field_master: NotSet # [Boolean] See Below. - is_on: true # [Bollean] Turns on or off the fields in an element. When off, the element looks like a drift. + is_on: true # [Boolean] Turns on or off the fields in an element. When off, the element looks like a drift. kind: "" # [enum] Kind of element (Quadrupole, etc.). length: 0 # [m] Length of element. For bends this is the arc length. name: "" # [string] The name of element. @@ -142,9 +142,6 @@ element-by-element. ```{include} parameters/magneticmultipole.md ``` -```{include} parameters/master.md -``` - ```{include} parameters/meta.md ``` diff --git a/source/extensions.md b/source/extensions.md new file mode 100644 index 0000000..78ca024 --- /dev/null +++ b/source/extensions.md @@ -0,0 +1,7 @@ +# Extensions + +Extensions are standards used with PALS lattice files that are specific to a single simulation program. +This section documents extensions to aid the User in identifying extension usage in lattice files +and in directing the User to detailed extension documentation. + +Program developers are encouraged to [contribute extension documentation](#s:contribute). \ No newline at end of file diff --git a/source/fileformats.md b/source/fileformats.md index f6f01d6..d5e3c59 100644 --- a/source/fileformats.md +++ b/source/fileformats.md @@ -2,7 +2,7 @@ # File Formats The Particle Accelerator Lattice Standard (PALS) documents objects and their properties. -For readability, [this standard uses YAML-style](c:introduction) examples, but the PALS schema can be implemented in a variety of file formats. +For readability, [this standard uses YAML-style](c:conventions) examples, but the PALS schema can be implemented in a variety of file formats. ## File Endings diff --git a/source/index.md b/source/index.md index 3f99f9c..df3d380 100644 --- a/source/index.md +++ b/source/index.md @@ -4,17 +4,30 @@ This standard is an effort to create a standard to promote lattice information e ```{toctree} :maxdepth: 2 -:caption: PALS Standard +:caption: Overview overview.md -introduction.md definitions.md +``` + +```{toctree} +:maxdepth: 2 +:caption: Schema + +conventions.md coordinates.md element-kinds.md element-parameters.md beamlines.md lattice-construction.md multipass.md +miscellaneous.md +``` + +```{toctree} +:maxdepth: 2 +:caption: Physics + bend-multipoles.md ``` @@ -27,6 +40,13 @@ libraries.md simulations.md ``` +```{toctree} +:maxdepth: 2 +:caption: Extensions + +extensions.md +``` + ```{toctree} :maxdepth: 2 :caption: Back Matter diff --git a/source/lattice-construction.md b/source/lattice-construction.md index e469f07..3c20dbc 100644 --- a/source/lattice-construction.md +++ b/source/lattice-construction.md @@ -5,11 +5,16 @@ (s:lattice.construct)= ## Constructing a Lattice -A `Lattice` contains a set of branches. +A `Lattice` contains a set of branches. The components of `Lattice` are: +```{code} yaml +name # [String] Name of the lattice. +branches # [List] List of branches. +``` Each branch is instantiated from a `BeamLine` that is called the `root BeamLine`. Example: ```{code} yaml - Lattice: + - name: My Toy Lattice - branches: - this_line # this_line is the root beamline for the branch. - that_line: @@ -24,8 +29,8 @@ are those branches created due to `Fork` elements. A branch has the optional components ```{code} yaml -inherit # Optional String. Name of the root BeamLine for the branch. Default is the name of the Branch. -periodic # Optional Bool. Are orbit and Twiss parameters periodic? +inherit # [String] Optional. Name of the root BeamLine for the branch. Default is the name of the Branch. +periodic # [Boolean] Optional. Are orbit and Twiss parameters periodic? # Default is the setting of the root BeamLine. ``` The setting of `periodic` for a `Branch` overrides the setting of `periodic` @@ -181,3 +186,24 @@ a `BeamLine` called `generic_dump`. In the expanded lattice, the branch will be `this_dump`. The reference properties at the `dump_beginning`, element that is forked to, assuming this is the `BeginningEle` element at the beginning of the branch., will inherit the reference properties at the `Fork` element. + +%--------------------------------------------------------------------------------------------------- +(s:use)= +## Use statement + +Multiple `Lattice`s can be defined in a lattice file. By default, the one that gets instantiated +is the last lattice. This default can be overridden by a `use` statement. Example: +```{code} yaml +- Lattice + - name: lat1 + - branches: + ... + +- Lattice + - name: lat2 + - branches: + ... + +- use: lat1 +``` + diff --git a/source/miscellaneous.md b/source/miscellaneous.md new file mode 100644 index 0000000..273c3b7 --- /dev/null +++ b/source/miscellaneous.md @@ -0,0 +1,31 @@ +(c:misc)= +# Miscellaneous + +%--------------------------------------------------------------------------------------------------- +(s:set)= +## Set command + +The `set` command is used for setting parameters. The components of `set` are: +```{code} yaml +parameter # [String] Parmeter(s) to vary. +value # [Expression] Value to set. +delta # [Boolean] Default false. If false, parameter is set to value. + # If true, value is added to existing value of parameter. +``` +In the `value` expression, the symbol `@` can be used for the value of the parameter being changed. +Example: +```{code} yaml +- Q1: + kind: Quadrupole + ... + +- set: + parameter: Q1.*>MagneticMultipoleP.Kn3 + value: 2 * @ + +- Lattice: + - branches: + - line1 # First branch + ... # More branches +``` +In this example, the `Kn3` parameter of all elements whose name begins with `Q1` is doubled. diff --git a/source/parameters/tracking.md b/source/parameters/tracking.md index 5a3f7cc..5cd485c 100644 --- a/source/parameters/tracking.md +++ b/source/parameters/tracking.md @@ -2,8 +2,15 @@ (s:tracking.params)= ## TrackingP: Parameters Pertaining to Tracking. -Tracking parameters are highly program specific but it is useful to have a group -having some standardization. - -In Construction... +Tracking parameters are highly program specific but it is useful to have a dedicated group +so that such program specific parameters can be clearly identified. +Example: +```{code} yaml +TrackingP: + SciBmad: + ds_step: 0.3 + tracking_method: scibmad_standard + ... +``` +The above set parameters specific to the SciBmad simulation ecosystem.