Mesh-based weight windows

[nglaser3]

Summary of changes

This PR adds mesh-based weight windows to MCDC. In the current state, only spatial and energy weight windows are supported. Additionally, the particle "passes through" a weight window on collision or surface crossing, as opposed to whenever a particles crosses into a new mesh bin.

Weight windows are stored as three separate 1D arrays of floats: lower_weights, target_weights, upper_weights.
To test the additions, I added a few unit tests to unit/transport/technique/weight_windows.py.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Organization and beautification (changes which improve readability and/or accessibility)

Developer Checklist

• I have read the contributing guide.
• My code follows the code style of this project.
• I have updated the documentation accordingly.
• I have added tests to cover my changes.
• All new and existing tests pass

Associated Issues and PRs

• closes [Feature] Mesh-based weight windows #393
• related to #

Associated Developers

• Dev: @munkm

[nglaser3]

@munkm @ilhamv should I add support for energy weight windows in this PR as well or do a follow up PR for that? Also, the added documentation to the website in this PR is pretty sad, but I was unsure as to whether I should expand the docs around all of the Techniques in this PR or also just make a follow up PR for that?

[munkm]

I think it's fine to do energy based WWs in a separate PR. I do think you want to add in at least minimal documentation to this PR (I will do my best to take a look to do a review in a few days). If you want to do expanded documentation you could make a second PR that is dependent on this one being merged in (?).

[nglaser3]

@munkm I will create a separate PR to add the docs to so as to not clutter this one

[nglaser3]

@ilhamv I am not sure what is causing the regression tests to fail, but I think (?) that since I did not add a regression test the weight_windows object was never added to the numba_types file. If this is the case, I will update this PR off of #396 (once merged in) and then update the numba_types file to contain weight_windows

[ilhamv]

This looks great, @nglaser3.

It looks like the WW is called not only at every collision, but also at every surface crossing, which is good, I think.

[ilhamv]

Hi Caleb (@shac170), I invited you to review/take a look at this PR on re-introducing weight windows into the refactored MC/DC.
Please let us know what you think or if you have any comments about it. Thanks!

[nglaser3]

@ilhamv thank you for the review, I will work on addressing your comments!

[nglaser3]

@ilhamv, I believe I have updated the PR with your comments! Below is a summary of the changes (enumerated from your comment):

1. Committed the suggestion!
2. Thank you! I added a regression test that uses an x/y mesh and weight windows that are all set to (0.55, 0.7, 0.9). The values for the weight windows were arbitrarily chosen to force splits (since particles are born with weight 1.0), force roulettes from the split particles (split particles would have weight 0.5) and the target weight was chosen to just be between the two.
3. I refactored the weight_roullete method a little bit to use the helper I wrote for weight windows, but kept the method distinct. I chose to do this to avoid an if statement in the helper method to determine how to get the target and threshold weights. Is this what you were thinking with your comment or did you mean to completely replace the weight_roulette method with the helper or use the weight_roulette method as the helper?
4. I changed the weight windows to use the Annotated like you suggested, and to do so I added a new method in code_factory/numba_objects_generator.py called _accessor_4d_element. This method does the same as the already existing _accessor_3d_element but for 4D (to support the energy and space indexing in the weight windows).
5. I changed from passing in simulation everywhere to passing in program to the main method call and then to the split method, everywhere else getting the simulation from mcdc.transport.util.access_simulation method.

[ilhamv]

@nglaser3 - I just redesigned the original weight roulette into global_weight_roulette to distinguish it from the utility function weight_roulette. I also redesigned the technique logic such that one can have multiple active techniques (e.g., for whatever reason, applying WW, followed by a global WR). Let me know what you think.

Minor: I added global_weight_roulette into the cooper2 regression test to get it tested.

[ilhamv]

@nglaser3 - Is it true that the way it is set up now, only one of the split particles will be rouletted (when applicable)? Should all of the split particles be rouletted instead?

[nglaser3]

Thanks @ilhamv for fixing up the roulette logic! I think it makes sense to be able to support both weight windows and global roulette as opposed to silently skip over the global roulette, even though it probably doesn't make sense for a user to set both

Yes, I did not even realize that if a split occurs, the split particles are not then checked for roulette, only the parent particle. I will change this so that all particles are roulette

[nglaser3]

@ilhamv, I have updated the weight window procedure to roulette all split particles not just the parent!

[ilhamv]

For some reason, the regression test answer still needed to be revised...

I have a question on the WW procedure. Can we split excessive-weight particles right into the targeted weight? (this would be similar to the split-roulette procedure in the population control)

[nglaser3]

@ilhamv I totally missed this, sorry! No, I do not think we could since the quotient of the particles current weight and the target weight from the weight window is no guaranteed to be an integer (to determine how many splits should occur).

[ilhamv]

Here is how we do the splitting-roulette procedure in the population control:
With a given particle weight w and target weight w_target, we want all particles coming out of the procedure to exactly have a weight of w_target:

1. Determine the splitting number s = w / w_target.
2. Split the particles into N_split copies, where N_split = floor(s) + 1.
3. Russian roulette the last copy with surviving probability s - floor(s).

Or, in the actual implementation, after we calculate s: with the probability s - floor(s), there will be floor(s) + 1 particles coming out of the procedure---otherwise, there will be only floor(s).

Note that this procedure works both for w > w_upper or w < w_lower.

===

Do you think this would work for WW?