Ray
A Ray
is the data structure that represents a single ray in the Ray Tracing Module that is generated and traced by a RayTracingStudy. It can store data and auxiliary data that can modified along the trace via RayKernels and RayBCs.
The discussion of how to use and interact with a Ray
is summarized into the following sections:
Defining a Ray Trajectory: How to define a
Ray
trajectory for it to be traced using a RayTracingStudy.Modifying a Ray Trajectory: How to modify a
Ray
trajectory while it is being traced via RayKernels and RayBCs.Using Ray Data: How to best access and use the data stored on the
Ray
.Getting a Ray: How to obtain a
Ray
to be used for tracing.
Useful member variables available on the Ray
are:
currentPoint()
- The current point of theRay
. Before being traced, this is the starting point. While being traced, this is the furthest point that theRay
has travelled (during RayKernel execution, this is the end of the segment). After being traced, this is the point where theRay
was killed.currentElem()
- The current element that theRay
is in. Before being traced, this is the starting element of theRay
. During tracing during RayKernel execution, this is the element that the segment is in. During tracing during RayBC execution, this is the element that the RayBC is being applied to. At the end of tracing, this is the element that theRay
died in.currentIncomingSide()
- The current incoming side oncurrentElem()
that theRay
was incoming on. Before being traced, this is the side that theRay
will begin on (if any). During tracing, this is only valid when RayKernels are being executed. After tracing, this is not valid.direction()
- The current direction of theRay
trajectory.data()
- Access into the data stored on theRay
.auxData()
- Access into the auxiliary data stored on theRay
.distance()
- The total distance theRay
has traveled thus far.maxDistance()
- The user-set maximum distance that thisRay
can travel. When a user defines theRay
trajectory usingsetStartingEndPoint()
, this is set internally to the straight-line distance from the start point to the user-set end point.endSet()
- Whether or not the user defined the trajectory using thesetStartingEndPoint()
method. This identifies whether or notmaxDistance()
was set internally to ensure that theRay
ends at the user-defined end point.endPoint()
- The user-set end point if it was set viasetStartingEndPoint()
.shouldContinue()
- Whether or not theRay
should continue to be traced after RayKernels and RayBCs are executed.setShouldContinue()
- Makes it possible to set aRay
to be killed after RayKernels and RayBCs are executed.getInfo()
- Helper method for creating astd::string
with useful information about theRay
.
Defining a Ray Trajectory
A Ray
's trajectory defines where it is going to be traced by the RayTracingStudy. This description is only for defining a Ray
's trajectory before it is being traced. To change a Ray
's trajectory mid-trace, see Modifying a Ray Trajectory.
First, you must define the starting point for the Ray
. This is achieved via the setStart()
method, which takes as arguments a starting point, an optional starting element, and an optional incoming side.
A starting element is required for a Ray
to be traced, but there exist cases in which you will not initially set the starting element. For example, the RepeatableRayStudyBase will internally determine both the starting element and starting incoming side (if any) for a Ray
via a claiming process.
Next, you must define where the Ray
is to travel from its starting point. This is achieved by one of the following methods:
setStartingEndPoint()
- Takes as an argument the desired end point for theRay
. It will be traced until it hits said end point within the mesh (but it can be killed by RayKernels or RayBCs along the way). Internally, this is handled by settingmaxDistance()
to the straight-line distance from the start point to the end point.Ray
s initialized using this method that have end points on the boundary will not have RayBCs executed on them on the boundary. They will be killed internally before the execution of RayBCs.setStartingDirection()
- Takes as an argument the desired direction for theRay
to travel.Ray
s initialized by this method must be killed by either RayKernels, by a RayBCs, by the maximum distancemaxDistance()
, or by the RayTracingStudy maximum distance parameterray_max_distance
. If aRay
in this situation hits a boundary and is not killed, an error will be generated.setStationary()
- Sets the Ray to be stationary. That is, it will end as soon as it started. Can be useful for unit testing or for Rays that represent stationary particles.
If you utilize the setStartingDirection()
method, you may also utilize setMaxDistance()
to set the maximum distance that the Ray
is allowed to travel. If it reaches this distance, it will be killed after execution of RayKernels. If the Ray
was initialized using the setStartingEndPoint()
method, you cannot set the maximum distance for said Ray
because it was set internally to the straight-line distance from the start to the user-set end.
The generation of rays can easily become a very complicated task. When a Ray
is added to the buffer to be traced, it must be on the processor that its starting element is on, or if on a processor boundary, on a neighboring processor to the starting element. It is recommended that you first see if the RepeatableRayStudy is sufficient for the generation of Rays for your use case.
Modifying a Ray Trajectory
It is possible to modify the trajectory of a Ray
while it is being traced via RayKernels and RayBCs:
To modify the trajectory of a Ray
mid trace, see:
Changing the Ray Trajectory for changing a
Ray
's trajectory in a RayKernelChanging the Ray Trajectory for changing a
Ray
's trajectory in a RayBC
Using Ray Data
In its simplest form, Ray
data is a vector of arbitrarily sized data and auxiliary data that lives on the Ray
and remains until it is changed.
In order to ensure that said data is sized appropriately for the use case, a system exists to register the need for data in the RayTracingStudy. This guarantees that RayTracingStudy objects, all RayBC objects, and all RayKernel objects will have access to the data that they need on all Ray
s that are traced. This registration devises an index into the Ray
data and auxiliary data. For more information, see Ray Data Registration.
With a specific data or auxiliary data index, the data are accessed using the data()
and auxData()
member variables on the Ray
.
Getting a Ray
The RayTracingStudy has a "pool" of Ray
objects available for use. This pool allows for previously-allocated Ray
objects that are no longer in use to be reset and re-used without deallocating and allocating memory again. This pool is the only way to construct new Ray
objects.
For more information on the pool, see Ray Pool.