From 1924a90bf72dbc8324ffdf1b7a3cad798c414da7 Mon Sep 17 00:00:00 2001 From: David Sagan Date: Tue, 20 Feb 2018 00:22:35 -0500 Subject: [PATCH 01/73] Ported EXT_BeamPhysics.md from other branch. --- EXT_BeamPhysics.md | 269 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 269 insertions(+) create mode 100644 EXT_BeamPhysics.md diff --git a/EXT_BeamPhysics.md b/EXT_BeamPhysics.md new file mode 100644 index 0000000..5acdb14 --- /dev/null +++ b/EXT_BeamPhysics.md @@ -0,0 +1,269 @@ +Extension to the openPMD Standard for Describing Particle Beams and X-rays +========================================== + +Version 1.0.0 (March 1, 2018) + +Overview +------------ + +The `BeamPhysics` extension to the openPMD standard is meant for describing particles and fields commonly encountered +in accelerator physics simulations. + +How to Use this Extension +--------------- + +The `BeamPhysics` extension to the openPMD standard is indicated in a data file by the setting of the `openPMDextension` attribute: +``` + openPMDextension = BeamPhysics, SpeciesType +``` + +Note: The `SpeciesType` extension must be used when using the `BeamPhysics` extension. + +Definitions +----------- + +- **Lattice**: A **lattice** is the arrangement of elements in a machine such as a particle accelerator. + +- **Global coordinate system**: The **global** coordinate system is a coordinate system that is +used to describe the position and orientation of machine elements in space. That is, the **global** +coordinate system is fixed with respect to the building or room where the machine is placed independent of the +machine itself. + +- **Lattice coordinate system**: The curvilinear coordinate system whose "longitudinal" +coordinate (typically called **s**) typically runs through the nominal centers of the elements +in the machine. Typically, the **lattice** coordinate system is used to describe misalignments +of lattice elements with respect to the rest of the lattice. + +- **Group**: A **group** is a container structure containing +a set of zero or more **attributes**, a set of zero or more **groups** (which can be called +**sub-groups**), and a set of zero or more **datasets**. Note: In HDF5, these are also +called **groups**. + +- **Dataset**: A **dataset** is a structure that contains a set of zero or more **attributes** and a +data aray (which may be multidimensional). Note: In HDF5, these are also called **datasets**. + +- **Record**: A **record** is a **group** (without any sub-groups) or a **dataset** that contains data +on a physical quantity like particle charge or electric field. There are two types of **records**: + - **scalar records** hold scalar quantity + values (like particle charge). If all the particles have the same charge, the value of the charge + is stored as an attribute of the **record** and there is no associated data array. That is, the + **record** is a **group**. If the particles have differing charges, the values are stored in an array + of the **scalar record**. In this case the **scalar record** is a **dataset**. + - **vector records** hold a set of **datasets**. In this case the **record** is a **group**. + - Example: A **record** named **E** for holding electric field values may have three datasets holding + the components of the field named **E/x**, **E/y**, and **E/z**. + +- **Attribute**: An **attribute** is a variable associated with a **group** along with a +value. Example: **snapshotPath** is a string variable associated with the root **/** group. + +- **Polar coordinates**: **Polar** coordinates are **(r, theta, phi)** where **r** is the radius, **theta** is he angle +from the **z** or **s** axis, and **phi** is the projected azimuthal angle in the **(x, y)** +plane. + +- **Particle Root Group**: The **Particle Root Group** is the root group for specifying a group of particles. There can be multiple **particle root groups** in a data file. For example, a set of particle bunches might specify one particle root group for each bunch. See the Base Standard for more information. + +Notes: +------ + +- When using the **lattice** coordinate system, the `position` coordinates are **(x, y, s)** where +nominally **x** is the "radial" component, +**y** is the "vertical" coordinate, and **s** is the lattice longitudinal coordinate. + + +Additional File Root Group (path `/`) Attributes +------------------------- + +The following attributes are defined for the file root group. + +- `latticeName` + - Type: Optional *(string)* + - Description: The name of the lattice. + +- `latticeFile` + - Type: Optional *(string)* + - Description: The location of the root lattice file. + + +`Particle Root Group` Attributes +--------------------- + +For each **particle root group** the following attributes are defined: + +- `SpeciesType` + - Type: Required *(string)* + - Description: The name of the particle species. Species names must conform to the + `SpeciesType` extension. + - Example: `electron`, `H2O`. + +- `charge` + - Type: Optional *(int)* + - Description: The charge state of the particles. Not needed if the charge can be computed + from knowledge of the `SpeciesType`. + +- `latticeElementName` + - Type: Optional *(string)* + - Description: The name of the lattice element the particle or particles are in. This only makes sense if all + particles are in the same lattice element. Also see: `latticeElementID` and `locaitonInElement`. + +- `latticeElementID` + - Type Optional *(string)* + - Description: The ID string for the lattice element given by `latticeElementName`. The idea is that while more than + one lattice element may have the same name, the ID string will be unique. + - This, along with `locationInElement` sets the origin for specifying particle positions in the **lattice** coordinate system. + - Example: With [Bmad](https://www.classe.cornell.edu/bmad/) based programs the ID string is of the form + **branch-index>>element-index** where **branch-index** is the associated +branch index integer, and **element-index** is the associated lattice element index within the branch. + +- `locationInElement` + - Type Optional *(int)* + - Description: This attribute is used with `latticeElementID`/`latticeElementName` to specify + the origin where the particle or particles are measured with respect in the **lattice** coordinate system. + - The origin is always on the longitudinal axis (x = y = 0) of the **lattice** coordinate system. + - Possible values: + - `Upstream-End`: Upstream end of element outside of any edge fields. + - ``: Where `` is a number. Inside the element at a distance, given by ``, + from the upsteam end of the element. + - `Downstream-End`: Downstream end of the element outside of any edge fields. + - Note: Since some programs will model edge fields of a lattice element as having zero length, the longitudinal **s**-position +does not necessarily provide enough information to determine where a particle is with respect to an edge field so `Upstream-End` and `Downstream-End` are provided. + +- `momentumNormalization` + - Type: Optional *(string)* + - Description: Normalization used for momentum values. + - Possible values: + - `referenceTotalMomentum`: Normalize with respect to the `referenceTotalMomentum` attribute + - `referenceEnergy`: Normalize with respect to the `referenceEenergy` attribute. + - `none`: No normalization. + +- `referenceEnergy` + - Type: Optional *(float)* attribute. + - Description: Specifies the reference energy from which the `energy` is measured with respect to. + +- `referenceTotalMomentum` + - Type: Optional *(float)* attribute + - Description: Specifies the reference total momentum from which the total momentum is measured with respect to. + +- `totalCharge` + - Type: Optional *(float)* attribute. + - Description: The total charge of all the particles. + +Per-Particle Records of the `Particle Root Group` +--------------------- + +The following records store data on a particle by particle basis. + +- `time-refTime` +- Type: Optional *(float)* +- Description: Particle time minus the referece time. + +- `energy/` + - Type: Optional *(float)* + - Description: The total energy of the particles relative to the `referenceEnergy` attribute. + +- `electricField/` + - Type: Optional 2-component *(float)* + - Description: Electric field. Used for photons only. + - Components: (`x`, `y`). + - For each component, the field is specified using either (`amplitude`, `phase`) or (`Real`, `Imaginary`) + subcomponents. + +- `macroCharge/` + - Type: Optional *(float)* + - Description: "Macro"-particles are simulation particles that represent multiple real particles. + The `macroCharge` is the the total charge of the collection of particles that a macro-particle + represents. + +- `momentum/` + - Type: Optional 2 or 3-vector *(float)* + - Description: The total momentum of the particles relative to the `momentumOrigin` attribute. + - Components: (`px`, `py`) or (`px`, `py`, `pz`). + - Note: A program using phase space coordinates to describe particle positions will typically use the transverse momentum + `px` and `py` along with the `totalMomentum` or `energy` records. + +- `pathLength/` + - Type: Optional *(float)* + - Description: Length that a particle has traveled. + +- `position` + - Type: Required 3-vector *(float)* + - Description: Position relative to the coordinate origin. + - Components: (`x`, `y`, ``) where `` is one of: + - `z`: True longitudinal coordinate. + - `-beta.c.dt`: Phase space coordinate conjugate to a momentum based "pz". + - `-beta.c.t`:Phase space coordinate conjugate to a momentum based "pz". + - `-c.dt`: Phase space coordinate conjugate to an energy based "pz". + - `-c.t`: Phase space coordinate conjugate to an energy based "pz". + - Where: **beta** = particle speed, **c** = speed of light, **t** = time, and **dt** = time relative to the reference time. + +- `refTime/` + - Type: Optional *(float)* + - Description: The reference particle time. + Note that the reference time is a function of **s** and therefore can be different for different particles. + +- `s-Position` + - Type: Optional *(float)* + - Description: Absolute longitudinal distance in **lattice** coordinates. + +- `speed/` + - Type: Optional *(float)* + - Description: The speed of the particles. + +- `spin/` + - Type: Optional 3-vector *(float)* + - Description: Particle spin. + - Components: (`x`, `y`, `s`) or (`r`, `theta`, `phi`). + +- `time/` + - Type: Optional *(float)* + - Description: Absolute particle time. Note: Particles may have different times if the snapshot + is, for example, taken at constant **s**. + +- `totalMomentum/` + - Type: Optional *(float)* + - Description: The total momentum of the particles relative to the `referenceTotalMomentum` attribute. + +Non Per-Particle Records of the `Particle Root Group` +--------------------- + +The following possible records of the `Particle Root Group` are for specifying properties of the entire group of particles. + +- `phaseSpaceFirstOrderMoment/` + - Type: Optional 6-vector *(float)* + - Description: First order beam moments. + +- `phaseSpaceSecondOrderMoment/` + - Type: Optional 6x6-matrix *(float)* + - Description: Second order beam moments. + +- `phaseSpaceThirdOrderMoment/` + - Type: Optional 6x6x6-tensor *(float)* + - Description: Third order beam moments. + +- `latticeToGlobalTransformation/` + - Type: Optional group. + - Description: Defines the transformation from **lattice** coordinates to **global** coordinates for a position + specified by `latticeElementName`/`latticeElementID` and `locationInElement`. + - `R_frame`: + - Required 3-vector *(float)* Attribute + - Description: specifying the (x, y, z) position of the **lattice** coordinate origin with respect + to the **global** coordinates. + - `W_matrix`: + - Required 3 x 3 matrix *(float)* + - Description: Dataset holding the 3x3 transformation matrix from **lattice** coordinates to **global** + coordinates. + - Position Transformation: Position_global = W_matrix * Position_lattice + R_frame + - Momentum transformation: Momentum_global = W_matrix * Momentum_lattice + + +Particle Record Dataset Attributes +----------------------------- + +The following attributes can be used with any dataset: + +- `minValue`: + - Type: Optional *(float)* + - Description: Minimum of the data. + +- `maxValue`: + - Type: Optional *(float)* + - Description: Maximum of the data. From 5ab09323d42c61fdd90cd5822966ea472ad8879c Mon Sep 17 00:00:00 2001 From: David Sagan Date: Sun, 25 Feb 2018 23:10:48 -0500 Subject: [PATCH 02/73] Changes made per discussion on openPMD. --- EXT_BeamPhysics.md | 103 +++++++++++++++++++++------------------------ 1 file changed, 49 insertions(+), 54 deletions(-) diff --git a/EXT_BeamPhysics.md b/EXT_BeamPhysics.md index 5acdb14..f085b4b 100644 --- a/EXT_BeamPhysics.md +++ b/EXT_BeamPhysics.md @@ -1,7 +1,7 @@ Extension to the openPMD Standard for Describing Particle Beams and X-rays ========================================== -Version 1.0.0 (March 1, 2018) +Version 2.0.0 Overview ------------ @@ -30,45 +30,26 @@ coordinate system is fixed with respect to the building or room where the machin machine itself. - **Lattice coordinate system**: The curvilinear coordinate system whose "longitudinal" -coordinate (typically called **s**) typically runs through the nominal centers of the elements -in the machine. Typically, the **lattice** coordinate system is used to describe misalignments -of lattice elements with respect to the rest of the lattice. - -- **Group**: A **group** is a container structure containing -a set of zero or more **attributes**, a set of zero or more **groups** (which can be called -**sub-groups**), and a set of zero or more **datasets**. Note: In HDF5, these are also -called **groups**. - -- **Dataset**: A **dataset** is a structure that contains a set of zero or more **attributes** and a -data aray (which may be multidimensional). Note: In HDF5, these are also called **datasets**. - -- **Record**: A **record** is a **group** (without any sub-groups) or a **dataset** that contains data -on a physical quantity like particle charge or electric field. There are two types of **records**: - - **scalar records** hold scalar quantity - values (like particle charge). If all the particles have the same charge, the value of the charge - is stored as an attribute of the **record** and there is no associated data array. That is, the - **record** is a **group**. If the particles have differing charges, the values are stored in an array - of the **scalar record**. In this case the **scalar record** is a **dataset**. - - **vector records** hold a set of **datasets**. In this case the **record** is a **group**. - - Example: A **record** named **E** for holding electric field values may have three datasets holding - the components of the field named **E/x**, **E/y**, and **E/z**. - -- **Attribute**: An **attribute** is a variable associated with a **group** along with a -value. Example: **snapshotPath** is a string variable associated with the root **/** group. - -- **Polar coordinates**: **Polar** coordinates are **(r, theta, phi)** where **r** is the radius, **theta** is he angle +coordinate (**s**) typically runs through the nominal centers of the elements +in the machine. The **lattice** coordinate system is often used to describe particle positions. + +- **Macro-particle**: Macro-particles are simulation particles that represent multiple real particles. + +- **Polar coordinates**: **Polar** coordinates are **(r, theta, phi)** where **r** is the radius, **theta** is the angle from the **z** or **s** axis, and **phi** is the projected azimuthal angle in the **(x, y)** plane. -- **Particle Root Group**: The **Particle Root Group** is the root group for specifying a group of particles. There can be multiple **particle root groups** in a data file. For example, a set of particle bunches might specify one particle root group for each bunch. See the Base Standard for more information. +- **Particle Root Group**: The **Particle Root Group** is a group for specifying a group of particles. See the Base Standard for more information. + +- **Phase Space Coordinates**: Phase space coordinates are ordered (x, px, y, py, z, pz). Notes: ------ - When using the **lattice** coordinate system, the `position` coordinates are **(x, y, s)** where -nominally **x** is the "radial" component, -**y** is the "vertical" coordinate, and **s** is the lattice longitudinal coordinate. +nominally **x** is the "horizontal" component, **y** is the "vertical" coordinate, and **s** is the lattice longitudinal coordinate. +- T Additional File Root Group (path `/`) Attributes ------------------------- @@ -115,7 +96,7 @@ For each **particle root group** the following attributes are defined: branch index integer, and **element-index** is the associated lattice element index within the branch. - `locationInElement` - - Type Optional *(int)* + - Type Optional *(string)* - Description: This attribute is used with `latticeElementID`/`latticeElementName` to specify the origin where the particle or particles are measured with respect in the **lattice** coordinate system. - The origin is always on the longitudinal axis (x = y = 0) of the **lattice** coordinate system. @@ -132,20 +113,9 @@ does not necessarily provide enough information to determine where a particle is - Description: Normalization used for momentum values. - Possible values: - `referenceTotalMomentum`: Normalize with respect to the `referenceTotalMomentum` attribute - - `referenceEnergy`: Normalize with respect to the `referenceEenergy` attribute. + - `referenceEnergy`: Normalize with respect to the `referenceEnergy` attribute. - `none`: No normalization. -- `referenceEnergy` - - Type: Optional *(float)* attribute. - - Description: Specifies the reference energy from which the `energy` is measured with respect to. - -- `referenceTotalMomentum` - - Type: Optional *(float)* attribute - - Description: Specifies the reference total momentum from which the total momentum is measured with respect to. - -- `totalCharge` - - Type: Optional *(float)* attribute. - - Description: The total charge of all the particles. Per-Particle Records of the `Particle Root Group` --------------------- @@ -154,11 +124,23 @@ The following records store data on a particle by particle basis. - `time-refTime` - Type: Optional *(float)* -- Description: Particle time minus the referece time. +- Description: Particle time minus the reference time. - `energy/` - Type: Optional *(float)* - - Description: The total energy of the particles relative to the `referenceEnergy` attribute. + - Description: The total energy of the particles. This record may be used instead of specifying the `pz` phase space coordinate. + - Attributes: The following attributes are defined. + - `relative`: + - Type: Required **(bool)** + - Description: Is the energy relative to the `referenceEnergy`? + - `normalized`: + - Type: Required **(bool)** + - Description: Is the energy normalized by the `totalMomentum`? + - Examples: [E = Energy, E0 = `referenceEnergy`, p0 = `totalMomentum`] + - `relative` = `F`, `normalized` = `F` --> Energy = E + - `relative` = `F`, `normalized` = `T` --> Energy = E / p0 + - `relative` = `T`, `normalized` = `F` --> Energy = E - E0 + - `relative` = `T`, `normalized` = `T` --> Energy = (E - E0) / p0 - `electricField/` - Type: Optional 2-component *(float)* @@ -167,18 +149,15 @@ The following records store data on a particle by particle basis. - For each component, the field is specified using either (`amplitude`, `phase`) or (`Real`, `Imaginary`) subcomponents. -- `macroCharge/` - - Type: Optional *(float)* - - Description: "Macro"-particles are simulation particles that represent multiple real particles. - The `macroCharge` is the the total charge of the collection of particles that a macro-particle - represents. - - `momentum/` - Type: Optional 2 or 3-vector *(float)* - Description: The total momentum of the particles relative to the `momentumOrigin` attribute. - Components: (`px`, `py`) or (`px`, `py`, `pz`). - - Note: A program using phase space coordinates to describe particle positions will typically use the transverse momentum - `px` and `py` along with the `totalMomentum` or `energy` records. + - Attributes: The following attributes are defined. + - `normalized`: + - Type: Required **(bool)** + - Description: Is the energy normalized by the `referenceTotalMomentum`? That is, is `px` equal to Px or Px/P0 (where Px is the true momentum component and P0 is `referenceTotalMomentum`)? + - Note: A program using phase space coordinates to describe particle positions will typically use the transverse momentum `px` and `py` along with the `totalMomentum` or `energy` records. - `pathLength/` - Type: Optional *(float)* @@ -222,6 +201,11 @@ The following records store data on a particle by particle basis. - Type: Optional *(float)* - Description: The total momentum of the particles relative to the `referenceTotalMomentum` attribute. +- `weighting/` + - Type: Optional *(float)* + - Description: If macro-particles are being simulated, the `weighting` is the the total charge or total number of the collection of particles that a macro-particle represents. + + Non Per-Particle Records of the `Particle Root Group` --------------------- @@ -254,6 +238,17 @@ The following possible records of the `Particle Root Group` are for specifying p - Position Transformation: Position_global = W_matrix * Position_lattice + R_frame - Momentum transformation: Momentum_global = W_matrix * Momentum_lattice +- `referenceEnergy` + - Type: Optional *(float)* attribute. + - Description: Specifies the reference energy from which the `energy` is measured with respect to. + +- `referenceTotalMomentum` + - Type: Optional *(float)* attribute + - Description: Specifies the reference total momentum from which the total momentum is measured with respect to. + +- `totalCharge` + - Type: Optional *(float)* attribute. + - Description: The total charge of all the particles. Particle Record Dataset Attributes ----------------------------- From 7d03aa76bdaf6437dc7ad7c914ab5a733d6ccf78 Mon Sep 17 00:00:00 2001 From: David Sagan Date: Sun, 25 Feb 2018 23:21:35 -0500 Subject: [PATCH 03/73] Minor update. --- EXT_BeamPhysics.md | 28 +++++++++++++++++++++------- 1 file changed, 21 insertions(+), 7 deletions(-) diff --git a/EXT_BeamPhysics.md b/EXT_BeamPhysics.md index f085b4b..f63bf3b 100644 --- a/EXT_BeamPhysics.md +++ b/EXT_BeamPhysics.md @@ -135,12 +135,12 @@ The following records store data on a particle by particle basis. - Description: Is the energy relative to the `referenceEnergy`? - `normalized`: - Type: Required **(bool)** - - Description: Is the energy normalized by the `totalMomentum`? - - Examples: [E = Energy, E0 = `referenceEnergy`, p0 = `totalMomentum`] - - `relative` = `F`, `normalized` = `F` --> Energy = E - - `relative` = `F`, `normalized` = `T` --> Energy = E / p0 - - `relative` = `T`, `normalized` = `F` --> Energy = E - E0 - - `relative` = `T`, `normalized` = `T` --> Energy = (E - E0) / p0 + - Description: Is the energy normalized by the `referenceTotalMomentum`? + - Examples: [E = Absolute Energy, E0 = `referenceEnergy`, p0 = `referenceTotalMomentum`] + - `relative` = `F`, `normalized` = `F` --> `Energy` = E + - `relative` = `F`, `normalized` = `T` --> `Energy` = E / p0 + - `relative` = `T`, `normalized` = `F` --> `Energy` = E - E0 + - `relative` = `T`, `normalized` = `T` --> `Energy` = (E - E0) / p0 - `electricField/` - Type: Optional 2-component *(float)* @@ -199,7 +199,21 @@ The following records store data on a particle by particle basis. - `totalMomentum/` - Type: Optional *(float)* - - Description: The total momentum of the particles relative to the `referenceTotalMomentum` attribute. + - Description: The total momentum of the particles. + + - Attributes: The following attributes are defined. + - `relative`: + - Type: Required **(bool)** + - Description: Is the energy relative to the `referenceTotalMomentum`? + - `normalized`: + - Type: Required **(bool)** + - Description: Is the energy normalized by the `totalMomentum`? + - Examples: [P = Absolute total momentum, P0 = `referenceTotalMomentum`, p0 = `referencetotalMomentum`] + - `relative` = `F`, `normalized` = `F` --> `totalMomentum` = P + - `relative` = `F`, `normalized` = `T` --> `totalMomentum` = P / p0 + - `relative` = `T`, `normalized` = `F` --> `totalMomentum` = P - P0 + - `relative` = `T`, `normalized` = `T` --> `totalMomentum` = (P - P0) / p0 + - `weighting/` - Type: Optional *(float)* From 746f716671eecd3ef0eb0c6e8fa31115f6162c71 Mon Sep 17 00:00:00 2001 From: David Sagan Date: Sun, 8 Apr 2018 22:02:22 -0400 Subject: [PATCH 04/73] Minor typo fixes. --- EXT_BeamPhysics.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/EXT_BeamPhysics.md b/EXT_BeamPhysics.md index f63bf3b..6f0203a 100644 --- a/EXT_BeamPhysics.md +++ b/EXT_BeamPhysics.md @@ -14,10 +14,10 @@ How to Use this Extension The `BeamPhysics` extension to the openPMD standard is indicated in a data file by the setting of the `openPMDextension` attribute: ``` - openPMDextension = BeamPhysics, SpeciesType + openPMDextension = BeamPhysics;SpeciesType ``` -Note: The `SpeciesType` extension must be used when using the `BeamPhysics` extension. +Note: The `speciesType` extension must be used when using the `BeamPhysics` extension. Definitions ----------- @@ -70,21 +70,21 @@ The following attributes are defined for the file root group. For each **particle root group** the following attributes are defined: -- `SpeciesType` +- `speciesType` - Type: Required *(string)* - Description: The name of the particle species. Species names must conform to the - `SpeciesType` extension. + `speciesType` extension. - Example: `electron`, `H2O`. - `charge` - Type: Optional *(int)* - Description: The charge state of the particles. Not needed if the charge can be computed - from knowledge of the `SpeciesType`. + from knowledge of the `speciesType`. - `latticeElementName` - Type: Optional *(string)* - Description: The name of the lattice element the particle or particles are in. This only makes sense if all - particles are in the same lattice element. Also see: `latticeElementID` and `locaitonInElement`. + particles are in the same lattice element. Also see: `latticeElementID` and `locationInElement`. - `latticeElementID` - Type Optional *(string)* From e00c44c2a2081ff7b627e2ff6d806210592302e2 Mon Sep 17 00:00:00 2001 From: David Sagan Date: Tue, 8 May 2018 01:14:28 -0400 Subject: [PATCH 05/73] More reorg. --- EXT_BeamPhysics.md | 193 +++++++++++++++++++++------------------------ 1 file changed, 92 insertions(+), 101 deletions(-) diff --git a/EXT_BeamPhysics.md b/EXT_BeamPhysics.md index 6f0203a..9842b6b 100644 --- a/EXT_BeamPhysics.md +++ b/EXT_BeamPhysics.md @@ -1,16 +1,16 @@ Extension to the openPMD Standard for Describing Particle Beams and X-rays -========================================== +========================================================================== Version 2.0.0 Overview ------------- +-------- The `BeamPhysics` extension to the openPMD standard is meant for describing particles and fields commonly encountered in accelerator physics simulations. How to Use this Extension ---------------- +------------------------- The `BeamPhysics` extension to the openPMD standard is indicated in a data file by the setting of the `openPMDextension` attribute: ``` @@ -24,16 +24,13 @@ Definitions - **Lattice**: A **lattice** is the arrangement of elements in a machine such as a particle accelerator. -- **Global coordinate system**: The **global** coordinate system is a coordinate system that is -used to describe the position and orientation of machine elements in space. That is, the **global** -coordinate system is fixed with respect to the building or room where the machine is placed independent of the +- **Global coordinate system**: The **global** coordinate system is a coordinate system that is used to describe the position and orientation of machine elements in space. That is, the **global** coordinate system is fixed with respect to the building or room where the machine is placed independent of the machine itself. - **Lattice coordinate system**: The curvilinear coordinate system whose "longitudinal" -coordinate (**s**) typically runs through the nominal centers of the elements -in the machine. The **lattice** coordinate system is often used to describe particle positions. +coordinate (**s**) typically runs through the nominal centers of the elements in the machine. The **lattice** coordinate system is often used to describe particle positions. -- **Macro-particle**: Macro-particles are simulation particles that represent multiple real particles. +- **Macro-particle**: Macro-particles are simulation particles that represent multiple real particles. The number of real particles that a macro-particle represents affects the calculation of the field due to a macro-particle but does not affect tracking. - **Polar coordinates**: **Polar** coordinates are **(r, theta, phi)** where **r** is the radius, **theta** is the angle from the **z** or **s** axis, and **phi** is the projected azimuthal angle in the **(x, y)** @@ -49,10 +46,8 @@ Notes: - When using the **lattice** coordinate system, the `position` coordinates are **(x, y, s)** where nominally **x** is the "horizontal" component, **y** is the "vertical" coordinate, and **s** is the lattice longitudinal coordinate. -- T - Additional File Root Group (path `/`) Attributes -------------------------- +------------------------------------------------ The following attributes are defined for the file root group. @@ -66,7 +61,7 @@ The following attributes are defined for the file root group. `Particle Root Group` Attributes ---------------------- +-------------------------------- For each **particle root group** the following attributes are defined: @@ -81,6 +76,27 @@ For each **particle root group** the following attributes are defined: - Description: The charge state of the particles. Not needed if the charge can be computed from knowledge of the `speciesType`. +- `referenceMomentum` + - Type: Optional *(float)* + - Description: Reference momentum Possibly used for normalizing particle momentum values. + +- `referenceTotalEnergy` + - Type: Optional *(string)* + - Description: Reference total (kinetic + rest mass) energy. Possibly used for normalizing particle momentum values. + + +Per-Particle Records of the `Particle Root Group` +------------------------------------------------- + +The following records store data on a particle-by-particle basis. + +- `electricField/` + - Type: Optional 2-component *(float)* + - Description: Electric field. Used for photons only. + - Components: (`x`, `y`). + - For each component, the field is specified using either (`amplitude`, `phase`) or (`Real`, `Imaginary`) + subcomponents. + - `latticeElementName` - Type: Optional *(string)* - Description: The name of the lattice element the particle or particles are in. This only makes sense if all @@ -96,68 +112,44 @@ For each **particle root group** the following attributes are defined: branch index integer, and **element-index** is the associated lattice element index within the branch. - `locationInElement` - - Type Optional *(string)* - - Description: This attribute is used with `latticeElementID`/`latticeElementName` to specify - the origin where the particle or particles are measured with respect in the **lattice** coordinate system. - - The origin is always on the longitudinal axis (x = y = 0) of the **lattice** coordinate system. + - Type Optional *(integer)* + - Description: The program generating the data file may model a lattice element using a "hard edge" model where the fringe fields at the ends of the element are modeled as having zero longitudinal length. In such a case, if a particle is at the end of the lattice element, it is important to know if the particle is outside of the fringe or if the particle is inside the fringe within the body of the element. Note that with a hard edge fringe, the longitudinal **s**-position does not necessarily provide enough information to determine where a particle is with respect to an edge field. Another situation where `locationInElement` is useful is with zero length elements that affect the particle transport (such as zero length multipole elements). If the program generating the data file does **not** use any hard edge models or zero length non-marker elements, `locationInElement` should not be present since this parameter is meaningless in this case. - Possible values: - - `Upstream-End`: Upstream end of element outside of any edge fields. - - ``: Where `` is a number. Inside the element at a distance, given by ``, - from the upsteam end of the element. - - `Downstream-End`: Downstream end of the element outside of any edge fields. - - Note: Since some programs will model edge fields of a lattice element as having zero length, the longitudinal **s**-position -does not necessarily provide enough information to determine where a particle is with respect to an edge field so `Upstream-End` and `Downstream-End` are provided. - -- `momentumNormalization` - - Type: Optional *(string)* - - Description: Normalization used for momentum values. - - Possible values: - - `referenceTotalMomentum`: Normalize with respect to the `referenceTotalMomentum` attribute - - `referenceEnergy`: Normalize with respect to the `referenceEnergy` attribute. - - `none`: No normalization. - - -Per-Particle Records of the `Particle Root Group` ---------------------- - -The following records store data on a particle by particle basis. - -- `time-refTime` -- Type: Optional *(float)* -- Description: Particle time minus the reference time. - -- `energy/` - - Type: Optional *(float)* - - Description: The total energy of the particles. This record may be used instead of specifying the `pz` phase space coordinate. - - Attributes: The following attributes are defined. - - `relative`: - - Type: Required **(bool)** - - Description: Is the energy relative to the `referenceEnergy`? - - `normalized`: - - Type: Required **(bool)** - - Description: Is the energy normalized by the `referenceTotalMomentum`? - - Examples: [E = Absolute Energy, E0 = `referenceEnergy`, p0 = `referenceTotalMomentum`] - - `relative` = `F`, `normalized` = `F` --> `Energy` = E - - `relative` = `F`, `normalized` = `T` --> `Energy` = E / p0 - - `relative` = `T`, `normalized` = `F` --> `Energy` = E - E0 - - `relative` = `T`, `normalized` = `T` --> `Energy` = (E - E0) / p0 - -- `electricField/` - - Type: Optional 2-component *(float)* - - Description: Electric field. Used for photons only. - - Components: (`x`, `y`). - - For each component, the field is specified using either (`amplitude`, `phase`) or (`Real`, `Imaginary`) - subcomponents. + - -1: Upstream end of element outside of the upstream fringe edge. + - 0: Inside the element. + - 1: Downstream end of the element outside outside the downstream fringe edge. - `momentum/` - - Type: Optional 2 or 3-vector *(float)* - - Description: The total momentum of the particles relative to the `momentumOrigin` attribute. - - Components: (`px`, `py`) or (`px`, `py`, `pz`). - - Attributes: The following attributes are defined. - - `normalized`: - - Type: Required **(bool)** - - Description: Is the energy normalized by the `referenceTotalMomentum`? That is, is `px` equal to Px or Px/P0 (where Px is the true momentum component and P0 is `referenceTotalMomentum`)? - - Note: A program using phase space coordinates to describe particle positions will typically use the transverse momentum `px` and `py` along with the `totalMomentum` or `energy` records. + - Type: Optional 2 or 3-vector *(float)* + - Description: The momentum vector of the particles. + - Components: (`px`, `py`, `pz`). + - Attributes: + - `pxType`: + - Type: Required **(string)** + - Description: Describes how the `px` component is to be interpreted. + - Possible values: [Where: Px = Momentum component, P0 = `referenceMomentum`] + - `Px`: `px` is the x-component of the momentum. + - `Px/P0`: `px` is the momentum normalized by the reference momentum. + - `pyType`: + - Type: Required **(string)** + - Description: Describes how the `py` component is to be interpreted. + - Possible values: [Where: Py = Momentum component , P0 = `referenceMomentum`] + - `Py`: `py` is the y-component of the momentum. + - `Py/P0`: `py` is the momentum normalized by the reference momentum. + - `pzType`: + - Type: Required **(string)** + - Description: Describes how the `pz` component is to be interpreted. + - Possible values: [Where: E = Total energy, P = momentum magnitude, E0 = `referenceTotalEnergy`, P0 = `referenceMomentum`, Pz = momentum component, dE = E - E0, dP = P - P0] + - `Pz` + - `Pz/P0` + - `P` + - `P/P0` + - `dP` + - `dP/P0` + - `E` + - `E/P0` + - `dE` + - `dE/P0` - `pathLength/` - Type: Optional *(float)* @@ -166,13 +158,17 @@ The following records store data on a particle by particle basis. - `position` - Type: Required 3-vector *(float)* - Description: Position relative to the coordinate origin. - - Components: (`x`, `y`, ``) where `` is one of: - - `z`: True longitudinal coordinate. - - `-beta.c.dt`: Phase space coordinate conjugate to a momentum based "pz". - - `-beta.c.t`:Phase space coordinate conjugate to a momentum based "pz". - - `-c.dt`: Phase space coordinate conjugate to an energy based "pz". - - `-c.t`: Phase space coordinate conjugate to an energy based "pz". - - Where: **beta** = particle speed, **c** = speed of light, **t** = time, and **dt** = time relative to the reference time. + - Components: (`x`, `y`, `z`) + - Attributes: + - `zType`: + - Type: Required **(string)** + - Description: Describes how the `z` component is to be interpreted. + - Possible values: [Where: **beta** = particle speed, **c** = speed of light, **t** = time, and **dt** = time relative to the reference time.] + - `-beta.c.dt`: `z` component is the phase space coordinate conjugate to a momentum based "pz". + - `-beta.c.t`: `z` component is the phase space coordinate conjugate to a momentum based "pz". + - `-c.dt`: `z` component is the phase space coordinate conjugate to an energy based "pz". + - `-c.t`: `z` component is the phase space coordinate conjugate to an energy based "pz". + - `z`: `z` component is the true longitudinal coordinate. - `refTime/` - Type: Optional *(float)* @@ -181,7 +177,12 @@ The following records store data on a particle by particle basis. - `s-Position` - Type: Optional *(float)* - - Description: Absolute longitudinal distance in **lattice** coordinates. + - Description: Longitudinal distance of the particle in **lattice** coordinates. This attribute establishes + the origin for the (x, y) transverse plane where the particle is measured with respect to in the **lattice** coordinate system. + - Attribute: + - `absolute`: + - Type: Required **(bool)** + - Description: `True` = Absolute position from the beginning of the lattice. `False` = Relative position measured from the beginning of the element the particle is in specified by `latticeElementName` and/or `latticeElementID`. - `speed/` - Type: Optional *(float)* @@ -197,23 +198,13 @@ The following records store data on a particle by particle basis. - Description: Absolute particle time. Note: Particles may have different times if the snapshot is, for example, taken at constant **s**. -- `totalMomentum/` - - Type: Optional *(float)* - - Description: The total momentum of the particles. - - - Attributes: The following attributes are defined. - - `relative`: - - Type: Required **(bool)** - - Description: Is the energy relative to the `referenceTotalMomentum`? - - `normalized`: - - Type: Required **(bool)** - - Description: Is the energy normalized by the `totalMomentum`? - - Examples: [P = Absolute total momentum, P0 = `referenceTotalMomentum`, p0 = `referencetotalMomentum`] - - `relative` = `F`, `normalized` = `F` --> `totalMomentum` = P - - `relative` = `F`, `normalized` = `T` --> `totalMomentum` = P / p0 - - `relative` = `T`, `normalized` = `F` --> `totalMomentum` = P - P0 - - `relative` = `T`, `normalized` = `T` --> `totalMomentum` = (P - P0) / p0 +- `time-refTime` + - Type: Optional *(float)* + - Description: Particle time minus the reference time. +- `velocity` + - Type: Required 3-vector *(float)* + - Description: (`Vx`, `Vy`, `Vz`) velocity vector. - `weighting/` - Type: Optional *(float)* @@ -221,7 +212,7 @@ The following records store data on a particle by particle basis. Non Per-Particle Records of the `Particle Root Group` ---------------------- +----------------------------------------------------- The following possible records of the `Particle Root Group` are for specifying properties of the entire group of particles. @@ -252,11 +243,11 @@ The following possible records of the `Particle Root Group` are for specifying p - Position Transformation: Position_global = W_matrix * Position_lattice + R_frame - Momentum transformation: Momentum_global = W_matrix * Momentum_lattice -- `referenceEnergy` +- `referenceTotalEnergy` - Type: Optional *(float)* attribute. - - Description: Specifies the reference energy from which the `energy` is measured with respect to. + - Description: Specifies the reference energy from which the `totalEnergy` is measured with respect to. -- `referenceTotalMomentum` +- `referenceMomentum` - Type: Optional *(float)* attribute - Description: Specifies the reference total momentum from which the total momentum is measured with respect to. @@ -265,7 +256,7 @@ The following possible records of the `Particle Root Group` are for specifying p - Description: The total charge of all the particles. Particle Record Dataset Attributes ------------------------------ +---------------------------------- The following attributes can be used with any dataset: From 203ee1220de45ac22a929700d7f1736928cf03a7 Mon Sep 17 00:00:00 2001 From: David Sagan Date: Mon, 14 May 2018 15:18:17 -0400 Subject: [PATCH 06/73] Minor edits. --- EXT_BeamPhysics.md | 29 ++++++++++++----------------- 1 file changed, 12 insertions(+), 17 deletions(-) diff --git a/EXT_BeamPhysics.md b/EXT_BeamPhysics.md index 9842b6b..81e666f 100644 --- a/EXT_BeamPhysics.md +++ b/EXT_BeamPhysics.md @@ -24,17 +24,13 @@ Definitions - **Lattice**: A **lattice** is the arrangement of elements in a machine such as a particle accelerator. -- **Global coordinate system**: The **global** coordinate system is a coordinate system that is used to describe the position and orientation of machine elements in space. That is, the **global** coordinate system is fixed with respect to the building or room where the machine is placed independent of the -machine itself. +- **Global coordinate system**: The **global** coordinate system is a coordinate system that is used to describe the position and orientation of machine elements in space. That is, the **global** coordinate system is fixed with respect to the building or room where the machine is placed independent of the machine itself. -- **Lattice coordinate system**: The curvilinear coordinate system whose "longitudinal" -coordinate (**s**) typically runs through the nominal centers of the elements in the machine. The **lattice** coordinate system is often used to describe particle positions. +- **Lattice coordinate system**: The curvilinear coordinate system whose "longitudinal" coordinate (**s**) typically runs through the nominal centers of the elements in the machine. The **lattice** coordinate system is often used to describe particle positions. - **Macro-particle**: Macro-particles are simulation particles that represent multiple real particles. The number of real particles that a macro-particle represents affects the calculation of the field due to a macro-particle but does not affect tracking. -- **Polar coordinates**: **Polar** coordinates are **(r, theta, phi)** where **r** is the radius, **theta** is the angle -from the **z** or **s** axis, and **phi** is the projected azimuthal angle in the **(x, y)** -plane. +- **Polar coordinates**: **Polar** coordinates are **(r, theta, phi)** where **r** is the radius, **theta** is the angle from the **z** or **s** axis, and **phi** is the projected azimuthal angle in the **(x, y)** plane. - **Particle Root Group**: The **Particle Root Group** is a group for specifying a group of particles. See the Base Standard for more information. @@ -43,8 +39,7 @@ plane. Notes: ------ -- When using the **lattice** coordinate system, the `position` coordinates are **(x, y, s)** where -nominally **x** is the "horizontal" component, **y** is the "vertical" coordinate, and **s** is the lattice longitudinal coordinate. +- When using the **lattice** coordinate system, the `position` coordinates are **(x, y, s)** or **(x, y, z)** where, nominally, **x** is the "horizontal" component, **y** is the "vertical" coordinate, and **s** or **z** is the lattice longitudinal coordinate. Additional File Root Group (path `/`) Attributes ------------------------------------------------ @@ -65,12 +60,6 @@ The following attributes are defined for the file root group. For each **particle root group** the following attributes are defined: -- `speciesType` - - Type: Required *(string)* - - Description: The name of the particle species. Species names must conform to the - `speciesType` extension. - - Example: `electron`, `H2O`. - - `charge` - Type: Optional *(int)* - Description: The charge state of the particles. Not needed if the charge can be computed @@ -84,6 +73,12 @@ For each **particle root group** the following attributes are defined: - Type: Optional *(string)* - Description: Reference total (kinetic + rest mass) energy. Possibly used for normalizing particle momentum values. + - `speciesType` + - Type: Required *(string)* + - Description: The name of the particle species. Species names must conform to the + `speciesType` extension. + - Example: `electron`, `H2O`. + Per-Particle Records of the `Particle Root Group` ------------------------------------------------- @@ -120,7 +115,7 @@ branch index integer, and **element-index** is the associated lattice element in - 1: Downstream end of the element outside outside the downstream fringe edge. - `momentum/` - - Type: Optional 2 or 3-vector *(float)* + - Type: Optional 3-vector *(float)* - Description: The momentum vector of the particles. - Components: (`px`, `py`, `pz`). - Attributes: @@ -186,7 +181,7 @@ branch index integer, and **element-index** is the associated lattice element in - `speed/` - Type: Optional *(float)* - - Description: The speed of the particles. + - Description: The speed (velocity magnitude) of a particle. - `spin/` - Type: Optional 3-vector *(float)* From 38170e8d2d5fc0bd24c02874f1c5dfb456f95a3f Mon Sep 17 00:00:00 2001 From: David Sagan Date: Mon, 21 May 2018 15:22:45 -0400 Subject: [PATCH 07/73] Minor tweaks based upon comments from Axel and Remi. --- EXT_BeamPhysics.md | 74 +++++++++++++++++++--------------------------- 1 file changed, 31 insertions(+), 43 deletions(-) diff --git a/EXT_BeamPhysics.md b/EXT_BeamPhysics.md index 81e666f..dc55411 100644 --- a/EXT_BeamPhysics.md +++ b/EXT_BeamPhysics.md @@ -17,7 +17,7 @@ The `BeamPhysics` extension to the openPMD standard is indicated in a data file openPMDextension = BeamPhysics;SpeciesType ``` -Note: The `speciesType` extension must be used when using the `BeamPhysics` extension. +Note: The `SpeciesType` extension must be used when using the `BeamPhysics` extension. Definitions ----------- @@ -60,10 +60,24 @@ The following attributes are defined for the file root group. For each **particle root group** the following attributes are defined: -- `charge` - - Type: Optional *(int)* - - Description: The charge state of the particles. Not needed if the charge can be computed - from knowledge of the `speciesType`. +- `latticeElementName` + - Type: Optional *(string)* + - Description: The name of the lattice element the particle or particles are in. This only makes sense if all particles are in the same lattice element. Also see: `latticeElementID` and `locationInElement`. + +- `latticeElementID` + - Type Optional *(string)* + - Description: The ID string for the lattice element given by `latticeElementName`. The idea is that while more than one lattice element may have the same name, the ID string will be unique. + - This, along with `locationInElement` sets the origin for specifying particle positions in the **lattice** coordinate system. + - Example: With [Bmad](https://www.classe.cornell.edu/bmad/) based programs the ID string is of the form + **branch-index>>element-index** where **branch-index** is the associated branch index integer, and **element-index** is the associated lattice element index within the branch. + +- `locationInElement` + - Type Optional *(integer)* + - Description: The program generating the data file may model a lattice element using a "hard edge" model where the fringe fields at the ends of the element are modeled as having zero longitudinal length. In such a case, if a particle is at the end of the lattice element, it is important to know if the particle is outside of the fringe or if the particle is inside the fringe within the body of the element. Note that with a hard edge fringe, the longitudinal **s**-position does not necessarily provide enough information to determine where a particle is with respect to an edge field. Another situation where `locationInElement` is useful is with zero length elements that affect the particle transport (such as zero length multipole elements). If the program generating the data file does **not** use any hard edge models or zero length non-marker elements, `locationInElement` should not be present since this parameter is meaningless in this case. + - Possible values: + - -1: Upstream end of element outside of the upstream fringe edge. + - 0: Inside the element. + - 1: Downstream end of the element outside outside the downstream fringe edge. - `referenceMomentum` - Type: Optional *(float)* @@ -73,11 +87,10 @@ For each **particle root group** the following attributes are defined: - Type: Optional *(string)* - Description: Reference total (kinetic + rest mass) energy. Possibly used for normalizing particle momentum values. - - `speciesType` - - Type: Required *(string)* - - Description: The name of the particle species. Species names must conform to the - `speciesType` extension. - - Example: `electron`, `H2O`. +- `speciesType` + - Type: Required *(string)* + - Description: The name of the particle species. Species names must conform to the `SpeciesType` extension. + - Example: `electron`, `H2O`. Per-Particle Records of the `Particle Root Group` @@ -85,6 +98,11 @@ Per-Particle Records of the `Particle Root Group` The following records store data on a particle-by-particle basis. +- `charge` + - Type: Optional *(int)* + - Description: The charge state of the particles. Not needed if the charge can be computed + from knowledge of the `SpeciesType`. + - `electricField/` - Type: Optional 2-component *(float)* - Description: Electric field. Used for photons only. @@ -92,28 +110,6 @@ The following records store data on a particle-by-particle basis. - For each component, the field is specified using either (`amplitude`, `phase`) or (`Real`, `Imaginary`) subcomponents. -- `latticeElementName` - - Type: Optional *(string)* - - Description: The name of the lattice element the particle or particles are in. This only makes sense if all - particles are in the same lattice element. Also see: `latticeElementID` and `locationInElement`. - -- `latticeElementID` - - Type Optional *(string)* - - Description: The ID string for the lattice element given by `latticeElementName`. The idea is that while more than - one lattice element may have the same name, the ID string will be unique. - - This, along with `locationInElement` sets the origin for specifying particle positions in the **lattice** coordinate system. - - Example: With [Bmad](https://www.classe.cornell.edu/bmad/) based programs the ID string is of the form - **branch-index>>element-index** where **branch-index** is the associated -branch index integer, and **element-index** is the associated lattice element index within the branch. - -- `locationInElement` - - Type Optional *(integer)* - - Description: The program generating the data file may model a lattice element using a "hard edge" model where the fringe fields at the ends of the element are modeled as having zero longitudinal length. In such a case, if a particle is at the end of the lattice element, it is important to know if the particle is outside of the fringe or if the particle is inside the fringe within the body of the element. Note that with a hard edge fringe, the longitudinal **s**-position does not necessarily provide enough information to determine where a particle is with respect to an edge field. Another situation where `locationInElement` is useful is with zero length elements that affect the particle transport (such as zero length multipole elements). If the program generating the data file does **not** use any hard edge models or zero length non-marker elements, `locationInElement` should not be present since this parameter is meaningless in this case. - - Possible values: - - -1: Upstream end of element outside of the upstream fringe edge. - - 0: Inside the element. - - 1: Downstream end of the element outside outside the downstream fringe edge. - - `momentum/` - Type: Optional 3-vector *(float)* - Description: The momentum vector of the particles. @@ -150,7 +146,7 @@ branch index integer, and **element-index** is the associated lattice element in - Type: Optional *(float)* - Description: Length that a particle has traveled. -- `position` +- `position/` - Type: Required 3-vector *(float)* - Description: Position relative to the coordinate origin. - Components: (`x`, `y`, `z`) @@ -170,7 +166,7 @@ branch index integer, and **element-index** is the associated lattice element in - Description: The reference particle time. Note that the reference time is a function of **s** and therefore can be different for different particles. -- `s-Position` +- `s-Position/` - Type: Optional *(float)* - Description: Longitudinal distance of the particle in **lattice** coordinates. This attribute establishes the origin for the (x, y) transverse plane where the particle is measured with respect to in the **lattice** coordinate system. @@ -193,7 +189,7 @@ branch index integer, and **element-index** is the associated lattice element in - Description: Absolute particle time. Note: Particles may have different times if the snapshot is, for example, taken at constant **s**. -- `time-refTime` +- `time-refTime/` - Type: Optional *(float)* - Description: Particle time minus the reference time. @@ -238,14 +234,6 @@ The following possible records of the `Particle Root Group` are for specifying p - Position Transformation: Position_global = W_matrix * Position_lattice + R_frame - Momentum transformation: Momentum_global = W_matrix * Momentum_lattice -- `referenceTotalEnergy` - - Type: Optional *(float)* attribute. - - Description: Specifies the reference energy from which the `totalEnergy` is measured with respect to. - -- `referenceMomentum` - - Type: Optional *(float)* attribute - - Description: Specifies the reference total momentum from which the total momentum is measured with respect to. - - `totalCharge` - Type: Optional *(float)* attribute. - Description: The total charge of all the particles. From 7395bc4f659e1b672b36439663eacbf9448f03c8 Mon Sep 17 00:00:00 2001 From: David Sagan Date: Mon, 21 May 2018 15:33:37 -0400 Subject: [PATCH 08/73] Fix Typo --- EXT_BeamPhysics.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/EXT_BeamPhysics.md b/EXT_BeamPhysics.md index dc55411..3975d3f 100644 --- a/EXT_BeamPhysics.md +++ b/EXT_BeamPhysics.md @@ -77,7 +77,7 @@ For each **particle root group** the following attributes are defined: - Possible values: - -1: Upstream end of element outside of the upstream fringe edge. - 0: Inside the element. - - 1: Downstream end of the element outside outside the downstream fringe edge. + - 1: Downstream end of the element outside the downstream fringe edge. - `referenceMomentum` - Type: Optional *(float)* From 0d762ef5c105ee13a0ca3af968d8a966af394c52 Mon Sep 17 00:00:00 2001 From: David Sagan Date: Wed, 23 May 2018 12:35:24 -0400 Subject: [PATCH 09/73] Very minor: Correct final "/" in names. --- EXT_BeamPhysics.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/EXT_BeamPhysics.md b/EXT_BeamPhysics.md index 3975d3f..24f8ec1 100644 --- a/EXT_BeamPhysics.md +++ b/EXT_BeamPhysics.md @@ -142,7 +142,7 @@ The following records store data on a particle-by-particle basis. - `dE` - `dE/P0` -- `pathLength/` +- `pathLength` - Type: Optional *(float)* - Description: Length that a particle has traveled. @@ -161,12 +161,12 @@ The following records store data on a particle-by-particle basis. - `-c.t`: `z` component is the phase space coordinate conjugate to an energy based "pz". - `z`: `z` component is the true longitudinal coordinate. -- `refTime/` +- `refTime` - Type: Optional *(float)* - Description: The reference particle time. Note that the reference time is a function of **s** and therefore can be different for different particles. -- `s-Position/` +- `s-Position` - Type: Optional *(float)* - Description: Longitudinal distance of the particle in **lattice** coordinates. This attribute establishes the origin for the (x, y) transverse plane where the particle is measured with respect to in the **lattice** coordinate system. @@ -175,7 +175,7 @@ The following records store data on a particle-by-particle basis. - Type: Required **(bool)** - Description: `True` = Absolute position from the beginning of the lattice. `False` = Relative position measured from the beginning of the element the particle is in specified by `latticeElementName` and/or `latticeElementID`. -- `speed/` +- `speed` - Type: Optional *(float)* - Description: The speed (velocity magnitude) of a particle. @@ -184,17 +184,17 @@ The following records store data on a particle-by-particle basis. - Description: Particle spin. - Components: (`x`, `y`, `s`) or (`r`, `theta`, `phi`). -- `time/` +- `time` - Type: Optional *(float)* - Description: Absolute particle time. Note: Particles may have different times if the snapshot is, for example, taken at constant **s**. -- `time-refTime/` +- `time-refTime` - Type: Optional *(float)* - Description: Particle time minus the reference time. -- `velocity` - - Type: Required 3-vector *(float)* +- `velocity/` + - Type: Optional 3-vector *(float)* - Description: (`Vx`, `Vy`, `Vz`) velocity vector. - `weighting/` From 35d4961f0f3fc7f3706314f46f5a053faede29cd Mon Sep 17 00:00:00 2001 From: David Sagan Date: Thu, 24 May 2018 19:15:44 -0400 Subject: [PATCH 10/73] Minor name correction. --- EXT_BeamPhysics.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/EXT_BeamPhysics.md b/EXT_BeamPhysics.md index 24f8ec1..c5d469e 100644 --- a/EXT_BeamPhysics.md +++ b/EXT_BeamPhysics.md @@ -166,7 +166,7 @@ The following records store data on a particle-by-particle basis. - Description: The reference particle time. Note that the reference time is a function of **s** and therefore can be different for different particles. -- `s-Position` +- `sPosition` - Type: Optional *(float)* - Description: Longitudinal distance of the particle in **lattice** coordinates. This attribute establishes the origin for the (x, y) transverse plane where the particle is measured with respect to in the **lattice** coordinate system. From 37524aeaeddb4ab474116f011d6b6f493934fa17 Mon Sep 17 00:00:00 2001 From: David Sagan Date: Mon, 1 Oct 2018 15:04:45 -0400 Subject: [PATCH 11/73] Minor mod --- EXT_BeamPhysics.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/EXT_BeamPhysics.md b/EXT_BeamPhysics.md index 3975d3f..46d03fb 100644 --- a/EXT_BeamPhysics.md +++ b/EXT_BeamPhysics.md @@ -154,11 +154,11 @@ The following records store data on a particle-by-particle basis. - `zType`: - Type: Required **(string)** - Description: Describes how the `z` component is to be interpreted. - - Possible values: [Where: **beta** = particle speed, **c** = speed of light, **t** = time, and **dt** = time relative to the reference time.] - - `-beta.c.dt`: `z` component is the phase space coordinate conjugate to a momentum based "pz". - - `-beta.c.t`: `z` component is the phase space coordinate conjugate to a momentum based "pz". - - `-c.dt`: `z` component is the phase space coordinate conjugate to an energy based "pz". - - `-c.t`: `z` component is the phase space coordinate conjugate to an energy based "pz". + - Possible values: [Where: **beta** = particle speed/speed of light, **c** = speed of light, **t** = time, and **dt** = time - reference time.] + - `-beta*c*dt`: `z` component is the phase space coordinate conjugate to a momentum based "pz". + - `-beta*c*t`: `z` component is the phase space coordinate conjugate to a momentum based "pz". + - `-c*dt`: `z` component is the phase space coordinate conjugate to an energy based "pz". + - `-c*t`: `z` component is the phase space coordinate conjugate to an energy based "pz". - `z`: `z` component is the true longitudinal coordinate. - `refTime/` From 7f50c3fb1be72b3e0d62afb6fa6356fc09af6623 Mon Sep 17 00:00:00 2001 From: David Sagan Date: Mon, 1 Oct 2018 15:44:44 -0400 Subject: [PATCH 12/73] Fix typo in text. --- EXT_BeamPhysics.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/EXT_BeamPhysics.md b/EXT_BeamPhysics.md index ae0d7f1..e605f8f 100644 --- a/EXT_BeamPhysics.md +++ b/EXT_BeamPhysics.md @@ -58,7 +58,7 @@ The following attributes are defined for the file root group. `Particle Root Group` Attributes -------------------------------- -For each **particle root group** the following attributes are defined: +For each **particle root group** the following components are defined: - `latticeElementName` - Type: Optional *(string)* From 76f403584b44fdf455b8db43d9c19663e61e1dea Mon Sep 17 00:00:00 2001 From: David Sagan Date: Mon, 1 Oct 2018 20:31:08 -0400 Subject: [PATCH 13/73] Correct "attribute" in several places should have been "record". --- EXT_BeamPhysics.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/EXT_BeamPhysics.md b/EXT_BeamPhysics.md index e605f8f..9cfb93e 100644 --- a/EXT_BeamPhysics.md +++ b/EXT_BeamPhysics.md @@ -41,10 +41,10 @@ Notes: - When using the **lattice** coordinate system, the `position` coordinates are **(x, y, s)** or **(x, y, z)** where, nominally, **x** is the "horizontal" component, **y** is the "vertical" coordinate, and **s** or **z** is the lattice longitudinal coordinate. -Additional File Root Group (path `/`) Attributes +Additional File Root Group (path `/`) records ------------------------------------------------ -The following attributes are defined for the file root group. +The following records are defined for the file root group. - `latticeName` - Type: Optional *(string)* @@ -55,10 +55,10 @@ The following attributes are defined for the file root group. - Description: The location of the root lattice file. -`Particle Root Group` Attributes +`Particle Root Group` records -------------------------------- -For each **particle root group** the following components are defined: +For each **particle root group** the following records are defined: - `latticeElementName` - Type: Optional *(string)* @@ -168,7 +168,7 @@ The following records store data on a particle-by-particle basis. - `sPosition` - Type: Optional *(float)* - - Description: Longitudinal distance of the particle in **lattice** coordinates. This attribute establishes + - Description: Longitudinal distance of the particle in **lattice** coordinates. This record establishes the origin for the (x, y) transverse plane where the particle is measured with respect to in the **lattice** coordinate system. - Attribute: - `absolute`: From 7646a7539e6bf9440f3846eee5afb0778d572ff3 Mon Sep 17 00:00:00 2001 From: David Sagan Date: Tue, 6 Nov 2018 12:56:46 -0500 Subject: [PATCH 14/73] Added particleStatus record --- EXT_BeamPhysics.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/EXT_BeamPhysics.md b/EXT_BeamPhysics.md index 9cfb93e..384f9f9 100644 --- a/EXT_BeamPhysics.md +++ b/EXT_BeamPhysics.md @@ -142,6 +142,10 @@ The following records store data on a particle-by-particle basis. - `dE` - `dE/P0` +- `particleStatus` + - Type: Optional *(int)* + - Description: Integer indicating whether a particle is "alive" or "dead" (for example, has hit the vacuum chamber wall). A zero value indicates the particle is alive and any other value indicates that the particle is dead. Programs are free to distinguish how a particle died by assigning different non-zero values to "modes of death". For example, a program might want to differentiate between particles that are dead due to hitting one surface verses hitting a different surface. + - `pathLength` - Type: Optional *(float)* - Description: Length that a particle has traveled. From 5b0cfc7212a5d231e0b2e1b82b099754f5790001 Mon Sep 17 00:00:00 2001 From: ChristopherMayes <31023527+ChristopherMayes@users.noreply.github.com> Date: Thu, 8 Nov 2018 11:05:41 -0800 Subject: [PATCH 15/73] Update EXT_BeamPhysics.md --- EXT_BeamPhysics.md | 15 +++------------ 1 file changed, 3 insertions(+), 12 deletions(-) diff --git a/EXT_BeamPhysics.md b/EXT_BeamPhysics.md index 384f9f9..9012f8e 100644 --- a/EXT_BeamPhysics.md +++ b/EXT_BeamPhysics.md @@ -115,22 +115,13 @@ The following records store data on a particle-by-particle basis. - Description: The momentum vector of the particles. - Components: (`px`, `py`, `pz`). - Attributes: - - `pxType`: + - `convention`: - Type: Required **(string)** - - Description: Describes how the `px` component is to be interpreted. - - Possible values: [Where: Px = Momentum component, P0 = `referenceMomentum`] + - Description: Describes how the component is to be interpreted. + - Possible values: [Where: Px = Momentum component, P0 = `referenceMomentum`, E = Total energy, P = momentum magnitude, E0 = `referenceTotalEnergy`, dE = E - E0, dP = P - P0] - `Px`: `px` is the x-component of the momentum. - `Px/P0`: `px` is the momentum normalized by the reference momentum. - - `pyType`: - - Type: Required **(string)** - - Description: Describes how the `py` component is to be interpreted. - - Possible values: [Where: Py = Momentum component , P0 = `referenceMomentum`] - - `Py`: `py` is the y-component of the momentum. - `Py/P0`: `py` is the momentum normalized by the reference momentum. - - `pzType`: - - Type: Required **(string)** - - Description: Describes how the `pz` component is to be interpreted. - - Possible values: [Where: E = Total energy, P = momentum magnitude, E0 = `referenceTotalEnergy`, P0 = `referenceMomentum`, Pz = momentum component, dE = E - E0, dP = P - P0] - `Pz` - `Pz/P0` - `P` From 17f6dca08fe50c8d6a3c1e427dd1dcea50a7f194 Mon Sep 17 00:00:00 2001 From: ChristopherMayes <31023527+ChristopherMayes@users.noreply.github.com> Date: Thu, 8 Nov 2018 11:08:41 -0800 Subject: [PATCH 16/73] Update EXT_BeamPhysics.md --- EXT_BeamPhysics.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/EXT_BeamPhysics.md b/EXT_BeamPhysics.md index 9012f8e..079e269 100644 --- a/EXT_BeamPhysics.md +++ b/EXT_BeamPhysics.md @@ -114,11 +114,11 @@ The following records store data on a particle-by-particle basis. - Type: Optional 3-vector *(float)* - Description: The momentum vector of the particles. - Components: (`px`, `py`, `pz`). - - Attributes: + - For each component, the convenction is specified by the attribute: - `convention`: - Type: Required **(string)** - Description: Describes how the component is to be interpreted. - - Possible values: [Where: Px = Momentum component, P0 = `referenceMomentum`, E = Total energy, P = momentum magnitude, E0 = `referenceTotalEnergy`, dE = E - E0, dP = P - P0] + - Possible values: - `Px`: `px` is the x-component of the momentum. - `Px/P0`: `px` is the momentum normalized by the reference momentum. - `Py/P0`: `py` is the momentum normalized by the reference momentum. @@ -132,6 +132,7 @@ The following records store data on a particle-by-particle basis. - `E/P0` - `dE` - `dE/P0` + [Where: Px = Momentum component, P0 = `referenceMomentum`, E = Total energy, P = momentum magnitude, E0 = `referenceTotalEnergy`, dE = E - E0, dP = P - P0] - `particleStatus` - Type: Optional *(int)* From 8d473fe8e51986a600edcbbfc686045bd82452ee Mon Sep 17 00:00:00 2001 From: ChristopherMayes <31023527+ChristopherMayes@users.noreply.github.com> Date: Thu, 8 Nov 2018 11:11:14 -0800 Subject: [PATCH 17/73] Update EXT_BeamPhysics.md --- EXT_BeamPhysics.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/EXT_BeamPhysics.md b/EXT_BeamPhysics.md index 079e269..d0b7d19 100644 --- a/EXT_BeamPhysics.md +++ b/EXT_BeamPhysics.md @@ -114,12 +114,12 @@ The following records store data on a particle-by-particle basis. - Type: Optional 3-vector *(float)* - Description: The momentum vector of the particles. - Components: (`px`, `py`, `pz`). - - For each component, the convenction is specified by the attribute: + - For each component, the covention is specified by the attribute: - `convention`: - Type: Required **(string)** - Description: Describes how the component is to be interpreted. - - Possible values: - - `Px`: `px` is the x-component of the momentum. + - Possible values [Where: Px = Momentum component, P0 = `referenceMomentum`, E = Total energy, P = momentum magnitude, E0 = `referenceTotalEnergy`, dE = E - E0, dP = P - P0]: + - `Px`: `px` is the x-component of the momentum: $m c \gamma\beta_x$ - `Px/P0`: `px` is the momentum normalized by the reference momentum. - `Py/P0`: `py` is the momentum normalized by the reference momentum. - `Pz` @@ -132,7 +132,7 @@ The following records store data on a particle-by-particle basis. - `E/P0` - `dE` - `dE/P0` - [Where: Px = Momentum component, P0 = `referenceMomentum`, E = Total energy, P = momentum magnitude, E0 = `referenceTotalEnergy`, dE = E - E0, dP = P - P0] + - `particleStatus` - Type: Optional *(int)* From 1da86d5f66310e018f8321233d75488f02d23751 Mon Sep 17 00:00:00 2001 From: ChristopherMayes <31023527+ChristopherMayes@users.noreply.github.com> Date: Thu, 8 Nov 2018 11:15:19 -0800 Subject: [PATCH 18/73] Update EXT_BeamPhysics.md --- EXT_BeamPhysics.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/EXT_BeamPhysics.md b/EXT_BeamPhysics.md index d0b7d19..78fae66 100644 --- a/EXT_BeamPhysics.md +++ b/EXT_BeamPhysics.md @@ -119,7 +119,7 @@ The following records store data on a particle-by-particle basis. - Type: Required **(string)** - Description: Describes how the component is to be interpreted. - Possible values [Where: Px = Momentum component, P0 = `referenceMomentum`, E = Total energy, P = momentum magnitude, E0 = `referenceTotalEnergy`, dE = E - E0, dP = P - P0]: - - `Px`: `px` is the x-component of the momentum: $m c \gamma\beta_x$ + - `Px`: `px` is the x-component of the momentum: - `Px/P0`: `px` is the momentum normalized by the reference momentum. - `Py/P0`: `py` is the momentum normalized by the reference momentum. - `Pz` @@ -132,6 +132,8 @@ The following records store data on a particle-by-particle basis. - `E/P0` - `dE` - `dE/P0` + - Physical definitions: + - `Px` = $m c \gamma\beta_x$ - `particleStatus` From d1833769a8feccf01f42a4fde5332b1d8b501541 Mon Sep 17 00:00:00 2001 From: ChristopherMayes <31023527+ChristopherMayes@users.noreply.github.com> Date: Thu, 8 Nov 2018 11:17:34 -0800 Subject: [PATCH 19/73] Update EXT_BeamPhysics.md --- EXT_BeamPhysics.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/EXT_BeamPhysics.md b/EXT_BeamPhysics.md index 78fae66..6f53923 100644 --- a/EXT_BeamPhysics.md +++ b/EXT_BeamPhysics.md @@ -133,7 +133,11 @@ The following records store data on a particle-by-particle basis. - `dE` - `dE/P0` - Physical definitions: - - `Px` = $m c \gamma\beta_x$ + - `Px` = m*c*gamma*beta_x + - `Py` = m*c*gamma*beta_y + - `Pz` = m*c*gamma*beta_z + - `P` = m*c*gamma*beta + - `E` = m*c*gamma - `particleStatus` From 2760d9067983e11da2a6e16a29f143cfab5089c5 Mon Sep 17 00:00:00 2001 From: ChristopherMayes <31023527+ChristopherMayes@users.noreply.github.com> Date: Thu, 8 Nov 2018 11:19:56 -0800 Subject: [PATCH 20/73] Update EXT_BeamPhysics.md --- EXT_BeamPhysics.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/EXT_BeamPhysics.md b/EXT_BeamPhysics.md index 6f53923..5f9280f 100644 --- a/EXT_BeamPhysics.md +++ b/EXT_BeamPhysics.md @@ -133,11 +133,11 @@ The following records store data on a particle-by-particle basis. - `dE` - `dE/P0` - Physical definitions: - - `Px` = m*c*gamma*beta_x - - `Py` = m*c*gamma*beta_y - - `Pz` = m*c*gamma*beta_z - - `P` = m*c*gamma*beta - - `E` = m*c*gamma + - `Px = m*c*gamma*beta_x` + - `Py = m*c*gamma*beta_y` + - `Pz = m*c*gamma*beta_z` + - `P = m*c*gamma*beta` Total Momentum + - `E = m*c*gamma` Total Energy - `particleStatus` From 1c665c32fe520a0d81bc881f96a555dad99b6943 Mon Sep 17 00:00:00 2001 From: ChristopherMayes <31023527+ChristopherMayes@users.noreply.github.com> Date: Thu, 8 Nov 2018 11:21:51 -0800 Subject: [PATCH 21/73] Update EXT_BeamPhysics.md --- EXT_BeamPhysics.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/EXT_BeamPhysics.md b/EXT_BeamPhysics.md index 5f9280f..72c912f 100644 --- a/EXT_BeamPhysics.md +++ b/EXT_BeamPhysics.md @@ -137,7 +137,7 @@ The following records store data on a particle-by-particle basis. - `Py = m*c*gamma*beta_y` - `Pz = m*c*gamma*beta_z` - `P = m*c*gamma*beta` Total Momentum - - `E = m*c*gamma` Total Energy + - `E = m*c^2*gamma` Total Energy - `particleStatus` From e565449afe55879ddfbfb9755035cb92b937f59d Mon Sep 17 00:00:00 2001 From: David Sagan Date: Mon, 3 Dec 2018 21:43:44 -0500 Subject: [PATCH 22/73] Merged pxType and pyType into pxyType --- EXT_BeamPhysics.md | 18 ++++++------------ 1 file changed, 6 insertions(+), 12 deletions(-) diff --git a/EXT_BeamPhysics.md b/EXT_BeamPhysics.md index 9cfb93e..0b7e2f5 100644 --- a/EXT_BeamPhysics.md +++ b/EXT_BeamPhysics.md @@ -115,22 +115,16 @@ The following records store data on a particle-by-particle basis. - Description: The momentum vector of the particles. - Components: (`px`, `py`, `pz`). - Attributes: - - `pxType`: + - `pxyType`: - Type: Required **(string)** - - Description: Describes how the `px` component is to be interpreted. - - Possible values: [Where: Px = Momentum component, P0 = `referenceMomentum`] - - `Px`: `px` is the x-component of the momentum. - - `Px/P0`: `px` is the momentum normalized by the reference momentum. - - `pyType`: - - Type: Required **(string)** - - Description: Describes how the `py` component is to be interpreted. - - Possible values: [Where: Py = Momentum component , P0 = `referenceMomentum`] - - `Py`: `py` is the y-component of the momentum. - - `Py/P0`: `py` is the momentum normalized by the reference momentum. + - Description: Describes how the `px` and `py` components are to be interpreted. + - Possible values: [Where: Pxy = x or y momentum component, P0 = `referenceMomentum`] + - `Pxy`: `px` and `py` are the x and y-components of the momentum. + - `Pxy/P0`: `px` and `py` are the x and y-components of the momentum normalized by the reference momentum. - `pzType`: - Type: Required **(string)** - Description: Describes how the `pz` component is to be interpreted. - - Possible values: [Where: E = Total energy, P = momentum magnitude, E0 = `referenceTotalEnergy`, P0 = `referenceMomentum`, Pz = momentum component, dE = E - E0, dP = P - P0] + - Possible values: [Where: E = Total energy, P = momentum magnitude, E0 = `referenceTotalEnergy`, P0 = `referenceMomentum`, Pz = momentum component along the z-axis, dE = E - E0, dP = P - P0] - `Pz` - `Pz/P0` - `P` From 5e2d554907fe148a4534d41c6d48be22eb9cb882 Mon Sep 17 00:00:00 2001 From: ChristopherMayes <31023527+ChristopherMayes@users.noreply.github.com> Date: Wed, 5 Dec 2018 15:25:38 -0800 Subject: [PATCH 23/73] Simplified momentum --- EXT_BeamPhysics.md | 44 +++++++++++++++++++------------------------- 1 file changed, 19 insertions(+), 25 deletions(-) diff --git a/EXT_BeamPhysics.md b/EXT_BeamPhysics.md index 72c912f..3e217d0 100644 --- a/EXT_BeamPhysics.md +++ b/EXT_BeamPhysics.md @@ -114,31 +114,25 @@ The following records store data on a particle-by-particle basis. - Type: Optional 3-vector *(float)* - Description: The momentum vector of the particles. - Components: (`px`, `py`, `pz`). - - For each component, the covention is specified by the attribute: - - `convention`: - - Type: Required **(string)** - - Description: Describes how the component is to be interpreted. - - Possible values [Where: Px = Momentum component, P0 = `referenceMomentum`, E = Total energy, P = momentum magnitude, E0 = `referenceTotalEnergy`, dE = E - E0, dP = P - P0]: - - `Px`: `px` is the x-component of the momentum: - - `Px/P0`: `px` is the momentum normalized by the reference momentum. - - `Py/P0`: `py` is the momentum normalized by the reference momentum. - - `Pz` - - `Pz/P0` - - `P` - - `P/P0` - - `dP` - - `dP/P0` - - `E` - - `E/P0` - - `dE` - - `dE/P0` - - Physical definitions: - - `Px = m*c*gamma*beta_x` - - `Py = m*c*gamma*beta_y` - - `Pz = m*c*gamma*beta_z` - - `P = m*c*gamma*beta` Total Momentum - - `E = m*c^2*gamma` Total Energy - + - Physical definitions: + - `Px = m*c*gamma*beta_x` + - `Py = m*c*gamma*beta_y` + - `Pz = m*c*gamma*beta_z` + +- `momentumOffset/` + - Type: Optional 3-vector *(float)* + - Description: offset for each momentum component. + - Components: (`px`, `py`, `pz`). + +- `totalMomentum/` + - Type: Optional *(float)* + - Description: Total momentum + - Physical definition: `p = sqrt(px^2 + py^2 + pz^2)` + +- `totalEnergy/` + - Type: Optional *(float)* + - Description: Total momentum + - Physical definition: `E = sqrt[(c*px)^2 + (c*py)^2 + (c*pz^2) + (m*c^2)^2]` - `particleStatus` - Type: Optional *(int)* From fc4bc8530ffb802954b1c4d6c373cb105a15a46c Mon Sep 17 00:00:00 2001 From: David Sagan Date: Wed, 5 Dec 2018 21:30:22 -0500 Subject: [PATCH 24/73] Minor styalistic edits. --- EXT_BeamPhysics.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/EXT_BeamPhysics.md b/EXT_BeamPhysics.md index 3e217d0..07c6fe9 100644 --- a/EXT_BeamPhysics.md +++ b/EXT_BeamPhysics.md @@ -41,8 +41,8 @@ Notes: - When using the **lattice** coordinate system, the `position` coordinates are **(x, y, s)** or **(x, y, z)** where, nominally, **x** is the "horizontal" component, **y** is the "vertical" coordinate, and **s** or **z** is the lattice longitudinal coordinate. -Additional File Root Group (path `/`) records ------------------------------------------------- +Additional File Root Group (Path `/`) Records +--------------------------------------------- The following records are defined for the file root group. @@ -56,7 +56,7 @@ The following records are defined for the file root group. `Particle Root Group` records --------------------------------- +----------------------------- For each **particle root group** the following records are defined: @@ -115,23 +115,23 @@ The following records store data on a particle-by-particle basis. - Description: The momentum vector of the particles. - Components: (`px`, `py`, `pz`). - Physical definitions: - - `Px = m*c*gamma*beta_x` + - `Px = m*c*gamma*beta_x` - `Py = m*c*gamma*beta_y` - - `Pz = m*c*gamma*beta_z` - + - `Pz = m*c*gamma*beta_z` + - `momentumOffset/` - Type: Optional 3-vector *(float)* - - Description: offset for each momentum component. + - Description: offset for each momentum component. - Components: (`px`, `py`, `pz`). - `totalMomentum/` - Type: Optional *(float)* - - Description: Total momentum + - Description: Total momentum - Physical definition: `p = sqrt(px^2 + py^2 + pz^2)` - `totalEnergy/` - Type: Optional *(float)* - - Description: Total momentum + - Description: Total momentum - Physical definition: `E = sqrt[(c*px)^2 + (c*py)^2 + (c*pz^2) + (m*c^2)^2]` - `particleStatus` @@ -148,7 +148,7 @@ The following records store data on a particle-by-particle basis. - Components: (`x`, `y`, `z`) - Attributes: - `zType`: - - Type: Required **(string)** + - Type: Required *(string)* - Description: Describes how the `z` component is to be interpreted. - Possible values: [Where: **beta** = particle speed/speed of light, **c** = speed of light, **t** = time, and **dt** = time - reference time.] - `-beta*c*dt`: `z` component is the phase space coordinate conjugate to a momentum based "pz". @@ -168,7 +168,7 @@ The following records store data on a particle-by-particle basis. the origin for the (x, y) transverse plane where the particle is measured with respect to in the **lattice** coordinate system. - Attribute: - `absolute`: - - Type: Required **(bool)** + - Type: Required *(bool)* - Description: `True` = Absolute position from the beginning of the lattice. `False` = Relative position measured from the beginning of the element the particle is in specified by `latticeElementName` and/or `latticeElementID`. - `speed` From 4605aced9c6b353e7cf4b389ff681db8b9fe913e Mon Sep 17 00:00:00 2001 From: David Sagan Date: Wed, 5 Dec 2018 22:27:34 -0500 Subject: [PATCH 25/73] Simplified position record. --- EXT_BeamPhysics.md | 63 +++++++++++++++++++++------------------------- 1 file changed, 29 insertions(+), 34 deletions(-) diff --git a/EXT_BeamPhysics.md b/EXT_BeamPhysics.md index 07c6fe9..88b9794 100644 --- a/EXT_BeamPhysics.md +++ b/EXT_BeamPhysics.md @@ -98,10 +98,9 @@ Per-Particle Records of the `Particle Root Group` The following records store data on a particle-by-particle basis. -- `charge` +- `charge/` - Type: Optional *(int)* - - Description: The charge state of the particles. Not needed if the charge can be computed - from knowledge of the `SpeciesType`. + - Description: The charge state of the particles. Used for atoms and molecules. Not needed if the charge can be computed from knowledge of the `SpeciesType` (That is, a fundamental particle). Also see `weighting`. - `electricField/` - Type: Optional 2-component *(float)* @@ -115,9 +114,9 @@ The following records store data on a particle-by-particle basis. - Description: The momentum vector of the particles. - Components: (`px`, `py`, `pz`). - Physical definitions: - - `Px = m*c*gamma*beta_x` - - `Py = m*c*gamma*beta_y` - - `Pz = m*c*gamma*beta_z` + - `px = m * gamma * V_x` + - `py = m * gamma * V_y` + - `pz = m * gamma * V_z` - `momentumOffset/` - Type: Optional 3-vector *(float)* @@ -129,63 +128,59 @@ The following records store data on a particle-by-particle basis. - Description: Total momentum - Physical definition: `p = sqrt(px^2 + py^2 + pz^2)` +- `totalMomentumOffset/` + - Type: Optional *(float)* + - Description: Offset for the total momentum. + - `totalEnergy/` - Type: Optional *(float)* - Description: Total momentum - Physical definition: `E = sqrt[(c*px)^2 + (c*py)^2 + (c*pz^2) + (m*c^2)^2]` -- `particleStatus` +- `totalEnergyOffset/` + - Type: Optional *(float)* + - Description: Offset for the total momentum. + +- `particleStatus/` - Type: Optional *(int)* - Description: Integer indicating whether a particle is "alive" or "dead" (for example, has hit the vacuum chamber wall). A zero value indicates the particle is alive and any other value indicates that the particle is dead. Programs are free to distinguish how a particle died by assigning different non-zero values to "modes of death". For example, a program might want to differentiate between particles that are dead due to hitting one surface verses hitting a different surface. -- `pathLength` +- `pathLength/` - Type: Optional *(float)* - Description: Length that a particle has traveled. - `position/` - Type: Required 3-vector *(float)* - - Description: Position relative to the coordinate origin. + - Description: Position relative to the curvilinear coordinate origin. + - Components: (`x`, `y`, `z`) + - Attributes: + +- `positionOffset/` + - Type: Optional 3-vector *(float)* + - Description: Offset for each position component. - Components: (`x`, `y`, `z`) - Attributes: - - `zType`: - - Type: Required *(string)* - - Description: Describes how the `z` component is to be interpreted. - - Possible values: [Where: **beta** = particle speed/speed of light, **c** = speed of light, **t** = time, and **dt** = time - reference time.] - - `-beta*c*dt`: `z` component is the phase space coordinate conjugate to a momentum based "pz". - - `-beta*c*t`: `z` component is the phase space coordinate conjugate to a momentum based "pz". - - `-c*dt`: `z` component is the phase space coordinate conjugate to an energy based "pz". - - `-c*t`: `z` component is the phase space coordinate conjugate to an energy based "pz". - - `z`: `z` component is the true longitudinal coordinate. - -- `refTime` + +- `refTime/` - Type: Optional *(float)* - Description: The reference particle time. Note that the reference time is a function of **s** and therefore can be different for different particles. -- `sPosition` - - Type: Optional *(float)* - - Description: Longitudinal distance of the particle in **lattice** coordinates. This record establishes - the origin for the (x, y) transverse plane where the particle is measured with respect to in the **lattice** coordinate system. - - Attribute: - - `absolute`: - - Type: Required *(bool)* - - Description: `True` = Absolute position from the beginning of the lattice. `False` = Relative position measured from the beginning of the element the particle is in specified by `latticeElementName` and/or `latticeElementID`. - -- `speed` +- `speed/` - Type: Optional *(float)* - Description: The speed (velocity magnitude) of a particle. - `spin/` - Type: Optional 3-vector *(float)* - Description: Particle spin. - - Components: (`x`, `y`, `s`) or (`r`, `theta`, `phi`). + - Components: (`x`, `y`, `z`) or (`r`, `theta`, `phi`). -- `time` +- `time/` - Type: Optional *(float)* - Description: Absolute particle time. Note: Particles may have different times if the snapshot is, for example, taken at constant **s**. -- `time-refTime` +- `time-refTime/` - Type: Optional *(float)* - Description: Particle time minus the reference time. @@ -195,7 +190,7 @@ The following records store data on a particle-by-particle basis. - `weighting/` - Type: Optional *(float)* - - Description: If macro-particles are being simulated, the `weighting` is the the total charge or total number of the collection of particles that a macro-particle represents. + - Description: If macro-particles are being simulated, the `weighting` is the the total charge or total number of the collection of particles that a macro-particle represents. Also see `charge`. Non Per-Particle Records of the `Particle Root Group` From ca89d08507e20ce3d6722eeaad615ec587f22fac Mon Sep 17 00:00:00 2001 From: David Sagan Date: Sun, 6 Jan 2019 11:52:18 -0500 Subject: [PATCH 26/73] "time", "refTime", and "time-refTime" are now "time" and "timeOffset". --- EXT_BeamPhysics.md | 34 ++++++++++++---------------------- 1 file changed, 12 insertions(+), 22 deletions(-) diff --git a/EXT_BeamPhysics.md b/EXT_BeamPhysics.md index 88b9794..d063c9b 100644 --- a/EXT_BeamPhysics.md +++ b/EXT_BeamPhysics.md @@ -111,12 +111,9 @@ The following records store data on a particle-by-particle basis. - `momentum/` - Type: Optional 3-vector *(float)* - - Description: The momentum vector of the particles. + - Description: The momentum vector of the particles relative to `momentumOffset` - Components: (`px`, `py`, `pz`). - - Physical definitions: - - `px = m * gamma * V_x` - - `py = m * gamma * V_y` - - `pz = m * gamma * V_z` + - True momentum = `momentum + momentumOffset` - `momentumOffset/` - Type: Optional 3-vector *(float)* @@ -125,8 +122,7 @@ The following records store data on a particle-by-particle basis. - `totalMomentum/` - Type: Optional *(float)* - - Description: Total momentum - - Physical definition: `p = sqrt(px^2 + py^2 + pz^2)` + - Description: Total momentum relative to the totalMomentumOffset. That is, True total momentum = `totalMomentum + totalMomentumOffset`. - `totalMomentumOffset/` - Type: Optional *(float)* @@ -134,8 +130,7 @@ The following records store data on a particle-by-particle basis. - `totalEnergy/` - Type: Optional *(float)* - - Description: Total momentum - - Physical definition: `E = sqrt[(c*px)^2 + (c*py)^2 + (c*pz^2) + (m*c^2)^2]` + - Description: Total energy relative to the totalEnergyOffset. That is, true total energy = `totalEnergy + totalEnergyOffset`. - `totalEnergyOffset/` - Type: Optional *(float)* @@ -151,21 +146,16 @@ The following records store data on a particle-by-particle basis. - `position/` - Type: Required 3-vector *(float)* - - Description: Position relative to the curvilinear coordinate origin. - Components: (`x`, `y`, `z`) - - Attributes: + - Description: particle Position relative to the `positionOffset`. + That is, true position relative to the curvilinear coordinate origin = `position + positionOffset`. - `positionOffset/` - Type: Optional 3-vector *(float)* - - Description: Offset for each position component. + - Description: Offset for each particle position component relative to the curvilinear coordinate origin. - Components: (`x`, `y`, `z`) - Attributes: -- `refTime/` - - Type: Optional *(float)* - - Description: The reference particle time. - Note that the reference time is a function of **s** and therefore can be different for different particles. - - `speed/` - Type: Optional *(float)* - Description: The speed (velocity magnitude) of a particle. @@ -177,12 +167,12 @@ The following records store data on a particle-by-particle basis. - `time/` - Type: Optional *(float)* - - Description: Absolute particle time. Note: Particles may have different times if the snapshot - is, for example, taken at constant **s**. + - Description: Time relative to `timeOffset`. That is, absolute time = `time + timeOffset`. -- `time-refTime/` - - Type: Optional *(float)* - - Description: Particle time minus the reference time. +- `timeOffset` + - Type: Optional *(float)* + - Description: The reference particle time. + Note that the reference time is a function of **s** and therefore can be different for different particles. - `velocity/` - Type: Optional 3-vector *(float)* From fe27e437252aed66b5b45cddbd18a6b70967ae0a Mon Sep 17 00:00:00 2001 From: ChristopherMayes <31023527+ChristopherMayes@users.noreply.github.com> Date: Wed, 27 Feb 2019 10:51:26 -0800 Subject: [PATCH 27/73] Added external fields --- EXT_BeamPhysics.md | 18 +++++++++++++----- 1 file changed, 13 insertions(+), 5 deletions(-) diff --git a/EXT_BeamPhysics.md b/EXT_BeamPhysics.md index d063c9b..ea6e954 100644 --- a/EXT_BeamPhysics.md +++ b/EXT_BeamPhysics.md @@ -103,11 +103,19 @@ The following records store data on a particle-by-particle basis. - Description: The charge state of the particles. Used for atoms and molecules. Not needed if the charge can be computed from knowledge of the `SpeciesType` (That is, a fundamental particle). Also see `weighting`. - `electricField/` - - Type: Optional 2-component *(float)* - - Description: Electric field. Used for photons only. - - Components: (`x`, `y`). - - For each component, the field is specified using either (`amplitude`, `phase`) or (`Real`, `Imaginary`) - subcomponents. + - Type: Optional 3-vector *(float)* + - Description: External electric field at the particle. + - Components: (`x`, `y`, `z`). + +- `magneticField/` + - Type: Optional 3-vector *(float)* + - Description: External magnetic field at the particle. + - Components: (`x`, `y`, `z`). + +- `photonPolarization/` + - Type: Optional 2-vector *(complex)* + - Description: Polarization of the photon + - Components: (`x`, `y`), transverse to the direction of the photon. - `momentum/` - Type: Optional 3-vector *(float)* From 5b6002f4eceea1571eb044b85df8ae356b234813 Mon Sep 17 00:00:00 2001 From: David Sagan Date: Wed, 6 Mar 2019 13:26:05 -0500 Subject: [PATCH 28/73] Changed "weighting" to "weight" as per opemPMD issue #199. --- EXT_BeamPhysics.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/EXT_BeamPhysics.md b/EXT_BeamPhysics.md index ea6e954..671ea2a 100644 --- a/EXT_BeamPhysics.md +++ b/EXT_BeamPhysics.md @@ -100,16 +100,16 @@ The following records store data on a particle-by-particle basis. - `charge/` - Type: Optional *(int)* - - Description: The charge state of the particles. Used for atoms and molecules. Not needed if the charge can be computed from knowledge of the `SpeciesType` (That is, a fundamental particle). Also see `weighting`. + - Description: The charge state of the particles. Used for atoms and molecules. Not needed if the charge can be computed from knowledge of the `SpeciesType` (That is, a fundamental particle). Also see `weight`. - `electricField/` - Type: Optional 3-vector *(float)* - - Description: External electric field at the particle. + - Description: External electric field at the particle. - Components: (`x`, `y`, `z`). - `magneticField/` - Type: Optional 3-vector *(float)* - - Description: External magnetic field at the particle. + - Description: External magnetic field at the particle. - Components: (`x`, `y`, `z`). - `photonPolarization/` @@ -186,9 +186,9 @@ The following records store data on a particle-by-particle basis. - Type: Optional 3-vector *(float)* - Description: (`Vx`, `Vy`, `Vz`) velocity vector. -- `weighting/` +- `weight/` - Type: Optional *(float)* - - Description: If macro-particles are being simulated, the `weighting` is the the total charge or total number of the collection of particles that a macro-particle represents. Also see `charge`. + - Description: If macro-particles are being simulated, the `weight` is the total charge of a macro-particle or the total number of particles that a macro-particle represents. Also see `charge`. Non Per-Particle Records of the `Particle Root Group` From 2523a519ecde49b7ca3809a84adc36d020b36c98 Mon Sep 17 00:00:00 2001 From: David Sagan Date: Thu, 7 Mar 2019 00:41:10 -0500 Subject: [PATCH 29/73] more cleanup. --- EXT_BeamPhysics.md | 113 +++++++++++++++++++++++++-------------------- 1 file changed, 63 insertions(+), 50 deletions(-) diff --git a/EXT_BeamPhysics.md b/EXT_BeamPhysics.md index d063c9b..1d76b2d 100644 --- a/EXT_BeamPhysics.md +++ b/EXT_BeamPhysics.md @@ -24,12 +24,16 @@ Definitions - **Lattice**: A **lattice** is the arrangement of elements in a machine such as a particle accelerator. +- **Lattice branches**: The lattices of some programs can contain multiple connected beam lines or rings. For example, an injection line connected to a storage ring connected to X-ray beam lines. Each line or ring is called a **branch**. In the above example, the injection line is one branch, the storage ring another branch, and each X-ray beam line is a branch. + - **Global coordinate system**: The **global** coordinate system is a coordinate system that is used to describe the position and orientation of machine elements in space. That is, the **global** coordinate system is fixed with respect to the building or room where the machine is placed independent of the machine itself. - **Lattice coordinate system**: The curvilinear coordinate system whose "longitudinal" coordinate (**s**) typically runs through the nominal centers of the elements in the machine. The **lattice** coordinate system is often used to describe particle positions. - **Macro-particle**: Macro-particles are simulation particles that represent multiple real particles. The number of real particles that a macro-particle represents affects the calculation of the field due to a macro-particle but does not affect tracking. +- **Particle coordinate system**: The coordinate system with respect to which particles positions and momenta are given. Some programs use the **global coordinate system** as the **particle coordinate system** while other programs use a coordinate system that is derived from the curvilinear **lattice coordinate system**. + - **Polar coordinates**: **Polar** coordinates are **(r, theta, phi)** where **r** is the radius, **theta** is the angle from the **z** or **s** axis, and **phi** is the projected azimuthal angle in the **(x, y)** plane. - **Particle Root Group**: The **Particle Root Group** is a group for specifying a group of particles. See the Base Standard for more information. @@ -58,56 +62,59 @@ The following records are defined for the file root group. `Particle Root Group` records ----------------------------- -For each **particle root group** the following records are defined: - -- `latticeElementName` - - Type: Optional *(string)* - - Description: The name of the lattice element the particle or particles are in. This only makes sense if all particles are in the same lattice element. Also see: `latticeElementID` and `locationInElement`. - -- `latticeElementID` - - Type Optional *(string)* - - Description: The ID string for the lattice element given by `latticeElementName`. The idea is that while more than one lattice element may have the same name, the ID string will be unique. - - This, along with `locationInElement` sets the origin for specifying particle positions in the **lattice** coordinate system. - - Example: With [Bmad](https://www.classe.cornell.edu/bmad/) based programs the ID string is of the form - **branch-index>>element-index** where **branch-index** is the associated branch index integer, and **element-index** is the associated lattice element index within the branch. +For each **particle root group** the following attributes are defined: -- `locationInElement` - - Type Optional *(integer)* - - Description: The program generating the data file may model a lattice element using a "hard edge" model where the fringe fields at the ends of the element are modeled as having zero longitudinal length. In such a case, if a particle is at the end of the lattice element, it is important to know if the particle is outside of the fringe or if the particle is inside the fringe within the body of the element. Note that with a hard edge fringe, the longitudinal **s**-position does not necessarily provide enough information to determine where a particle is with respect to an edge field. Another situation where `locationInElement` is useful is with zero length elements that affect the particle transport (such as zero length multipole elements). If the program generating the data file does **not** use any hard edge models or zero length non-marker elements, `locationInElement` should not be present since this parameter is meaningless in this case. - - Possible values: - - -1: Upstream end of element outside of the upstream fringe edge. - - 0: Inside the element. - - 1: Downstream end of the element outside the downstream fringe edge. +- `chargeDead` + - Type: Optional *(float)* + - Description: The total charge of all the dead particles. -- `referenceMomentum` +- `chargeLive` - Type: Optional *(float)* - - Description: Reference momentum Possibly used for normalizing particle momentum values. + - Description: The total charge of all the live particles. -- `referenceTotalEnergy` +- `latticeElementName` - Type: Optional *(string)* - - Description: Reference total (kinetic + rest mass) energy. Possibly used for normalizing particle momentum values. + - Description: The name of the lattice element the particle are in. This only makes sense if all particles are in the same element. [Keep in mind that if particles are lost and the lost particles are also included in the file, not all particles may be in the same element.] Also see: `locationInElement`. - `speciesType` - Type: Required *(string)* - Description: The name of the particle species. Species names must conform to the `SpeciesType` extension. - Example: `electron`, `H2O`. +- `totalCharge` + - Type: Optional *(float)* + - Description: The total charge of all the particles. Per-Particle Records of the `Particle Root Group` ------------------------------------------------- The following records store data on a particle-by-particle basis. +- `branchIndex/` + - Type Optional *(int)* + - Description: The unique index number assigned to the lattice branch the particle is in. + - `charge/` - Type: Optional *(int)* - Description: The charge state of the particles. Used for atoms and molecules. Not needed if the charge can be computed from knowledge of the `SpeciesType` (That is, a fundamental particle). Also see `weighting`. - `electricField/` - - Type: Optional 2-component *(float)* - - Description: Electric field. Used for photons only. - - Components: (`x`, `y`). - - For each component, the field is specified using either (`amplitude`, `phase`) or (`Real`, `Imaginary`) - subcomponents. + - Type: Optional 2-component *(float)* + - Description: Electric field. Used for photons only. + - Components: (`x`, `y`). + - For each component, the field is specified using either (`amplitude`, `phase`) or (`Real`, `Imaginary`) subcomponents. + +- `elementIndex/` + - Type Optional *(int)* + - Description: The unique index number assigned to the lattice element the particle is in. + +- `locationInElement` + - Type Optional *(integer)* + - Description: The program generating the data file may model a lattice element using a "hard edge" model where the fringe fields at the ends of the element are modeled as having zero longitudinal length. In such a case, if a particle is at the end of the lattice element, it is important to know if the particle is outside of the fringe or if the particle is inside the fringe within the body of the element. Note that with a hard edge fringe, the longitudinal **s**-position does not necessarily provide enough information to determine where a particle is with respect to an edge field. Another situation where `locationInElement` is useful is with zero length elements that affect the particle transport (such as zero length multipole elements). If the program generating the data file does **not** use any hard edge models or zero length non-marker elements, `locationInElement` should not be present since this parameter is meaningless in this case. + - Possible values: + - -1: Upstream end of element outside of the upstream fringe edge. + - 0: Inside the element. + - 1: Downstream end of the element outside the downstream fringe edge. - `momentum/` - Type: Optional 3-vector *(float)* @@ -120,6 +127,18 @@ The following records store data on a particle-by-particle basis. - Description: offset for each momentum component. - Components: (`px`, `py`, `pz`). +- `referenceMomentum` + - Type: Optional *(float)* + - Description: Reference momentum Possibly used for normalizing particle momentum values. + +- `referenceTotalEnergy` + - Type: Optional *(float)* + - Description: Reference total (kinetic + rest mass) energy. Possibly used for normalizing particle momentum values. + +- `sPosition` + - Type: Optional *(float)* + - Description: The value of the longitudinal position in the curvilinear lattice coordinate system. + - `totalMomentum/` - Type: Optional *(float)* - Description: Total momentum relative to the totalMomentumOffset. That is, True total momentum = `totalMomentum + totalMomentumOffset`. @@ -136,9 +155,22 @@ The following records store data on a particle-by-particle basis. - Type: Optional *(float)* - Description: Offset for the total momentum. +- `particleCoordinatesToGlobalTransformation/` + - Type: Optional group. + - Description: Defines the transformation from the coordinates used to describe a particle to the **global** coordinate system. + - `R_frame`: + - Required 3-vector *(float)* Attribute + - Description: specifying the (x, y, z) position of the coordinate origin that the particles are measured with respect to in the **global** coordinate frame. + - `W_matrix`: + - Required 3 x 3 matrix *(float)* + - Description: Dataset holding the 3x3 transformation matrix from coordinates to **global** + coordinates. + - Position Transformation: Position_global = W_matrix * (position + positionOffset) + R_frame + - Momentum transformation: Momentum_global = W_matrix * (momentum + momentumOffset) + - `particleStatus/` - Type: Optional *(int)* - - Description: Integer indicating whether a particle is "alive" or "dead" (for example, has hit the vacuum chamber wall). A zero value indicates the particle is alive and any other value indicates that the particle is dead. Programs are free to distinguish how a particle died by assigning different non-zero values to "modes of death". For example, a program might want to differentiate between particles that are dead due to hitting one surface verses hitting a different surface. + - Description: Integer indicating whether a particle is "alive" or "dead" (for example, has hit the vacuum chamber wall). A zero value indicates the particle is alive and any other value indicates that the particle is dead. Programs are free to distinguish how a particle died by assigning different non-zero values to "modes of death". For example, a program might want to differentiate between particles that are dead due to hitting the side walls versus reversing the direction longitudinally in an RF cavity. - `pathLength/` - Type: Optional *(float)* @@ -148,11 +180,11 @@ The following records store data on a particle-by-particle basis. - Type: Required 3-vector *(float)* - Components: (`x`, `y`, `z`) - Description: particle Position relative to the `positionOffset`. - That is, true position relative to the curvilinear coordinate origin = `position + positionOffset`. + That is, true position relative to the coordinate origin = `position + positionOffset`. - `positionOffset/` - Type: Optional 3-vector *(float)* - - Description: Offset for each particle position component relative to the curvilinear coordinate origin. + - Description: Offset for each particle position component relative to the coordinate origin. - Components: (`x`, `y`, `z`) - Attributes: @@ -200,25 +232,6 @@ The following possible records of the `Particle Root Group` are for specifying p - Type: Optional 6x6x6-tensor *(float)* - Description: Third order beam moments. -- `latticeToGlobalTransformation/` - - Type: Optional group. - - Description: Defines the transformation from **lattice** coordinates to **global** coordinates for a position - specified by `latticeElementName`/`latticeElementID` and `locationInElement`. - - `R_frame`: - - Required 3-vector *(float)* Attribute - - Description: specifying the (x, y, z) position of the **lattice** coordinate origin with respect - to the **global** coordinates. - - `W_matrix`: - - Required 3 x 3 matrix *(float)* - - Description: Dataset holding the 3x3 transformation matrix from **lattice** coordinates to **global** - coordinates. - - Position Transformation: Position_global = W_matrix * Position_lattice + R_frame - - Momentum transformation: Momentum_global = W_matrix * Momentum_lattice - -- `totalCharge` - - Type: Optional *(float)* attribute. - - Description: The total charge of all the particles. - Particle Record Dataset Attributes ---------------------------------- From 699eefeacd0e8f0583366c73d643317142de07c1 Mon Sep 17 00:00:00 2001 From: David Sagan Date: Fri, 8 Mar 2019 23:50:10 -0500 Subject: [PATCH 30/73] Remove redundant chargeDead. --- EXT_BeamPhysics.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/EXT_BeamPhysics.md b/EXT_BeamPhysics.md index 1309781..5ce6bee 100644 --- a/EXT_BeamPhysics.md +++ b/EXT_BeamPhysics.md @@ -64,10 +64,6 @@ The following records are defined for the file root group. For each **particle root group** the following attributes are defined: -- `chargeDead` - - Type: Optional *(float)* - - Description: The total charge of all the dead particles. - - `chargeLive` - Type: Optional *(float)* - Description: The total charge of all the live particles. From 802a6888301843cd0a397fca39aec35cbd5b8e30 Mon Sep 17 00:00:00 2001 From: David Sagan Date: Sat, 9 Mar 2019 18:13:10 -0500 Subject: [PATCH 31/73] Minor cleanup of particleStatus. --- EXT_BeamPhysics.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/EXT_BeamPhysics.md b/EXT_BeamPhysics.md index 5ce6bee..cc8f074 100644 --- a/EXT_BeamPhysics.md +++ b/EXT_BeamPhysics.md @@ -163,7 +163,7 @@ The following records store data on a particle-by-particle basis. - `particleStatus/` - Type: Optional *(int)* - - Description: Integer indicating whether a particle is "alive" or "dead" (for example, has hit the vacuum chamber wall). A zero value indicates the particle is alive and any other value indicates that the particle is dead. Programs are free to distinguish how a particle died by assigning different non-zero values to "modes of death". For example, a program might want to differentiate between particles that are dead due to hitting the side walls versus reversing the direction longitudinally in an RF cavity. + - Description: Integer indicating whether a particle is "alive" or "dead" (for example, has hit the vacuum chamber wall). A value of one indicates the particle is alive and any other value indicates that the particle is dead. Programs are free to distinguish how a particle died by assigning different non-unit values to `particleStatus`. For example, a program might want to differentiate between particles that are dead due to hitting the side walls versus reversing the direction longitudinally in an RF cavity. - `pathLength/` - Type: Optional *(float)* From 405319a7572180dc251c4cfdc3f163780785f3f1 Mon Sep 17 00:00:00 2001 From: David Sagan Date: Sat, 9 Mar 2019 21:12:25 -0500 Subject: [PATCH 32/73] Reinstated elementIndex and locationInElement which were accedentially deleted. --- EXT_BeamPhysics.md | 20 ++++++++++++++++---- 1 file changed, 16 insertions(+), 4 deletions(-) diff --git a/EXT_BeamPhysics.md b/EXT_BeamPhysics.md index cc8f074..9dfdb45 100644 --- a/EXT_BeamPhysics.md +++ b/EXT_BeamPhysics.md @@ -99,15 +99,22 @@ The following records store data on a particle-by-particle basis. - Description: External electric field at the particle. - Components: (`x`, `y`, `z`). + - `elementIndex/` + - Type Optional *(int)* + - Description: The unique index number assigned to the lattice element the particle is in. + - `magneticField/` - Type: Optional 3-vector *(float)* - Description: External magnetic field at the particle. - Components: (`x`, `y`, `z`). -- `photonPolarization/` - - Type: Optional 2-vector *(complex)* - - Description: Polarization of the photon - - Components: (`x`, `y`), transverse to the direction of the photon. +- `locationInElement` + - Type Optional *(integer)* + - Description: The program generating the data file may model a lattice element using a "hard edge" model where the fringe fields at the ends of the element are modeled as having zero longitudinal length. In such a case, if a particle is at the end of the lattice element, it is important to know if the particle is outside of the fringe or if the particle is inside the fringe within the body of the element. Note that with a hard edge fringe, the longitudinal **s**-position does not necessarily provide enough information to determine where a particle is with respect to an edge field. Another situation where `locationInElement` is useful is with zero length elements that affect the particle transport (such as zero length multipole elements). If the program generating the data file does **not** use any hard edge models or zero length non-marker elements, `locationInElement` should not be present since this parameter is meaningless in this case. + - Possible values: + - -1: Upstream end of element outside of the upstream fringe edge. + - 0: Inside the element. + - 1: Downstream end of the element outside the downstream fringe edge. - `momentum/` - Type: Optional 3-vector *(float)* @@ -120,6 +127,11 @@ The following records store data on a particle-by-particle basis. - Description: offset for each momentum component. - Components: (`px`, `py`, `pz`). +- `photonPolarization/` + - Type: Optional 2-vector *(complex)* + - Description: Polarization of the photon + - Components: (`x`, `y`), transverse to the direction of the photon. + - `referenceMomentum` - Type: Optional *(float)* - Description: Reference momentum Possibly used for normalizing particle momentum values. From fe0a4cf1f32dfee3ad993ee80a7a1d2333de0127 Mon Sep 17 00:00:00 2001 From: David Sagan Date: Wed, 20 Mar 2019 14:59:12 -0400 Subject: [PATCH 33/73] Added numParticles attribute. --- EXT_BeamPhysics.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/EXT_BeamPhysics.md b/EXT_BeamPhysics.md index 9dfdb45..74ad525 100644 --- a/EXT_BeamPhysics.md +++ b/EXT_BeamPhysics.md @@ -72,6 +72,10 @@ For each **particle root group** the following attributes are defined: - Type: Optional *(string)* - Description: The name of the lattice element the particle are in. This only makes sense if all particles are in the same element. [Keep in mind that if particles are lost and the lost particles are also included in the file, not all particles may be in the same element.] Also see: `locationInElement`. +- `numParticles` + - Type: Required *(int)* + - Description: The number of particles in the group. + - `speciesType` - Type: Required *(string)* - Description: The name of the particle species. Species names must conform to the `SpeciesType` extension. From 76cd7418f420782964caa9d5b96020099a3b7b8f Mon Sep 17 00:00:00 2001 From: David Sagan Date: Wed, 20 Mar 2019 22:00:43 -0400 Subject: [PATCH 34/73] Now the components of momentum and velocity are x,y,z the same as other vectors. --- EXT_BeamPhysics.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/EXT_BeamPhysics.md b/EXT_BeamPhysics.md index 74ad525..e1aa217 100644 --- a/EXT_BeamPhysics.md +++ b/EXT_BeamPhysics.md @@ -38,8 +38,6 @@ Definitions - **Particle Root Group**: The **Particle Root Group** is a group for specifying a group of particles. See the Base Standard for more information. -- **Phase Space Coordinates**: Phase space coordinates are ordered (x, px, y, py, z, pz). - Notes: ------ @@ -123,13 +121,13 @@ The following records store data on a particle-by-particle basis. - `momentum/` - Type: Optional 3-vector *(float)* - Description: The momentum vector of the particles relative to `momentumOffset` - - Components: (`px`, `py`, `pz`). + - Components: (`x`, `y`, `z`). - True momentum = `momentum + momentumOffset` - `momentumOffset/` - Type: Optional 3-vector *(float)* - Description: offset for each momentum component. - - Components: (`px`, `py`, `pz`). + - Components: (`x`, `y`, `z`). - `photonPolarization/` - Type: Optional 2-vector *(complex)* @@ -217,7 +215,7 @@ The following records store data on a particle-by-particle basis. - `velocity/` - Type: Optional 3-vector *(float)* - - Description: (`Vx`, `Vy`, `Vz`) velocity vector. + - Description: (`x`, `y`, `z`) velocity vector. - `weight/` - Type: Optional *(float)* From b392cc6bcf488fea2c64f99d8977ce6471302abe Mon Sep 17 00:00:00 2001 From: David Sagan Date: Wed, 20 Mar 2019 22:50:07 -0400 Subject: [PATCH 35/73] Added chargeUnitSI attribute. --- EXT_BeamPhysics.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/EXT_BeamPhysics.md b/EXT_BeamPhysics.md index e1aa217..5c9594f 100644 --- a/EXT_BeamPhysics.md +++ b/EXT_BeamPhysics.md @@ -66,6 +66,10 @@ For each **particle root group** the following attributes are defined: - Type: Optional *(float)* - Description: The total charge of all the live particles. +- `chargeUnitSI` + - Type: *(float)*. Only required if `chargeLive` or `totalCharge` is present. + - Description: Unit conversion factor to multiply `chargeLive` or `totalCharge` by in order to convert to SI units. + - `latticeElementName` - Type: Optional *(string)* - Description: The name of the lattice element the particle are in. This only makes sense if all particles are in the same element. [Keep in mind that if particles are lost and the lost particles are also included in the file, not all particles may be in the same element.] Also see: `locationInElement`. @@ -81,7 +85,7 @@ For each **particle root group** the following attributes are defined: - `totalCharge` - Type: Optional *(float)* - - Description: The total charge of all the particles. + - Description: The total charge of all the particles alive and dead. Per-Particle Records of the `Particle Root Group` ------------------------------------------------- @@ -94,7 +98,7 @@ The following records store data on a particle-by-particle basis. - `charge/` - Type: Optional *(int)* - - Description: The charge state of the particles. Used for atoms and molecules. Not needed if the charge can be computed from knowledge of the `SpeciesType` (That is, a fundamental particle). Also see `weight`. + - Description: The charge state of the particles. Used for atoms and molecules. Not needed if the charge can be computed from knowledge of the `SpeciesType` (That is, is a fundamental particle). Also see `weight`. - `electricField/` - Type: Optional 3-vector *(float)* @@ -219,7 +223,7 @@ The following records store data on a particle-by-particle basis. - `weight/` - Type: Optional *(float)* - - Description: If macro-particles are being simulated, the `weight` is the total charge of a macro-particle or the total number of particles that a macro-particle represents. Also see `charge`. + - Description: If macro-particles are being simulated, the `weight` is the total charge of a macro-particle. This is proportional to the number of particles that a macro-particle represents. Also see `charge`. Non Per-Particle Records of the `Particle Root Group` From 0174f0ef01161d8d35ce6cbd1a2341084d121e9d Mon Sep 17 00:00:00 2001 From: David Sagan Date: Wed, 20 Mar 2019 23:25:28 -0400 Subject: [PATCH 36/73] Minor spelling fix. --- EXT_BeamPhysics.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/EXT_BeamPhysics.md b/EXT_BeamPhysics.md index 5c9594f..331cfe6 100644 --- a/EXT_BeamPhysics.md +++ b/EXT_BeamPhysics.md @@ -57,7 +57,7 @@ The following records are defined for the file root group. - Description: The location of the root lattice file. -`Particle Root Group` records +`Particle Root Group` Records ----------------------------- For each **particle root group** the following attributes are defined: From dc427a02453a10df3d3a7474a2b3c64e36ca74af Mon Sep 17 00:00:00 2001 From: David Sagan Date: Fri, 22 Mar 2019 20:26:35 -0400 Subject: [PATCH 37/73] Change "charge" to "chargeState" as more accurate. --- EXT_BeamPhysics.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/EXT_BeamPhysics.md b/EXT_BeamPhysics.md index 331cfe6..76bcf87 100644 --- a/EXT_BeamPhysics.md +++ b/EXT_BeamPhysics.md @@ -96,7 +96,7 @@ The following records store data on a particle-by-particle basis. - Type Optional *(int)* - Description: The unique index number assigned to the lattice branch the particle is in. -- `charge/` +- `chargeState/` - Type: Optional *(int)* - Description: The charge state of the particles. Used for atoms and molecules. Not needed if the charge can be computed from knowledge of the `SpeciesType` (That is, is a fundamental particle). Also see `weight`. From 55d44838e0878a7b9efdf7ca529a8d443f63f87a Mon Sep 17 00:00:00 2001 From: David Sagan Date: Sat, 23 Mar 2019 13:47:12 -0400 Subject: [PATCH 38/73] Corrected some typos and added the fileType attribute. --- EXT_BeamPhysics.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/EXT_BeamPhysics.md b/EXT_BeamPhysics.md index 76bcf87..9e85092 100644 --- a/EXT_BeamPhysics.md +++ b/EXT_BeamPhysics.md @@ -43,11 +43,15 @@ Notes: - When using the **lattice** coordinate system, the `position` coordinates are **(x, y, s)** or **(x, y, z)** where, nominally, **x** is the "horizontal" component, **y** is the "vertical" coordinate, and **s** or **z** is the lattice longitudinal coordinate. -Additional File Root Group (Path `/`) Records ---------------------------------------------- +Additional File Root Group (Path `/`) Attributes +------------------------------------------------ The following records are defined for the file root group. +- `fileType` + - Type: Optional *(string)* + - Description: The type of data being stored in the file. If present, must be set to `openPMD`. This attribute is used in systems where different data files can contain different types of data and allows for quick identification of the what type of data is in a given file. + - `latticeName` - Type: Optional *(string)* - Description: The name of the lattice. @@ -57,8 +61,8 @@ The following records are defined for the file root group. - Description: The location of the root lattice file. -`Particle Root Group` Records ------------------------------ +`Particle Root Group` Attributes +-------------------------------- For each **particle root group** the following attributes are defined: From 7e15db180a4ee526f9ee33123be94da87f4f5f14 Mon Sep 17 00:00:00 2001 From: David Sagan Date: Sun, 24 Mar 2019 01:20:34 -0400 Subject: [PATCH 39/73] Removed reference energy and momentum records as well as total energy. --- EXT_BeamPhysics.md | 87 ++++++++++++++++++---------------------------- 1 file changed, 33 insertions(+), 54 deletions(-) diff --git a/EXT_BeamPhysics.md b/EXT_BeamPhysics.md index 9e85092..1d6fe3c 100644 --- a/EXT_BeamPhysics.md +++ b/EXT_BeamPhysics.md @@ -67,11 +67,11 @@ The following records are defined for the file root group. For each **particle root group** the following attributes are defined: - `chargeLive` - - Type: Optional *(float)* + - Type: Optional *(real)* - Description: The total charge of all the live particles. - `chargeUnitSI` - - Type: *(float)*. Only required if `chargeLive` or `totalCharge` is present. + - Type: *(real)*. Only required if `chargeLive` or `totalCharge` is present. - Description: Unit conversion factor to multiply `chargeLive` or `totalCharge` by in order to convert to SI units. - `latticeElementName` @@ -88,7 +88,7 @@ For each **particle root group** the following attributes are defined: - Example: `electron`, `H2O`. - `totalCharge` - - Type: Optional *(float)* + - Type: Optional *(real)* - Description: The total charge of all the particles alive and dead. Per-Particle Records of the `Particle Root Group` @@ -105,7 +105,7 @@ The following records store data on a particle-by-particle basis. - Description: The charge state of the particles. Used for atoms and molecules. Not needed if the charge can be computed from knowledge of the `SpeciesType` (That is, is a fundamental particle). Also see `weight`. - `electricField/` - - Type: Optional 3-vector *(float)* + - Type: Optional 3-vector *(real)* - Description: External electric field at the particle. - Components: (`x`, `y`, `z`). @@ -114,7 +114,7 @@ The following records store data on a particle-by-particle basis. - Description: The unique index number assigned to the lattice element the particle is in. - `magneticField/` - - Type: Optional 3-vector *(float)* + - Type: Optional 3-vector *(real)* - Description: External magnetic field at the particle. - Components: (`x`, `y`, `z`). @@ -127,14 +127,14 @@ The following records store data on a particle-by-particle basis. - 1: Downstream end of the element outside the downstream fringe edge. - `momentum/` - - Type: Optional 3-vector *(float)* + - Type: Optional 3-vector *(real)* - Description: The momentum vector of the particles relative to `momentumOffset` - Components: (`x`, `y`, `z`). - True momentum = `momentum + momentumOffset` - `momentumOffset/` - - Type: Optional 3-vector *(float)* - - Description: offset for each momentum component. + - Type: Optional 3-vector *(real)* + - Description: Base momentum from which `momentum` is measured. That is, True momentum = `momentum + momentumOffset`. Assumed zero if not present. - Components: (`x`, `y`, `z`). - `photonPolarization/` @@ -142,42 +142,26 @@ The following records store data on a particle-by-particle basis. - Description: Polarization of the photon - Components: (`x`, `y`), transverse to the direction of the photon. -- `referenceMomentum` - - Type: Optional *(float)* - - Description: Reference momentum Possibly used for normalizing particle momentum values. - -- `referenceTotalEnergy` - - Type: Optional *(float)* - - Description: Reference total (kinetic + rest mass) energy. Possibly used for normalizing particle momentum values. - - `sPosition` - - Type: Optional *(float)* + - Type: Optional *(real)* - Description: The value of the longitudinal position in the curvilinear lattice coordinate system. - `totalMomentum/` - - Type: Optional *(float)* - - Description: Total momentum relative to the totalMomentumOffset. That is, True total momentum = `totalMomentum + totalMomentumOffset`. + - Type: Optional *(real)* + - Description: Total momentum relative to the totalMomentumOffset. That is, True total momentum = `totalMomentum + totalMomentumOffset`. Assumed zero if not present. - `totalMomentumOffset/` - - Type: Optional *(float)* - - Description: Offset for the total momentum. - -- `totalEnergy/` - - Type: Optional *(float)* - - Description: Total energy relative to the totalEnergyOffset. That is, true total energy = `totalEnergy + totalEnergyOffset`. - -- `totalEnergyOffset/` - - Type: Optional *(float)* - - Description: Offset for the total momentum. + - Type: Optional *(real)* + - Description: Base total momentum from which `totalMomentum` is measured. That is, True total momentum = `totalMomentum + totalMomentumOffset`. Some programs will use `totalMomentumOffset/` to store the **reference momentum** in which case `totalMomentum` will then be the deviation from the referece. - `particleCoordinatesToGlobalTransformation/` - Type: Optional group. - Description: Defines the transformation from the coordinates used to describe a particle to the **global** coordinate system. - `R_frame`: - - Required 3-vector *(float)* Attribute + - Required 3-vector *(real)* Attribute - Description: specifying the (x, y, z) position of the coordinate origin that the particles are measured with respect to in the **global** coordinate frame. - `W_matrix`: - - Required 3 x 3 matrix *(float)* + - Required 3 x 3 matrix *(real)* - Description: Dataset holding the 3x3 transformation matrix from coordinates to **global** coordinates. - Position Transformation: Position_global = W_matrix * (position + positionOffset) + R_frame @@ -188,45 +172,44 @@ The following records store data on a particle-by-particle basis. - Description: Integer indicating whether a particle is "alive" or "dead" (for example, has hit the vacuum chamber wall). A value of one indicates the particle is alive and any other value indicates that the particle is dead. Programs are free to distinguish how a particle died by assigning different non-unit values to `particleStatus`. For example, a program might want to differentiate between particles that are dead due to hitting the side walls versus reversing the direction longitudinally in an RF cavity. - `pathLength/` - - Type: Optional *(float)* + - Type: Optional *(real)* - Description: Length that a particle has traveled. - `position/` - - Type: Required 3-vector *(float)* + - Type: Required 3-vector *(real)* - Components: (`x`, `y`, `z`) - Description: particle Position relative to the `positionOffset`. That is, true position relative to the coordinate origin = `position + positionOffset`. - `positionOffset/` - - Type: Optional 3-vector *(float)* - - Description: Offset for each particle position component relative to the coordinate origin. + - Type: Optional 3-vector *(real)* + - Description: Offset for each particle position component relative to the coordinate origin. Assumed zero if not present. - Components: (`x`, `y`, `z`) - Attributes: - `speed/` - - Type: Optional *(float)* + - Type: Optional *(real)* - Description: The speed (velocity magnitude) of a particle. - `spin/` - - Type: Optional 3-vector *(float)* + - Type: Optional 3-vector *(real)* - Description: Particle spin. - Components: (`x`, `y`, `z`) or (`r`, `theta`, `phi`). - `time/` - - Type: Optional *(float)* + - Type: Optional *(real)* - Description: Time relative to `timeOffset`. That is, absolute time = `time + timeOffset`. -- `timeOffset` - - Type: Optional *(float)* - - Description: The reference particle time. - Note that the reference time is a function of **s** and therefore can be different for different particles. +- `timeOffset/` + - Type: Optional *(real)* + - Description: Base time from which `time` is measured. That is, absolute time = `time + timeOffset`. Assumed zero if not present. Some programs will use the `timeOffset` to store the **reference time** in which case `time` will then be the deviation from the reference. - `velocity/` - - Type: Optional 3-vector *(float)* + - Type: Optional 3-vector *(real)* - Description: (`x`, `y`, `z`) velocity vector. - `weight/` - - Type: Optional *(float)* + - Type: Optional *(real)* - Description: If macro-particles are being simulated, the `weight` is the total charge of a macro-particle. This is proportional to the number of particles that a macro-particle represents. Also see `charge`. @@ -236,16 +219,12 @@ Non Per-Particle Records of the `Particle Root Group` The following possible records of the `Particle Root Group` are for specifying properties of the entire group of particles. - `phaseSpaceFirstOrderMoment/` - - Type: Optional 6-vector *(float)* - - Description: First order beam moments. + - Type: Optional 6-vector *(real)* + - Description: First order beam moments of `(x, px, y, py, z, pz)`. - `phaseSpaceSecondOrderMoment/` - - Type: Optional 6x6-matrix *(float)* - - Description: Second order beam moments. - -- `phaseSpaceThirdOrderMoment/` - - Type: Optional 6x6x6-tensor *(float)* - - Description: Third order beam moments. + - Type: Optional 6x6-matrix *(real)* + - Description: Second order beam moments of `(x, px, y, py, z, pz)`. Particle Record Dataset Attributes ---------------------------------- @@ -253,9 +232,9 @@ Particle Record Dataset Attributes The following attributes can be used with any dataset: - `minValue`: - - Type: Optional *(float)* + - Type: Optional *(real)* - Description: Minimum of the data. - `maxValue`: - - Type: Optional *(float)* + - Type: Optional *(real)* - Description: Maximum of the data. From 4d0b760282e5a2b6c7f084db94bbab6fd0934207 Mon Sep 17 00:00:00 2001 From: David Sagan Date: Sun, 24 Mar 2019 10:58:44 -0400 Subject: [PATCH 40/73] Minor doc update. --- EXT_BeamPhysics.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/EXT_BeamPhysics.md b/EXT_BeamPhysics.md index 1d6fe3c..336e9d2 100644 --- a/EXT_BeamPhysics.md +++ b/EXT_BeamPhysics.md @@ -206,7 +206,7 @@ The following records store data on a particle-by-particle basis. - `velocity/` - Type: Optional 3-vector *(real)* - - Description: (`x`, `y`, `z`) velocity vector. + - Description: (`x`, `y`, `z`) velocity vector. Meant to be used for photons where using `momentum` is not appropriate. - `weight/` - Type: Optional *(real)* From 51ffc8a821614212dc55783349cd707773abdeef Mon Sep 17 00:00:00 2001 From: David Sagan Date: Thu, 23 May 2019 19:03:19 -0400 Subject: [PATCH 41/73] First pass at adding external mesh fields group. --- EXT_BeamPhysics.md | 45 ++++++++++++++++++++++++++++++++++++--------- 1 file changed, 36 insertions(+), 9 deletions(-) diff --git a/EXT_BeamPhysics.md b/EXT_BeamPhysics.md index 336e9d2..cd041ed 100644 --- a/EXT_BeamPhysics.md +++ b/EXT_BeamPhysics.md @@ -1,5 +1,5 @@ -Extension to the openPMD Standard for Describing Particle Beams and X-rays -========================================================================== +BeamPhysics Extension to the openPMD Standard for Describing Particle Beams, Photons, and External Fields +========================================================================================================= Version 2.0.0 @@ -36,7 +36,7 @@ Definitions - **Polar coordinates**: **Polar** coordinates are **(r, theta, phi)** where **r** is the radius, **theta** is the angle from the **z** or **s** axis, and **phi** is the projected azimuthal angle in the **(x, y)** plane. -- **Particle Root Group**: The **Particle Root Group** is a group for specifying a group of particles. See the Base Standard for more information. +- **Particle Group**: The **Particle Group** is a group for specifying a set of particles such as the particles in a bunch. The Beam Physics extension defines a standard for the **Particle Group** as discussed below. Notes: ------ @@ -60,18 +60,23 @@ The following records are defined for the file root group. - Type: Optional *(string)* - Description: The location of the root lattice file. +Particle Group Standard +============================ -`Particle Root Group` Attributes +The **Particle Group** is a group for specifying a set of particles such as the particles in a bunch. Multiple **Particle Groups** can be defined in a file. The path for a **Particle Group** is given by the **basePath** and **particlesPath** attributes in the file root group as discussed in the base OpenPMD standard. For example, if **basePath** is "/data/%T/", and **ParticlesPath** is "particles/", then **Particle Groups** paths would be of the form "/data/%T/particles/" where "%T" is an integer. EG: "/data/37/particles/". + + +`Particle Group` Attributes -------------------------------- -For each **particle root group** the following attributes are defined: +For each **particle group** the following attributes are defined: - `chargeLive` - Type: Optional *(real)* - Description: The total charge of all the live particles. - `chargeUnitSI` - - Type: *(real)*. Only required if `chargeLive` or `totalCharge` is present. + - Type: *(real)*. Only required if `chargeLive` or `totalCharge` is present. - Description: Unit conversion factor to multiply `chargeLive` or `totalCharge` by in order to convert to SI units. - `latticeElementName` @@ -91,7 +96,7 @@ For each **particle root group** the following attributes are defined: - Type: Optional *(real)* - Description: The total charge of all the particles alive and dead. -Per-Particle Records of the `Particle Root Group` +Per-Particle Records of the `Particle Group` ------------------------------------------------- The following records store data on a particle-by-particle basis. @@ -213,10 +218,10 @@ The following records store data on a particle-by-particle basis. - Description: If macro-particles are being simulated, the `weight` is the total charge of a macro-particle. This is proportional to the number of particles that a macro-particle represents. Also see `charge`. -Non Per-Particle Records of the `Particle Root Group` +Non Per-Particle Records of the `Particle Group` ----------------------------------------------------- -The following possible records of the `Particle Root Group` are for specifying properties of the entire group of particles. +The following possible records of the `Particle Group` are for specifying properties of the entire group of particles. - `phaseSpaceFirstOrderMoment/` - Type: Optional 6-vector *(real)* @@ -238,3 +243,25 @@ The following attributes can be used with any dataset: - `maxValue`: - Type: Optional *(real)* - Description: Maximum of the data. + +External Mesh Fields Groups +=========================== + +The **external mesh field group** is a group for specifying electric and/or magnetic fields, due to a lattice element, at regularly spaced grid points. For example, the fields due to an RF cavity or the fields due to a magnet. Multiple **external mesh field groups** can be defined in a file. The path for a **external mesh field group** is given by the **basePath** and **meshesPath** attributes in the file root group as discussed in the base OpenPMD standard. For example, if **basePath** is "/data/%T/", and **meshesPath** is "ExternalField/", then **External mesh field group** paths would be of the form "/data/%T/ExternalField/" where "%T" is an integer. EG: "/data/37/ExternalField/". + +AC fields can be described using complex numbers. The actual field is the real part of `Z * Exp[-i omega (t - t0)]` where `Z` is the field complex number, `omega` is the field frequency, `t` is the time, and `t0` is a reference time. + +`External Fields Group` Attributes +---------------------------------- + +- `branchIndex/` + - Type Optional *(int)* + - Description: The unique index number assigned to the lattice branch the lattice element associated with the fields. + +- `elementIndex/` + - Type Optional *(int)* + - Description: The unique index number assigned to the lattice element associated with the fields. + +- `latticeElementName` + - Type: Optional *(string)* + - Description: The name of the lattice element associated with the fields. From 7e6bc0c6c8016135287d897e2d95b1022a29c40e Mon Sep 17 00:00:00 2001 From: David Sagan Date: Wed, 10 Jul 2019 00:09:29 -0400 Subject: [PATCH 42/73] more... --- EXT_BeamPhysics.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/EXT_BeamPhysics.md b/EXT_BeamPhysics.md index cd041ed..1a91301 100644 --- a/EXT_BeamPhysics.md +++ b/EXT_BeamPhysics.md @@ -247,7 +247,7 @@ The following attributes can be used with any dataset: External Mesh Fields Groups =========================== -The **external mesh field group** is a group for specifying electric and/or magnetic fields, due to a lattice element, at regularly spaced grid points. For example, the fields due to an RF cavity or the fields due to a magnet. Multiple **external mesh field groups** can be defined in a file. The path for a **external mesh field group** is given by the **basePath** and **meshesPath** attributes in the file root group as discussed in the base OpenPMD standard. For example, if **basePath** is "/data/%T/", and **meshesPath** is "ExternalField/", then **External mesh field group** paths would be of the form "/data/%T/ExternalField/" where "%T" is an integer. EG: "/data/37/ExternalField/". +The **external mesh field group** is a group for specifying electric and/or magnetic fields, due to a lattice element, at regularly spaced grid points. For example, the fields due to an RF cavity or the fields due to a magnet. Multiple **external mesh field groups** can be defined in a file. The path for a **external mesh field group** is given by the **basePath** and **meshesPath** attributes in the file root group as discussed in the base OpenPMD standard. For example, if **basePath** is "/data/%T/", and **meshesPath** is "ExternalFieldMesh/", then **External mesh field group** paths would be of the form "/data/%T/ExternalFieldMesh/" where "%T" is an integer. EG: "/data/37/ExternalFieldMesh/". AC fields can be described using complex numbers. The actual field is the real part of `Z * Exp[-i omega (t - t0)]` where `Z` is the field complex number, `omega` is the field frequency, `t` is the time, and `t0` is a reference time. From 9e5b616de6b1755c32dc1812bc4cb388e9ffcdc5 Mon Sep 17 00:00:00 2001 From: David Sagan Date: Sun, 14 Jul 2019 19:54:04 -0400 Subject: [PATCH 43/73] First pass at external fields definition. --- EXT_BeamPhysics.md | 85 ++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 74 insertions(+), 11 deletions(-) diff --git a/EXT_BeamPhysics.md b/EXT_BeamPhysics.md index 1a91301..feb764d 100644 --- a/EXT_BeamPhysics.md +++ b/EXT_BeamPhysics.md @@ -247,21 +247,84 @@ The following attributes can be used with any dataset: External Mesh Fields Groups =========================== -The **external mesh field group** is a group for specifying electric and/or magnetic fields, due to a lattice element, at regularly spaced grid points. For example, the fields due to an RF cavity or the fields due to a magnet. Multiple **external mesh field groups** can be defined in a file. The path for a **external mesh field group** is given by the **basePath** and **meshesPath** attributes in the file root group as discussed in the base OpenPMD standard. For example, if **basePath** is "/data/%T/", and **meshesPath** is "ExternalFieldMesh/", then **External mesh field group** paths would be of the form "/data/%T/ExternalFieldMesh/" where "%T" is an integer. EG: "/data/37/ExternalFieldMesh/". +The **external mesh field group** is a group for specifying electric and/or magnetic fields, due to a lattice element, at regularly spaced grid points. For example, the fields due to an RF cavity or the fields due to a magnet. Multiple **external mesh field groups** can be defined in a file. The path for a **external mesh field group** is given by the **externalFieldPath** in the file root group: +- `externalFieldPath` + - Type: Required if there are external mesh field group(s) *(string)* + - Description: Base path to the external mesh field groups. Use the **%T** construct if there are multiple meshes present. + - Example: `/ExternalFieldMesh/%T/`. Base paths to the external fields group, in this case, would be `/ExternalFieldMesh/1/`, etc. + - Example: `/ExternalFieldMesh/`. In this case there is only one external fields group. + +Notes +----- + +- AC fields can be described using complex numbers. The actual field is the real part of `Z * Exp[-i omega (t - t0)]` where `Z` is the field complex number, `omega` is the field frequency, `t` is the time, and `t0` is a reference time. -AC fields can be described using complex numbers. The actual field is the real part of `Z * Exp[-i omega (t - t0)]` where `Z` is the field complex number, `omega` is the field frequency, `t` is the time, and `t0` is a reference time. `External Fields Group` Attributes ---------------------------------- -- `branchIndex/` - - Type Optional *(int)* - - Description: The unique index number assigned to the lattice branch the lattice element associated with the fields. - -- `elementIndex/` - - Type Optional *(int)* - - Description: The unique index number assigned to the lattice element associated with the fields. +- `gridCurvatureRadius` + - Type: Optional *(real)* + - Description: Only used if `gridGeometry` is set to `xyz`. A zero value indicates that the grid is rectilinear. A non-zero value indicates that the grid is curved. The curvature is in the **(x, z)** plane with positive **x** pointing away from the center of curvature if `gridCurvatureRadius` is positive and vice versa for negative values. `gridCurvatureRadius` is the radius for the lines **x = 0** at constant **y**. -- `latticeElementName` +- `eleAnchorPt` - Type: Optional *(string)* - - Description: The name of the lattice element associated with the fields. + - Description: Point on the lattice element that the grid origin is referenced to. Possible values are: `beginning`, `center`, or `end`. The `beginning` point is at + the entrance end of the element, the `center` point is at the center of the element and the `end` point is at the exit end of the element. All three points are on the reference orbit. + +- `fieldScale` + - Type: Optional *(real)* + - Description: A scale factor that is used to scale the fields. If not present then a value of 1 is assumed. + + +- `fundamentalFrequency` + - Type: Optional *(real)* + - Description: The fundamental RF frequency. Used for AC fields. + +- `gridGeometry` + - Type: Required *(string)* + - Description: Values are `xyz` or `rotationally_symmetric_rz`. The `xyz` value is for a 3D **(x, y, z)** grid with field components **(Bx, By, Bz)** and/or **(Ex, Ey, Ez)**. The `rotationally_symmetric_rz` value is for a 2D **(r, z)** grid with field components **(Br, Bphi, Bz)** and/or **(Er, Ephi, Ez)** field components. + + +- `gridSpacing` + - Type: Required 2-vector or 3-vector *(real)* + - Description: Spacing between grid points. This is a 2-vector if `gridGeometry` is set to `rotationally_symmetric_rz` and is a 3-vector if `gridGeometry` is set to `xyz`. + + +- `harmonic` + - Type: Required *(int)* + - Description: Harmonic number of the fundamental frequency. A value of zero implies a DC field. + +- `gridLowerBound` + - Type: Required 2-vector or 3-vector *(int)* + - Description: Lower bound of the grid index. This is a 2-vector if `gridGeometry` is set to `rotationally_symmetric_rz` and is a 3-vector if `gridGeometry` is set to `xyz`. Note: The grid upper bound will be `gridLowerBound` + `gridSize` - 1. + +- `gridSize` + - Type: Required 2-vector or 3-vector *(int)* + - Description: Size of the grid. This is a 2-vector if `gridGeometry` is set to `rotationally_symmetric_rz` and is a 3-vector if `gridGeometry` is set to `xyz`. + +- `gridOriginOffset` + - Type: Required 2-vector or 3-vector *(real)* + - Description: distance from `eleAnchorPt` to the grid origin point. This is a 2-vector if `gridGeometry` is set to `rotationally_symmetric_rz` and is a 3-vector if `gridGeometry` is set to `xyz`. + +`External Fields Group` Records +------------------------------- + +- `Bx`, `By`, `Bz` + - Type: Optional (Either all must be present or all must be absent) *(complex)* + - Description: Magnetic field components. Used with `gridGeometry` set to `xyz`. If the field is DC, only the real component should be nonzero. + + +- `Br`, `Bphi`, `Bz` + - Type: Optional (Either all must be present or all must be absent) *(complex)* + - Description: Magnetic field components. Used with `gridGeometry` set to `rotationally_symmetric_rz`. If the field is DC, only the real component should be nonzero. + + +- `Ex`, `Ey`, `Ez` + - Type: Optional (Either all must be present or all must be absent) *(complex)* + - Description: Electric field components. Used with `gridGeometry` set to `xyz`.If the field is DC, only the real component should be nonzero. + + +- `Er`, `Ephi`, `Ez` + - Type: Optional (Either all must be present or all must be absent) *(complex)* + - Description: Electric field components. Used with `gridGeometry` set to `rotationally_symmetric_rz`. If the field is DC, only the real component should be nonzero. From 8f0cbfb739bb2ebf3d5e32540ad331e7ab76ecb9 Mon Sep 17 00:00:00 2001 From: David Sagan Date: Tue, 16 Jul 2019 10:53:30 -0400 Subject: [PATCH 44/73] More mesh field devel. --- EXT_BeamPhysics.md | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/EXT_BeamPhysics.md b/EXT_BeamPhysics.md index feb764d..c144bac 100644 --- a/EXT_BeamPhysics.md +++ b/EXT_BeamPhysics.md @@ -265,7 +265,7 @@ Notes - `gridCurvatureRadius` - Type: Optional *(real)* - - Description: Only used if `gridGeometry` is set to `xyz`. A zero value indicates that the grid is rectilinear. A non-zero value indicates that the grid is curved. The curvature is in the **(x, z)** plane with positive **x** pointing away from the center of curvature if `gridCurvatureRadius` is positive and vice versa for negative values. `gridCurvatureRadius` is the radius for the lines **x = 0** at constant **y**. + - Description: Only used if `gridGeometry` is set to `xyz`. A zero value indicates that the grid is rectilinear. A non-zero value indicates that the grid is curved. The curvature is in the **(x, z)** plane with positive **x** pointing away from the center of curvature if `gridCurvatureRadius` is positive and vice versa for negative values. `gridCurvatureRadius` is the radius for the lines **x = 0** at constant **y**. - `eleAnchorPt` - Type: Optional *(string)* @@ -290,11 +290,6 @@ Notes - Type: Required 2-vector or 3-vector *(real)* - Description: Spacing between grid points. This is a 2-vector if `gridGeometry` is set to `rotationally_symmetric_rz` and is a 3-vector if `gridGeometry` is set to `xyz`. - -- `harmonic` - - Type: Required *(int)* - - Description: Harmonic number of the fundamental frequency. A value of zero implies a DC field. - - `gridLowerBound` - Type: Required 2-vector or 3-vector *(int)* - Description: Lower bound of the grid index. This is a 2-vector if `gridGeometry` is set to `rotationally_symmetric_rz` and is a 3-vector if `gridGeometry` is set to `xyz`. Note: The grid upper bound will be `gridLowerBound` + `gridSize` - 1. @@ -307,6 +302,15 @@ Notes - Type: Required 2-vector or 3-vector *(real)* - Description: distance from `eleAnchorPt` to the grid origin point. This is a 2-vector if `gridGeometry` is set to `rotationally_symmetric_rz` and is a 3-vector if `gridGeometry` is set to `xyz`. + +- `harmonic` + - Type: Required *(int)* + - Description: Harmonic number of the fundamental frequency. A value of zero implies a DC field. + +- `name` + - Type: Optional *(string)* + - Description: Name to be used to identify the grid. + `External Fields Group` Records ------------------------------- From 119f62a43b50ec76caf228c37c4435304af650c0 Mon Sep 17 00:00:00 2001 From: David Sagan Date: Wed, 17 Jul 2019 00:41:56 -0400 Subject: [PATCH 45/73] more... --- EXT_BeamPhysics.md | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/EXT_BeamPhysics.md b/EXT_BeamPhysics.md index feb764d..84c440e 100644 --- a/EXT_BeamPhysics.md +++ b/EXT_BeamPhysics.md @@ -257,7 +257,11 @@ The **external mesh field group** is a group for specifying electric and/or magn Notes ----- -- AC fields can be described using complex numbers. The actual field is the real part of `Z * Exp[-i omega (t - t0)]` where `Z` is the field complex number, `omega` is the field frequency, `t` is the time, and `t0` is a reference time. +- AC fields can be described using complex numbers. The actual field is the real part of + + Z * Exp[-2 * pi * I * (f * t + phi)] + +where `Z` is the field complex number, `f` is the Oscillation frequency, `t` is the time, and `phi0` is a reference time. `External Fields Group` Attributes @@ -265,10 +269,10 @@ Notes - `gridCurvatureRadius` - Type: Optional *(real)* - - Description: Only used if `gridGeometry` is set to `xyz`. A zero value indicates that the grid is rectilinear. A non-zero value indicates that the grid is curved. The curvature is in the **(x, z)** plane with positive **x** pointing away from the center of curvature if `gridCurvatureRadius` is positive and vice versa for negative values. `gridCurvatureRadius` is the radius for the lines **x = 0** at constant **y**. + - Description: Only used if `gridGeometry` is set to `xyz`. A zero value (the default) indicates that the grid is rectilinear. A non-zero value indicates that the grid is curved. The curvature is in the **(x, z)** plane with positive **x** pointing away from the center of curvature if `gridCurvatureRadius` is positive and vice versa for negative values. `gridCurvatureRadius` is the radius for the lines **x = 0** at constant **y**. - `eleAnchorPt` - - Type: Optional *(string)* + - Type: Required *(string)* - Description: Point on the lattice element that the grid origin is referenced to. Possible values are: `beginning`, `center`, or `end`. The `beginning` point is at the entrance end of the element, the `center` point is at the center of the element and the `end` point is at the exit end of the element. All three points are on the reference orbit. @@ -276,6 +280,9 @@ Notes - Type: Optional *(real)* - Description: A scale factor that is used to scale the fields. If not present then a value of 1 is assumed. +- `fieldPhase` + - Type Optional *(real)* + - Description: Phase offset for oscillating fields. See the note above. - `fundamentalFrequency` - Type: Optional *(real)* From 732c509cb619ada27679050625f9528e9c762aa2 Mon Sep 17 00:00:00 2001 From: David Sagan Date: Wed, 17 Jul 2019 10:07:28 -0400 Subject: [PATCH 46/73] Minor mod --- EXT_BeamPhysics.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/EXT_BeamPhysics.md b/EXT_BeamPhysics.md index 32f3891..08a04f6 100644 --- a/EXT_BeamPhysics.md +++ b/EXT_BeamPhysics.md @@ -278,11 +278,11 @@ where `Z` is the field complex number, `f` is the Oscillation frequency, `t` is - `fieldScale` - Type: Optional *(real)* - - Description: A scale factor that is used to scale the fields. If not present then a value of 1 is assumed. + - Description: A scale factor that is used to scale the fields. Default is 1. - `fieldPhase` - Type Optional *(real)* - - Description: Phase offset for oscillating fields. See the note above. + - Description: Phase offset for oscillating fields. See the note above. Default is zero. - `fundamentalFrequency` - Type: Optional *(real)* From b24a6295e81163162ab7b722761124c84407ee4b Mon Sep 17 00:00:00 2001 From: David Sagan Date: Wed, 17 Jul 2019 10:17:22 -0400 Subject: [PATCH 47/73] minor change --- EXT_BeamPhysics.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/EXT_BeamPhysics.md b/EXT_BeamPhysics.md index 08a04f6..9c850a7 100644 --- a/EXT_BeamPhysics.md +++ b/EXT_BeamPhysics.md @@ -280,10 +280,6 @@ where `Z` is the field complex number, `f` is the Oscillation frequency, `t` is - Type: Optional *(real)* - Description: A scale factor that is used to scale the fields. Default is 1. -- `fieldPhase` - - Type Optional *(real)* - - Description: Phase offset for oscillating fields. See the note above. Default is zero. - - `fundamentalFrequency` - Type: Optional *(real)* - Description: The fundamental RF frequency. Used for AC fields. @@ -318,6 +314,10 @@ where `Z` is the field complex number, `f` is the Oscillation frequency, `t` is - Type: Optional *(string)* - Description: Name to be used to identify the grid. +- `RFphase` + - Type Optional *(real)* + - Description: Phase offset for oscillating fields. See the note above. Default is zero. + `External Fields Group` Records ------------------------------- From acec36474dc2f4114bb03d2a5f6f3cca5aa1ea9e Mon Sep 17 00:00:00 2001 From: David Sagan Date: Wed, 17 Jul 2019 10:19:43 -0400 Subject: [PATCH 48/73] minor change --- EXT_BeamPhysics.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/EXT_BeamPhysics.md b/EXT_BeamPhysics.md index 9c850a7..474311e 100644 --- a/EXT_BeamPhysics.md +++ b/EXT_BeamPhysics.md @@ -315,7 +315,7 @@ where `Z` is the field complex number, `f` is the Oscillation frequency, `t` is - Description: Name to be used to identify the grid. - `RFphase` - - Type Optional *(real)* + - Type Required if `harmonic` is not zero *(real)* - Description: Phase offset for oscillating fields. See the note above. Default is zero. `External Fields Group` Records From d1ab1f26208f30563ab00f9f242a255f06f04571 Mon Sep 17 00:00:00 2001 From: David Sagan Date: Thu, 18 Jul 2019 00:51:20 -0400 Subject: [PATCH 49/73] more grid devel. --- EXT_BeamPhysics.md | 59 +++++++++++++++++++++++++++------------------- 1 file changed, 35 insertions(+), 24 deletions(-) diff --git a/EXT_BeamPhysics.md b/EXT_BeamPhysics.md index 474311e..59417bb 100644 --- a/EXT_BeamPhysics.md +++ b/EXT_BeamPhysics.md @@ -142,10 +142,15 @@ The following records store data on a particle-by-particle basis. - Description: Base momentum from which `momentum` is measured. That is, True momentum = `momentum + momentumOffset`. Assumed zero if not present. - Components: (`x`, `y`, `z`). -- `photonPolarization/` - - Type: Optional 2-vector *(complex)* - - Description: Polarization of the photon - - Components: (`x`, `y`), transverse to the direction of the photon. +- `photonPolarizationAmplitude/` + - Type: Optional 2-vector *(real)* + - Description: Polarization amplitude of the photon. + - Components: (`x`, `y`). + +- `photonPolarizationPhase/` + - Type: Optional 2-vector *(real)* + - Description: Polarization phase of the photon. + - Components: (`x`, `y`). - `sPosition` - Type: Optional *(real)* @@ -269,12 +274,11 @@ where `Z` is the field complex number, `f` is the Oscillation frequency, `t` is - `gridCurvatureRadius` - Type: Optional *(real)* - - Description: Only used if `gridGeometry` is set to `xyz`. A zero value (the default) indicates that the grid is rectilinear. A non-zero value indicates that the grid is curved. The curvature is in the **(x, z)** plane with positive **x** pointing away from the center of curvature if `gridCurvatureRadius` is positive and vice versa for negative values. `gridCurvatureRadius` is the radius for the lines **x = 0** at constant **y**. + - Description: Only used if `gridGeometry` is set to `rectangular`. A zero value (the default) indicates that the grid is rectilinear. A non-zero value indicates that the grid is curved. The curvature is in the **(x, z)** plane with positive **x** pointing away from the center of curvature if `gridCurvatureRadius` is positive and vice versa for negative values. `gridCurvatureRadius` is the radius for the lines **x = 0** at constant **y**. - `eleAnchorPt` - Type: Required *(string)* - - Description: Point on the lattice element that the grid origin is referenced to. Possible values are: `beginning`, `center`, or `end`. The `beginning` point is at - the entrance end of the element, the `center` point is at the center of the element and the `end` point is at the exit end of the element. All three points are on the reference orbit. + - Description: Point on the lattice element that the grid origin is referenced to. Possible values are: `beginning`, `center`, or `end`. The `beginning` point is at the entrance end of the element, the `center` point is at the center of the element and the `end` point is at the exit end of the element. All three points are on the reference orbit. - `fieldScale` - Type: Optional *(real)* @@ -286,24 +290,24 @@ where `Z` is the field complex number, `f` is the Oscillation frequency, `t` is - `gridGeometry` - Type: Required *(string)* - - Description: Values are `xyz` or `rotationally_symmetric_rz`. The `xyz` value is for a 3D **(x, y, z)** grid with field components **(Bx, By, Bz)** and/or **(Ex, Ey, Ez)**. The `rotationally_symmetric_rz` value is for a 2D **(r, z)** grid with field components **(Br, Bphi, Bz)** and/or **(Er, Ephi, Ez)** field components. + - Description: Values are `rectangular` or `cylindrical`. The `rectangular` value is for a **(x, y, z)** grid with field components **(Bx, By, Bz)** and/or **(Ex, Ey, Ez)**. The `cylindrical` value is for a **(r, theta, z)** grid with field components **(Br, Btheta, Bz)** and/or **(Er, Etheta, Ez)** field components. Note: If the grid size in the `theta` direction is 1, the field is taken to be axially symmetric. - `gridSpacing` - - Type: Required 2-vector or 3-vector *(real)* - - Description: Spacing between grid points. This is a 2-vector if `gridGeometry` is set to `rotationally_symmetric_rz` and is a 3-vector if `gridGeometry` is set to `xyz`. + - Type: Required 3-vector *(real)* + - Description: Spacing between grid points. - `gridLowerBound` - - Type: Required 2-vector or 3-vector *(int)* - - Description: Lower bound of the grid index. This is a 2-vector if `gridGeometry` is set to `rotationally_symmetric_rz` and is a 3-vector if `gridGeometry` is set to `xyz`. Note: The grid upper bound will be `gridLowerBound` + `gridSize` - 1. + - Type: Required 3-vector *(int)* + - Description: Lower bound of the grid index. Note: The grid upper bound will be `gridLowerBound` + `gridSize` - 1. - `gridSize` - - Type: Required 2-vector or 3-vector *(int)* - - Description: Size of the grid. This is a 2-vector if `gridGeometry` is set to `rotationally_symmetric_rz` and is a 3-vector if `gridGeometry` is set to `xyz`. + - Type: Required 3-vector *(int)* + - Description: Size of the grid. - `gridOriginOffset` - - Type: Required 2-vector or 3-vector *(real)* - - Description: distance from `eleAnchorPt` to the grid origin point. This is a 2-vector if `gridGeometry` is set to `rotationally_symmetric_rz` and is a 3-vector if `gridGeometry` is set to `xyz`. + - Type: Required 3-vector *(real)* + - Description: distance from `eleAnchorPt` to the grid origin point. - `harmonic` @@ -318,24 +322,31 @@ where `Z` is the field complex number, `f` is the Oscillation frequency, `t` is - Type Required if `harmonic` is not zero *(real)* - Description: Phase offset for oscillating fields. See the note above. Default is zero. -`External Fields Group` Records -------------------------------- + +Per-grid `External Fields Group` Records for `(x, y, z)` Grids +-------------------------------------------------------------- - `Bx`, `By`, `Bz` - Type: Optional (Either all must be present or all must be absent) *(complex)* - - Description: Magnetic field components. Used with `gridGeometry` set to `xyz`. If the field is DC, only the real component should be nonzero. + - Description: Magnetic field components using rectangular coordinates. Used with `gridGeometry` set to `rectangular`. If the field is DC (`harmonic` is zero), only the real component should be nonzero. -- `Br`, `Bphi`, `Bz` +- `Ex`, `Ey`, `Ez` - Type: Optional (Either all must be present or all must be absent) *(complex)* - - Description: Magnetic field components. Used with `gridGeometry` set to `rotationally_symmetric_rz`. If the field is DC, only the real component should be nonzero. + - Description: Electric field components. Used with `gridGeometry` set to `xyz`.If the field is DC, only the real component should be nonzero. -- `Ex`, `Ey`, `Ez` +Per-grid `External Fields Group` Records for `(r, theta, z)` Grids +-------------------------------------------------------------- + +Note: If the grid size in the `theta` direction is 1, the field is taken to be axially symmetric. + + +- `Br`, `Btheta`, `Bz` - Type: Optional (Either all must be present or all must be absent) *(complex)* - - Description: Electric field components. Used with `gridGeometry` set to `xyz`.If the field is DC, only the real component should be nonzero. + - Description: Magnetic field components using cylindrical coordinates. Used with `gridGeometry` set to `cylindrical`. If the field is DC (`harmonic` is zero), only the real component should be nonzero. -- `Er`, `Ephi`, `Ez` +- `Er`, `Etheta`, `Ez` - Type: Optional (Either all must be present or all must be absent) *(complex)* - Description: Electric field components. Used with `gridGeometry` set to `rotationally_symmetric_rz`. If the field is DC, only the real component should be nonzero. From 6e022a8e7ceb782460b607c8df41d7a4e25a0294 Mon Sep 17 00:00:00 2001 From: David Sagan Date: Mon, 26 Aug 2019 16:44:53 -0400 Subject: [PATCH 50/73] Removed speed dataset. --- EXT_BeamPhysics.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/EXT_BeamPhysics.md b/EXT_BeamPhysics.md index c144bac..3f7eb46 100644 --- a/EXT_BeamPhysics.md +++ b/EXT_BeamPhysics.md @@ -192,10 +192,6 @@ The following records store data on a particle-by-particle basis. - Components: (`x`, `y`, `z`) - Attributes: -- `speed/` - - Type: Optional *(real)* - - Description: The speed (velocity magnitude) of a particle. - - `spin/` - Type: Optional 3-vector *(real)* - Description: Particle spin. From 03f5fe959438fd3da7dc3c58ad98c660b1a7b393 Mon Sep 17 00:00:00 2001 From: David Sagan Date: Fri, 13 Sep 2019 16:30:52 -0400 Subject: [PATCH 51/73] removed version number. --- EXT_BeamPhysics.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/EXT_BeamPhysics.md b/EXT_BeamPhysics.md index ab2bf22..ea46d04 100644 --- a/EXT_BeamPhysics.md +++ b/EXT_BeamPhysics.md @@ -1,8 +1,6 @@ BeamPhysics Extension to the openPMD Standard for Describing Particle Beams, Photons, and External Fields ========================================================================================================= -Version 2.0.0 - Overview -------- From f2e62178de7042ec80aaf4efe26c67f632bedb13 Mon Sep 17 00:00:00 2001 From: David Sagan Date: Fri, 13 Sep 2019 16:35:26 -0400 Subject: [PATCH 52/73] cosmetic change. --- EXT_BeamPhysics.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/EXT_BeamPhysics.md b/EXT_BeamPhysics.md index ea46d04..bfcb084 100644 --- a/EXT_BeamPhysics.md +++ b/EXT_BeamPhysics.md @@ -331,7 +331,7 @@ Per-grid `External Fields Group` Records for `(x, y, z)` Grids Per-grid `External Fields Group` Records for `(r, theta, z)` Grids --------------------------------------------------------------- +------------------------------------------------------------------ Note: If the grid size in the `theta` direction is 1, the field is taken to be axially symmetric. From 04db263c1a5a7489b32439ca3f152d1c95b1790f Mon Sep 17 00:00:00 2001 From: David Sagan Date: Fri, 13 Sep 2019 16:50:18 -0400 Subject: [PATCH 53/73] Cosmetic change. --- EXT_BeamPhysics.md | 241 ++++++++++++++++++++++----------------------- 1 file changed, 120 insertions(+), 121 deletions(-) diff --git a/EXT_BeamPhysics.md b/EXT_BeamPhysics.md index bfcb084..1ddaa5b 100644 --- a/EXT_BeamPhysics.md +++ b/EXT_BeamPhysics.md @@ -47,16 +47,16 @@ Additional File Root Group (Path `/`) Attributes The following records are defined for the file root group. - `fileType` - - Type: Optional *(string)* - - Description: The type of data being stored in the file. If present, must be set to `openPMD`. This attribute is used in systems where different data files can contain different types of data and allows for quick identification of the what type of data is in a given file. + - type: Optional *(string)* + - description: The type of data being stored in the file. If present, must be set to `openPMD`. This attribute is used in systems where different data files can contain different types of data and allows for quick identification of the what type of data is in a given file. - `latticeName` - - Type: Optional *(string)* - - Description: The name of the lattice. + - type: Optional *(string)* + - description: The name of the lattice. - `latticeFile` - - Type: Optional *(string)* - - Description: The location of the root lattice file. + - type: Optional *(string)* + - description: The location of the root lattice file. Particle Group Standard ============================ @@ -70,29 +70,29 @@ The **Particle Group** is a group for specifying a set of particles such as the For each **particle group** the following attributes are defined: - `chargeLive` - - Type: Optional *(real)* - - Description: The total charge of all the live particles. + - type: Optional *(real)* + - description: The total charge of all the live particles. - `chargeUnitSI` - - Type: *(real)*. Only required if `chargeLive` or `totalCharge` is present. - - Description: Unit conversion factor to multiply `chargeLive` or `totalCharge` by in order to convert to SI units. + - type: *(real)*. Only required if `chargeLive` or `totalCharge` is present. + - description: Unit conversion factor to multiply `chargeLive` or `totalCharge` by in order to convert to SI units. - `latticeElementName` - - Type: Optional *(string)* - - Description: The name of the lattice element the particle are in. This only makes sense if all particles are in the same element. [Keep in mind that if particles are lost and the lost particles are also included in the file, not all particles may be in the same element.] Also see: `locationInElement`. + - type: Optional *(string)* + - description: The name of the lattice element the particle are in. This only makes sense if all particles are in the same element. [Keep in mind that if particles are lost and the lost particles are also included in the file, not all particles may be in the same element.] Also see: `locationInElement`. - `numParticles` - - Type: Required *(int)* - - Description: The number of particles in the group. + - type: Required *(int)* + - description: The number of particles in the group. - `speciesType` - - Type: Required *(string)* - - Description: The name of the particle species. Species names must conform to the `SpeciesType` extension. + - type: Required *(string)* + - description: The name of the particle species. Species names must conform to the `SpeciesType` extension. - Example: `electron`, `H2O`. - `totalCharge` - - Type: Optional *(real)* - - Description: The total charge of all the particles alive and dead. + - type: Optional *(real)* + - description: The total charge of all the particles alive and dead. Per-Particle Records of the `Particle Group` ------------------------------------------------- @@ -100,121 +100,120 @@ Per-Particle Records of the `Particle Group` The following records store data on a particle-by-particle basis. - `branchIndex/` - - Type Optional *(int)* - - Description: The unique index number assigned to the lattice branch the particle is in. + - type Optional *(int)* + - description: The unique index number assigned to the lattice branch the particle is in. - `chargeState/` - - Type: Optional *(int)* - - Description: The charge state of the particles. Used for atoms and molecules. Not needed if the charge can be computed from knowledge of the `SpeciesType` (That is, is a fundamental particle). Also see `weight`. + - type: Optional *(int)* + - description: The charge state of the particles. Used for atoms and molecules. Not needed if the charge can be computed from knowledge of the `SpeciesType` (That is, is a fundamental particle). Also see `weight`. - `electricField/` - - Type: Optional 3-vector *(real)* - - Description: External electric field at the particle. - - Components: (`x`, `y`, `z`). + - type: Optional 3-vector *(real)* + - description: External electric field at the particle. + - components: (`x`, `y`, `z`). - `elementIndex/` - - Type Optional *(int)* - - Description: The unique index number assigned to the lattice element the particle is in. + - type Optional *(int)* + - description: The unique index number assigned to the lattice element the particle is in. - `magneticField/` - - Type: Optional 3-vector *(real)* - - Description: External magnetic field at the particle. - - Components: (`x`, `y`, `z`). + - type: Optional 3-vector *(real)* + - description: External magnetic field at the particle. + - components: (`x`, `y`, `z`). - `locationInElement` - - Type Optional *(integer)* - - Description: The program generating the data file may model a lattice element using a "hard edge" model where the fringe fields at the ends of the element are modeled as having zero longitudinal length. In such a case, if a particle is at the end of the lattice element, it is important to know if the particle is outside of the fringe or if the particle is inside the fringe within the body of the element. Note that with a hard edge fringe, the longitudinal **s**-position does not necessarily provide enough information to determine where a particle is with respect to an edge field. Another situation where `locationInElement` is useful is with zero length elements that affect the particle transport (such as zero length multipole elements). If the program generating the data file does **not** use any hard edge models or zero length non-marker elements, `locationInElement` should not be present since this parameter is meaningless in this case. + - type Optional *(integer)* + - description: The program generating the data file may model a lattice element using a "hard edge" model where the fringe fields at the ends of the element are modeled as having zero longitudinal length. In such a case, if a particle is at the end of the lattice element, it is important to know if the particle is outside of the fringe or if the particle is inside the fringe within the body of the element. Note that with a hard edge fringe, the longitudinal **s**-position does not necessarily provide enough information to determine where a particle is with respect to an edge field. Another situation where `locationInElement` is useful is with zero length elements that affect the particle transport (such as zero length multipole elements). If the program generating the data file does **not** use any hard edge models or zero length non-marker elements, `locationInElement` should not be present since this parameter is meaningless in this case. - Possible values: - -1: Upstream end of element outside of the upstream fringe edge. - 0: Inside the element. - 1: Downstream end of the element outside the downstream fringe edge. - `momentum/` - - Type: Optional 3-vector *(real)* - - Description: The momentum vector of the particles relative to `momentumOffset` - - Components: (`x`, `y`, `z`). - - True momentum = `momentum + momentumOffset` + - type: Optional 3-vector *(real)* + - description: The momentum vector of the particles relative to `momentumOffset` + - components: (`x`, `y`, `z`). + - true momentum = `momentum + momentumOffset` - `momentumOffset/` - - Type: Optional 3-vector *(real)* - - Description: Base momentum from which `momentum` is measured. That is, True momentum = `momentum + momentumOffset`. Assumed zero if not present. - - Components: (`x`, `y`, `z`). + - type: Optional 3-vector *(real)* + - description: Base momentum from which `momentum` is measured. That is, True momentum = `momentum + momentumOffset`. Assumed zero if not present. + - components: (`x`, `y`, `z`). - `photonPolarizationAmplitude/` - - Type: Optional 2-vector *(real)* - - Description: Polarization amplitude of the photon. - - Components: (`x`, `y`). + - type: Optional 2-vector *(real)* + - description: Polarization amplitude of the photon. + - components: (`x`, `y`). - `photonPolarizationPhase/` - - Type: Optional 2-vector *(real)* - - Description: Polarization phase of the photon. - - Components: (`x`, `y`). + - type: Optional 2-vector *(real)* + - description: Polarization phase of the photon. + - components: (`x`, `y`). - `sPosition` - - Type: Optional *(real)* - - Description: The value of the longitudinal position in the curvilinear lattice coordinate system. + - type: Optional *(real)* + - description: The value of the longitudinal position in the curvilinear lattice coordinate system. - `totalMomentum/` - - Type: Optional *(real)* - - Description: Total momentum relative to the totalMomentumOffset. That is, True total momentum = `totalMomentum + totalMomentumOffset`. Assumed zero if not present. + - type: Optional *(real)* + - description: Total momentum relative to the totalMomentumOffset. That is, True total momentum = `totalMomentum + totalMomentumOffset`. Assumed zero if not present. - `totalMomentumOffset/` - - Type: Optional *(real)* - - Description: Base total momentum from which `totalMomentum` is measured. That is, True total momentum = `totalMomentum + totalMomentumOffset`. Some programs will use `totalMomentumOffset/` to store the **reference momentum** in which case `totalMomentum` will then be the deviation from the referece. + - type: Optional *(real)* + - description: Base total momentum from which `totalMomentum` is measured. That is, True total momentum = `totalMomentum + totalMomentumOffset`. Some programs will use `totalMomentumOffset/` to store the **reference momentum** in which case `totalMomentum` will then be the deviation from the referece. - `particleCoordinatesToGlobalTransformation/` - - Type: Optional group. - - Description: Defines the transformation from the coordinates used to describe a particle to the **global** coordinate system. + - type: Optional group. + - description: Defines the transformation from the coordinates used to describe a particle to the **global** coordinate system. - `R_frame`: - Required 3-vector *(real)* Attribute - - Description: specifying the (x, y, z) position of the coordinate origin that the particles are measured with respect to in the **global** coordinate frame. + - description: specifying the (x, y, z) position of the coordinate origin that the particles are measured with respect to in the **global** coordinate frame. - `W_matrix`: - Required 3 x 3 matrix *(real)* - - Description: Dataset holding the 3x3 transformation matrix from coordinates to **global** + - description: Dataset holding the 3x3 transformation matrix from coordinates to **global** coordinates. - Position Transformation: Position_global = W_matrix * (position + positionOffset) + R_frame - Momentum transformation: Momentum_global = W_matrix * (momentum + momentumOffset) - `particleStatus/` - - Type: Optional *(int)* - - Description: Integer indicating whether a particle is "alive" or "dead" (for example, has hit the vacuum chamber wall). A value of one indicates the particle is alive and any other value indicates that the particle is dead. Programs are free to distinguish how a particle died by assigning different non-unit values to `particleStatus`. For example, a program might want to differentiate between particles that are dead due to hitting the side walls versus reversing the direction longitudinally in an RF cavity. + - type: Optional *(int)* + - description: Integer indicating whether a particle is "alive" or "dead" (for example, has hit the vacuum chamber wall). A value of one indicates the particle is alive and any other value indicates that the particle is dead. Programs are free to distinguish how a particle died by assigning different non-unit values to `particleStatus`. For example, a program might want to differentiate between particles that are dead due to hitting the side walls versus reversing the direction longitudinally in an RF cavity. - `pathLength/` - - Type: Optional *(real)* - - Description: Length that a particle has traveled. + - type: Optional *(real)* + - description: Length that a particle has traveled. - `position/` - - Type: Required 3-vector *(real)* - - Components: (`x`, `y`, `z`) - - Description: particle Position relative to the `positionOffset`. + - type: Required 3-vector *(real)* + - components: (`x`, `y`, `z`) + - description: particle Position relative to the `positionOffset`. That is, true position relative to the coordinate origin = `position + positionOffset`. - `positionOffset/` - - Type: Optional 3-vector *(real)* - - Description: Offset for each particle position component relative to the coordinate origin. Assumed zero if not present. - - Components: (`x`, `y`, `z`) - - Attributes: + - type: Optional 3-vector *(real)* + - description: Offset for each particle position component relative to the coordinate origin. Assumed zero if not present. + - components: (`x`, `y`, `z`) - `spin/` - - Type: Optional 3-vector *(real)* - - Description: Particle spin. - - Components: (`x`, `y`, `z`) or (`r`, `theta`, `phi`). + - type: Optional 3-vector *(real)* + - description: Particle spin. + - components: (`x`, `y`, `z`) or (`r`, `theta`, `phi`). - `time/` - - Type: Optional *(real)* - - Description: Time relative to `timeOffset`. That is, absolute time = `time + timeOffset`. + - type: Optional *(real)* + - description: Time relative to `timeOffset`. That is, absolute time = `time + timeOffset`. - `timeOffset/` - - Type: Optional *(real)* - - Description: Base time from which `time` is measured. That is, absolute time = `time + timeOffset`. Assumed zero if not present. Some programs will use the `timeOffset` to store the **reference time** in which case `time` will then be the deviation from the reference. + - type: Optional *(real)* + - description: Base time from which `time` is measured. That is, absolute time = `time + timeOffset`. Assumed zero if not present. Some programs will use the `timeOffset` to store the **reference time** in which case `time` will then be the deviation from the reference. - `velocity/` - - Type: Optional 3-vector *(real)* - - Description: (`x`, `y`, `z`) velocity vector. Meant to be used for photons where using `momentum` is not appropriate. + - type: Optional 3-vector *(real)* + - description: (`x`, `y`, `z`) velocity vector. Meant to be used for photons where using `momentum` is not appropriate. - `weight/` - - Type: Optional *(real)* - - Description: If macro-particles are being simulated, the `weight` is the total charge of a macro-particle. This is proportional to the number of particles that a macro-particle represents. Also see `charge`. + - type: Optional *(real)* + - description: If macro-particles are being simulated, the `weight` is the total charge of a macro-particle. This is proportional to the number of particles that a macro-particle represents. Also see `charge`. Non Per-Particle Records of the `Particle Group` @@ -223,12 +222,12 @@ Non Per-Particle Records of the `Particle Group` The following possible records of the `Particle Group` are for specifying properties of the entire group of particles. - `phaseSpaceFirstOrderMoment/` - - Type: Optional 6-vector *(real)* - - Description: First order beam moments of `(x, px, y, py, z, pz)`. + - type: Optional 6-vector *(real)* + - description: First order beam moments of `(x, px, y, py, z, pz)`. - `phaseSpaceSecondOrderMoment/` - - Type: Optional 6x6-matrix *(real)* - - Description: Second order beam moments of `(x, px, y, py, z, pz)`. + - type: Optional 6x6-matrix *(real)* + - description: Second order beam moments of `(x, px, y, py, z, pz)`. Particle Record Dataset Attributes ---------------------------------- @@ -236,22 +235,22 @@ Particle Record Dataset Attributes The following attributes can be used with any dataset: - `minValue`: - - Type: Optional *(real)* - - Description: Minimum of the data. + - type: Optional *(real)* + - description: Minimum of the data. - `maxValue`: - - Type: Optional *(real)* - - Description: Maximum of the data. + - type: Optional *(real)* + - description: Maximum of the data. External Mesh Fields Groups =========================== The **external mesh field group** is a group for specifying electric and/or magnetic fields, due to a lattice element, at regularly spaced grid points. For example, the fields due to an RF cavity or the fields due to a magnet. Multiple **external mesh field groups** can be defined in a file. The path for a **external mesh field group** is given by the **externalFieldPath** in the file root group: - `externalFieldPath` - - Type: Required if there are external mesh field group(s) *(string)* - - Description: Base path to the external mesh field groups. Use the **%T** construct if there are multiple meshes present. - - Example: `/ExternalFieldMesh/%T/`. Base paths to the external fields group, in this case, would be `/ExternalFieldMesh/1/`, etc. - - Example: `/ExternalFieldMesh/`. In this case there is only one external fields group. + - type: Required if there are external mesh field group(s) *(string)* + - description: Base path to the external mesh field groups. Use the **%T** construct if there are multiple meshes present. + - example: `/ExternalFieldMesh/%T/`. Base paths to the external fields group, in this case, would be `/ExternalFieldMesh/1/`, etc. + - example: `/ExternalFieldMesh/`. In this case there is only one external fields group. Notes ----- @@ -267,67 +266,67 @@ where `Z` is the field complex number, `f` is the Oscillation frequency, `t` is ---------------------------------- - `gridCurvatureRadius` - - Type: Optional *(real)* - - Description: Only used if `gridGeometry` is set to `rectangular`. A zero value (the default) indicates that the grid is rectilinear. A non-zero value indicates that the grid is curved. The curvature is in the **(x, z)** plane with positive **x** pointing away from the center of curvature if `gridCurvatureRadius` is positive and vice versa for negative values. `gridCurvatureRadius` is the radius for the lines **x = 0** at constant **y**. + - type: Optional *(real)* + - description: Only used if `gridGeometry` is set to `rectangular`. A zero value (the default) indicates that the grid is rectilinear. A non-zero value indicates that the grid is curved. The curvature is in the **(x, z)** plane with positive **x** pointing away from the center of curvature if `gridCurvatureRadius` is positive and vice versa for negative values. `gridCurvatureRadius` is the radius for the lines **x = 0** at constant **y**. - `eleAnchorPt` - - Type: Required *(string)* - - Description: Point on the lattice element that the grid origin is referenced to. Possible values are: `beginning`, `center`, or `end`. The `beginning` point is at the entrance end of the element, the `center` point is at the center of the element and the `end` point is at the exit end of the element. All three points are on the reference orbit. + - type: Required *(string)* + - description: Point on the lattice element that the grid origin is referenced to. Possible values are: `beginning`, `center`, or `end`. The `beginning` point is at the entrance end of the element, the `center` point is at the center of the element and the `end` point is at the exit end of the element. All three points are on the reference orbit. - `fieldScale` - - Type: Optional *(real)* - - Description: A scale factor that is used to scale the fields. Default is 1. + - type: Optional *(real)* + - description: A scale factor that is used to scale the fields. Default is 1. - `fundamentalFrequency` - - Type: Optional *(real)* - - Description: The fundamental RF frequency. Used for AC fields. + - type: Optional *(real)* + - description: The fundamental RF frequency. Used for AC fields. - `gridGeometry` - - Type: Required *(string)* - - Description: Values are `rectangular` or `cylindrical`. The `rectangular` value is for a **(x, y, z)** grid with field components **(Bx, By, Bz)** and/or **(Ex, Ey, Ez)**. The `cylindrical` value is for a **(r, theta, z)** grid with field components **(Br, Btheta, Bz)** and/or **(Er, Etheta, Ez)** field components. Note: If the grid size in the `theta` direction is 1, the field is taken to be axially symmetric. + - type: Required *(string)* + - description: Values are `rectangular` or `cylindrical`. The `rectangular` value is for a **(x, y, z)** grid with field components **(Bx, By, Bz)** and/or **(Ex, Ey, Ez)**. The `cylindrical` value is for a **(r, theta, z)** grid with field components **(Br, Btheta, Bz)** and/or **(Er, Etheta, Ez)** field components. Note: If the grid size in the `theta` direction is 1, the field is taken to be axially symmetric. - `gridSpacing` - - Type: Required 3-vector *(real)* - - Description: Spacing between grid points. + - type: Required 3-vector *(real)* + - description: Spacing between grid points. - `gridLowerBound` - - Type: Required 3-vector *(int)* - - Description: Lower bound of the grid index. Note: The grid upper bound will be `gridLowerBound` + `gridSize` - 1. + - type: Required 3-vector *(int)* + - description: Lower bound of the grid index. Note: The grid upper bound will be `gridLowerBound` + `gridSize` - 1. - `gridSize` - - Type: Required 3-vector *(int)* - - Description: Size of the grid. + - type: Required 3-vector *(int)* + - description: Size of the grid. - `gridOriginOffset` - - Type: Required 3-vector *(real)* - - Description: distance from `eleAnchorPt` to the grid origin point. + - type: Required 3-vector *(real)* + - description: distance from `eleAnchorPt` to the grid origin point. - `harmonic` - - Type: Required *(int)* - - Description: Harmonic number of the fundamental frequency. A value of zero implies a DC field. + - type: Required *(int)* + - description: Harmonic number of the fundamental frequency. A value of zero implies a DC field. - `name` - - Type: Optional *(string)* - - Description: Name to be used to identify the grid. + - type: Optional *(string)* + - description: Name to be used to identify the grid. - `RFphase` - - Type Required if `harmonic` is not zero *(real)* - - Description: Phase offset for oscillating fields. See the note above. Default is zero. + - type Required if `harmonic` is not zero *(real)* + - description: Phase offset for oscillating fields. See the note above. Default is zero. Per-grid `External Fields Group` Records for `(x, y, z)` Grids -------------------------------------------------------------- - `Bx`, `By`, `Bz` - - Type: Optional (Either all must be present or all must be absent) *(complex)* - - Description: Magnetic field components using rectangular coordinates. Used with `gridGeometry` set to `rectangular`. If the field is DC (`harmonic` is zero), only the real component should be nonzero. + - type: Optional (Either all must be present or all must be absent) *(complex)* + - description: Magnetic field components using rectangular coordinates. Used with `gridGeometry` set to `rectangular`. If the field is DC (`harmonic` is zero), only the real component should be nonzero. - `Ex`, `Ey`, `Ez` - - Type: Optional (Either all must be present or all must be absent) *(complex)* - - Description: Electric field components. Used with `gridGeometry` set to `xyz`.If the field is DC, only the real component should be nonzero. + - type: Optional (Either all must be present or all must be absent) *(complex)* + - description: Electric field components. Used with `gridGeometry` set to `xyz`.If the field is DC, only the real component should be nonzero. Per-grid `External Fields Group` Records for `(r, theta, z)` Grids @@ -337,10 +336,10 @@ Note: If the grid size in the `theta` direction is 1, the field is taken to be a - `Br`, `Btheta`, `Bz` - - Type: Optional (Either all must be present or all must be absent) *(complex)* - - Description: Magnetic field components using cylindrical coordinates. Used with `gridGeometry` set to `cylindrical`. If the field is DC (`harmonic` is zero), only the real component should be nonzero. + - type: Optional (Either all must be present or all must be absent) *(complex)* + - description: Magnetic field components using cylindrical coordinates. Used with `gridGeometry` set to `cylindrical`. If the field is DC (`harmonic` is zero), only the real component should be nonzero. - `Er`, `Etheta`, `Ez` - - Type: Optional (Either all must be present or all must be absent) *(complex)* - - Description: Electric field components. Used with `gridGeometry` set to `rotationally_symmetric_rz`. If the field is DC, only the real component should be nonzero. + - type: Optional (Either all must be present or all must be absent) *(complex)* + - description: Electric field components. Used with `gridGeometry` set to `rotationally_symmetric_rz`. If the field is DC, only the real component should be nonzero. From 8bb8e3971bd10c2ab7f506603a5546d903fa9687 Mon Sep 17 00:00:00 2001 From: David Sagan Date: Fri, 13 Sep 2019 17:10:16 -0400 Subject: [PATCH 54/73] Small stylistic changes. --- EXT_BeamPhysics.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/EXT_BeamPhysics.md b/EXT_BeamPhysics.md index 1ddaa5b..9b752be 100644 --- a/EXT_BeamPhysics.md +++ b/EXT_BeamPhysics.md @@ -59,9 +59,9 @@ The following records are defined for the file root group. - description: The location of the root lattice file. Particle Group Standard -============================ +======================= -The **Particle Group** is a group for specifying a set of particles such as the particles in a bunch. Multiple **Particle Groups** can be defined in a file. The path for a **Particle Group** is given by the **basePath** and **particlesPath** attributes in the file root group as discussed in the base OpenPMD standard. For example, if **basePath** is "/data/%T/", and **ParticlesPath** is "particles/", then **Particle Groups** paths would be of the form "/data/%T/particles/" where "%T" is an integer. EG: "/data/37/particles/". +The **Particle Group** is a group for specifying a set of particles such as the particles in a bunch. Multiple **Particle Groups** can be defined in a file. The path for a **Particle Group** is given by the **basePath** and **particlesPath** attributes in the file root group as discussed in the base OpenPMD standard. For example, if **basePath** is `/data/%T/`, and **ParticlesPath** is `particles/`, then **Particle Groups** paths would be of the form `/data/%T/particles/` where `%T` is an integer. EG: `/data/37/particles/`. `Particle Group` Attributes @@ -95,7 +95,7 @@ For each **particle group** the following attributes are defined: - description: The total charge of all the particles alive and dead. Per-Particle Records of the `Particle Group` -------------------------------------------------- +-------------------------------------------- The following records store data on a particle-by-particle basis. @@ -125,9 +125,9 @@ The following records store data on a particle-by-particle basis. - type Optional *(integer)* - description: The program generating the data file may model a lattice element using a "hard edge" model where the fringe fields at the ends of the element are modeled as having zero longitudinal length. In such a case, if a particle is at the end of the lattice element, it is important to know if the particle is outside of the fringe or if the particle is inside the fringe within the body of the element. Note that with a hard edge fringe, the longitudinal **s**-position does not necessarily provide enough information to determine where a particle is with respect to an edge field. Another situation where `locationInElement` is useful is with zero length elements that affect the particle transport (such as zero length multipole elements). If the program generating the data file does **not** use any hard edge models or zero length non-marker elements, `locationInElement` should not be present since this parameter is meaningless in this case. - Possible values: - - -1: Upstream end of element outside of the upstream fringe edge. - - 0: Inside the element. - - 1: Downstream end of the element outside the downstream fringe edge. + - `-1`: Upstream end of element outside of the upstream fringe edge. + - `0`: Inside the element. + - `1`: Downstream end of the element outside the downstream fringe edge. - `momentum/` - type: Optional 3-vector *(real)* @@ -167,7 +167,7 @@ The following records store data on a particle-by-particle basis. - description: Defines the transformation from the coordinates used to describe a particle to the **global** coordinate system. - `R_frame`: - Required 3-vector *(real)* Attribute - - description: specifying the (x, y, z) position of the coordinate origin that the particles are measured with respect to in the **global** coordinate frame. + - description: Specifying the (`x`, `y`, `z`) position of the coordinate origin that the particles are measured with respect to in the **global** coordinate frame. - `W_matrix`: - Required 3 x 3 matrix *(real)* - description: Dataset holding the 3x3 transformation matrix from coordinates to **global** @@ -217,7 +217,7 @@ The following records store data on a particle-by-particle basis. Non Per-Particle Records of the `Particle Group` ------------------------------------------------------ +------------------------------------------------ The following possible records of the `Particle Group` are for specifying properties of the entire group of particles. From bcc45fb2cf3301a2106f0c0aaa8117941670202b Mon Sep 17 00:00:00 2001 From: David Sagan Date: Fri, 13 Sep 2019 17:13:53 -0400 Subject: [PATCH 55/73] Cosmetic change. --- EXT_BeamPhysics.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/EXT_BeamPhysics.md b/EXT_BeamPhysics.md index 9b752be..db29710 100644 --- a/EXT_BeamPhysics.md +++ b/EXT_BeamPhysics.md @@ -4,8 +4,7 @@ BeamPhysics Extension to the openPMD Standard for Describing Particle Beams, Pho Overview -------- -The `BeamPhysics` extension to the openPMD standard is meant for describing particles and fields commonly encountered -in accelerator physics simulations. +The `BeamPhysics` extension to the openPMD standard is meant for describing particles and fields commonly encountered in accelerator physics simulations. How to Use this Extension ------------------------- From feeb1b2429ccdc6b31d3dad52cb61f3acd1c161b Mon Sep 17 00:00:00 2001 From: David Sagan Date: Tue, 5 Nov 2019 15:15:48 -0500 Subject: [PATCH 56/73] Cosmetic change. --- EXT_BeamPhysics.md | 1 + 1 file changed, 1 insertion(+) diff --git a/EXT_BeamPhysics.md b/EXT_BeamPhysics.md index db29710..6367cbf 100644 --- a/EXT_BeamPhysics.md +++ b/EXT_BeamPhysics.md @@ -1,5 +1,6 @@ BeamPhysics Extension to the openPMD Standard for Describing Particle Beams, Photons, and External Fields ========================================================================================================= +openPMD extension name: `BeamPhysics` Overview -------- From 9807a2b70b560453f0b024dd6ffb8735f9c9ac5e Mon Sep 17 00:00:00 2001 From: David Sagan Date: Fri, 13 Dec 2019 10:55:04 -0500 Subject: [PATCH 57/73] Added note on complex storage. --- EXT_BeamPhysics.md | 5 +- EXT_BeamPhysics.md~ | 345 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 348 insertions(+), 2 deletions(-) create mode 100644 EXT_BeamPhysics.md~ diff --git a/EXT_BeamPhysics.md b/EXT_BeamPhysics.md index 6367cbf..8771e38 100644 --- a/EXT_BeamPhysics.md +++ b/EXT_BeamPhysics.md @@ -257,10 +257,11 @@ Notes - AC fields can be described using complex numbers. The actual field is the real part of - Z * Exp[-2 * pi * I * (f * t + phi)] + Z * Exp[-2 pi i f * (t - t0)] -where `Z` is the field complex number, `f` is the Oscillation frequency, `t` is the time, and `phi0` is a reference time. +where `Z` is the complex field, `f` is the Oscillation frequency, `t` is the time, and `t0` is a reference time. +Software that writes complex data must use native complex storage for formats that support complex numbers. For formats that do not have native complex support (for example, HDF5), complex numbers are to be stored using subgroups labeled `r` and `i` for real and imaginary respectively. `External Fields Group` Attributes ---------------------------------- diff --git a/EXT_BeamPhysics.md~ b/EXT_BeamPhysics.md~ new file mode 100644 index 0000000..9b752be --- /dev/null +++ b/EXT_BeamPhysics.md~ @@ -0,0 +1,345 @@ +BeamPhysics Extension to the openPMD Standard for Describing Particle Beams, Photons, and External Fields +========================================================================================================= + +Overview +-------- + +The `BeamPhysics` extension to the openPMD standard is meant for describing particles and fields commonly encountered +in accelerator physics simulations. + +How to Use this Extension +------------------------- + +The `BeamPhysics` extension to the openPMD standard is indicated in a data file by the setting of the `openPMDextension` attribute: +``` + openPMDextension = BeamPhysics;SpeciesType +``` + +Note: The `SpeciesType` extension must be used when using the `BeamPhysics` extension. + +Definitions +----------- + +- **Lattice**: A **lattice** is the arrangement of elements in a machine such as a particle accelerator. + +- **Lattice branches**: The lattices of some programs can contain multiple connected beam lines or rings. For example, an injection line connected to a storage ring connected to X-ray beam lines. Each line or ring is called a **branch**. In the above example, the injection line is one branch, the storage ring another branch, and each X-ray beam line is a branch. + +- **Global coordinate system**: The **global** coordinate system is a coordinate system that is used to describe the position and orientation of machine elements in space. That is, the **global** coordinate system is fixed with respect to the building or room where the machine is placed independent of the machine itself. + +- **Lattice coordinate system**: The curvilinear coordinate system whose "longitudinal" coordinate (**s**) typically runs through the nominal centers of the elements in the machine. The **lattice** coordinate system is often used to describe particle positions. + +- **Macro-particle**: Macro-particles are simulation particles that represent multiple real particles. The number of real particles that a macro-particle represents affects the calculation of the field due to a macro-particle but does not affect tracking. + +- **Particle coordinate system**: The coordinate system with respect to which particles positions and momenta are given. Some programs use the **global coordinate system** as the **particle coordinate system** while other programs use a coordinate system that is derived from the curvilinear **lattice coordinate system**. + +- **Polar coordinates**: **Polar** coordinates are **(r, theta, phi)** where **r** is the radius, **theta** is the angle from the **z** or **s** axis, and **phi** is the projected azimuthal angle in the **(x, y)** plane. + +- **Particle Group**: The **Particle Group** is a group for specifying a set of particles such as the particles in a bunch. The Beam Physics extension defines a standard for the **Particle Group** as discussed below. + +Notes: +------ + +- When using the **lattice** coordinate system, the `position` coordinates are **(x, y, s)** or **(x, y, z)** where, nominally, **x** is the "horizontal" component, **y** is the "vertical" coordinate, and **s** or **z** is the lattice longitudinal coordinate. + +Additional File Root Group (Path `/`) Attributes +------------------------------------------------ + +The following records are defined for the file root group. + +- `fileType` + - type: Optional *(string)* + - description: The type of data being stored in the file. If present, must be set to `openPMD`. This attribute is used in systems where different data files can contain different types of data and allows for quick identification of the what type of data is in a given file. + +- `latticeName` + - type: Optional *(string)* + - description: The name of the lattice. + +- `latticeFile` + - type: Optional *(string)* + - description: The location of the root lattice file. + +Particle Group Standard +======================= + +The **Particle Group** is a group for specifying a set of particles such as the particles in a bunch. Multiple **Particle Groups** can be defined in a file. The path for a **Particle Group** is given by the **basePath** and **particlesPath** attributes in the file root group as discussed in the base OpenPMD standard. For example, if **basePath** is `/data/%T/`, and **ParticlesPath** is `particles/`, then **Particle Groups** paths would be of the form `/data/%T/particles/` where `%T` is an integer. EG: `/data/37/particles/`. + + +`Particle Group` Attributes +-------------------------------- + +For each **particle group** the following attributes are defined: + +- `chargeLive` + - type: Optional *(real)* + - description: The total charge of all the live particles. + +- `chargeUnitSI` + - type: *(real)*. Only required if `chargeLive` or `totalCharge` is present. + - description: Unit conversion factor to multiply `chargeLive` or `totalCharge` by in order to convert to SI units. + +- `latticeElementName` + - type: Optional *(string)* + - description: The name of the lattice element the particle are in. This only makes sense if all particles are in the same element. [Keep in mind that if particles are lost and the lost particles are also included in the file, not all particles may be in the same element.] Also see: `locationInElement`. + +- `numParticles` + - type: Required *(int)* + - description: The number of particles in the group. + +- `speciesType` + - type: Required *(string)* + - description: The name of the particle species. Species names must conform to the `SpeciesType` extension. + - Example: `electron`, `H2O`. + +- `totalCharge` + - type: Optional *(real)* + - description: The total charge of all the particles alive and dead. + +Per-Particle Records of the `Particle Group` +-------------------------------------------- + +The following records store data on a particle-by-particle basis. + +- `branchIndex/` + - type Optional *(int)* + - description: The unique index number assigned to the lattice branch the particle is in. + +- `chargeState/` + - type: Optional *(int)* + - description: The charge state of the particles. Used for atoms and molecules. Not needed if the charge can be computed from knowledge of the `SpeciesType` (That is, is a fundamental particle). Also see `weight`. + +- `electricField/` + - type: Optional 3-vector *(real)* + - description: External electric field at the particle. + - components: (`x`, `y`, `z`). + + - `elementIndex/` + - type Optional *(int)* + - description: The unique index number assigned to the lattice element the particle is in. + +- `magneticField/` + - type: Optional 3-vector *(real)* + - description: External magnetic field at the particle. + - components: (`x`, `y`, `z`). + +- `locationInElement` + - type Optional *(integer)* + - description: The program generating the data file may model a lattice element using a "hard edge" model where the fringe fields at the ends of the element are modeled as having zero longitudinal length. In such a case, if a particle is at the end of the lattice element, it is important to know if the particle is outside of the fringe or if the particle is inside the fringe within the body of the element. Note that with a hard edge fringe, the longitudinal **s**-position does not necessarily provide enough information to determine where a particle is with respect to an edge field. Another situation where `locationInElement` is useful is with zero length elements that affect the particle transport (such as zero length multipole elements). If the program generating the data file does **not** use any hard edge models or zero length non-marker elements, `locationInElement` should not be present since this parameter is meaningless in this case. + - Possible values: + - `-1`: Upstream end of element outside of the upstream fringe edge. + - `0`: Inside the element. + - `1`: Downstream end of the element outside the downstream fringe edge. + +- `momentum/` + - type: Optional 3-vector *(real)* + - description: The momentum vector of the particles relative to `momentumOffset` + - components: (`x`, `y`, `z`). + - true momentum = `momentum + momentumOffset` + +- `momentumOffset/` + - type: Optional 3-vector *(real)* + - description: Base momentum from which `momentum` is measured. That is, True momentum = `momentum + momentumOffset`. Assumed zero if not present. + - components: (`x`, `y`, `z`). + +- `photonPolarizationAmplitude/` + - type: Optional 2-vector *(real)* + - description: Polarization amplitude of the photon. + - components: (`x`, `y`). + +- `photonPolarizationPhase/` + - type: Optional 2-vector *(real)* + - description: Polarization phase of the photon. + - components: (`x`, `y`). + +- `sPosition` + - type: Optional *(real)* + - description: The value of the longitudinal position in the curvilinear lattice coordinate system. + +- `totalMomentum/` + - type: Optional *(real)* + - description: Total momentum relative to the totalMomentumOffset. That is, True total momentum = `totalMomentum + totalMomentumOffset`. Assumed zero if not present. + +- `totalMomentumOffset/` + - type: Optional *(real)* + - description: Base total momentum from which `totalMomentum` is measured. That is, True total momentum = `totalMomentum + totalMomentumOffset`. Some programs will use `totalMomentumOffset/` to store the **reference momentum** in which case `totalMomentum` will then be the deviation from the referece. + +- `particleCoordinatesToGlobalTransformation/` + - type: Optional group. + - description: Defines the transformation from the coordinates used to describe a particle to the **global** coordinate system. + - `R_frame`: + - Required 3-vector *(real)* Attribute + - description: Specifying the (`x`, `y`, `z`) position of the coordinate origin that the particles are measured with respect to in the **global** coordinate frame. + - `W_matrix`: + - Required 3 x 3 matrix *(real)* + - description: Dataset holding the 3x3 transformation matrix from coordinates to **global** + coordinates. + - Position Transformation: Position_global = W_matrix * (position + positionOffset) + R_frame + - Momentum transformation: Momentum_global = W_matrix * (momentum + momentumOffset) + +- `particleStatus/` + - type: Optional *(int)* + - description: Integer indicating whether a particle is "alive" or "dead" (for example, has hit the vacuum chamber wall). A value of one indicates the particle is alive and any other value indicates that the particle is dead. Programs are free to distinguish how a particle died by assigning different non-unit values to `particleStatus`. For example, a program might want to differentiate between particles that are dead due to hitting the side walls versus reversing the direction longitudinally in an RF cavity. + +- `pathLength/` + - type: Optional *(real)* + - description: Length that a particle has traveled. + +- `position/` + - type: Required 3-vector *(real)* + - components: (`x`, `y`, `z`) + - description: particle Position relative to the `positionOffset`. + That is, true position relative to the coordinate origin = `position + positionOffset`. + +- `positionOffset/` + - type: Optional 3-vector *(real)* + - description: Offset for each particle position component relative to the coordinate origin. Assumed zero if not present. + - components: (`x`, `y`, `z`) + +- `spin/` + - type: Optional 3-vector *(real)* + - description: Particle spin. + - components: (`x`, `y`, `z`) or (`r`, `theta`, `phi`). + +- `time/` + - type: Optional *(real)* + - description: Time relative to `timeOffset`. That is, absolute time = `time + timeOffset`. + +- `timeOffset/` + - type: Optional *(real)* + - description: Base time from which `time` is measured. That is, absolute time = `time + timeOffset`. Assumed zero if not present. Some programs will use the `timeOffset` to store the **reference time** in which case `time` will then be the deviation from the reference. + +- `velocity/` + - type: Optional 3-vector *(real)* + - description: (`x`, `y`, `z`) velocity vector. Meant to be used for photons where using `momentum` is not appropriate. + +- `weight/` + - type: Optional *(real)* + - description: If macro-particles are being simulated, the `weight` is the total charge of a macro-particle. This is proportional to the number of particles that a macro-particle represents. Also see `charge`. + + +Non Per-Particle Records of the `Particle Group` +------------------------------------------------ + +The following possible records of the `Particle Group` are for specifying properties of the entire group of particles. + +- `phaseSpaceFirstOrderMoment/` + - type: Optional 6-vector *(real)* + - description: First order beam moments of `(x, px, y, py, z, pz)`. + +- `phaseSpaceSecondOrderMoment/` + - type: Optional 6x6-matrix *(real)* + - description: Second order beam moments of `(x, px, y, py, z, pz)`. + +Particle Record Dataset Attributes +---------------------------------- + +The following attributes can be used with any dataset: + +- `minValue`: + - type: Optional *(real)* + - description: Minimum of the data. + +- `maxValue`: + - type: Optional *(real)* + - description: Maximum of the data. + +External Mesh Fields Groups +=========================== + +The **external mesh field group** is a group for specifying electric and/or magnetic fields, due to a lattice element, at regularly spaced grid points. For example, the fields due to an RF cavity or the fields due to a magnet. Multiple **external mesh field groups** can be defined in a file. The path for a **external mesh field group** is given by the **externalFieldPath** in the file root group: +- `externalFieldPath` + - type: Required if there are external mesh field group(s) *(string)* + - description: Base path to the external mesh field groups. Use the **%T** construct if there are multiple meshes present. + - example: `/ExternalFieldMesh/%T/`. Base paths to the external fields group, in this case, would be `/ExternalFieldMesh/1/`, etc. + - example: `/ExternalFieldMesh/`. In this case there is only one external fields group. + +Notes +----- + +- AC fields can be described using complex numbers. The actual field is the real part of + + Z * Exp[-2 * pi * I * (f * t + phi)] + +where `Z` is the field complex number, `f` is the Oscillation frequency, `t` is the time, and `phi0` is a reference time. + + +`External Fields Group` Attributes +---------------------------------- + +- `gridCurvatureRadius` + - type: Optional *(real)* + - description: Only used if `gridGeometry` is set to `rectangular`. A zero value (the default) indicates that the grid is rectilinear. A non-zero value indicates that the grid is curved. The curvature is in the **(x, z)** plane with positive **x** pointing away from the center of curvature if `gridCurvatureRadius` is positive and vice versa for negative values. `gridCurvatureRadius` is the radius for the lines **x = 0** at constant **y**. + +- `eleAnchorPt` + - type: Required *(string)* + - description: Point on the lattice element that the grid origin is referenced to. Possible values are: `beginning`, `center`, or `end`. The `beginning` point is at the entrance end of the element, the `center` point is at the center of the element and the `end` point is at the exit end of the element. All three points are on the reference orbit. + +- `fieldScale` + - type: Optional *(real)* + - description: A scale factor that is used to scale the fields. Default is 1. + +- `fundamentalFrequency` + - type: Optional *(real)* + - description: The fundamental RF frequency. Used for AC fields. + +- `gridGeometry` + - type: Required *(string)* + - description: Values are `rectangular` or `cylindrical`. The `rectangular` value is for a **(x, y, z)** grid with field components **(Bx, By, Bz)** and/or **(Ex, Ey, Ez)**. The `cylindrical` value is for a **(r, theta, z)** grid with field components **(Br, Btheta, Bz)** and/or **(Er, Etheta, Ez)** field components. Note: If the grid size in the `theta` direction is 1, the field is taken to be axially symmetric. + + +- `gridSpacing` + - type: Required 3-vector *(real)* + - description: Spacing between grid points. + +- `gridLowerBound` + - type: Required 3-vector *(int)* + - description: Lower bound of the grid index. Note: The grid upper bound will be `gridLowerBound` + `gridSize` - 1. + +- `gridSize` + - type: Required 3-vector *(int)* + - description: Size of the grid. + +- `gridOriginOffset` + - type: Required 3-vector *(real)* + - description: distance from `eleAnchorPt` to the grid origin point. + + +- `harmonic` + - type: Required *(int)* + - description: Harmonic number of the fundamental frequency. A value of zero implies a DC field. + +- `name` + - type: Optional *(string)* + - description: Name to be used to identify the grid. + +- `RFphase` + - type Required if `harmonic` is not zero *(real)* + - description: Phase offset for oscillating fields. See the note above. Default is zero. + + +Per-grid `External Fields Group` Records for `(x, y, z)` Grids +-------------------------------------------------------------- + +- `Bx`, `By`, `Bz` + - type: Optional (Either all must be present or all must be absent) *(complex)* + - description: Magnetic field components using rectangular coordinates. Used with `gridGeometry` set to `rectangular`. If the field is DC (`harmonic` is zero), only the real component should be nonzero. + + +- `Ex`, `Ey`, `Ez` + - type: Optional (Either all must be present or all must be absent) *(complex)* + - description: Electric field components. Used with `gridGeometry` set to `xyz`.If the field is DC, only the real component should be nonzero. + + +Per-grid `External Fields Group` Records for `(r, theta, z)` Grids +------------------------------------------------------------------ + +Note: If the grid size in the `theta` direction is 1, the field is taken to be axially symmetric. + + +- `Br`, `Btheta`, `Bz` + - type: Optional (Either all must be present or all must be absent) *(complex)* + - description: Magnetic field components using cylindrical coordinates. Used with `gridGeometry` set to `cylindrical`. If the field is DC (`harmonic` is zero), only the real component should be nonzero. + + +- `Er`, `Etheta`, `Ez` + - type: Optional (Either all must be present or all must be absent) *(complex)* + - description: Electric field components. Used with `gridGeometry` set to `rotationally_symmetric_rz`. If the field is DC, only the real component should be nonzero. From 2dcbf0be9a4133da2a161504d59225dff1f5f320 Mon Sep 17 00:00:00 2001 From: David Sagan Date: Fri, 20 Dec 2019 09:30:21 -0500 Subject: [PATCH 58/73] Changed standard on how complex numbers are stored. --- EXT_BeamPhysics.md | 2 +- EXT_BeamPhysics.md~ | 9 +++++---- 2 files changed, 6 insertions(+), 5 deletions(-) diff --git a/EXT_BeamPhysics.md b/EXT_BeamPhysics.md index 8771e38..d490cff 100644 --- a/EXT_BeamPhysics.md +++ b/EXT_BeamPhysics.md @@ -261,7 +261,7 @@ Notes where `Z` is the complex field, `f` is the Oscillation frequency, `t` is the time, and `t0` is a reference time. -Software that writes complex data must use native complex storage for formats that support complex numbers. For formats that do not have native complex support (for example, HDF5), complex numbers are to be stored using subgroups labeled `r` and `i` for real and imaginary respectively. +Note: To ensure portability, complex data types are to be stored in a group with datasets (or constant record components if the values are constant) labeled "re" for the real part and "im" for the imaginary part. Using "re" and "im" datasets is mandated even if the storage format supports native complex numbers. `External Fields Group` Attributes ---------------------------------- diff --git a/EXT_BeamPhysics.md~ b/EXT_BeamPhysics.md~ index 9b752be..8771e38 100644 --- a/EXT_BeamPhysics.md~ +++ b/EXT_BeamPhysics.md~ @@ -1,11 +1,11 @@ BeamPhysics Extension to the openPMD Standard for Describing Particle Beams, Photons, and External Fields ========================================================================================================= +openPMD extension name: `BeamPhysics` Overview -------- -The `BeamPhysics` extension to the openPMD standard is meant for describing particles and fields commonly encountered -in accelerator physics simulations. +The `BeamPhysics` extension to the openPMD standard is meant for describing particles and fields commonly encountered in accelerator physics simulations. How to Use this Extension ------------------------- @@ -257,10 +257,11 @@ Notes - AC fields can be described using complex numbers. The actual field is the real part of - Z * Exp[-2 * pi * I * (f * t + phi)] + Z * Exp[-2 pi i f * (t - t0)] -where `Z` is the field complex number, `f` is the Oscillation frequency, `t` is the time, and `phi0` is a reference time. +where `Z` is the complex field, `f` is the Oscillation frequency, `t` is the time, and `t0` is a reference time. +Software that writes complex data must use native complex storage for formats that support complex numbers. For formats that do not have native complex support (for example, HDF5), complex numbers are to be stored using subgroups labeled `r` and `i` for real and imaginary respectively. `External Fields Group` Attributes ---------------------------------- From cdc26a67d9c39a8212aefbaf9741f7ab7752e662 Mon Sep 17 00:00:00 2001 From: David Sagan Date: Wed, 5 Feb 2020 10:13:30 -0500 Subject: [PATCH 59/73] Minor description updates. --- EXT_BeamPhysics.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/EXT_BeamPhysics.md b/EXT_BeamPhysics.md index d490cff..c8d6e07 100644 --- a/EXT_BeamPhysics.md +++ b/EXT_BeamPhysics.md @@ -28,7 +28,7 @@ Definitions - **Lattice coordinate system**: The curvilinear coordinate system whose "longitudinal" coordinate (**s**) typically runs through the nominal centers of the elements in the machine. The **lattice** coordinate system is often used to describe particle positions. -- **Macro-particle**: Macro-particles are simulation particles that represent multiple real particles. The number of real particles that a macro-particle represents affects the calculation of the field due to a macro-particle but does not affect tracking. +- **Macro-particle**: Macro-particles are simulation particles that represent multiple real particles. The number of real particles that a macro-particle represents affects the calculation of the field due to a macro-particle. - **Particle coordinate system**: The coordinate system with respect to which particles positions and momenta are given. Some programs use the **global coordinate system** as the **particle coordinate system** while other programs use a coordinate system that is derived from the curvilinear **lattice coordinate system**. @@ -36,6 +36,8 @@ Definitions - **Particle Group**: The **Particle Group** is a group for specifying a set of particles such as the particles in a bunch. The Beam Physics extension defines a standard for the **Particle Group** as discussed below. +- **Reference Time**, **Reference Energy**, etc. Some programs have a reference from which various quantities are measured. For example, the **Reference Position** may be defined as the position of the center of the bunch under consideration. + Notes: ------ @@ -205,7 +207,7 @@ The following records store data on a particle-by-particle basis. - `timeOffset/` - type: Optional *(real)* - - description: Base time from which `time` is measured. That is, absolute time = `time + timeOffset`. Assumed zero if not present. Some programs will use the `timeOffset` to store the **reference time** in which case `time` will then be the deviation from the reference. + - description: Base time from which `time` is measured. That is, absolute time = `time + timeOffset`. Assumed zero if not present. Some programs will use the `timeOffset` to store the **reference time** in which case `time` will then be the deviation from the reference. [Note: The **reference time** may depend upon the longitudinal position of a particle and so may be different for different particles.] - `velocity/` - type: Optional 3-vector *(real)* @@ -213,7 +215,7 @@ The following records store data on a particle-by-particle basis. - `weight/` - type: Optional *(real)* - - description: If macro-particles are being simulated, the `weight` is the total charge of a macro-particle. This is proportional to the number of particles that a macro-particle represents. Also see `charge`. + - description: Typically used when macro-particles are being simulated. The `weight` is a weighting factor to be used in calculations and will generally (but not necessarily) be proportional to the number of particles a macro-particle represents. For example, the `weight` may be the total charge of a macro-particle. Or the `weight` could be the intensity (in, say, particles per second) represented by a macro-particle. Also see `charge`. Non Per-Particle Records of the `Particle Group` From 1db927705769e231e7d77cb41218aea000cc6c90 Mon Sep 17 00:00:00 2001 From: David Sagan Date: Wed, 5 Feb 2020 10:16:49 -0500 Subject: [PATCH 60/73] Minor cleanup. --- EXT_BeamPhysics.md~ | 346 -------------------------------------------- 1 file changed, 346 deletions(-) delete mode 100644 EXT_BeamPhysics.md~ diff --git a/EXT_BeamPhysics.md~ b/EXT_BeamPhysics.md~ deleted file mode 100644 index 8771e38..0000000 --- a/EXT_BeamPhysics.md~ +++ /dev/null @@ -1,346 +0,0 @@ -BeamPhysics Extension to the openPMD Standard for Describing Particle Beams, Photons, and External Fields -========================================================================================================= -openPMD extension name: `BeamPhysics` - -Overview --------- - -The `BeamPhysics` extension to the openPMD standard is meant for describing particles and fields commonly encountered in accelerator physics simulations. - -How to Use this Extension -------------------------- - -The `BeamPhysics` extension to the openPMD standard is indicated in a data file by the setting of the `openPMDextension` attribute: -``` - openPMDextension = BeamPhysics;SpeciesType -``` - -Note: The `SpeciesType` extension must be used when using the `BeamPhysics` extension. - -Definitions ------------ - -- **Lattice**: A **lattice** is the arrangement of elements in a machine such as a particle accelerator. - -- **Lattice branches**: The lattices of some programs can contain multiple connected beam lines or rings. For example, an injection line connected to a storage ring connected to X-ray beam lines. Each line or ring is called a **branch**. In the above example, the injection line is one branch, the storage ring another branch, and each X-ray beam line is a branch. - -- **Global coordinate system**: The **global** coordinate system is a coordinate system that is used to describe the position and orientation of machine elements in space. That is, the **global** coordinate system is fixed with respect to the building or room where the machine is placed independent of the machine itself. - -- **Lattice coordinate system**: The curvilinear coordinate system whose "longitudinal" coordinate (**s**) typically runs through the nominal centers of the elements in the machine. The **lattice** coordinate system is often used to describe particle positions. - -- **Macro-particle**: Macro-particles are simulation particles that represent multiple real particles. The number of real particles that a macro-particle represents affects the calculation of the field due to a macro-particle but does not affect tracking. - -- **Particle coordinate system**: The coordinate system with respect to which particles positions and momenta are given. Some programs use the **global coordinate system** as the **particle coordinate system** while other programs use a coordinate system that is derived from the curvilinear **lattice coordinate system**. - -- **Polar coordinates**: **Polar** coordinates are **(r, theta, phi)** where **r** is the radius, **theta** is the angle from the **z** or **s** axis, and **phi** is the projected azimuthal angle in the **(x, y)** plane. - -- **Particle Group**: The **Particle Group** is a group for specifying a set of particles such as the particles in a bunch. The Beam Physics extension defines a standard for the **Particle Group** as discussed below. - -Notes: ------- - -- When using the **lattice** coordinate system, the `position` coordinates are **(x, y, s)** or **(x, y, z)** where, nominally, **x** is the "horizontal" component, **y** is the "vertical" coordinate, and **s** or **z** is the lattice longitudinal coordinate. - -Additional File Root Group (Path `/`) Attributes ------------------------------------------------- - -The following records are defined for the file root group. - -- `fileType` - - type: Optional *(string)* - - description: The type of data being stored in the file. If present, must be set to `openPMD`. This attribute is used in systems where different data files can contain different types of data and allows for quick identification of the what type of data is in a given file. - -- `latticeName` - - type: Optional *(string)* - - description: The name of the lattice. - -- `latticeFile` - - type: Optional *(string)* - - description: The location of the root lattice file. - -Particle Group Standard -======================= - -The **Particle Group** is a group for specifying a set of particles such as the particles in a bunch. Multiple **Particle Groups** can be defined in a file. The path for a **Particle Group** is given by the **basePath** and **particlesPath** attributes in the file root group as discussed in the base OpenPMD standard. For example, if **basePath** is `/data/%T/`, and **ParticlesPath** is `particles/`, then **Particle Groups** paths would be of the form `/data/%T/particles/` where `%T` is an integer. EG: `/data/37/particles/`. - - -`Particle Group` Attributes --------------------------------- - -For each **particle group** the following attributes are defined: - -- `chargeLive` - - type: Optional *(real)* - - description: The total charge of all the live particles. - -- `chargeUnitSI` - - type: *(real)*. Only required if `chargeLive` or `totalCharge` is present. - - description: Unit conversion factor to multiply `chargeLive` or `totalCharge` by in order to convert to SI units. - -- `latticeElementName` - - type: Optional *(string)* - - description: The name of the lattice element the particle are in. This only makes sense if all particles are in the same element. [Keep in mind that if particles are lost and the lost particles are also included in the file, not all particles may be in the same element.] Also see: `locationInElement`. - -- `numParticles` - - type: Required *(int)* - - description: The number of particles in the group. - -- `speciesType` - - type: Required *(string)* - - description: The name of the particle species. Species names must conform to the `SpeciesType` extension. - - Example: `electron`, `H2O`. - -- `totalCharge` - - type: Optional *(real)* - - description: The total charge of all the particles alive and dead. - -Per-Particle Records of the `Particle Group` --------------------------------------------- - -The following records store data on a particle-by-particle basis. - -- `branchIndex/` - - type Optional *(int)* - - description: The unique index number assigned to the lattice branch the particle is in. - -- `chargeState/` - - type: Optional *(int)* - - description: The charge state of the particles. Used for atoms and molecules. Not needed if the charge can be computed from knowledge of the `SpeciesType` (That is, is a fundamental particle). Also see `weight`. - -- `electricField/` - - type: Optional 3-vector *(real)* - - description: External electric field at the particle. - - components: (`x`, `y`, `z`). - - - `elementIndex/` - - type Optional *(int)* - - description: The unique index number assigned to the lattice element the particle is in. - -- `magneticField/` - - type: Optional 3-vector *(real)* - - description: External magnetic field at the particle. - - components: (`x`, `y`, `z`). - -- `locationInElement` - - type Optional *(integer)* - - description: The program generating the data file may model a lattice element using a "hard edge" model where the fringe fields at the ends of the element are modeled as having zero longitudinal length. In such a case, if a particle is at the end of the lattice element, it is important to know if the particle is outside of the fringe or if the particle is inside the fringe within the body of the element. Note that with a hard edge fringe, the longitudinal **s**-position does not necessarily provide enough information to determine where a particle is with respect to an edge field. Another situation where `locationInElement` is useful is with zero length elements that affect the particle transport (such as zero length multipole elements). If the program generating the data file does **not** use any hard edge models or zero length non-marker elements, `locationInElement` should not be present since this parameter is meaningless in this case. - - Possible values: - - `-1`: Upstream end of element outside of the upstream fringe edge. - - `0`: Inside the element. - - `1`: Downstream end of the element outside the downstream fringe edge. - -- `momentum/` - - type: Optional 3-vector *(real)* - - description: The momentum vector of the particles relative to `momentumOffset` - - components: (`x`, `y`, `z`). - - true momentum = `momentum + momentumOffset` - -- `momentumOffset/` - - type: Optional 3-vector *(real)* - - description: Base momentum from which `momentum` is measured. That is, True momentum = `momentum + momentumOffset`. Assumed zero if not present. - - components: (`x`, `y`, `z`). - -- `photonPolarizationAmplitude/` - - type: Optional 2-vector *(real)* - - description: Polarization amplitude of the photon. - - components: (`x`, `y`). - -- `photonPolarizationPhase/` - - type: Optional 2-vector *(real)* - - description: Polarization phase of the photon. - - components: (`x`, `y`). - -- `sPosition` - - type: Optional *(real)* - - description: The value of the longitudinal position in the curvilinear lattice coordinate system. - -- `totalMomentum/` - - type: Optional *(real)* - - description: Total momentum relative to the totalMomentumOffset. That is, True total momentum = `totalMomentum + totalMomentumOffset`. Assumed zero if not present. - -- `totalMomentumOffset/` - - type: Optional *(real)* - - description: Base total momentum from which `totalMomentum` is measured. That is, True total momentum = `totalMomentum + totalMomentumOffset`. Some programs will use `totalMomentumOffset/` to store the **reference momentum** in which case `totalMomentum` will then be the deviation from the referece. - -- `particleCoordinatesToGlobalTransformation/` - - type: Optional group. - - description: Defines the transformation from the coordinates used to describe a particle to the **global** coordinate system. - - `R_frame`: - - Required 3-vector *(real)* Attribute - - description: Specifying the (`x`, `y`, `z`) position of the coordinate origin that the particles are measured with respect to in the **global** coordinate frame. - - `W_matrix`: - - Required 3 x 3 matrix *(real)* - - description: Dataset holding the 3x3 transformation matrix from coordinates to **global** - coordinates. - - Position Transformation: Position_global = W_matrix * (position + positionOffset) + R_frame - - Momentum transformation: Momentum_global = W_matrix * (momentum + momentumOffset) - -- `particleStatus/` - - type: Optional *(int)* - - description: Integer indicating whether a particle is "alive" or "dead" (for example, has hit the vacuum chamber wall). A value of one indicates the particle is alive and any other value indicates that the particle is dead. Programs are free to distinguish how a particle died by assigning different non-unit values to `particleStatus`. For example, a program might want to differentiate between particles that are dead due to hitting the side walls versus reversing the direction longitudinally in an RF cavity. - -- `pathLength/` - - type: Optional *(real)* - - description: Length that a particle has traveled. - -- `position/` - - type: Required 3-vector *(real)* - - components: (`x`, `y`, `z`) - - description: particle Position relative to the `positionOffset`. - That is, true position relative to the coordinate origin = `position + positionOffset`. - -- `positionOffset/` - - type: Optional 3-vector *(real)* - - description: Offset for each particle position component relative to the coordinate origin. Assumed zero if not present. - - components: (`x`, `y`, `z`) - -- `spin/` - - type: Optional 3-vector *(real)* - - description: Particle spin. - - components: (`x`, `y`, `z`) or (`r`, `theta`, `phi`). - -- `time/` - - type: Optional *(real)* - - description: Time relative to `timeOffset`. That is, absolute time = `time + timeOffset`. - -- `timeOffset/` - - type: Optional *(real)* - - description: Base time from which `time` is measured. That is, absolute time = `time + timeOffset`. Assumed zero if not present. Some programs will use the `timeOffset` to store the **reference time** in which case `time` will then be the deviation from the reference. - -- `velocity/` - - type: Optional 3-vector *(real)* - - description: (`x`, `y`, `z`) velocity vector. Meant to be used for photons where using `momentum` is not appropriate. - -- `weight/` - - type: Optional *(real)* - - description: If macro-particles are being simulated, the `weight` is the total charge of a macro-particle. This is proportional to the number of particles that a macro-particle represents. Also see `charge`. - - -Non Per-Particle Records of the `Particle Group` ------------------------------------------------- - -The following possible records of the `Particle Group` are for specifying properties of the entire group of particles. - -- `phaseSpaceFirstOrderMoment/` - - type: Optional 6-vector *(real)* - - description: First order beam moments of `(x, px, y, py, z, pz)`. - -- `phaseSpaceSecondOrderMoment/` - - type: Optional 6x6-matrix *(real)* - - description: Second order beam moments of `(x, px, y, py, z, pz)`. - -Particle Record Dataset Attributes ----------------------------------- - -The following attributes can be used with any dataset: - -- `minValue`: - - type: Optional *(real)* - - description: Minimum of the data. - -- `maxValue`: - - type: Optional *(real)* - - description: Maximum of the data. - -External Mesh Fields Groups -=========================== - -The **external mesh field group** is a group for specifying electric and/or magnetic fields, due to a lattice element, at regularly spaced grid points. For example, the fields due to an RF cavity or the fields due to a magnet. Multiple **external mesh field groups** can be defined in a file. The path for a **external mesh field group** is given by the **externalFieldPath** in the file root group: -- `externalFieldPath` - - type: Required if there are external mesh field group(s) *(string)* - - description: Base path to the external mesh field groups. Use the **%T** construct if there are multiple meshes present. - - example: `/ExternalFieldMesh/%T/`. Base paths to the external fields group, in this case, would be `/ExternalFieldMesh/1/`, etc. - - example: `/ExternalFieldMesh/`. In this case there is only one external fields group. - -Notes ------ - -- AC fields can be described using complex numbers. The actual field is the real part of - - Z * Exp[-2 pi i f * (t - t0)] - -where `Z` is the complex field, `f` is the Oscillation frequency, `t` is the time, and `t0` is a reference time. - -Software that writes complex data must use native complex storage for formats that support complex numbers. For formats that do not have native complex support (for example, HDF5), complex numbers are to be stored using subgroups labeled `r` and `i` for real and imaginary respectively. - -`External Fields Group` Attributes ----------------------------------- - -- `gridCurvatureRadius` - - type: Optional *(real)* - - description: Only used if `gridGeometry` is set to `rectangular`. A zero value (the default) indicates that the grid is rectilinear. A non-zero value indicates that the grid is curved. The curvature is in the **(x, z)** plane with positive **x** pointing away from the center of curvature if `gridCurvatureRadius` is positive and vice versa for negative values. `gridCurvatureRadius` is the radius for the lines **x = 0** at constant **y**. - -- `eleAnchorPt` - - type: Required *(string)* - - description: Point on the lattice element that the grid origin is referenced to. Possible values are: `beginning`, `center`, or `end`. The `beginning` point is at the entrance end of the element, the `center` point is at the center of the element and the `end` point is at the exit end of the element. All three points are on the reference orbit. - -- `fieldScale` - - type: Optional *(real)* - - description: A scale factor that is used to scale the fields. Default is 1. - -- `fundamentalFrequency` - - type: Optional *(real)* - - description: The fundamental RF frequency. Used for AC fields. - -- `gridGeometry` - - type: Required *(string)* - - description: Values are `rectangular` or `cylindrical`. The `rectangular` value is for a **(x, y, z)** grid with field components **(Bx, By, Bz)** and/or **(Ex, Ey, Ez)**. The `cylindrical` value is for a **(r, theta, z)** grid with field components **(Br, Btheta, Bz)** and/or **(Er, Etheta, Ez)** field components. Note: If the grid size in the `theta` direction is 1, the field is taken to be axially symmetric. - - -- `gridSpacing` - - type: Required 3-vector *(real)* - - description: Spacing between grid points. - -- `gridLowerBound` - - type: Required 3-vector *(int)* - - description: Lower bound of the grid index. Note: The grid upper bound will be `gridLowerBound` + `gridSize` - 1. - -- `gridSize` - - type: Required 3-vector *(int)* - - description: Size of the grid. - -- `gridOriginOffset` - - type: Required 3-vector *(real)* - - description: distance from `eleAnchorPt` to the grid origin point. - - -- `harmonic` - - type: Required *(int)* - - description: Harmonic number of the fundamental frequency. A value of zero implies a DC field. - -- `name` - - type: Optional *(string)* - - description: Name to be used to identify the grid. - -- `RFphase` - - type Required if `harmonic` is not zero *(real)* - - description: Phase offset for oscillating fields. See the note above. Default is zero. - - -Per-grid `External Fields Group` Records for `(x, y, z)` Grids --------------------------------------------------------------- - -- `Bx`, `By`, `Bz` - - type: Optional (Either all must be present or all must be absent) *(complex)* - - description: Magnetic field components using rectangular coordinates. Used with `gridGeometry` set to `rectangular`. If the field is DC (`harmonic` is zero), only the real component should be nonzero. - - -- `Ex`, `Ey`, `Ez` - - type: Optional (Either all must be present or all must be absent) *(complex)* - - description: Electric field components. Used with `gridGeometry` set to `xyz`.If the field is DC, only the real component should be nonzero. - - -Per-grid `External Fields Group` Records for `(r, theta, z)` Grids ------------------------------------------------------------------- - -Note: If the grid size in the `theta` direction is 1, the field is taken to be axially symmetric. - - -- `Br`, `Btheta`, `Bz` - - type: Optional (Either all must be present or all must be absent) *(complex)* - - description: Magnetic field components using cylindrical coordinates. Used with `gridGeometry` set to `cylindrical`. If the field is DC (`harmonic` is zero), only the real component should be nonzero. - - -- `Er`, `Etheta`, `Ez` - - type: Optional (Either all must be present or all must be absent) *(complex)* - - description: Electric field components. Used with `gridGeometry` set to `rotationally_symmetric_rz`. If the field is DC, only the real component should be nonzero. From 89c158d6cd2eae5b5819559a109fb339f8cd96e1 Mon Sep 17 00:00:00 2001 From: David Sagan Date: Tue, 10 Mar 2020 01:06:26 -0400 Subject: [PATCH 61/73] Change from using Bx, By, Bz to MagneticField/x, y, z. And similarly for the electric field. --- EXT_BeamPhysics.md | 48 ++++++++++++---------------------------------- 1 file changed, 12 insertions(+), 36 deletions(-) diff --git a/EXT_BeamPhysics.md b/EXT_BeamPhysics.md index c8d6e07..c0b108c 100644 --- a/EXT_BeamPhysics.md +++ b/EXT_BeamPhysics.md @@ -247,12 +247,12 @@ The following attributes can be used with any dataset: External Mesh Fields Groups =========================== -The **external mesh field group** is a group for specifying electric and/or magnetic fields, due to a lattice element, at regularly spaced grid points. For example, the fields due to an RF cavity or the fields due to a magnet. Multiple **external mesh field groups** can be defined in a file. The path for a **external mesh field group** is given by the **externalFieldPath** in the file root group: +The **external mesh field group** is a group for specifying electric and/or magnetic fields, due to a lattice element, at regularly spaced grid points. For example, the fields due to an RF cavity or the fields due to a DC magnet. Multiple **external mesh field groups** can be defined in a file. The path for a **external mesh field group** is given by the **externalFieldPath** in the file root group: - `externalFieldPath` - type: Required if there are external mesh field group(s) *(string)* - description: Base path to the external mesh field groups. Use the **%T** construct if there are multiple meshes present. - - example: `/ExternalFieldMesh/%T/`. Base paths to the external fields group, in this case, would be `/ExternalFieldMesh/1/`, etc. - - example: `/ExternalFieldMesh/`. In this case there is only one external fields group. + - example: `/ExternalFieldMesh/%T/`. Base paths to the external fields group, in this case, would be `/ExternalFieldMesh/01/`, etc. + - example: `/ExternalFieldMesh/`. In this case since there is no `%T` in the name, there is only one external fields group. Notes ----- @@ -270,7 +270,7 @@ Note: To ensure portability, complex data types are to be stored in a group with - `gridCurvatureRadius` - type: Optional *(real)* - - description: Only used if `gridGeometry` is set to `rectangular`. A zero value (the default) indicates that the grid is rectilinear. A non-zero value indicates that the grid is curved. The curvature is in the **(x, z)** plane with positive **x** pointing away from the center of curvature if `gridCurvatureRadius` is positive and vice versa for negative values. `gridCurvatureRadius` is the radius for the lines **x = 0** at constant **y**. + - description: Only used if using **(x, y, z)** field components. A zero value (the default) indicates that the grid is rectilinear. A non-zero value indicates that the grid is curved. The curvature is in the **(x, z)** plane with positive **x** pointing away from the center of curvature if `gridCurvatureRadius` is positive and vice versa for negative values. `gridCurvatureRadius` is the radius for the lines **x = 0** at constant **y**. - `eleAnchorPt` - type: Required *(string)* @@ -284,11 +284,6 @@ Note: To ensure portability, complex data types are to be stored in a group with - type: Optional *(real)* - description: The fundamental RF frequency. Used for AC fields. -- `gridGeometry` - - type: Required *(string)* - - description: Values are `rectangular` or `cylindrical`. The `rectangular` value is for a **(x, y, z)** grid with field components **(Bx, By, Bz)** and/or **(Ex, Ey, Ez)**. The `cylindrical` value is for a **(r, theta, z)** grid with field components **(Br, Btheta, Bz)** and/or **(Er, Etheta, Ez)** field components. Note: If the grid size in the `theta` direction is 1, the field is taken to be axially symmetric. - - - `gridSpacing` - type: Required 3-vector *(real)* - description: Spacing between grid points. @@ -305,7 +300,6 @@ Note: To ensure portability, complex data types are to be stored in a group with - type: Required 3-vector *(real)* - description: distance from `eleAnchorPt` to the grid origin point. - - `harmonic` - type: Required *(int)* - description: Harmonic number of the fundamental frequency. A value of zero implies a DC field. @@ -318,31 +312,13 @@ Note: To ensure portability, complex data types are to be stored in a group with - type Required if `harmonic` is not zero *(real)* - description: Phase offset for oscillating fields. See the note above. Default is zero. +Per-grid `External Fields Group` Records +---------------------------------------- -Per-grid `External Fields Group` Records for `(x, y, z)` Grids --------------------------------------------------------------- - -- `Bx`, `By`, `Bz` - - type: Optional (Either all must be present or all must be absent) *(complex)* - - description: Magnetic field components using rectangular coordinates. Used with `gridGeometry` set to `rectangular`. If the field is DC (`harmonic` is zero), only the real component should be nonzero. - - -- `Ex`, `Ey`, `Ez` - - type: Optional (Either all must be present or all must be absent) *(complex)* - - description: Electric field components. Used with `gridGeometry` set to `xyz`.If the field is DC, only the real component should be nonzero. - - -Per-grid `External Fields Group` Records for `(r, theta, z)` Grids ------------------------------------------------------------------- - -Note: If the grid size in the `theta` direction is 1, the field is taken to be axially symmetric. - - -- `Br`, `Btheta`, `Bz` - - type: Optional (Either all must be present or all must be absent) *(complex)* - - description: Magnetic field components using cylindrical coordinates. Used with `gridGeometry` set to `cylindrical`. If the field is DC (`harmonic` is zero), only the real component should be nonzero. - +- `magneticField` + - type: Optional 3-vector *(complex)* + - description: Magnetic field. If the field is DC, only the real part should be nonzero. The components of `magneticField` may be either **(x, y, z)** representing `Bx`, `By`, and `Bz` or **(r, theta, z)** representing `Br`, `Btheta`, and `Bz`. Each component contains a 3-dimensional table giving the field on a grid. When using **(x, y, z)** components, each component contains a **(x, y, z)** spatial grid. When using **(r, theta, z)** components, each component contains a **(r, theta, z)** spatial grid. In this case, if the grid size in the `theta` direction is 1, the field is taken to be axially symmetric. -- `Er`, `Etheta`, `Ez` - - type: Optional (Either all must be present or all must be absent) *(complex)* - - description: Electric field components. Used with `gridGeometry` set to `rotationally_symmetric_rz`. If the field is DC, only the real component should be nonzero. +- `electricField` + - type: Optional 3-vector *(complex)* + - description: Electric field. If the field is DC, only the real part should be nonzero. The components of `magneticField` may be either **(x, y, z)** representing `Ex`, `Ey`, and `Ez` or **(r, theta, z)** representing `Er`, `Etheta`, and `Ez`. Each component contains a 3-dimensional table giving the field on a grid. When using **(x, y, z)** components, each component contains a **(x, y, z)** spatial grid. When using **(r, theta, z)** components, each component contains a **(r, theta, z)** spatial grid. In this case, if the grid size in the `theta` direction is 1, the field is taken to be axially symmetric. From 55a3b82dbde2f49444e9c3794fc01eecd6b818dc Mon Sep 17 00:00:00 2001 From: David Sagan Date: Sat, 11 Apr 2020 03:54:20 -0400 Subject: [PATCH 62/73] Minor mod. --- EXT_BeamPhysics.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/EXT_BeamPhysics.md b/EXT_BeamPhysics.md index c0b108c..0938757 100644 --- a/EXT_BeamPhysics.md +++ b/EXT_BeamPhysics.md @@ -263,7 +263,7 @@ Notes where `Z` is the complex field, `f` is the Oscillation frequency, `t` is the time, and `t0` is a reference time. -Note: To ensure portability, complex data types are to be stored in a group with datasets (or constant record components if the values are constant) labeled "re" for the real part and "im" for the imaginary part. Using "re" and "im" datasets is mandated even if the storage format supports native complex numbers. +Note: To ensure portability, complex data types are to be stored in a group with datasets (or constant record components if the values are constant) labeled "r" for the real part and "i" for the imaginary part. Exception: If the storage format supports native complex numbers, use the native storage. Note: HDF5 in particular does not have native support for complex numbers. `External Fields Group` Attributes ---------------------------------- From eac41ef2609483ca2276dc0050b5164263b4d52e Mon Sep 17 00:00:00 2001 From: David Sagan Date: Wed, 15 Apr 2020 14:48:04 -0400 Subject: [PATCH 63/73] Added particleID field. --- EXT_BeamPhysics.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/EXT_BeamPhysics.md b/EXT_BeamPhysics.md index 0938757..6c9f915 100644 --- a/EXT_BeamPhysics.md +++ b/EXT_BeamPhysics.md @@ -142,6 +142,10 @@ The following records store data on a particle-by-particle basis. - description: Base momentum from which `momentum` is measured. That is, True momentum = `momentum + momentumOffset`. Assumed zero if not present. - components: (`x`, `y`, `z`). +-`particleID` + - type: Optional *(int)* + - description: Some programs give each particle an ID number. This field can be used to record that number. + - `photonPolarizationAmplitude/` - type: Optional 2-vector *(real)* - description: Polarization amplitude of the photon. From d649e31d40b8bc7badb6944c61cf9d87c194ab1a Mon Sep 17 00:00:00 2001 From: David Sagan Date: Wed, 15 Apr 2020 20:56:23 -0400 Subject: [PATCH 64/73] Modify "id" description. --- EXT_BeamPhysics.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/EXT_BeamPhysics.md b/EXT_BeamPhysics.md index 6c9f915..f52083a 100644 --- a/EXT_BeamPhysics.md +++ b/EXT_BeamPhysics.md @@ -142,9 +142,9 @@ The following records store data on a particle-by-particle basis. - description: Base momentum from which `momentum` is measured. That is, True momentum = `momentum + momentumOffset`. Assumed zero if not present. - components: (`x`, `y`, `z`). --`particleID` +-`id` - type: Optional *(int)* - - description: Some programs give each particle an ID number. This field can be used to record that number. + - description: Some programs give each particle an ID number. This field can be used to record that number. The `id` parameter is defined in the openPMD base standard and is just mentioned here for completeness sake. See the openPMD base standard for more details. - `photonPolarizationAmplitude/` - type: Optional 2-vector *(real)* From ec66f04415fa89eb5138a6235abf40bedcc84387 Mon Sep 17 00:00:00 2001 From: David Sagan Date: Wed, 2 Sep 2020 14:01:39 -0400 Subject: [PATCH 65/73] Removed paragraph on how to store complex numbers (this is now in the base standard). --- EXT_BeamPhysics.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/EXT_BeamPhysics.md b/EXT_BeamPhysics.md index f52083a..8f36bd0 100644 --- a/EXT_BeamPhysics.md +++ b/EXT_BeamPhysics.md @@ -267,8 +267,6 @@ Notes where `Z` is the complex field, `f` is the Oscillation frequency, `t` is the time, and `t0` is a reference time. -Note: To ensure portability, complex data types are to be stored in a group with datasets (or constant record components if the values are constant) labeled "r" for the real part and "i" for the imaginary part. Exception: If the storage format supports native complex numbers, use the native storage. Note: HDF5 in particular does not have native support for complex numbers. - `External Fields Group` Attributes ---------------------------------- From 3cb59f41ce1bf3039eccde0ae812e5854b44efe9 Mon Sep 17 00:00:00 2001 From: David Sagan Date: Fri, 23 Oct 2020 15:35:41 -0400 Subject: [PATCH 66/73] Minor corrections --- EXT_BeamPhysics.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/EXT_BeamPhysics.md b/EXT_BeamPhysics.md index 8f36bd0..54c40e0 100644 --- a/EXT_BeamPhysics.md +++ b/EXT_BeamPhysics.md @@ -54,11 +54,11 @@ The following records are defined for the file root group. - `latticeName` - type: Optional *(string)* - - description: The name of the lattice. + - description: The name of the lattice. This name is a descriptive string. Some programs allow a descriptive string to be associated with the lattice. - `latticeFile` - type: Optional *(string)* - - description: The location of the root lattice file. + - description: The name of the root lattice file. This name may contain a path component. Particle Group Standard ======================= @@ -142,7 +142,7 @@ The following records store data on a particle-by-particle basis. - description: Base momentum from which `momentum` is measured. That is, True momentum = `momentum + momentumOffset`. Assumed zero if not present. - components: (`x`, `y`, `z`). --`id` +- `id` - type: Optional *(int)* - description: Some programs give each particle an ID number. This field can be used to record that number. The `id` parameter is defined in the openPMD base standard and is just mentioned here for completeness sake. See the openPMD base standard for more details. From 2c60d7c4a71a85f8076faf2afdcf49d5771d57dc Mon Sep 17 00:00:00 2001 From: David Sagan Date: Thu, 21 Oct 2021 00:28:42 -0400 Subject: [PATCH 67/73] Make storage clearer. --- EXT_BeamPhysics.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/EXT_BeamPhysics.md b/EXT_BeamPhysics.md index 54c40e0..5b28c3a 100644 --- a/EXT_BeamPhysics.md +++ b/EXT_BeamPhysics.md @@ -235,7 +235,7 @@ The following possible records of the `Particle Group` are for specifying proper - type: Optional 6x6-matrix *(real)* - description: Second order beam moments of `(x, px, y, py, z, pz)`. -Particle Record Dataset Attributes +Record Dataset Attributes ---------------------------------- The following attributes can be used with any dataset: @@ -248,6 +248,10 @@ The following attributes can be used with any dataset: - type: Optional *(real)* - description: Maximum of the data. +- `gridDataOrder`: + - type: Optional *(string)* + - description: Used with HDF5 and any other storage medium where the storage order of multidimensional arrays can vary depending upon the language of the code interfaced to the API of the storage medium. Possible values are "C" indicating row major storage or "F" indicating column major order. Default if not present or blank is "F". + External Mesh Fields Groups =========================== From 9b86b293159f6d100e92ee37428938b3a6eab6eb Mon Sep 17 00:00:00 2001 From: David Sagan Date: Tue, 24 May 2022 17:00:28 -0400 Subject: [PATCH 68/73] Now particleStatus of zero indicates particle is waiting to be emitted. --- EXT_BeamPhysics.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/EXT_BeamPhysics.md b/EXT_BeamPhysics.md index 5b28c3a..c865393 100644 --- a/EXT_BeamPhysics.md +++ b/EXT_BeamPhysics.md @@ -183,7 +183,7 @@ The following records store data on a particle-by-particle basis. - `particleStatus/` - type: Optional *(int)* - - description: Integer indicating whether a particle is "alive" or "dead" (for example, has hit the vacuum chamber wall). A value of one indicates the particle is alive and any other value indicates that the particle is dead. Programs are free to distinguish how a particle died by assigning different non-unit values to `particleStatus`. For example, a program might want to differentiate between particles that are dead due to hitting the side walls versus reversing the direction longitudinally in an RF cavity. + - description: Integer indicating whether a particle is "alive" or "dead" (for example, has hit the vacuum chamber wall). A value of one indicates the particle is alive. A value of zero indicates the particle is within the body of a material (EG: cathode emitter) waiting to be emitted. Any other value indicates that the particle is dead. Programs are free to distinguish how a particle died by assigning different non-unit values to `particleStatus`. For example, a program might want to differentiate between particles that are dead due to hitting the side walls versus reversing the direction longitudinally in an RF cavity. - `pathLength/` - type: Optional *(real)* From 8fdaaeec0c0149f5fe83dfbe37878654b7c92c72 Mon Sep 17 00:00:00 2001 From: David Sagan Date: Sun, 5 Nov 2023 22:54:38 -0500 Subject: [PATCH 69/73] Added RFphase parameter and cleaned up the descriptions. --- EXT_BeamPhysics.md | 50 +++++++++++++++++++++++++++++++--------------- 1 file changed, 34 insertions(+), 16 deletions(-) diff --git a/EXT_BeamPhysics.md b/EXT_BeamPhysics.md index c865393..85d8cb6 100644 --- a/EXT_BeamPhysics.md +++ b/EXT_BeamPhysics.md @@ -34,7 +34,7 @@ Definitions - **Polar coordinates**: **Polar** coordinates are **(r, theta, phi)** where **r** is the radius, **theta** is the angle from the **z** or **s** axis, and **phi** is the projected azimuthal angle in the **(x, y)** plane. -- **Particle Group**: The **Particle Group** is a group for specifying a set of particles such as the particles in a bunch. The Beam Physics extension defines a standard for the **Particle Group** as discussed below. +- **Particle Group**: The **Particle Group** is a group for specifying a set of particles such as the particles in a bunch. The Beam Physics extension defines a standard for the **Particle Group** as discussed below. - **Reference Time**, **Reference Energy**, etc. Some programs have a reference from which various quantities are measured. For example, the **Reference Position** may be defined as the position of the center of the bunch under consideration. @@ -58,12 +58,12 @@ The following records are defined for the file root group. - `latticeFile` - type: Optional *(string)* - - description: The name of the root lattice file. This name may contain a path component. + - description: The name of the root lattice file. This name may contain a path component. Particle Group Standard ======================= -The **Particle Group** is a group for specifying a set of particles such as the particles in a bunch. Multiple **Particle Groups** can be defined in a file. The path for a **Particle Group** is given by the **basePath** and **particlesPath** attributes in the file root group as discussed in the base OpenPMD standard. For example, if **basePath** is `/data/%T/`, and **ParticlesPath** is `particles/`, then **Particle Groups** paths would be of the form `/data/%T/particles/` where `%T` is an integer. EG: `/data/37/particles/`. +The **Particle Group** is a group for specifying a set of particles such as the particles in a bunch. Multiple **Particle Groups** can be defined in a file. The path for a **Particle Group** is given by the **basePath** and **particlesPath** attributes in the file root group as discussed in the base OpenPMD standard. For example, if **basePath** is `/data/%T/`, and **ParticlesPath** is `particles/`, then **Particle Groups** paths would be of the form `/data/%T/particles/` where `%T` is an integer. EG: `/data/37/particles/`. `Particle Group` Attributes @@ -126,7 +126,7 @@ The following records store data on a particle-by-particle basis. - `locationInElement` - type Optional *(integer)* - description: The program generating the data file may model a lattice element using a "hard edge" model where the fringe fields at the ends of the element are modeled as having zero longitudinal length. In such a case, if a particle is at the end of the lattice element, it is important to know if the particle is outside of the fringe or if the particle is inside the fringe within the body of the element. Note that with a hard edge fringe, the longitudinal **s**-position does not necessarily provide enough information to determine where a particle is with respect to an edge field. Another situation where `locationInElement` is useful is with zero length elements that affect the particle transport (such as zero length multipole elements). If the program generating the data file does **not** use any hard edge models or zero length non-marker elements, `locationInElement` should not be present since this parameter is meaningless in this case. - - Possible values: + - Possible values: - `-1`: Upstream end of element outside of the upstream fringe edge. - `0`: Inside the element. - `1`: Downstream end of the element outside the downstream fringe edge. @@ -176,7 +176,7 @@ The following records store data on a particle-by-particle basis. - description: Specifying the (`x`, `y`, `z`) position of the coordinate origin that the particles are measured with respect to in the **global** coordinate frame. - `W_matrix`: - Required 3 x 3 matrix *(real)* - - description: Dataset holding the 3x3 transformation matrix from coordinates to **global** + - description: Dataset holding the 3x3 transformation matrix from coordinates to **global** coordinates. - Position Transformation: Position_global = W_matrix * (position + positionOffset) + R_frame - Momentum transformation: Momentum_global = W_matrix * (momentum + momentumOffset) @@ -235,7 +235,7 @@ The following possible records of the `Particle Group` are for specifying proper - type: Optional 6x6-matrix *(real)* - description: Second order beam moments of `(x, px, y, py, z, pz)`. -Record Dataset Attributes +Particle Record Dataset Attributes ---------------------------------- The following attributes can be used with any dataset: @@ -267,9 +267,9 @@ Notes - AC fields can be described using complex numbers. The actual field is the real part of - Z * Exp[-2 pi i f * (t - t0)] + Z * Exp[-2 pi i (f * t + RFphase)] -where `Z` is the complex field, `f` is the Oscillation frequency, `t` is the time, and `t0` is a reference time. +where `Z` is the complex field, `f` is the Oscillation frequency, `t` is the time, and `RFphase` is a reference phase. `External Fields Group` Attributes ---------------------------------- @@ -290,9 +290,9 @@ where `Z` is the complex field, `f` is the Oscillation frequency, `t` is the tim - type: Optional *(real)* - description: The fundamental RF frequency. Used for AC fields. -- `gridSpacing` - - type: Required 3-vector *(real)* - - description: Spacing between grid points. +- `gridGeometry` + - type: Required *(string)* + - description: The type of coordinate system being used. Must be set to either `rectangular` which specifies fields using **(x, y, z)**, or `cylindrical` which uses coordinates **(r, theta, z)**. - `gridLowerBound` - type: Required 3-vector *(int)* @@ -302,9 +302,13 @@ where `Z` is the complex field, `f` is the Oscillation frequency, `t` is the tim - type: Required 3-vector *(int)* - description: Size of the grid. +- `gridSpacing` + - type: Required 3-vector *(real)* + - description: Spacing between grid points. + - `gridOriginOffset` - type: Required 3-vector *(real)* - - description: distance from `eleAnchorPt` to the grid origin point. + - Description: Cartesian (`x`, `y`, `z`) distance from `eleAnchorPt` to the grid origin point. Notice that Cartesian coordinates are used here independent of the coordinates used for the field grid itself. - `harmonic` - type: Required *(int)* @@ -315,16 +319,30 @@ where `Z` is the complex field, `f` is the Oscillation frequency, `t` is the tim - description: Name to be used to identify the grid. - `RFphase` - - type Required if `harmonic` is not zero *(real)* - - description: Phase offset for oscillating fields. See the note above. Default is zero. + - type Optional *(real)* + - description: Phase offset for oscillating fields. See the equation above. Default is zero. Note that the units are `2 pi` and not `radians`. Per-grid `External Fields Group` Records ---------------------------------------- +**Note:** Each field component contains a 3-dimensional table giving the field on a grid. When using **(x, y, z)** field components, each component contains an **(x, y, z)** spatial grid. When using **(r, theta, z)** field components, each component contains an **(r, theta, z)** spatial grid. In this case, if the grid size in the `theta` direction is 1, the field is taken to be axially symmetric. + +**Note:** If any field component is not present in the data file, the value of that component will be taken as zero everywhere. + - `magneticField` - type: Optional 3-vector *(complex)* - - description: Magnetic field. If the field is DC, only the real part should be nonzero. The components of `magneticField` may be either **(x, y, z)** representing `Bx`, `By`, and `Bz` or **(r, theta, z)** representing `Br`, `Btheta`, and `Bz`. Each component contains a 3-dimensional table giving the field on a grid. When using **(x, y, z)** components, each component contains a **(x, y, z)** spatial grid. When using **(r, theta, z)** components, each component contains a **(r, theta, z)** spatial grid. In this case, if the grid size in the `theta` direction is 1, the field is taken to be axially symmetric. + - description: Magnetic field. +If the field is DC, only the real part should be nonzero. +The components of `magneticField` will be either **(x, y, z)** representing `Bx`, `By`, and `Bz` or **(r, theta, z)** representing `Br`, `Btheta`, and `Bz` depending upon the setting of `gridGeomety`. +Each component contains a 3-dimensional table giving the field on a grid. +When using **(x, y, z)** components, each component contains a **(x, y, z)** spatial grid. +When using **(r, theta, z)** components, each component contains a **(r, theta, z)** spatial grid. In this case, if the grid size in the `theta` direction is 1, the field is taken to be axially symmetric. - `electricField` - type: Optional 3-vector *(complex)* - - description: Electric field. If the field is DC, only the real part should be nonzero. The components of `magneticField` may be either **(x, y, z)** representing `Ex`, `Ey`, and `Ez` or **(r, theta, z)** representing `Er`, `Etheta`, and `Ez`. Each component contains a 3-dimensional table giving the field on a grid. When using **(x, y, z)** components, each component contains a **(x, y, z)** spatial grid. When using **(r, theta, z)** components, each component contains a **(r, theta, z)** spatial grid. In this case, if the grid size in the `theta` direction is 1, the field is taken to be axially symmetric. + - description: Electric field. +If the field is DC, only the real part should be nonzero. +The components of `magneticField` may be either **(x, y, z)** representing `Ex`, `Ey`, and `Ez` or **(r, theta, z)** representing `Er`, `Etheta`, and `Ez` depending upon the setting of `gridGeomety`. +Each component contains a 3-dimensional table giving the field on a grid. +When using **(x, y, z)** components, each component contains a **(x, y, z)** spatial grid. +When using **(r, theta, z)** components, each component contains a **(r, theta, z)** spatial grid. In this case, if the grid size in the `theta` direction is 1, the field is taken to be axially symmetric. From bd2a5e517f45669e300920ebc4fb6a27bb4f956f Mon Sep 17 00:00:00 2001 From: David Sagan Date: Sun, 5 Nov 2023 23:03:33 -0500 Subject: [PATCH 70/73] Fix typo --- EXT_BeamPhysics.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/EXT_BeamPhysics.md b/EXT_BeamPhysics.md index 85d8cb6..81d72e6 100644 --- a/EXT_BeamPhysics.md +++ b/EXT_BeamPhysics.md @@ -342,7 +342,7 @@ When using **(r, theta, z)** components, each component contains a **(r, theta, - type: Optional 3-vector *(complex)* - description: Electric field. If the field is DC, only the real part should be nonzero. -The components of `magneticField` may be either **(x, y, z)** representing `Ex`, `Ey`, and `Ez` or **(r, theta, z)** representing `Er`, `Etheta`, and `Ez` depending upon the setting of `gridGeomety`. +The components of `magneticField` will be either **(x, y, z)** representing `Ex`, `Ey`, and `Ez` or **(r, theta, z)** representing `Er`, `Etheta`, and `Ez` depending upon the setting of `gridGeomety`. Each component contains a 3-dimensional table giving the field on a grid. When using **(x, y, z)** components, each component contains a **(x, y, z)** spatial grid. When using **(r, theta, z)** components, each component contains a **(r, theta, z)** spatial grid. In this case, if the grid size in the `theta` direction is 1, the field is taken to be axially symmetric. From 7f78edfbb10529f7f81c47431bf7aeaf79b99700 Mon Sep 17 00:00:00 2001 From: David Sagan Date: Sun, 26 May 2024 23:14:14 -0400 Subject: [PATCH 71/73] Removed gridDataOrder and added axisLabels. --- EXT_BeamPhysics.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/EXT_BeamPhysics.md b/EXT_BeamPhysics.md index 81d72e6..9cb18fe 100644 --- a/EXT_BeamPhysics.md +++ b/EXT_BeamPhysics.md @@ -248,10 +248,6 @@ The following attributes can be used with any dataset: - type: Optional *(real)* - description: Maximum of the data. -- `gridDataOrder`: - - type: Optional *(string)* - - description: Used with HDF5 and any other storage medium where the storage order of multidimensional arrays can vary depending upon the language of the code interfaced to the API of the storage medium. Possible values are "C" indicating row major storage or "F" indicating column major order. Default if not present or blank is "F". - External Mesh Fields Groups =========================== @@ -322,6 +318,11 @@ where `Z` is the complex field, `f` is the Oscillation frequency, `t` is the tim - type Optional *(real)* - description: Phase offset for oscillating fields. See the equation above. Default is zero. Note that the units are `2 pi` and not `radians`. +- `axisLabels` + - type: Required *(string array)* + - description: Array of axis labels. See the OpenPMD standard for more details. For the fields here, and with Fortran-like ordering of the grid, the labels will be `["z", "y", "x"]` or `["z", "theta", "r"]`. +For C-like ordering of the grid, the labels will be in opposite order. + Per-grid `External Fields Group` Records ---------------------------------------- From dcdb987d60ca56b39034c9a947aad2f4b37213bf Mon Sep 17 00:00:00 2001 From: David Sagan Date: Mon, 27 May 2024 21:58:07 -0400 Subject: [PATCH 72/73] Minor correction. --- EXT_BeamPhysics.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/EXT_BeamPhysics.md b/EXT_BeamPhysics.md index 9cb18fe..ca33019 100644 --- a/EXT_BeamPhysics.md +++ b/EXT_BeamPhysics.md @@ -320,11 +320,12 @@ where `Z` is the complex field, `f` is the Oscillation frequency, `t` is the tim - `axisLabels` - type: Required *(string array)* - - description: Array of axis labels. See the OpenPMD standard for more details. For the fields here, and with Fortran-like ordering of the grid, the labels will be `["z", "y", "x"]` or `["z", "theta", "r"]`. + - description: Array of axis labels. See the OpenPMD standard for more details. +For the fields here, and with Fortran-like ordering of the grid, the labels will be `["z", "y", "x"]` or `["z", "theta", "r"]`. For C-like ordering of the grid, the labels will be in opposite order. -Per-grid `External Fields Group` Records ----------------------------------------- +`External Fields Group` Records +------------------------------- **Note:** Each field component contains a 3-dimensional table giving the field on a grid. When using **(x, y, z)** field components, each component contains an **(x, y, z)** spatial grid. When using **(r, theta, z)** field components, each component contains an **(r, theta, z)** spatial grid. In this case, if the grid size in the `theta` direction is 1, the field is taken to be axially symmetric. From d5bc4a028eff848f51c786301c2995210dccdf94 Mon Sep 17 00:00:00 2001 From: David Sagan Date: Wed, 29 May 2024 19:33:27 -0400 Subject: [PATCH 73/73] Revert axisLabels back up one level. --- EXT_BeamPhysics.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/EXT_BeamPhysics.md b/EXT_BeamPhysics.md index ca33019..8ff87bb 100644 --- a/EXT_BeamPhysics.md +++ b/EXT_BeamPhysics.md @@ -318,6 +318,7 @@ where `Z` is the complex field, `f` is the Oscillation frequency, `t` is the tim - type Optional *(real)* - description: Phase offset for oscillating fields. See the equation above. Default is zero. Note that the units are `2 pi` and not `radians`. + - `axisLabels` - type: Required *(string array)* - description: Array of axis labels. See the OpenPMD standard for more details. @@ -348,3 +349,5 @@ The components of `magneticField` will be either **(x, y, z)** representing `Ex` Each component contains a 3-dimensional table giving the field on a grid. When using **(x, y, z)** components, each component contains a **(x, y, z)** spatial grid. When using **(r, theta, z)** components, each component contains a **(r, theta, z)** spatial grid. In this case, if the grid size in the `theta` direction is 1, the field is taken to be axially symmetric. + +