Added seed as an optional argument to pre_config hooks.

Author: LarsAsplund

docs/news.d/1176.feature.rst

@@ -0,0 +1 @@
+Added seed as an optional input to ``pre_config`` hooks. The seed is identical to the base seed provided to the simulation.

docs/py/ui.rst

@@ -102,9 +102,10 @@ There are two hooks to run user defined Python code.
 :pre_config: A ``pre_config`` is called before simulation of the test
              case. The function accepts an optional string argument
              ``output_path``, which is the filesystem path to the
-             directory where test outputs are stored, and an optional
+             directory where test outputs are stored, an optional
              string argument ``simulator_output_path`` which is the path
-             to the simulator working directory.
+             to the simulator working directory, and ``seed`` which is the
+             seed assigned to the test case.
 
              .. note::
                ``simulator_output_path`` is shared by all test runs. The
@@ -126,6 +127,11 @@ There are two hooks to run user defined Python code.
              code expecting input files to be located in the
              simulator working directory.
 
+             The use case for ``seed`` is to have access to a reproducible
+             seed for data randomization. The seed is identical to the
+             base seed provided to the simulation, see the
+             :doc:`run library user guide <../run/user_guide>`.
+
 :post_check: A ``post_check`` is called after a passing simulation of
              the test case. The function accepts an optional string argument
              ``output_path``, which is the filesystem path to the

docs/run/user_guide.rst

@@ -259,7 +259,7 @@ level of test coverage.
 The base seed is provided via the ``runner_cfg`` generic and new derived seeds can be obtained by calling the
 ``get_seed`` function with ``runner_cfg`` and a salt string. The salt string is hashed together with the base seed to
 ensure the uniqueness of each derived seed (with very high probability). The ``salt`` parameter can be omitted if only a
-single seed is needed:
+single seed is needed. In that case, the base seed is hashed with the empty string.
 
 .. raw:: html
     :file: img/get_seed_and_runner_cfg.html

tests/acceptance/artificial/vhdl/run.py

@@ -169,12 +169,27 @@ def pre_config(output_path):
 def configure_tb_seed(ui):
     tb = ui.library("lib").test_bench("tb_seed")
 
+    def make_pre_config(expected_seed=""):
+        def pre_config(seed):
+            print(f"pre_config seed: {seed}")
+            if not expected_seed:
+                assert seed != "0123456789abcdef"
+            else:
+                assert seed == expected_seed
+
+            return True
+
+        return pre_config
+
     if args.seed == "0123456789abcdef":
         tb.test("test_1").set_generic("expected_seed", "2e373913e5ad677d")
         tb.test("test_2").set_generic("expected_seed", "2e373913e5ad677d")
+        tb.set_pre_config(make_pre_config("0123456789abcdef"))
     elif args.seed == "repeat":
         tb.test("test_1").set_generic("expected_seed", "ffa08cd9489aad14")
         tb.test("test_2").set_generic("expected_seed", "9a292b3679afd081")
+        tb.test("test_1").set_pre_config(make_pre_config("7ac31eb89c4059f9"))
+        tb.test("test_2").set_pre_config(make_pre_config("8b1cd665d806e572"))
 
 
 def configure_tb_vunit_pkg(vu):

tests/unit/test_configuration.py

@@ -172,14 +172,14 @@ def post_check(output):
         )
 
     def test_call_pre_config_none(self):
-        self.assertEqual(self._call_pre_config(None, "output_path", "simulator_output_path"), True)
+        self.assertEqual(self._call_pre_config(None, "output_path", "simulator_output_path", "seed"), True)
 
     def test_call_pre_config_false(self):
         def pre_config():
             return False
 
         self.assertEqual(
-            self._call_pre_config(pre_config, "output_path", "simulator_output_path"),
+            self._call_pre_config(pre_config, "output_path", "simulator_output_path", "seed"),
             False,
         )
 
@@ -188,7 +188,7 @@ def pre_config():
             return True
 
         self.assertEqual(
-            self._call_pre_config(pre_config, "output_path", "simulator_output_path"),
+            self._call_pre_config(pre_config, "output_path", "simulator_output_path", "seed"),
             True,
         )
 
@@ -197,7 +197,7 @@ def pre_config():
             pass
 
         self.assertEqual(
-            self._call_pre_config(pre_config, "output_path", "simulator_output_path"),
+            self._call_pre_config(pre_config, "output_path", "simulator_output_path", "seed"),
             False,
         )
 
@@ -209,13 +209,7 @@ def pre_config(output_path):
             self.assertEqual(output_path, "output_path")
             raise WasHere
 
-        self.assertRaises(
-            WasHere,
-            self._call_pre_config,
-            pre_config,
-            "output_path",
-            "simulator_output_path",
-        )
+        self.assertRaises(WasHere, self._call_pre_config, pre_config, "output_path", "simulator_output_path", "seed")
 
     def test_call_pre_config_with_simulator_output_path(self):
         def pre_config(output_path, simulator_output_path):
@@ -226,13 +220,19 @@ def pre_config(output_path, simulator_output_path):
             self.assertEqual(simulator_output_path, "simulator_output_path")
             raise WasHere
 
-        self.assertRaises(
-            WasHere,
-            self._call_pre_config,
-            pre_config,
-            "output_path",
-            "simulator_output_path",
-        )
+        self.assertRaises(WasHere, self._call_pre_config, pre_config, "output_path", "simulator_output_path", "seed")
+
+    def test_call_pre_config_with_seed(self):
+        def pre_config(output_path, simulator_output_path, seed):
+            """
+            Pre config with output path
+            """
+            self.assertEqual(output_path, "output_path")
+            self.assertEqual(simulator_output_path, "simulator_output_path")
+            self.assertEqual(seed, "seed")
+            raise WasHere
+
+        self.assertRaises(WasHere, self._call_pre_config, pre_config, "output_path", "simulator_output_path", "seed")
 
     def test_call_pre_config_class_method(self):
         class MyClass(object):
@@ -243,30 +243,27 @@ class MyClass(object):
             def __init__(self, value):
                 self.value = value
 
-            def pre_config(self, output_path, simulator_output_path):
+            def pre_config(self, output_path, simulator_output_path, seed):
                 """
                 Pre config with output path
                 """
                 assert self.value == 2
                 assert output_path == "output_path"
                 assert simulator_output_path == "simulator_output_path"
+                assert seed == "seed"
                 raise WasHere
 
         self.assertRaises(
-            WasHere,
-            self._call_pre_config,
-            MyClass(value=2).pre_config,
-            "output_path",
-            "simulator_output_path",
+            WasHere, self._call_pre_config, MyClass(value=2).pre_config, "output_path", "simulator_output_path", "seed"
         )
 
     @staticmethod
-    def _call_pre_config(pre_config, output_path, simulator_output_path):
+    def _call_pre_config(pre_config, output_path, simulator_output_path, seed):
         """
         Helper method to test call_pre_config method
         """
         with _create_config(pre_config=pre_config) as config:
-            return config.call_pre_config(output_path, simulator_output_path)
+            return config.call_pre_config(output_path, simulator_output_path, seed)
 
     @staticmethod
     def _call_post_check(post_check, **kwargs):

vunit/configuration.py

@@ -148,7 +148,7 @@ def vhdl_assert_stop_level(self):
 
         return level
 
-    def call_pre_config(self, output_path, simulator_output_path):
+    def call_pre_config(self, output_path, simulator_output_path, seed):
         """
         Call pre_config if available. Setting optional output_path
         """
@@ -157,10 +157,7 @@ def call_pre_config(self, output_path, simulator_output_path):
 
         args = inspect.getfullargspec(self.pre_config).args
 
-        kwargs = {
-            "output_path": output_path,
-            "simulator_output_path": simulator_output_path,
-        }
+        kwargs = {"output_path": output_path, "simulator_output_path": simulator_output_path, "seed": seed}
 
         for argname in list(kwargs.keys()):
             if argname not in args:

vunit/test/suites.py

@@ -211,7 +211,7 @@ def run(self, output_path, read_output):
         for name in self._test_cases:
             results[name] = FAILED
 
-        if not self._config.call_pre_config(output_path, self._simulator_if.output_path):
+        if not self._config.call_pre_config(output_path, self._simulator_if.output_path, self._seed):
             return results
 
         # Ensure result file exists