Enforce particle orbit bounds for implicit solvers

[JustinRayAngus]

This PR adds particle bounds checks prior to field gather and current deposition for the implicit solvers. The checks are included for each suborbit when particle suborbits are used.

This PR also adds checks that the number of cell crossings in each direction are within the bounds determined by particles.max_grid_crossings when using the mass matrices for the Jacobian and using the Villasenor deposition.

Note that the particle bounds check prior to gather/deposition is not sufficient to ensure that each particle orbit remains within the maximum allowed value set by particles.max_grid_crossings. This is because a particle with a large orbit can be located anywhere within the tilebox, whereas the bounds check only catches particles near the tilebox boundaries.

When a particle is found to be out of bounds, or has too many cell crossings, the simulation aborts. In the future, the abort can be replaced with a trigger to subcycle the implicit step (see PR #7000).

This PR replaces PR #6156.

[dpgrote]

This error message is cryptic. Can you add a suggestion here about how the user could fix this to avoid this error? Presumably this could be fixed by increasing villasenor_mass_matrices_max_grid_crossings and recompiling or decreasing dt.

[JustinRayAngus]

This has been refactored. I still have the following check:

if (num_segments > max_num_segments) {
    amrex::Abort("num_segments exceeds max_num_segments");
}

However, it should never trigger unless something else has gone seriously wrong, since the function now returns if the number of cell crossings in any direction exceeds the maximum permitted value. Because the function constructs and uses arrays of size max_num_segments, it seems like good practice to retain this check.

[JustinRayAngus]

@dpgrote @atmyers

I may be able to simplify some of the checks I've added here for particles being within range using:

AMREX_ASSERT_WITH_MESSAGE(
    amrex::numParticlesOutOfRange(pti, range) == 0,
    "Particles shape does not fit within tile (CPU) or guard cells (GPU) used for current deposition");

But it's not clear to me what this actually checks. I presume it uses the stored position of the particle and checks that it is within the specified range of the valid region of the box/tile that it lives in. Is that correct?

If yes, then I would need to convert the position from time-centered to time n+1 prior to calling this.

How does it work for curvilinear geometries? Does it convert xp and yp to rp = sqrt(xp^2 + yp^2)?