Write surface source files per batch

[zoeprieto]

Description

This is a preliminary solution to the first part of the issue #3123 for writing surface source files in the last N active batches chosen by the user.

By default it still saves a surface source file only in the last batch. The difference is that the files will be named: surface_source_batch_N.h5 with N being the number of the last batch.

It has also added the ability to print the number of particles that were saved per batch as the simulation runs.

Fixes #3123

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)

[pshriwise]

Some minor comments on verbosity and file naming formats, and I finally figured out what I think we should do:

The current implementation is very nice and accomplishes the goal of this feature (to allow more surface crossings to be generated by the simulation than allowed by the max_particles setting on the surface source). In the end though, I think this feature should behave in a similar manner to the openmc.Settings.statepoint['batches'] capability.

So for this features we would incorporate a openmc.Settings.surf_source_batches option that would allow users to specify a list of batches after which the surface source bank will be written to file and the surface source bank in memory will be cleared. With this method the user can specify that they'd like to write the current set of source particles after as many batches as they like. If they'd like all of the batches it's as simple as specifying:

settings.surface_source_batches = [i for i in range(settings.batches)]

Sorry it took me so long to come to this conclusion. What do you think @zoeprieto?

[zoeprieto]

Thanks for all the suggestions @pshriwise . I think using the same format of creating files as in statepoint is really very good, and simplifies the need to create more variables. Also, it adds the ability to not be so strict on whether it's in all batches or just the last batch.
When I implemented it to make it consistent with the statepoint implementation, the variable that is added is ‘batches’ inside surface_source_write, and it receives a list. By default the list is unitary and only has the value of the last batch.

[pshriwise]

This looks really nice @zoeprieto. 🥇 Mainly a couple of high-level questions here to address.

[pshriwise]

A couple more thoughts, but I think this is really close.

[pshriwise]

Almost there! If you don't mind, let's add one test with the batches property set to ensure the correct number of files and filenames are generated.

[pshriwise]

Teeny-tiny documentation tweak and then I'm happy! 😄

[pshriwise]

Thank you @zoeprieto!

[paulromano]

Sorry to stall the merging -- wanted to take a look at this but haven't had a chance to yet. I'll try to review in the next few days!

[paulromano]

To summarize some discussion that @pshriwise @zoeprieto and I had offline -- rather than writing a surface source file at specific batches, I am recommending that we write the surface source file at the point where it fills up and then give the user an option as to how many times they are allowing a full source file to be written. If the surface source bank is not full by the end of the simulation, it will write out the surface source as is. This removes some of the guess work for the user in figuring out how often they should be writing the surface source (i.e., which batches).

[zoeprieto]

Thank you @paulromano for your comment. You are right, it is more reasonable to create another file only if the first one is full. I solved it by adding a max_surf_files variable which defaults is 1. I had to create another variable called current_surface_file to know which is the current surface source file I'm writing to.
The documentation and tests were also updated.

[paulromano]

Thanks again for this enhancement @zoeprieto. I made the following changes on this branch:

• Renamed global variables to all start with ssw_ to indicate they are related to surface source writing.
• Introduced a new write_source_point function to consistently handle the logic for writing either a .h5 and .mcpl file
• Changed the name of the user input "max_surf_files" to "max_source_files"
• Updated the test case

[zoeprieto]

Thank you @paulromano for your feedback and changes!