From c65e721d9a48308ccea9072b0d428b54c9bc9350 Mon Sep 17 00:00:00 2001 From: Enrico Stragiotti <44843509+enricostragiotti@users.noreply.github.com> Date: Tue, 17 Dec 2024 10:22:55 +0100 Subject: [PATCH 1/2] Update the documentation on how to build the documentation (#697) Co-authored-by: Enrico Stragiotti --- doc/_src_docs/dev_docs.rst | 3 ++- doc/_src_docs/dev_docs.rstx | 3 ++- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/doc/_src_docs/dev_docs.rst b/doc/_src_docs/dev_docs.rst index 4514f7812..0a20294a8 100644 --- a/doc/_src_docs/dev_docs.rst +++ b/doc/_src_docs/dev_docs.rst @@ -43,7 +43,8 @@ Users can read the docs online at `smt.readthedocs.io Date: Tue, 17 Dec 2024 10:58:46 +0100 Subject: [PATCH 2/2] Add the option to specify a seed for the Random sampling method (#696) * Add the option to specify a seed for the Random sampling method * Behaviour is controlled by the numpy version used * Create unit tests * Update doc with new option and add seed to test function to avoid to generete different image every time the doc is compiled * Change authors order --------- Co-authored-by: Enrico Stragiotti --- AUTHORS.md | 1 + doc/_src_docs/sampling_methods.rst | 2 +- doc/_src_docs/sampling_methods/random.rst | 7 +- .../random_Test_run_random.png | Bin 15698 -> 16195 bytes .../sampling_methods_Test_run_random.png | Bin 15226 -> 16195 bytes smt/sampling_methods/random.py | 48 +++++++++++- smt/sampling_methods/tests/test_random.py | 73 ++++++++++++++++++ .../tests/test_sampling_method_examples.py | 2 +- 8 files changed, 129 insertions(+), 4 deletions(-) create mode 100644 smt/sampling_methods/tests/test_random.py diff --git a/AUTHORS.md b/AUTHORS.md index 3bfcd4e79..217aef5ff 100644 --- a/AUTHORS.md +++ b/AUTHORS.md @@ -15,6 +15,7 @@ SMT has been developed thanks to contributions from: * Andres Lopez Lopera * Antoine Averland * Emile Roux +* Enrico Stragiotti * Ewout ter Hoeven * Florent Vergnes * Frederick Zahle diff --git a/doc/_src_docs/sampling_methods.rst b/doc/_src_docs/sampling_methods.rst index ce47bdc22..d012bb141 100644 --- a/doc/_src_docs/sampling_methods.rst +++ b/doc/_src_docs/sampling_methods.rst @@ -25,7 +25,7 @@ Usage from smt.sampling_methods import Random xlimits = np.array([[0.0, 4.0], [0.0, 3.0]]) - sampling = Random(xlimits=xlimits) + sampling = Random(xlimits=xlimits, random_state=12) num = 50 x = sampling(num) diff --git a/doc/_src_docs/sampling_methods/random.rst b/doc/_src_docs/sampling_methods/random.rst index f14d9d3dd..08519e2d4 100644 --- a/doc/_src_docs/sampling_methods/random.rst +++ b/doc/_src_docs/sampling_methods/random.rst @@ -14,7 +14,7 @@ Usage from smt.sampling_methods import Random xlimits = np.array([[0.0, 4.0], [0.0, 3.0]]) - sampling = Random(xlimits=xlimits) + sampling = Random(xlimits=xlimits, random_state=12) num = 50 x = sampling(num) @@ -52,3 +52,8 @@ Options - None - ['ndarray'] - The interval of the domain in each dimension with shape nx x 2 (required) + * - random_state + - None + - None + - ['NoneType', 'int', 'RandomState', 'Generator'] + - Numpy RandomState or Generator object or seed number which controls random draws diff --git a/doc/_src_docs/sampling_methods/random_Test_run_random.png b/doc/_src_docs/sampling_methods/random_Test_run_random.png index 84257b2350af08ce29c956906813dd79638785f3..c559304341fca99faa2dc60e4944ee93c878433a 100644 GIT binary patch literal 16195 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 literal 15698 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 literal 15226 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 jJu}L`{x812S-(NnX7x-zkUGo|fq(L6Rb 2.0.0, or use the legacy numpy.random.RandomState " + "class in the future.", + FutureWarning, + ) + elif isinstance(self.options["random_state"], int): + self.random_state = np.random.RandomState(self.options["random_state"]) + else: + self.random_state = np.random.RandomState() + else: + # Construct a new Generator with the default BitGenerator (PCG64). + # If passed a Generator, it will be returned unaltered. When passed a legacy + # RandomState instance it will be coerced to a Generator. + self.random_state = np.random.default_rng(seed=self.options["random_state"]) + def _compute(self, nt): """ Implemented by sampling methods to compute the requested number of sampling points. @@ -30,4 +71,9 @@ def _compute(self, nt): """ xlimits = self.options["xlimits"] nx = xlimits.shape[0] - return np.random.rand(nt, nx) + if numpy_version < (2, 0): # Version is below 2.0.0 + return self.random_state.rand(nt, nx) + else: + # Create a Generator object with a specified seed (numpy.random_state.rand(nt, nx) + # is being deprecated) + return self.random_state.random((nt, nx)) diff --git a/smt/sampling_methods/tests/test_random.py b/smt/sampling_methods/tests/test_random.py new file mode 100644 index 000000000..9e00bc7f5 --- /dev/null +++ b/smt/sampling_methods/tests/test_random.py @@ -0,0 +1,73 @@ +import unittest +from unittest.mock import patch + +import numpy as np +import numpy.testing as npt + +from smt.sampling_methods import Random + + +class TestRandomSamplingMethod(unittest.TestCase): + def setUp(self): + self.xlimits = np.array([[0.0, 1.0], [0.0, 1.0]]) # 2D unit hypercube + + def test_random_state_initialization_legacy(self): + # Test random state initialization for numpy < 2.0.0 + with patch("smt.sampling_methods.random.numpy_version", new=(1, 21)): + sampler = Random(xlimits=self.xlimits, random_state=12) + self.assertIsInstance(sampler.random_state, np.random.RandomState) + + def test_random_state_initialization_new(self): + # Test random state initialization for numpy >= 2.0.0 + with patch("smt.sampling_methods.random.numpy_version", new=(2, 0)): + sampler = Random(xlimits=self.xlimits, random_state=12) + self.assertIsInstance(sampler.random_state, np.random.Generator) + + def test_random_state_warning_for_generator_legacy(self): + # Test that a warning is issued when using Generator with numpy < 2.0.0 + with ( + patch("smt.sampling_methods.random.numpy_version", new=(1, 21)), + self.assertWarns(FutureWarning), + ): + sampler = Random(xlimits=self.xlimits, random_state=np.random.default_rng()) + self.assertIsInstance(sampler.random_state, np.random.RandomState) + + def test_compute_legacy(self): + # Test _compute method for numpy < 2.0.0 + with patch("smt.sampling_methods.random.numpy_version", new=(1, 26)): + sampler = Random(xlimits=self.xlimits, random_state=12) + points = sampler(4) + self.assertEqual(points.shape, (4, 2)) + self.assertTrue(np.all(points >= 0) and np.all(points <= 1)) + # Check almost equality with known seed-generated data (example) + expected_points = np.array( + [ + [0.154163, 0.74005], + [0.263315, 0.533739], + [0.014575, 0.918747], + [0.900715, 0.033421], + ] + ) + npt.assert_allclose(points, expected_points, rtol=1e-4) + + def test_compute_new(self): + # Test _compute method for numpy >= 2.0.0 + with patch("smt.sampling_methods.random.numpy_version", new=(2, 2)): + sampler = Random(xlimits=self.xlimits, random_state=12) + points = sampler(4) + self.assertEqual(points.shape, (4, 2)) + self.assertTrue(np.all(points >= 0) and np.all(points <= 1)) + # Check almost equality with known seed-generated data (example) + expected_points = np.array( + [ + [0.250824, 0.946753], + [0.18932, 0.179291], + [0.349889, 0.230541], + [0.670446, 0.115079], + ] + ) + npt.assert_allclose(points, expected_points, rtol=1e-4) + + +if __name__ == "__main__": + unittest.main() diff --git a/smt/sampling_methods/tests/test_sampling_method_examples.py b/smt/sampling_methods/tests/test_sampling_method_examples.py index 2e1da1d8e..111b6c7fa 100644 --- a/smt/sampling_methods/tests/test_sampling_method_examples.py +++ b/smt/sampling_methods/tests/test_sampling_method_examples.py @@ -18,7 +18,7 @@ def run_random(): from smt.sampling_methods import Random xlimits = np.array([[0.0, 4.0], [0.0, 3.0]]) - sampling = Random(xlimits=xlimits) + sampling = Random(xlimits=xlimits, random_state=12) num = 50 x = sampling(num)