More offline discussion has exposed another area of the documentation which I think is a little lacking. Currently the documentation makes no mention of topology and the fact that XDG (like DAGMC) is topology aware library in its spatial queries.
It would be useful to explain what it means that a surface belongs to multiple volumes topologically and how sense is used in regards to surface normals. This pretty closely links to some of the ideas described in the implicit complement issue #223 so perhaps a single PR could close out both of these issues.
Copied from slack so as not to lose the discussion had:
What are the surface_sense functions supposed to do? I guess, it's determining if one entity contains another
[Patrick]
Surface senses indicate two things at once: 1. What volumes (blocks) a surface is adjacent to and 2. Which of the volumes have a "forward" and "reverse" sense with respect to the faces of the surface in question. The "forward" volume comes first in this pair, and the "reverse" volume second.
This is used during ray tracing to determine whether or not the normals of the faces are reversed to indicate an entering or exiting intersection for the volume being queried.
@Waqar-ukaea I see you're typing too. Add or clarify anything I've missed of course
[Waqar]
Patrick kinda answered it already but maybe a diagram can help make it feel less abstract
This is the topology-aware part of the geometry. The diagram shows a shared surface boundary between two volumes, A and B. The surface might have a "natural" forward normal pointing from A into B (shown by the arrow). But from the perspective of each volume that normal has the opposite meaning:
From A: we have reverse sense
From B: we have forward sense
And then for the two methods in the mesh manager:
Sense MeshManager::surface_sense(MeshID surface, MeshID volume) you pass a surface and it returns an enum denoting whether the sense is forwards or reverse respective to the volume passed to the method.
std::pair<MeshID, MeshID> surface_senses(MeshID surface) I am pretty sure this just returns the two parent volumes of a surface but Patrick can correct me if im wrong
It does return the parent volumes, but the ordering matters. Forward is first, reverse is second.
More offline discussion has exposed another area of the documentation which I think is a little lacking. Currently the documentation makes no mention of topology and the fact that XDG (like DAGMC) is topology aware library in its spatial queries.
It would be useful to explain what it means that a surface belongs to multiple volumes topologically and how sense is used in regards to surface normals. This pretty closely links to some of the ideas described in the implicit complement issue #223 so perhaps a single PR could close out both of these issues.
Copied from slack so as not to lose the discussion had:
[Patrick]
Surface senses indicate two things at once: 1. What volumes (blocks) a surface is adjacent to and 2. Which of the volumes have a "forward" and "reverse" sense with respect to the faces of the surface in question. The "forward" volume comes first in this pair, and the "reverse" volume second.
This is used during ray tracing to determine whether or not the normals of the faces are reversed to indicate an entering or exiting intersection for the volume being queried.
@Waqar-ukaea I see you're typing too. Add or clarify anything I've missed of course
[Waqar]
Patrick kinda answered it already but maybe a diagram can help make it feel less abstract
This is the topology-aware part of the geometry. The diagram shows a shared surface boundary between two volumes, A and B. The surface might have a "natural" forward normal pointing from A into B (shown by the arrow). But from the perspective of each volume that normal has the opposite meaning:
From A: we have reverse sense
From B: we have forward sense
And then for the two methods in the mesh manager:
Sense MeshManager::surface_sense(MeshID surface, MeshID volume)you pass a surface and it returns an enum denoting whether the sense is forwards or reverse respective to the volume passed to the method.It does return the parent volumes, but the ordering matters. Forward is first, reverse is second.