Generalize RotationalPeriodicBC for X-, Y-, or Z-axis

[lewisgross1296]

Description

Currently only periodicity around the Z-axis is supported. This PR extends this capability for X and Y periodicity. Fixes #3559.

Checklist

• I have performed a self-review of my own code
• I have run clang-format (version 15) on any C++ source files (if applicable)
• I have followed the style guidelines for Python source files (if applicable)
• I have made corresponding changes to the documentation (if applicable)
• I have added tests that prove my fix is effective or that my feature works (if applicable)

[lewisgross1296]

I think this is getting close. I'm currently running into a problem when trying to generate the test files

 WARNING: Couldn't find particle after hitting periodic boundary on surface 4.
          The normal vector of one periodic surface may need to be reversed.

I think I understand conceptually what's going on, i.e. the particle is moved to the other periodic surface and continues in the same direction (to where there is no geometry) when it should continue in the opposite direction (inside the geometry). I'm trying to find the correct line to fix this, but I didn't think I changed this behavior from how it worked when there was only rotational periodicity around the z-axis.

[lewisgross1296]

Just realized that my "generalization" was based on the z-case that existed here before. The x and z cases should be similar but the y rotation matrix has the sign flipped, which I think explains why I'm seeing one test failure in this way. If we condition on zero_axis_idx I think I can get it right

[lewisgross1296]

So I just pushed my attempt at accounting for the signs in the transformation of r->new_r and u->new_u, but I'm still failing the tests. I did some scaffolding and it seems like my transformations are not actually transforming anything at all and I'm confused why. For example, the ycyl_model test

                                %%%%%%%%%%%%%%%
                           %%%%%%%%%%%%%%%%%%%%%%%%
                        %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
                      %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
                    %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
                   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
                                    %%%%%%%%%%%%%%%%%%%%%%%%
                                     %%%%%%%%%%%%%%%%%%%%%%%%
                 ###############      %%%%%%%%%%%%%%%%%%%%%%%%
                ##################     %%%%%%%%%%%%%%%%%%%%%%%
                ###################     %%%%%%%%%%%%%%%%%%%%%%%
                ####################     %%%%%%%%%%%%%%%%%%%%%%
                #####################     %%%%%%%%%%%%%%%%%%%%%
                ######################     %%%%%%%%%%%%%%%%%%%%
                #######################     %%%%%%%%%%%%%%%%%%
                 #######################     %%%%%%%%%%%%%%%%%
                 ######################     %%%%%%%%%%%%%%%%%
                  ####################     %%%%%%%%%%%%%%%%%
                    #################     %%%%%%%%%%%%%%%%%
                     ###############     %%%%%%%%%%%%%%%%
                       ############     %%%%%%%%%%%%%%%
                          ########     %%%%%%%%%%%%%%
                                      %%%%%%%%%%%

                 | The OpenMC Monte Carlo Code
       Copyright | 2011-2025 MIT, UChicago Argonne LLC, and contributors
         License | https://docs.openmc.org/en/latest/license.html
         Version | 0.13.1-dev2826
     Commit Hash | dbd1a421d063fa78ff93e9c5e6995f84f7177a06
       Date/Time | 2025-11-06 19:45:53
   MPI Processes | 1
  OpenMP Threads | 1

 Reading model XML file 'model.xml' ...
 Reading cross sections XML file...
 Reading U235 from /root/nndc_hdf5/U235.h5
 Reading U238 from /root/nndc_hdf5/U238.h5
 Minimum neutron data temperature: 294 K
 Maximum neutron data temperature: 294 K
 Preparing distributed cell instances...
 Writing summary.h5 file...
 Maximum neutron transport energy: 20000000 eV for U235
 Initializing source particles...

 ====================>     K EIGENVALUE SIMULATION     <====================

  Bat./Gen.      k            Average k
  =========   ========   ====================
r = (2.58686, 2.82336, 1.49352)
new r =(2.58686, 2.82336, 1.49352)
u = (-0.454864, 0.605916, -0.65266)
new u= (-0.454863, 0.605916, -0.65266)
 WARNING: Couldn't find particle after hitting periodic boundary on surface 5.
          The normal vector of one periodic surface may need to be reversed.
r = (12.5437, 1.66067, 7.24214)
new r =(12.5437, 1.66066, 7.24214)
u = (0.393612, -0.597981, -0.698203)
new u= (0.393612, -0.597981, -0.698203)
 WARNING: Couldn't find particle after hitting periodic boundary on surface 5.
          The normal vector of one periodic surface may need to be reversed.
r = (8.8592, 0.761051, 5.11486)
new r =(8.8592, 0.761049, 5.11486)
u = (0.176424, -0.197484, -0.9643)
new u= (0.176424, -0.197484, -0.9643)
 WARNING: Couldn't find particle after hitting periodic boundary on surface 5.
          The normal vector of one periodic surface may need to be reversed.
r = (15.7526, 5.01236, 9.09476)
new r =(15.7526, 5.01236, 9.09476)
u = (0.600818, -0.366639, -0.710347)
new u= (0.600818, -0.36664, -0.710347)
 WARNING: Couldn't find particle after hitting periodic boundary on surface 5.
          The normal vector of one periodic surface may need to be reversed.
r = (1.28161, 0.308098, 0.739938)
new r =(1.28161, 0.308097, 0.739938)
u = (-0.0700045, 0.35889, -0.930751)
new u= (-0.0700045, 0.35889, -0.930751)
 WARNING: Couldn't find particle after hitting periodic boundary on surface 5.
          The normal vector of one periodic surface may need to be reversed.
r = (2.34625, 16.3285, 1.35461)
new r =(2.34625, 16.3285, 1.35461)
u = (-0.0332286, -0.0999964, -0.994433)
new u= (-0.0332286, -0.0999964, -0.994433)
 WARNING: Couldn't find particle after hitting periodic boundary on surface 5.
          The normal vector of one periodic surface may need to be reversed.
r = (0, 0.324183, 13.9665)
new r =(-5.66819e-08, 0.324183, 13.9665)
u = (-0.351669, 0.691558, -0.630933)
new u= (-0.351669, 0.691558, -0.630933)
 WARNING: Couldn't find particle after hitting periodic boundary on surface 4.
          The normal vector of one periodic surface may need to be reversed.
r = (13.8063, 1.3389, 7.97107)
new r =(13.8063, 1.33889, 7.97107)
u = (0.964377, 0.0384617, -0.261719)
new u= (0.964377, 0.0384615, -0.261719)
 WARNING: Couldn't find particle after hitting periodic boundary on surface 5.
          The normal vector of one periodic surface may need to be reversed.
r = (0, 18.4322, 9.88184)
new r =(-3.22278e-06, 18.4322, 9.88184)
u = (-0.680602, 0.701058, 0.212835)
new u= (-0.680602, 0.701058, 0.212835)
 WARNING: Couldn't find particle after hitting periodic boundary on surface 4.
          The normal vector of one periodic surface may need to be reversed.
r = (0, 6.40015, 9.41111)
new r =(-1.11904e-06, 6.40015, 9.41111)
u = (-0.641745, -0.303774, 0.704191)
new u= (-0.641745, -0.303774, 0.704191)
 WARNING: Couldn't find particle after hitting periodic boundary on surface 4.
          The normal vector of one periodic surface may need to be reversed.
 ERROR: Maximum number of lost particles has been reached.
Abort(-1) on node 0 (rank 0 in comm 0): application called MPI_Abort(MPI_COMM_WORLD, -1) - process 0

Am I missing some C++ thing about scope or something like that?

  // rotations around the y-axis have sign flipped for the sin_theta terms
  int flip;
  if (zero_axis_idx_ == 1) {
    flip = -1;
  } else {
    flip = 1;
  }

  Position new_r;
  new_r[zero_axis_idx_] = r[zero_axis_idx_];
  new_r[axis_1_idx_] =
    cos_theta * r[axis_1_idx_] - flip * sin_theta * r[axis_2_idx_];
  new_r[axis_2_idx_] =
    flip * sin_theta * r[axis_1_idx_] + cos_theta * r[axis_2_idx_];

  Direction new_u;
  new_u[zero_axis_idx_] = u[zero_axis_idx_];
  new_u[axis_1_idx_] =
    cos_theta * u[axis_1_idx_] - flip * sin_theta * u[axis_2_idx_];
  new_u[axis_2_idx_] =
    flip * sin_theta * u[axis_1_idx_] + cos_theta * u[axis_2_idx_];