fix(custom_experiments): required_properties parameter of decorator was required instead of optional (#278)

* fix(core): required_properties param of decorator should be optional

* build(core): Add custom experiment example

Test the custom experiment we give as example to user in docs.

* test: there should now be 3 experiments

* fix(test): update other assertion

* fix(test): update one more assertion

---------

Co-authored-by: Alessandro Pomponio <[email protected]>

Author: michael-johnston

examples/density_example/density/__init__.py

@@ -0,0 +1,2 @@
+# Copyright (c) IBM Corporation
+# SPDX-License-Identifier: MIT

examples/density_example/density/density.py

@@ -0,0 +1,12 @@
+# Copyright (c) IBM Corporation
+# SPDX-License-Identifier: MIT
+
+from typing import Any
+
+from orchestrator.modules.actuators.custom_experiments import custom_experiment
+
+
+@custom_experiment(output_property_identifiers=["density"])
+def calculate_density(mass: float, volume: float) -> dict[str, Any]:
+    density_value = mass / volume if volume else None
+    return {"density": density_value}

examples/density_example/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["hatchling", "uv-dynamic-versioning>=0.7.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "density_test"
+description = "Example custom experiment from website docs"
+dynamic = ["version"]
+
+[tool.hatch.build]
+# Include the full namespace path
+include = [
+    "density/**",
+]
+
+[tool.hatch.build.targets.wheel]
+only-include = [
+    "density"
+]
+
+[tool.hatch.version]
+source = "uv-dynamic-versioning"
+
+[tool.uv-dynamic-versioning]
+vcs = "git"
+style = "pep440"
+pattern = "default-unprefixed"
+fallback-version = "0.0.0"
+tagged-metadata = true
+dirty = true
+bump = true
+
+#Add entry point for custom experiments
+[project.entry-points."ado.custom_experiments"]
+optimization_test_functions = "density.density"
+

orchestrator/modules/actuators/custom_experiments.py

@@ -275,8 +275,8 @@ def check_parameters_valid(func, _required_properties, _optional_properties):
 
 
 def custom_experiment(
-    required_properties: list[ConstitutiveProperty | ObservedProperty],
     output_property_identifiers: list[str],
+    required_properties: list[ConstitutiveProperty | ObservedProperty] | None = None,
     optional_properties: list[ConstitutiveProperty] | None = None,
     parameterization: dict[str, typing.Any] | None = None,
     metadata: dict[str, typing.Any] | None = None,
@@ -323,6 +323,7 @@ def calculate_density(mass, volume):
 
     metadata = metadata if metadata else {}
     logger = logging.getLogger("custom_experiment_decorator")
+    required_properties = required_properties if required_properties else []
 
     ray_options_model = None
     if ray_options is not None:

pyproject.toml

@@ -82,6 +82,7 @@ test = [
     "ado-ray-tune",
     "ado-sfttrainer",
     "anomalous-series",
+    "density-test",
     "optimization-test-functions",
     "pfas-custom-functions",
     "profile-space",
@@ -100,6 +101,7 @@ members = [
     "plugins/operators/profile_space",
     "plugins/operators/anomalous_series",
     "plugins/actuators/example_actuator",
+    "examples/density_example",
 ]
 
 [tool.uv.sources]
@@ -110,6 +112,7 @@ pfas-custom-functions = { workspace = true }
 profile-space = { workspace = true }
 anomalous-series = { workspace = true }
 robotic-lab = { workspace = true }
+density-test = { workspace = true }
 
 [project.scripts]
 ado = "orchestrator.cli.core.cli:app"

tests/actuators/test_actuators.py

@@ -104,12 +104,13 @@ def test_custom_experiments(objectiveFunctionConfiguration, experiment_catalogs)
     #  - examples/optimization_test_functions/custom_experiments
     # Locally this may not work because we might have more or less of these.
     assert (
-        len(catalog.experiments) == 2
-    ), "Expected 2 experiments in the custom_experiments catalog for testing "
+        len(catalog.experiments) == 3
+    ), "Expected 3 experiments in the custom_experiments catalog for testing "
 
     identifiers = {e.identifier for e in catalog.experiments}
     assert {
         "acid_test",
+        "calculate_density",
         "nevergrad_opt_3d_test_func",
     } == identifiers, f"Expected the experiments to be called - acid_test and nevergrad_opt_3d_test_func but they are called {identifiers}"
     loaded = custom_experiments.loadedExperiment.remote(
@@ -124,7 +125,7 @@ def test_custom_experiments(objectiveFunctionConfiguration, experiment_catalogs)
         "custom_experiments"
     )
 
-    assert len(c.experiments) == 2
+    assert len(c.experiments) == 3
 
     for e in c.experiments:
         assert catalog.experimentForReference(e.reference) is not None

tox.ini

@@ -51,6 +51,8 @@ commands=
     pytest -n auto --dist worksteal -rx -vv --log-level=INFO --color=yes tests/
     # Run the SFTTrainer tests
     pytest -n auto --dist worksteal -rx -vv --log-level=INFO --color=yes plugins/actuators/sfttrainer/ado_actuators/sfttrainer/tests/
+    # Basic test of custom experiment examples
+    ado describe experiment calculate_density
     # Basic test of ray_tune
     ado get operator ray_tune
     ado template operation --operator-name=ray_tune