Update docs

Author: toby-coleman

docs/examples/tutorials/tuning-a-process.md

@@ -73,3 +73,31 @@ Plugboard's YAML config supports an optional `tune` section, allowing you to def
 3.  Parameters need to reference a type, so that Plugboard knows the type of parameter to build.
 
 Now run `plugboard process tune model-with-tuner.yaml` to execute the optimisation job from the CLI.
+
+## Advanced usage: complex search spaces
+
+Occasionally you may need to define more complex search spaces, which go beyond what can be defined with a simple parameter configuration. For example:
+
+*  Conditional parameters, e.g. where parameter `a` must be greater than parameter `b`; or
+*  Looping, e.g. building up a list of tunable parameters that is of variable length.
+
+These conditional search space functions are supported by Ray Tune and can be defined as described in the [Ray documentation](https://docs.ray.io/en/latest/tune/examples/optuna_example.html#conditional-search-spaces). To use such a function you will need to:
+
+1. Setup the [`Tuner`][plugboard.tune.Tuner], defining your parameters as usual;
+2. Write a custom function to define the search space, where each tunable parameter has a name of the form `"{component_name.field_or_arg_name}"`; then
+3. Supply your custom function to the `OptunaSpec` algorithm configuration.
+
+For example, the following search space makes the velocity depend on the angle:
+```python
+--8<-- "examples/tutorials/006_optimisation/hello_tuner.py:custom_search_space"
+```
+
+Then use this configuration to point the  tuner to the `custom_space` function.
+```yaml
+--8<-- "examples/tutorials/006_optimisation/model-with-tuner-custom.yaml"
+```
+
+1. We can reference a [`Process`][plugboard.process.Process] from another YAML file here to avoid repetition.
+2. Add the algorithm configuration here.
+
+Then run using `plugboard process tune model-with-tuner-custom.yaml`.

examples/tutorials/006_optimisation/hello_tuner.py

@@ -2,7 +2,7 @@
 
 # fmt: off
 import typing as _t
-
+from optuna import Trial
 from plugboard.component import Component, IOController as IO
 from plugboard.process import ProcessBuilder
 from plugboard.schemas import ComponentArgsDict, ProcessSpec, ProcessArgsSpec, ObjectiveSpec
@@ -64,6 +64,15 @@ async def step(self) -> None:
 # --8<-- [end:components]
 
 
+# --8<-- [start:custom_search_space]
+def custom_space(trial: Trial) -> dict[str, _t.Any] | None:
+    """Defines a custom search space for Optuna."""
+    angle = trial.suggest_int("trajectory.angle", 0, 90)
+    # Make velocity depend on angle
+    trial.suggest_int("trajectory.velocity", angle, 100)
+# --8<-- [end:custom_search_space]
+
+
 if __name__ == "__main__":
     # --8<-- [start:define_process]
     process_spec = ProcessSpec(

examples/tutorials/006_optimisation/model-with-tuner-custom.yaml

@@ -0,0 +1,30 @@
+plugboard:
+  process: model-with-tuner.yaml  # (1)!
+  tune:
+    args:
+      objective:
+        object_name: max-height
+        field_type: field
+        field_name: max_y
+      parameters:
+      - type: ray.tune.uniform
+        object_type: component
+        object_name: trajectory
+        field_type: arg
+        field_name: angle
+        lower: 0
+        upper: 90
+      - type: ray.tune.uniform
+        object_type: component
+        object_name: trajectory
+        field_type: arg
+        field_name: velocity
+        lower: 0
+        upper: 100
+      num_samples: 40
+      mode: max
+      max_concurrent: 4
+      algorithm:  # (2)!
+        type: ray.tune.search.optuna.OptunaSearch
+        space: hello_tuner.custom_space
+