diff --git a/EXT_BeamPhysics.md b/EXT_BeamPhysics.md new file mode 100644 index 0000000..8ff87bb --- /dev/null +++ b/EXT_BeamPhysics.md @@ -0,0 +1,353 @@ +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. This name is a descriptive string. Some programs allow a descriptive string to be associated with the lattice. + +- `latticeFile` + - type: Optional *(string)* + - 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/`. + + +`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. 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)* + - 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 + RFphase)] + +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 +---------------------------------- + +- `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. + +- `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)* + - 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. + +- `gridSpacing` + - type: Required 3-vector *(real)* + - description: Spacing between grid points. + +- `gridOriginOffset` + - type: Required 3-vector *(real)* + - 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)* + - 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 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. + +`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` 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` 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. + +