Phase 3: common/named product (#133)

* Add named_product implementation

Signed-off-by: Maria Teresa Ortega <teresa.ortega0903@gmail.com>

* Add test_named_product

Signed-off-by: Maria Teresa Ortega <teresa.ortega0903@gmail.com>

* Switch from unittest to pytest

Signed-off-by: Maria Teresa Ortega <teresa.ortega0903@gmail.com>

* pytest parametrize

Signed-off-by: Maria Teresa Ortega <teresa.ortega0903@gmail.com>

* Address some reviews

Signed-off-by: Maria Teresa Ortega <teresa.ortega0903@gmail.com>

* Fix kwargs

Signed-off-by: Maria Teresa Ortega <teresa.ortega0903@gmail.com>

* Add comments

Signed-off-by: Maria Teresa Ortega <teresa.ortega0903@gmail.com>

* Fixed TODO comments

Signed-off-by: Maria Teresa Ortega <teresa.ortega0903@gmail.com>

---------

Signed-off-by: Maria Teresa Ortega <teresa.ortega0903@gmail.com>

Author: teresa-ortega

pyproject.toml

@@ -53,4 +53,4 @@ convention = "google"
 [tool.pytest.ini_options]
 testpaths = ["test"]
 pythonpath = [".",
-             "examples"]
+             "examples", "src"]

src/lambkin/common/__init__.py

@@ -16,3 +16,9 @@
 
 Exposes named_product and all base exceptions for convenience.
 """
+
+from .named_product import named_product
+
+__all__ = [
+    "named_product",
+]

src/lambkin/common/named_product.py

@@ -17,3 +17,44 @@
 Provides named_product(), a utility to generate combinatorial parameter sets.
 Used to define benchmark configurations in a readable and structured way.
 """
+
+import itertools
+
+
+def named_product(**parameters):
+    """Generate all combinations of named parameters.
+
+    Takes parameters where each value is a list of options
+    and returns a list of dictionaries representing every possible
+    combination, one dictionary per benchmark run configuration.
+
+    Args:
+        **parameters: Named parameter lists to combine. Each value must be a list.
+
+    Returns:
+        A list of dicts, each mapping parameter names to a specific value.
+    """
+    # Example:
+    # parameters == (sensor_model = [likelihood_field,beam],
+    #            num_particles = [1, 10, 1000, 2000])
+
+    # keys = ("sensor_model", "num_particles")
+    keys = list(parameters.keys())
+
+    # values = ( [likelihood_field,beam],[1, 10, 1000, 2000] )
+    values = list(parameters.values())
+
+    # TODO(teresa-ortega): Empty list exception
+
+    # Make combinations
+    combinations = itertools.product(*values)
+
+    # Create the dictionary
+    variants = []
+    for combination in combinations:
+        # Re-attach the parameter labels to the generated values.
+        # zip() pairs keys with values; dict() creates the mapping.
+        variant = dict(zip(keys, combination, strict=True))
+        # TODO(teresa-ortega) : combination fails
+        variants.append(variant)
+    return variants

test/common/test_named_product.py

@@ -0,0 +1,60 @@
+# Copyright 2026 Ekumen, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Unit tests for the named_product function in lambkin.common."""
+
+import pytest
+
+from lambkin.common.named_product import named_product
+
+
+@pytest.mark.parametrize(
+    "parameters, expected_combinations , expected_len",
+    [
+        (  # Two parameters with 2 values each -> 2×2 = 4 combinations
+            {"sensor_model": ["likelihood_field", "beam"], "num_particles": [1, 10]},
+            [
+                {"sensor_model": "likelihood_field", "num_particles": 1},
+                {"sensor_model": "likelihood_field", "num_particles": 10},
+                {"sensor_model": "beam", "num_particles": 1},
+                {"sensor_model": "beam", "num_particles": 10},
+            ],
+            4,
+        ),
+        (  # Single parameter with 2 values -> 2 combinations
+            {"sensor_model": ["likelihood_field", "beam"]},
+            [
+                {"sensor_model": "likelihood_field"},
+                {"sensor_model": "beam"},
+            ],
+            2,
+        ),
+        (  # No parameters at all -> 1 combination: a single empty dict
+            {},
+            [{}],
+            1,
+        ),
+        (  # One parameter with an empty list -> no combinations can be formed
+            # TODO(teresa-ortega): if the user introduce a empty list -> Exception
+            {"sensor_model": [], "num_particles": [1]},
+            [],
+            0,
+        ),
+    ],
+)
+def test_named_product_combinations(parameters, expected_combinations, expected_len):
+    """named_product returns the correct number and combinations."""
+    result = named_product(**parameters)
+    assert result == expected_combinations
+    assert len(result) == expected_len

test/example/test_process_management.py

@@ -0,0 +1,54 @@
+# Copyright 2026 Ekumen, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Unit tests for the process management functions in lambkin.py."""
+
+import subprocess
+import time
+
+from examples.lambkin_benchmarking import execute_background_process, wait_for_processes
+
+
+def test_execute_background_process():
+    """Tests if execute_background_process correctly starts a process.
+
+    It verifies the process runs in the background without blocking
+    the main thread.
+    """
+    process = execute_background_process(["sleep", "3"])
+    assert process.poll() is None, "The process should be running in background."
+    process.terminate()
+    process.wait()
+
+
+def test_wait_for_processes():
+    """Tests if wait_for_processes properly blocks until waitlist completes.
+
+    It verifies that the function waits for the processes in the waitlist
+    and subsequently terminates the processes in the termination_list.
+    """
+    p_play = subprocess.Popen(["sleep", "2"])
+    p_infinite = subprocess.Popen(["sleep", "infinity"])
+
+    start_time = time.time()
+    wait_for_processes(waitlist=[p_play], termination_list=[p_infinite])
+    end_time = time.time()
+
+    total_time = end_time - start_time
+
+    assert total_time >= 2.0, "The function did not wait for the waitlist to finish."
+    assert total_time < 5.0, "The function got stuck waiting for the infinite process."
+    assert p_infinite.poll() is not None, (
+        "The process in the termination_list was not closed properly."
+    )