- namesUnique names for the Rays
C++ Type:std::vector<std::string>
Controllable:No
Description:Unique names for the Rays
RepeatableRayStudy
A ray tracing study that generates rays from vector of user-input start points and end points/directions.
commentnote
The RepeatableRayStudy is meant to be the primary RayTracingStudy to be used for the majority of use cases and is not meant to be derived from! It is "repeatable" because it works with adaptivity and multiple executions (transients, on residual/Jacobian evaluations, etc). It does not require the user to have any knowledge of how to generate rays or determine on which processor and element element rays need to start depending on their starting point.
Defining the Rays
The following parameters must first be set:
"names": A list of unique names to identify the rays being generated.
"start_points": A list of points that the rays should start from.
When using RayKernels and RayBCs with the RepeatableRayStudy, you must specify which rays the RayKernels/RayBCs are applied to via their own "names" parameter. The names supplied to the RayKernels and RayBCs are the same as the names specified in your RepeatableRayStudy.
After setting these parameters, you must decide if you want to define the remainder of the trajectory by end points or by directions. This decision is significant.
schooltip
Defining a Ray trajectory by end points (set with the "end_points" parameter) is the recommended method for non-advanced cases. The rays will be traced until they reach the user-set end point. Example use cases of setting Ray trajectories via end points are line sources and line integrals, for which examples are found in Using Line Sources and Computing Line Integrals, respectively.
Defining By End Points
To define the remainder of the trajectory by end points, provide the points at which you want the rays to end in the "end_points" parameter. When the Ray end points are set, internally the tracer will set the max distance of each Ray individually such that they all end at the straight-line distance between the provided start point and the provided end point.
RayKernels and RayBCs can still end the rays earlier along their trajectory, but they are guaranteed to end once they hit either their end point or possibly sooner if the study's global maximum ray distance (the "ray_distance" parameter) is less than the distance from the start to end point.
Rays that are killed due to reaching their max distance (which is the case when they reach their end point) are killed before the execution of RayBCs. For example, if a Ray reaches its end point and said end point is on a boundary with RayBCs, the RayBCs will not be executed on the Ray.
commentnote
Rays that have had their trajectory set via end points are not allowed to have their trajectories modified mid-trace via RayKernels or RayBCs. For example, these rays cannot be reflected on boundaries via the ReflectRayBC. You must instead define rays by the "directions" parameter if you want them to be able to have their trajectories changed mid-trace.
Defining By Directions (Advanced Use)
The definition of Ray trajectory is considered advanced use because the user is responsible for ending the Ray by one of the following four methods:
Killing it with a RayKernel.
Setting a maximum distance that it is allowed to travel via the "max_distances" parameter.
Setting a maximum distance that all rays are allowed to travel via the "ray_distance" parameter.
To define the trajectory by directions, provide the directions at which you want the rays to travel in the "directions" parameter. These directions do not need to be normalized.
If the Ray intersects an external boundary and is not set to be killed and its trajectory is not changed, the tracer will error.
Setting Ray Data
For more advanced use, one can also register Ray data/auxiliary data and initialize it as desired. It is important that this is not necessary when using RayKernels that contribute to residuals or integrate along lines, as the Ray data management in those cases is handled under the hood.
Input Parameters
- execute_onTIMESTEP_ENDThe list of flag(s) indicating when this object should be executed, the available options include NONE, INITIAL, LINEAR, NONLINEAR, POSTCHECK, TIMESTEP_END, TIMESTEP_BEGIN, MULTIAPP_FIXED_POINT_END, MULTIAPP_FIXED_POINT_BEGIN, FINAL, CUSTOM.
Default:TIMESTEP_END
C++ Type:ExecFlagEnum
Controllable:No
Description:The list of flag(s) indicating when this object should be executed, the available options include NONE, INITIAL, LINEAR, NONLINEAR, POSTCHECK, TIMESTEP_END, TIMESTEP_BEGIN, MULTIAPP_FIXED_POINT_END, MULTIAPP_FIXED_POINT_BEGIN, FINAL, CUSTOM.
- prop_getter_suffixAn optional suffix parameter that can be appended to any attempt to retrieve/get material properties. The suffix will be prepended with a '_' character.
C++ Type:MaterialPropertyName
Controllable:No
Description:An optional suffix parameter that can be appended to any attempt to retrieve/get material properties. The suffix will be prepended with a '_' character.
- ray_distance1.79769e+308The maximum distance all Rays can travel
Default:1.79769e+308
C++ Type:double
Controllable:No
Description:The maximum distance all Rays can travel
- tolerate_failureFalseWhether or not to tolerate a ray tracing failure
Default:False
C++ Type:bool
Controllable:No
Description:Whether or not to tolerate a ray tracing failure
- use_internal_sidesetsFalseWhether or not to use internal sidesets for RayBCs in ray tracing
Default:False
C++ Type:bool
Controllable:No
Description:Whether or not to use internal sidesets for RayBCs in ray tracing
- use_interpolated_stateFalseFor the old and older state use projected material properties interpolated at the quadrature points. To set up projection use the ProjectedStatefulMaterialStorageAction.
Default:False
C++ Type:bool
Controllable:No
Description:For the old and older state use projected material properties interpolated at the quadrature points. To set up projection use the ProjectedStatefulMaterialStorageAction.
Optional Parameters
- allow_duplicate_execution_on_initialFalseIn the case where this UserObject is depended upon by an initial condition, allow it to be executed twice during the initial setup (once before the IC and again after mesh adaptivity (if applicable).
Default:False
C++ Type:bool
Controllable:No
Description:In the case where this UserObject is depended upon by an initial condition, allow it to be executed twice during the initial setup (once before the IC and again after mesh adaptivity (if applicable).
- allow_new_work_during_executionTrueWhether or not to allow the addition of new work to the work buffer during execution
Default:True
C++ Type:bool
Controllable:No
Description:Whether or not to allow the addition of new work to the work buffer during execution
- buffer_growth_multiplier2How much to grow a SendBuffer by if the buffer completely fills and dumps. Will max at send_buffer_size
Default:2
C++ Type:double
Controllable:No
Description:How much to grow a SendBuffer by if the buffer completely fills and dumps. Will max at send_buffer_size
- buffer_shrink_multiplier0.5Multiplier (between 0 and 1) to apply to the current buffer size if it is force dumped. Will stop at min_buffer_size.
Default:0.5
C++ Type:double
Controllable:No
Description:Multiplier (between 0 and 1) to apply to the current buffer size if it is force dumped. Will stop at min_buffer_size.
- chunk_size100The number of objects to process at one time during execution
Default:100
C++ Type:unsigned int
Controllable:No
Description:The number of objects to process at one time during execution
- clicks_per_communication10Iterations to wait before communicating
Default:10
C++ Type:unsigned int
Controllable:No
Description:Iterations to wait before communicating
- clicks_per_receive1Iterations to wait before checking for new objects
Default:1
C++ Type:unsigned int
Controllable:No
Description:Iterations to wait before checking for new objects
- clicks_per_root_communication10Iterations to wait before communicating with root
Default:10
C++ Type:unsigned int
Controllable:No
Description:Iterations to wait before communicating with root
- control_tagsAdds user-defined labels for accessing object parameters via control logic.
C++ Type:std::vector<std::string>
Controllable:No
Description:Adds user-defined labels for accessing object parameters via control logic.
- enableTrueSet the enabled status of the MooseObject.
Default:True
C++ Type:bool
Controllable:Yes
Description:Set the enabled status of the MooseObject.
- execution_order_group0Execution order groups are executed in increasing order (e.g., the lowest number is executed first). Note that negative group numbers may be used to execute groups before the default (0) group. Please refer to the user object documentation for ordering of user object execution within a group.
Default:0
C++ Type:int
Controllable:No
Description:Execution order groups are executed in increasing order (e.g., the lowest number is executed first). Note that negative group numbers may be used to execute groups before the default (0) group. Please refer to the user object documentation for ordering of user object execution within a group.
- force_postauxFalseForces the UserObject to be executed in POSTAUX
Default:False
C++ Type:bool
Controllable:No
Description:Forces the UserObject to be executed in POSTAUX
- force_preauxFalseForces the UserObject to be executed in PREAUX
Default:False
C++ Type:bool
Controllable:No
Description:Forces the UserObject to be executed in PREAUX
- force_preicFalseForces the UserObject to be executed in PREIC during initial setup
Default:False
C++ Type:bool
Controllable:No
Description:Forces the UserObject to be executed in PREIC during initial setup
- methodsmartThe algorithm to use
Default:smart
C++ Type:MooseEnum
Controllable:No
Description:The algorithm to use
- min_buffer_sizeThe initial size of the SendBuffer and the floor for shrinking it. This defaults to send_buffer_size if not set (i.e. the buffer won't change size)
C++ Type:unsigned int
Controllable:No
Description:The initial size of the SendBuffer and the floor for shrinking it. This defaults to send_buffer_size if not set (i.e. the buffer won't change size)
- send_buffer_size100The size of the send buffer
Default:100
C++ Type:unsigned int
Controllable:No
Description:The size of the send buffer
- use_displaced_meshFalseWhether or not this object should use the displaced mesh for computation. Note that in the case this is true but no displacements are provided in the Mesh block the undisplaced mesh will still be used.
Default:False
C++ Type:bool
Controllable:No
Description:Whether or not this object should use the displaced mesh for computation. Note that in the case this is true but no displacements are provided in the Mesh block the undisplaced mesh will still be used.
- work_buffer_typecircularThe work buffer type to use
Default:circular
C++ Type:MooseEnum
Controllable:No
Description:The work buffer type to use
Advanced Parameters
- always_cache_tracesFalseWhether or not to cache the Ray traces on every execution, primarily for use in output. Warning: this can get expensive very quick with a large number of rays!
Default:False
C++ Type:bool
Controllable:No
Description:Whether or not to cache the Ray traces on every execution, primarily for use in output. Warning: this can get expensive very quick with a large number of rays!
- aux_data_on_cache_tracesFalseWhether or not to also cache the Ray's aux data when caching its traces
Default:False
C++ Type:bool
Controllable:No
Description:Whether or not to also cache the Ray's aux data when caching its traces
- data_on_cache_tracesFalseWhether or not to also cache the Ray's data when caching its traces
Default:False
C++ Type:bool
Controllable:No
Description:Whether or not to also cache the Ray's data when caching its traces
- segments_on_cache_tracesTrueWhether or not to cache individual segments when trace caching is enabled. If false, we will instead cache a segment for each part of the trace where the direction is the same. This minimizes the number of segments requied to represent the Ray's path, but removes the ability to show Ray field data on each segment through an element.
Default:True
C++ Type:bool
Controllable:No
Description:Whether or not to cache individual segments when trace caching is enabled. If false, we will instead cache a segment for each part of the trace where the direction is the same. This minimizes the number of segments requied to represent the Ray's path, but removes the ability to show Ray field data on each segment through an element.
Trace Cache Parameters
- directionsThe directions to spawn Rays in (they do not need to be normalized to 1). Use either this parameter or the end_points parameter, but not both!
C++ Type:std::vector<libMesh::Point>
Controllable:No
Description:The directions to spawn Rays in (they do not need to be normalized to 1). Use either this parameter or the end_points parameter, but not both!
- end_pointsThe points where Rays should end. Use either this parameter or the directions parameter, but not both!
C++ Type:std::vector<libMesh::Point>
Controllable:No
Description:The points where Rays should end. Use either this parameter or the directions parameter, but not both!
- max_distancesThe maximum distances that each Ray can travel before it is killed internally after RayKernel execution. This can ONLY be used when the 'directions' parameter is used. When this is not set, the Rays must be killed by RayKernels, RayBCs, or the global max distance parameter, 'ray_max_distance' (applies to all Rays)
C++ Type:std::vector<double>
Controllable:No
Description:The maximum distances that each Ray can travel before it is killed internally after RayKernel execution. This can ONLY be used when the 'directions' parameter is used. When this is not set, the Rays must be killed by RayKernels, RayBCs, or the global max distance parameter, 'ray_max_distance' (applies to all Rays)
- start_pointsThe points to start Rays from
C++ Type:std::vector<libMesh::Point>
Controllable:No
Description:The points to start Rays from
Trajectory Parameters
- initial_ray_aux_dataThe initial Ray aux data to set for each Ray. You must have size(ray_aux_data_names) entries for each Ray defined by 'names'. The data for each Ray should be separated by ';'.
C++ Type:std::vector<std::vector<double>>
Controllable:No
Description:The initial Ray aux data to set for each Ray. You must have size(ray_aux_data_names) entries for each Ray defined by 'names'. The data for each Ray should be separated by ';'.
- initial_ray_dataThe initial Ray data to set for each Ray. You must have size(ray_data_names) entries for each Ray defined by 'names'. The data for each Ray should be separated by ';'.
C++ Type:std::vector<std::vector<double>>
Controllable:No
Description:The initial Ray data to set for each Ray. You must have size(ray_data_names) entries for each Ray defined by 'names'. The data for each Ray should be separated by ';'.
- ray_aux_data_namesThe Ray aux data names to register. If 'initial_ray_aux_data' is set, these aux data names will be associated with said initial values. Otherwise, they will be set to zero.
C++ Type:std::vector<std::string>
Controllable:No
Description:The Ray aux data names to register. If 'initial_ray_aux_data' is set, these aux data names will be associated with said initial values. Otherwise, they will be set to zero.
- ray_data_namesThe Ray data names to register. If 'initial_ray_data' is set, these data names will be associated with said initial values. Otherwise, they will be set to zero.
C++ Type:std::vector<std::string>
Controllable:No
Description:The Ray data names to register. If 'initial_ray_data' is set, these data names will be associated with said initial values. Otherwise, they will be set to zero.
Ray Data Parameters
- ray_kernel_coverage_checkTrueWhether or not to perform coverage checks on RayKernels
Default:True
C++ Type:bool
Controllable:No
Description:Whether or not to perform coverage checks on RayKernels
- verify_raysTrueWhether or not to verify the generated Rays. This includes checking their starting information and the uniqueness of Rays before and after execution. This is also used by derived studies for more specific verification.
Default:True
C++ Type:bool
Controllable:No
Description:Whether or not to verify the generated Rays. This includes checking their starting information and the uniqueness of Rays before and after execution. This is also used by derived studies for more specific verification.
- verify_trace_intersectionsTrueWhether or not to verify the trace intersections in devel and dbg modes. Trace intersections are not verified regardless of this parameter in optimized modes (opt, oprof).
Default:True
C++ Type:bool
Controllable:No
Description:Whether or not to verify the trace intersections in devel and dbg modes. Trace intersections are not verified regardless of this parameter in optimized modes (opt, oprof).
Checks And Verifications Parameters
- warn_non_planarTrueWhether or not to produce a warning if any element faces are non-planar.
Default:True
C++ Type:bool
Controllable:No
Description:Whether or not to produce a warning if any element faces are non-planar.
- warn_subdomain_hmaxTrueWhether or not to warn if the approximated hmax (constant on subdomain) varies significantly for an element
Default:True
C++ Type:bool
Controllable:No
Description:Whether or not to warn if the approximated hmax (constant on subdomain) varies significantly for an element