Exporting and importing physical properties

[paulromano]

This PR adds two new functions to our C API, openmc_properties_export and openmc_properties_import that allow physical properties (cell temperatures, material densities) to be exported to a HDF5 file, by default called "properties.h5". This is primarily intended for multiphysics coupling where we want to be able to save, load, and visualize temperature and density distributions. Right now, we don't have a good way to do this. Along with the two C functions, this PR also introduces:

• Corresponding openmc.lib.export_properties and openmc.lib.import_properties Python bindings to the underlying C functions
• A Model.import_properties method that takes an existing Model object and modifies cell temperatures and material densities from a properties.h5 file. This modified Model can then be re-exported using the normal Model.export_to_xml method.
• For convenience, a new Model.from_xml classmethod that does what you would expect: create a Model object based on existing XML files. Not sure why we didn't add this before...

Other small changes:

• openmc.lib.Cell now has a num_instances property, relying on a corresponding openmc_cell_get_num_instances C API function
• I've changed openmc_id_map to return both cell IDs and instances

Documentation and unit tests have been updated accordingly.

Companion PRs

After this, I will submit two companion PRs taking advantage of the new functionality

• Change to openmc-plotter to be able to import properties and use new id_map for identifying cell instances
• Change to ENRICO to export OpenMC properties at each iteration

As a sneak peak of what's possible with these capabilities, here is a converged axial temperature distribution in an assembly simulated with ENRICO (using this PR) visualized using openmc-plotter:

Design alternatives

In discussion with @pshriwise, I did consider a few design alternatives. The first alternative was to include this information in our normal statepoint files. This would have the benefit of not introducing a new file, but statepoints are really about tally results, not so much physical properties that may have changed. Plus, in some cases, we may just want to load a model via openmc.lib change temperatures/densities, and export the properties without ever having run a transport simulation.

The other alternative was to include this information in our summary file. However, in the common case where we are writing this information at each iteration of a multiphysics calculation, this may result in unnecessarily large files. By separating out the temperature/density data in a single file, we ensure that only the minimum amount of data is written each time.

I'd appreciate any thoughts/feedback from those of you working on multiphysics stuff (@smharper @aprilnovak @mkreher13 @helen-brooks)

[mkreher13]

Looks very useful - I will undoubtedly be using this soon! Thanks for explaining why this shouldn't be done in a statepoint file, which was my only question.

In the transient code I'm proposing (the adiabatic PR), you'll notice we use a log_file.h5. These property.h5 files remind me of that, but better catered toward the CAPI. In the transient code, full OpenMC runs are completed before updating properties, so the state point files and the log_file are sufficient. However, as I move forward with my PhD and include multiphysics coupling into that scheme, the CAPI will quickly get involved which might move my strategy more toward these property files.

[helen-brooks]

Thanks for the tag! I think this will provide a useful verification check (I assume the write of the properties can be turned on and off?), maybe even allow for an integration test in AURORA that the representations of temperature and density are consistent between MOOSE/OpenMC. There's less of a use case for me at run-time though, as I pass this information in memory; I would probably stick with this to avoid too many IO operations.

[aprilnovak]

This comes at the perfect time, @pshriwise and I were just discussing ways to verify the temperature setting in OpenMC. Thanks @paulromano!

[paulromano]

Glad to hear that this feature will likely get some use!

@helen-brooks Right now, writing of properties doesn't really have an on/off switch in the same way that, say, statepoint files do. Instead, it is up to an external application to make a call to openmc_properties_export at an appropriate time (or if controlling via Python, openmc.lib.export_properties).

[pshriwise]

This is really nice @paulromano. It's going to be very handy to dump and load this information so seamlessly.

[paulromano]

@pshriwise I believe all your comments have been addressed. Let me know if you have further requests

[pshriwise]

Looking good! Thanks for adding this handy feature @paulromano