Unclear instructions for `FieldProbe:Plane`

[titoiride]

Hi all,
I find the documentation regarding the definition of a planar probe a bit confusing and I don't seem to be able to extract meaningful results from it.
For my simulation, the probe is defined as

fieldsOnPlanexz.type = FieldProbe
fieldsOnPlanexz.probe_geometry = Plane
fieldsOnPlanexz.x_probe = 0
fieldsOnPlanexz.y_probe = 0
fieldsOnPlanexz.z_probe = -15e-6
fieldsOnPlanexz.target_normal_x = 0
fieldsOnPlanexz.target_normal_y = 1
fieldsOnPlanexz.target_normal_z = 0
fieldsOnPlanexz.target_up_x = 1
fieldsOnPlanexz.target_up_y = 0
fieldsOnPlanexz.target_up_z = 0
fieldsOnPlanexz.detector_radius = 15e-6
fieldsOnPlanexz.resolution = 1000
fieldsOnPlanexz.intervals = 500
fieldsOnPlanexz.do_moving_window_FP = 1

My understanding from the guide is that this should be a x-z plane (normal vector y), centered in (0, 0, -15) um and with a 15 um size (each direction?), 1000 points per side. However, when I extract the data from it i get some inconsistencies and I wanted to understand where I'm mistaken, if in the probe definition or the data extraction. I extracted the files using a pandas dataframe and I'm looking at the axis produced. The y axis is the only one that seems consistent with the definition, i.e. the np.unique function returns array([0.]).

For the xaxis:

• 1470 entries
• x_min = -10.6 um
• x_max = 10.6 um

For the z axis:

• 1000 entries
• z_min = -25.6 um
• z_max = -4.4 um

Both axis have an extent of 21.2 um, which seems to me being 15*sqrt(2). How do I interpret the detector radius and resolution parameters? Unfortunately the documentation does not provide too many details. Last point, the other parameter that is not clear from the documentation is the "up" vector. Would it be possible to include this picture for future reference?

[ax3l]

Last point, the other parameter that is not clear from the documentation is the "up" vector. Would it be possible to include this picture for future reference?

Thanks! Yes, fully agree that is a good addition to the docs.

Because of my upcoming leave, this might not make the cut this week for me, but anyone else please feel free to PR an update to the docs in during my absence.

[ax3l]

Both axis have an extent of 21.2 um, which seems to me being 15*sqrt(2). How do I interpret the detector radius and resolution parameters?

Yeah that seems very off. The detector should be a square with the placement you described and an edge length of 2x the "detector_radius". I do not understand (anymore) why the sqrt(2) is coming in here:

warpx/Source/Diagnostics/ReducedDiags/FieldProbe.cpp

Lines 273 to 307 in a28b20a

	else if (m_probe_geometry == DetectorGeometry::Plane)
	{
	std::size_t const res2 = std::size_t(m_resolution) * std::size_t(m_resolution);
	xpos.reserve(res2);
	ypos.reserve(res2);
	zpos.reserve(res2);
	// ensure that input vectors are normalized
	normalize(target_normal_x, target_normal_y, target_normal_z);
	normalize(target_up_x, target_up_y, target_up_z);
	// create vector orthonormal to input vectors
	const amrex::Real orthotarget[3]{
	target_normal_y * target_up_z - target_normal_z * target_up_y,
	target_normal_z * target_up_x - target_normal_x * target_up_z,
	target_normal_x * target_up_y - target_normal_y * target_up_x};
	// find upper left and lower right bounds of detector
	amrex::Real direction[3]{
	orthotarget[0] - target_up_x,
	orthotarget[1] - target_up_y,
	orthotarget[2] - target_up_z};
	normalize(direction[0], direction[1], direction[2]);
	const amrex::Real uppercorner[3]{
	x_probe - (direction[0] * detector_radius),
	y_probe - (direction[1] * detector_radius),
	z_probe - (direction[2] * detector_radius)};
	const amrex::Real lowercorner[3]{
	uppercorner[0] - (target_up_x * std::sqrt(2_rt) * detector_radius),
	uppercorner[1] - (target_up_y * std::sqrt(2_rt) * detector_radius),
	uppercorner[2] - (target_up_z * std::sqrt(2_rt) * detector_radius)};
	const amrex::Real loweropposite[3]{
	x_probe + (direction[0] * detector_radius),
	y_probe + (direction[1] * detector_radius),
	z_probe + (direction[2] * detector_radius)};

@roelof-groenewald you modified the calculation of the plane in #3497, can you recall the sqrt(2) you added?

[roelof-groenewald]

Hopefully this diagram will help clarify what is done here:

The probes cover the red square. This is a result of defining a square through a radius, which is ambiguous - is the radius meant to be half the length of the sides or the maximum distance a probe will be from the center. I opted for the latter definition in the changes @ax3l referenced, but we can certainly have a discussion about changing the definition.

[roelof-groenewald]

Regarding the "up" vector, it sets the orientation of the square, so for example, if you had set the up vector to (1, 0, 1) the picture would change to: