Adding raytracing extension for X-rays and neutrons

EXT_BeamPhysics_PRAYTRACE.md

@@ -0,0 +1,171 @@
+Additional definitions for photon raytracing for BeamPhysics Extension of the openPMD Standard
+=========================================================================================================
+openPMD extension name: `Raytracing`
+
+Overview
+--------
+
+The `Raytracing` extension to the openPMD standard is meant for describing particles and fields commonly encountered in photon and neutron raytracing simulations.
+
+How to Use this Extension
+-------------------------
+
+The `Raytracing` extension to the openPMD standard is indicated in a data file by the setting of the `openPMDextension` attribute:
+```
+  openPMDextension = Raytracing;SpeciesType
+```
+
+Note: The `SpeciesType` extension must be used when using the `Raytracing` extension, setting it to either `photon` or `neutron`.
+
+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 beamline.
+
+- `latticeFile`
+  - type: Optional *(string)*
+  - description: The location of the root lattice file.
+
+- `particlesPath`
+  - type: Optional *(string)*
+  - value: `particles/rays/`
+  - description: name of the particles path
+
+Particle Group Standard
+=======================
+
+The **Particle Group** is a group for specifying a set of rays. 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/`, and **ParticlesPath** is `particles/rays/`, then **Particle Groups** paths would be of the form `/data/particles/rays`.
+
+In case of photon raytracing extension, the default **particlesPath** is `particles/rays/`. EG: `data/particles/rays/`.
+
+
+`Particle Group` Attributes
+--------------------------------
+
+For each **particle group** the following attributes are defined:
+
+- `numParticles`
+  - type: Required *(int)*
+  - description: The number of particles in the group.
+
+- `speciesType`
+  - type: Required *(string)*
+  - value: `photon`
+  - description: The name of the particle species. Species names must conform to the `SpeciesType` extension.
+
+Per-Particle Records of the `Particle Group`
+--------------------------------------------
+
+The following records store data on a particle-by-particle basis.
+
+- `direction`
+  - type: Required 3 x N-vector *(real)*
+  - components: numParticles columns and rows of (`x'`, `y'`, `z'`)
+  - description: `velocity` in beamphysics extension. 3 x N vector with rows being the direction in (`x`, `y`, `z`) respectively.
+
+- `neutronPolarization/`
+  - type: Optional 3 x N-vector *(real)*
+  - description: Polarization for neutrons.
+  - components: numParticles columns and rows of (`x`, `y`, `z`).
+
+- `wavelength/`
+  - type: Required 1 x N-vector *(real)*
+  - description: Wavelength of the N-th ray.
+
+- `opticalPath/`
+  - type: Optional 1 x N-vector *(real)*
+  - description: For photons, the accumulated flying distance for the ray from the source to the current beam position.
+
+- `rayTime/`
+  - type: Optional 1 x N-vector *(real)*
+  - description: For neutrons, the time w. r. t. emission of the neutron.
+
+- `weight/`
+  - type: Optional 1 x N-vector *(real)*
+  - description: Weight of the N-th particle.
+
+- `id/`
+  - type: Optional 1 x N-vector *(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.
+
+- `photonSPolarizationAmplitude/`
+  - type: Optional 3 x N-vector *(real)*
+  - description: Electric field amplitude of s- polarized photons.
+  - components: numParticles columns and rows of (`x`, `y`, `z`).
+
+- `photonSPolarizationPhase/`
+  - type: Optional 1 x N-vector *(real)*
+  - description: Electric field phase of s- polarized photons.
+  - components: numParticles of phase in [rad].
+
+- `photonPPolarizationAmplitude/`
+  - type: Optional 3 x N-vector *(real)*
+  - description: Electric field amplitude of p- polarized photons.
+  - components: numParticles columns and rows of (`x`, `y`, `z`).
+
+- `photonPPolarizationPhase/`
+  - type: Optional 1 x N-vector *(real)*
+  - description: Electric field phase of p- polarized photons.
+  - components: numParticles of phase in [rad].
+
+- `particleStatus/`
+    - type: Optional 1 x N-vector *(int)*
+    - description: Integer indicating whether N-th 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.
+
+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.
+
+Additional variables related to the coordinate system
+----------------------------------
+
+- `directionOfGravity`:
+  - type: Optional 3 x 1-vector *(real)*
+  - description: (`x`, `y`, `z`) unit vector pointing into the direction of gravity.
+
+- `horizontalCoordinate`:
+  - type: Optional 3 x 1-vector *(real)*
+  - description: (`x`, `y`, `z`) unit vector pointing into the horizontal direction.