Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
* Ported EXT_BeamPhysics.md from other branch. * Changes made per discussion on openPMD. * Minor update. * Minor typo fixes. * More reorg. * Minor edits. * Minor tweaks based upon comments from Axel and Remi. * Fix Typo * Very minor: Correct final "/" in names. * Minor name correction. * Minor mod * Fix typo in text. * Correct "attribute" in several places should have been "record". * Added particleStatus record * Update EXT_BeamPhysics.md * Merged pxType and pyType into pxyType * Simplified momentum * Minor styalistic edits. * Simplified position record. * "time", "refTime", and "time-refTime" are now "time" and "timeOffset". * Added external fields * Changed "weighting" to "weight" as per opemPMD issue #199. * more cleanup. * Remove redundant chargeDead. * Minor cleanup of particleStatus. * Reinstated elementIndex and locationInElement which were accedentially deleted. * Added numParticles attribute. * Now the components of momentum and velocity are x,y,z the same as other vectors. * Added chargeUnitSI attribute. * Minor spelling fix. * Change "charge" to "chargeState" as more accurate. * Corrected some typos and added the fileType attribute. * Removed reference energy and momentum records as well as total energy. * Minor doc update. * First pass at adding external mesh fields group. * more... * First pass at external fields definition. * More mesh field devel. * more... * Minor mod * minor change * minor change * more grid devel. * Removed speed dataset. * removed version number. * cosmetic change. * Cosmetic change. * Small stylistic changes. * Cosmetic change. * Cosmetic change. * Added note on complex storage. * Changed standard on how complex numbers are stored. * Minor description updates. * Minor cleanup. * Change from using Bx, By, Bz to MagneticField/x, y, z. And similarly for the electric field. * Minor mod. * Added particleID field. * Modify "id" description. * Removed paragraph on how to store complex numbers (this is now in the base standard). Co-authored-by: Christopher Mayes <cem52@cornell.edu>
- Loading branch information
1 parent
b602500
commit 70d06c8
Showing
1 changed file
with
326 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,326 @@ | ||
| 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. | ||
|
|
||
| - **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. | ||
|
|
||
| - **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: | ||
| ------ | ||
|
|
||
| - 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`). | ||
|
|
||
| -`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. | ||
|
|
||
| - `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. [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)* | ||
| - description: (`x`, `y`, `z`) velocity vector. Meant to be used for photons where using `momentum` is not appropriate. | ||
|
|
||
| - `weight/` | ||
| - type: Optional *(real)* | ||
| - 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` | ||
| ------------------------------------------------ | ||
|
|
||
| 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 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/01/`, etc. | ||
| - example: `/ExternalFieldMesh/`. In this case since there is no `%T` in the name, 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. | ||
|
|
||
| `External Fields Group` Attributes | ||
| ---------------------------------- | ||
|
|
||
| - `gridCurvatureRadius` | ||
| - type: Optional *(real)* | ||
| - 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)* | ||
| - 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. | ||
|
|
||
| - `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 | ||
| ---------------------------------------- | ||
|
|
||
| - `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. | ||
|
|
||
| - `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. |