Fix windows error where random seeds could be too large for C long

[AlexanderFengler]

This pull request focuses on improving the robustness and clarity of random seed handling for the C-level random number generator (RNG) used in the simulator. The main changes ensure that integer seeds passed to the simulator are always within the valid range for a 32-bit signed C long, preventing platform-dependent errors, especially on Windows. Additionally, the documentation has been updated for clarity, and new tests and notebooks have been added for validation and demonstration purposes.

Random seed validation and handling improvements:

• Added a new function _validate_random_state_for_c_rng in simulator.py to check that integer seeds provided to the simulator are within the valid 32-bit signed C long range ([-231, 231 - 1]). This prevents overflow errors in the Cython layer, particularly on Windows, and provides a clear Python error if the value is out of range.
• Updated the _get_unique_seed function to generate seeds within the safe range for all platforms, matching the requirements of the C-level RNG.
• Integrated the new seed validation function into both the simulator function and the simulate method of Simulator class, ensuring all entry points enforce the seed range. [1] [2]
• Updated imports in simulator_class.py to include the new validation function.

Documentation updates:

• Clarified the docstrings for the random_state parameter in both simulator and simulate to specify the valid integer range and the reason for the restriction (compatibility with C long). [1] [2]

Testing and demonstration:

• Added a new notebook notebooks/int_bug_test.ipynb to test simulator behavior with various models and seeds, and to check the package version.
• Added a new notebook notebooks/test_ziggurat.ipynb that implements and visualizes the Ziggurat algorithm for Gaussian random number generation, likely for further RNG testing or demonstration.

Other changes:

• Bumped the package version to 0.12.4 in pyproject.toml to reflect these improvements and fixes.
• Added missing import of numbers to simulator.py for type checking in the new validation function.

These changes make the simulator more robust across platforms, prevent subtle bugs related to random seed overflow, and improve clarity for users and developers.

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB

[codecov]

Codecov Report

❌ Patch coverage is 92.85714% with 1 line in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
ssms/basic_simulators/simulator.py	92.30%	1 Missing ⚠️

Flag	Coverage Δ
unittests	92.38% <92.85%> (-0.01%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
ssms/basic_simulators/simulator_class.py	81.56% <100.00%> (+0.10%)	⬆️
ssms/basic_simulators/simulator.py	89.53% <92.30%> (+0.11%)	⬆️

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.