Make MCPL a Runtime Optional Dependency

[ahnaf-tahmid-chowdhury]

Description

This pull request refactors the MCPL interface in OpenMC to make MCPL a runtime optional dependency rather than a build-time one. This version enhances the previous effort by implementing cross-platform dynamic library loading and discovery mechanisms, including support for Windows.

Benefits

• Simplified Build Process: OpenMC can be built without requiring MCPL to be pre-installed.
• Reduced Build-Time Dependencies: Contributes to a leaner core build.
• Flexibility: Users can install MCPL separately. OpenMC will attempt to load it at runtime using platform-appropriate methods.

Key Changes

1. CMake Modifications:

   • Removed the OPENMC_USE_MCPL CMake option.

2. Cross-Platform Runtime Library Loading (mcpl_interface.cpp):

   • The MCPL shared library is now loaded at runtime using:
     • dlopen() on POSIX-like systems (Linux, macOS).
     • LoadLibraryA() on Windows.
   • Pointers to required MCPL API functions are resolved using:
     • dlsym() on POSIX.
     • GetProcAddress() on Windows.
   • Platform-specific library handles (void* or HMODULE) and cleanup functions (dlclose or FreeLibrary) are used.
   • An McplApi struct holds these function pointers.
   • A one-time initialization function (initialize_mcpl_interface_if_needed) handles the loading and symbol resolution.

3. Library Discovery Mechanisms:
   The initialize_mcpl_interface_impl function attempts to locate the MCPL library in the following order:

   1. mcpl-config --show libpath Command:
      • Uses popen() on POSIX systems.
      • Uses _popen() on Windows systems (requires mcpl-config.bat or .exe to be in the system PATH).
      • The output path is used to load the library.
   2. Standard Library Names:
      • Tries libmcpl.so, libmcpl.dylib on POSIX.
      • Tries mcpl.dll, libmcpl.dll on Windows. These are searched in standard system library locations (e.g., those covered by PATH on Windows or LD_LIBRARY_PATH on Linux).

4. Avoidance of mcpl.h at Compile Time:

   • mcpl.h is not included to ensure MCPL is not a compile-time dependency.

   • Necessary MCPL data structures (e.g., mcpl_particle_t) and function signatures are manually re-declared within mcpl_interface.cpp as mcpl_particle_repr_t, etc.

     Important Note: These manual declarations must precisely match the ABI of the MCPL library (MCPL 2.2.0 is currently targeted). pragma pack(1) is used for structure packing consistency.

5. Error Handling and User Guidance:

   • If the MCPL library cannot be found or loaded, OpenMC issues a warning (once, by master MPI rank) detailing the attempted load methods and errors.
   • If an MCPL-dependent feature is used and the library is unavailable, OpenMC fatal_errors with an informative message, suggesting installation (e.g., pip install mcpl) and how to make the library findable.
   • The is_mcpl_interface_available() function can be used to programmatically check MCPL availability.

6. Code Updates:

   • All calls to MCPL functions within mcpl_interface.cpp use the dynamically resolved function pointers.
   • The MCPL_ENABLED preprocessor logic has been removed.

[paulromano]

@tkittel Does this PR look sensible to you? From a quick scan, it looks very similar to what we did with the NCrystal interface.

[shimwell]

This PR would be useful for getting the sci kit build core working again. Any objections to merging

[shimwell]

Thanks Ahnaf another nice build system improvement.

LGTM

I will merge this in on Friday if there are no objections

[paulromano]

Just putting a placeholder review as I'd like to take a look before we merge this. I was also hoping to get @tkittel's vote of confidence on this. I'm assuming he's been in the loop on this?

[shimwell]

I'm assuming he's been in the loop on this?

I've not seen any conversations on this PR outside of this PR thread.

[tkittel]

Hi guys. Sorry, I am on vacation so I didnt have a chance to look at this. I like the aim of this PR though :-)

Not 100% sure when I might have a chance to have a look at the details, but perhaps I can find a quiet moment within the next few days.

[tkittel]

Hi guys,

So I had a very quick skim through, and I have a few comments. Do keep in mind though, that the OpenMC-MCPL bindings were initially contributed by @ebknudsen not me.

In general, big thumbs up to the work here. And yes, the intention is to have the MCPL C ABI stable enough to do these kinds of things. I have a few minor issues though:

1. I would feel more comfortable (and I think it would be more easy to understand going forward) if the various structures from mcpl.h were replicated exactly. I understand that the memory layout of for instance:

   typedef struct MCPL_API { void * internal; } mcpl_file_t;  

   is in reality the same as the raw void-pointer, and that it therefore technically works to pretend it is instead:

   typedef void* mcpl_file_handle_repr_t;

   Would it not be more obvious to simply have a section where you repeat the necessary typedef's from mcpl.h in your code, with clear comments around it telling people that these must be kept EXACTLY as in mcpl.h?
   Anyway, it is not a deal-breaker for me.

2. As was also discussed during the PR of the corresponding NCrystal feature, I am very much skeptical of having dlclose/FreeLibrary calls. Unlike free'ing a piece of allocated memory like a good citizen, there is simply too many potential pitfalls when it comes to library unloading.

3. Instead of having the diagnostic message just telling people that they might want to "pip install mcpl", perhaps it would be sensible to also remind them of the option to conda install mcpl? (to avoid getting pypi pkgs in the users conda env, where conda mcpl pkgs would be the better choice.

4. If I understand correctly, you now emit a fatal error if you run on an mcpl file containing a particle type not supported by OpenMC. That is not in general how we recommend applications to consume MCPL files, since it makes it harder to interchange files between applications. Instead we recommend that any unsupported particles encountered are skipped over, and that the application emits some sort of diagnostics message to warn the user (this could perhaps be a final summary message or warning like: "3% of the particles in the MCPL source were ignored since their particle type is not supported by OpenMC").

   As an example, Providing an MCPL file to McStas which contains both neutrons and gammas from a moderator simulation, McStas will use the neutrons and merely warn the user that so and so many particles were ignored.

   The alternative is that users will have to pre-filter MCPL files depending on the application in which they want them to be used, and at that point they become a bit less "universally interchangeable".

Anyway, apart from the points above and the fact that it was just a quick skim-through, it all looks great to me :-)

[ahnaf-tahmid-chowdhury]

Hi @tkittel,

Thank you very much for taking the time to review the changes and for your excellent, detailed feedback.

Here’s a summary of the key changes based on your points:

• ABI-Compliant Handles: I've updated the code to replicate the opaque mcpl_file_t and mcpl_outfile_t structs from mcpl.h instead of just using void*.

• Library Unloading: I have removed the dlclose/FreeLibrary call at exit. The library handle is now intentionally "leaked," which is the safer approach to avoid the potential pitfalls of unloading a shared library that might still be in use.

• Installation Help: I've added 'conda install mcpl' to the user-facing error message to provide a more complete set of installation options.

• Handling of Unsupported Particles: The code now iterates through all particles in the MCPL file, skips any with PDG codes not supported by OpenMC, and then issues a summary warning to the user detailing how many particles (and what percentage) were skipped. A fatal error is now only triggered if the file contains no usable particles at all, ensuring the simulation doesn't start with an empty source.

[tkittel]

Great @ahnaf-tahmid-chowdhury, all looks good as far as I am concerned then 😄

[shimwell]

Many thanks for the suggested improvements @tkittel and updated implementation @ahnaf-tahmid-chowdhury
I am keen to leave this for a few days to settle but will merge this on Monday if there are no objections?

[shimwell]

@paulromano is this one ok to merge, I see you have a holding review on it.

[paulromano]

Just made a few small updates here but otherwise looks good. Thanks all!