From 328de46f079a5bcd9a5be92baaaabce2f5c7227c Mon Sep 17 00:00:00 2001 From: Aljosa Hafner Date: Thu, 2 Dec 2021 14:44:23 +0100 Subject: [PATCH 1/3] Adding raytracing extension for X-rays and neutrons --- EXT_BeamPhysics_PRAYTRACE.md | 171 +++++++++++++++++++++++++++++++++++ 1 file changed, 171 insertions(+) create mode 100644 EXT_BeamPhysics_PRAYTRACE.md diff --git a/EXT_BeamPhysics_PRAYTRACE.md b/EXT_BeamPhysics_PRAYTRACE.md new file mode 100644 index 0000000..c8d9763 --- /dev/null +++ b/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. From 7398eda38e0c3ac68d156fc487b5c0a672d5dd74 Mon Sep 17 00:00:00 2001 From: aljosahafner <51963146+aljosahafner@users.noreply.github.com> Date: Fri, 28 Jan 2022 13:32:29 +0100 Subject: [PATCH 2/3] Update EXT_BeamPhysics_PRAYTRACE.md Co-authored-by: Axel Huebl --- EXT_BeamPhysics_PRAYTRACE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/EXT_BeamPhysics_PRAYTRACE.md b/EXT_BeamPhysics_PRAYTRACE.md index c8d9763..d6ea069 100644 --- a/EXT_BeamPhysics_PRAYTRACE.md +++ b/EXT_BeamPhysics_PRAYTRACE.md @@ -74,7 +74,7 @@ In case of photon raytracing extension, the default **particlesPath** is `partic `Particle Group` Attributes --------------------------------- +--------------------------- For each **particle group** the following attributes are defined: From 09c0467e1883de1ca10403368d1191ad1d9d61b6 Mon Sep 17 00:00:00 2001 From: Aljosa Hafner Date: Fri, 28 Jan 2022 13:45:05 +0100 Subject: [PATCH 3/3] Cross-link to the new extension in STANDARD.md --- STANDARD.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/STANDARD.md b/STANDARD.md index 628ca16..0eecfa8 100644 --- a/STANDARD.md +++ b/STANDARD.md @@ -730,6 +730,8 @@ defined: - **ED-PIC**: electro-dynamic/static particle-in-cell codes, see [EXT_ED-PIC.md](EXT_ED-PIC.md). + +- **Raytracing**: photon and neutron raytracing extension, see [EXT_BeamPhysics_PRAYTRACE.md](EXT_BeamPhysics_PRAYTRACE.md) Extensions to similar domains such as fluid, finite-element or molecular-dynamics simulations, CCD images or other particle and/or mesh-based