Documentation for run_args

docs/neps_run.md

@@ -38,6 +38,16 @@ To define a budget, provide either or both of the following parameters:
       for example, return {'loss': loss, 'cost': cost}. For more details, please refer
       [here](https://automl.github/io/neps/latest/run_pipeline)
 
+You have the option to configure all arguments using a YAML file. This can be done by specifying the file path with
+the following argument:
+
+- **`run_args`** (str): Path to the YAML file for argument configuration. See [setup details](#setup-run_args) for more.
+
+!!! note "Note"
+        Currently we have a strict usage for `run_args`. So you can define either all arguments by providing them
+        directly to neps.run or via the yaml file. This might change in the future. If you use yaml, directly provided
+        arguments get overwritten either by the defined yaml config or the default value.
+
 ### Optional Arguments
 ##### Further Monitoring Options
   - **`overwrite_working_directory`** (bool, default: False): When set to True, the working directory
@@ -78,13 +88,104 @@ the [Parallelization Overview](#parallelization).
     manually which of the optimization strategy to use. Provide a string identifying one of the built-in
     search strategies or an instance of a custom `BaseOptimizer`.
   - **`searcher_path`** (Path | str, default: None): A path to a custom searcher implementation.
-  - **`**searcher_kwargs`**: Additional keyword arguments to be passed to the searcher.
+  - **`searcher_kwargs`**: Additional keyword arguments to be passed to the searcher.
+
 
   For more information about the available searchers and how to customize your own, refer
 [here](https://automl.github.io/neps/latest/optimizers).
 ##### Others
   - **`pre_load_hooks`** (Iterable, default: None): A list of hook functions to be called before loading results.
 
+## Setup `run_args`
+
+To configure the execution parameters, you can also define them via a YAML file provided through the `run_args`
+argument. Parameters not explicitly defined within this file will receive their default values. Below is
+an example of how to structure your YAML configuration.
+
+```yaml
+run_args:  # Essential starting key; everything under this key gets considered for configuration.
+  run_pipeline:
+    path: "path/to/your/run_pipeline" # File path of the run_pipeline function
+    name: "name_of_your_run_pipeline" # Function name
+  pipeline_space: "path/to/your/search_space.yaml" # Path of the search space yaml file
+  root_directory: "neps_results"  # Output directory for results
+  max_evaluations_total: 100
+  post_run_summary: # Defaults applied if left empty
+  searcher: "bayesian_optimization"
+  searcher_kwargs:
+    initial_design_size: 5
+    surrogate_model: "gp"
+...
+```
+Once you've configured your YAML file as shown above, execute your setup by passing the file path to neps.run like this:
+```python
+neps.run(run_args="path/to/your/config.yaml")
+```
+### Special Loading Procedures
+For defining `run_args`, some settings like `run_pipeline`, `pre_load_hooks`, and custom `searcher` need both a path
+and a name to dynamically load them. This is crucial for components where NePS must find and execute specific code.
+Below, the configurations for dynamic loading are outlined:
+
+- **`run_pipeline`**:
+    Specify the path and name of the pipeline function. This information allows NePS to find and initiate the desired
+    pipeline.
+    ```yaml
+    run_pipeline:
+      path: <path_to_run_pipeline>
+      name: <run_pipeline_name>
+    ```
+
+
+- **`pipeline_space`**:
+The pipeline_space configuration supports two modes of definition: directly in a YAML file or through a Python
+dictionary that NePS can dynamically load.
+      - **Direct YAML File Path**: Simply specify the path to your search space YAML.
+        ```yaml
+        pipeline_space: "path/to/your/search_space.yaml"
+        ```
+      - **Python Dictionary**: To define pipeline_space as a Python dictionary, specify the file path containing the
+        dictionary and its name. This enables dynamic loading by NePS.
+          ```yaml
+          pipeline_space:
+            path: <path_to_pipeline_space>
+            name: <pipeline_space_name>
+          ```
+
+
+- **`searcher`**:
+Configure the searcher to either utilize a built-in searcher or integrate a custom searcher of your creation.
+      - **Built-in Searcher**: For using an already integrated searcher, simply specify its key. This is the
+        straightforward method for standard optimization scenarios.
+          ```yaml
+          searcher: "bayesian_optimization" # key of the searcher
+          ```
+      - **Custom Searcher**: If you've developed a custom optimization algorithm and wish to employ it within NePS,
+        specify the path and name of your custom searcher class. This allows NePS to dynamically load and use your
+        custom implementation.
+          ```yaml
+          searcher:
+            path: <path_to_custom_searcher_class>
+            name: <custom_searcher_class_name>
+          ```
+
+
+- **`pre_load_hooks`**:
+    Define hooks to be loaded before the main execution process begins. Assign each hook a unique identifier (e.g.
+    hook1, hook2..) and detail the path to its implementation file along with the function name.
+    This setup enables NePS to dynamically import and run these hooks during initialization.
+        ```yaml
+        pre_load_hooks:
+          hook1:  # # Assign any unique key.
+            path: <path_to_hook>  # Path to the hook's implementation file.
+            name: <function_name>  # Name of the hook.
+          hook2:
+            path: <path_to_hook>
+            name: <function_name>
+        ```
+
+
+For detailed examples and specific use case configurations,
+visit [here](https://github.com/automl/neps/tree/master/neps_examples/basic_usage/yaml_usage)
 ## Parallelization
 
 `neps.run` can be called multiple times with multiple processes or machines, to parallelize the optimization process.

neps/utils/cli.py

@@ -4,7 +4,7 @@
 import neps
 
 
-def init_config():
+def init_config(args):
     # Define the paths for the configuration files
     config_path = "config.yaml"
     search_space_path = "search_space.yaml"

neps/utils/run_args_from_yaml.py

@@ -405,6 +405,7 @@ def check_essential_arguments(
         max_cost_total: Max allowed total cost for experiments.
         max_evaluation_total: Max allowed evaluations.
         searcher: Optimizer for the configuration space.
+        run_args: A YAML file containing the configuration settings.
 
     Raises:
         ValueError: Missing or invalid essential arguments.

tests/test_yaml_run_args/test_yaml_run_args.py

@@ -2,7 +2,6 @@
 import neps
 from neps.utils.run_args_from_yaml import get_run_args_from_yaml
 from neps.optimizers.bayesian_optimization.optimizer import BayesianOptimization
-from neps.search_spaces.search_space import SearchSpace
 
 BASE_PATH = "tests/test_yaml_run_args/"
 pipeline_space = dict(lr=neps.FloatParameter(lower=1.2, upper=4.2),
@@ -86,7 +85,6 @@ def are_functions_equivalent(f1, f2):
     assert output == expected_output, f"Expected {expected_output}, but got {output}"
 
 
-
 @pytest.mark.neps_api
 @pytest.mark.parametrize(
     "yaml_path,expected_output",