Bug/220 spice makes bsk sims not thread safe

[Natsoulas]

• Tickets addressed: Spice makes BSK simulations not thread safe #220
• Review: By commit

Description

The changes implement thread safety for the SPICE interface to address GitHub issue #220, which reported deadlocks and data corruption when running parallel Monte Carlo simulations.

This solution uses a mutex and reference counting approach to protect SPICE kernel loading and unloading operations (inspired by Juan's suggestion comment on the issue):

1. Added a static mutex kernel_manipulation_mutex in the SpiceInterface class
2. Added a static reference counter kernel_reference_counter to track kernel usage
3. Modified loadSpiceKernel() to only load kernels once and use reference counting
4. Modified unloadSpiceKernel() to only unload kernels when no longer needed
5. Protected clearKeeper() with the mutex
6. Updated the destructor to properly unload kernels

This ensures that when multiple simulations run in parallel, they won't encounter race conditions or deadlocks when accessing SPICE kernels.

Verification

The changes were verified with a dedicated thread safety unit test:

• Added test_spiceThreadSafety.py unit test in the SPICE interface's _UnitTest directory
• The test creates multiple SpiceInterface instances in parallel and forces them to simultaneously load/unload kernels
• It verifies no deadlocks occur and no kernel files are corrupted
• No existing functionality was broken - all other SPICE-related tests continue to pass

The test specifically reproduces the conditions described in issue #220.

Documentation

Added code comments explaining the thread safety mechanism in:

• spiceInterface.h for the static mutex and reference counter
• spiceInterface.cpp for the mutex implementation and kernel reference counting logic

No existing documentation was invalidated.

Future work

1. Monitor for the release of NAIF's thread-safe SPICE implementation, which may provide a better solution in the future (Juan's advice from a comment in the issue 220 page).

[schaubh]

nice work! All tests passed on my system. Just some minor comments to address

[schaubh]

Nice work, looks like we are there. @juan-g-bonilla , as you commented on the original issue with the suggestion to use a mutex, would you have time to take a look at this code?

[juan-g-bonilla]

Nicely done @Natsoulas ! Many of my comments are actually encouraging you to fix existing issues or even the original fix I proposed so we can get this class to its highest quality possible.

Thanks for the tag @schaubh .

[Natsoulas]

@juan-g-bonilla
My latest implementation doesn't look exactly like ur suggestions, but I was able to use a majority of your suggested quality improvements like using unordered map and string concatenation etc. Thank you!

[schaubh]

Some quick comments to address.

[juan-g-bonilla]

Left some minor suggestions + a warning about an edge cases when unloading happens before loading. Would be great to address those, but otherwise if you address Dr Shaub's comments LGTM.

[schaubh]

good to go. Thanks for addressing this long-standing issue.

[Mark2000]

This PR is leading to errors in some of my unit tests in BSK-RL, BSK_ERROR: Attempting to unload kernel that was never loaded for every spice file (https://github.com/AVSLab/bsk_rl/actions/runs/15291893777/job/43012764022?pr=268). Specifically, I had a "safe" way of trying to unload spice

    def __del__(self) -> None:
        """Unload spice kernels when object is deleted."""
        try:
            self.gravFactory.unloadSpiceKernels()
        except AttributeError:
            pass

but I believe that is no longer working. I'm not sure if it's newly trying to unload files that weren't explicitly loaded, or if it always tried that but the error is being passed in a way that's no longer caught by my code. The error is triggered when this object (https://github.com/AVSLab/bsk_rl/blob/f70bd259049f2bcdc40c76eb258736968bf98cf2/src/bsk_rl/utils/orbital.py#L294) is created then deleted.

[schaubh]

@Natsoulas , please see Mark's recent issue with your branch. Could you please take a look at this?

[Natsoulas]

I'll take a look asap.