Rename read_params_from_cmdline and save_metrics_params

Rename
- `read_params_from_cmdline` to `initialize_job`, and
- `save_metrics_params` to `finalize_job`.

The purpose of the renaming is to better reflect when/why to call the
functions instead of focusing too much on technical details.

The old names are kept as aliases but are marked as deprecated.

BREAKING: I used this occasion to remove the following options from
`initialize_job/read_params_from_cmdline`:
- `make_immutable`: Parameters are always immutable now.  If one really
  needs a mutable structure, this is still possible by copying the data.
- `save_params`: It simply always saves now.

Author: luator

CHANGELOG.md

@@ -55,8 +55,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Local submissions now store stdout and stderr to log files, like they would do on the cluster.
   This should be useful for debugging scripts to work with the cluster locally, as previously,
   there was no way to access the outputs of locally running jobs.
+- Renamed `read_params_from_cmdline` to `initialize_job`.  An alias with the old name is
+  available but will raise a FutureWarning.
+- Renamed `save_metrics_params` to `finalize_job`.  An alias with the old name is
+  available but will raise a FutureWarning.
 - *Relevant for Dev's only:* Use ruff instead of flake8 for linting.
 
+### Removed
+- Removed option `save_params` from `read_params_from_cmdline`.  They will always be
+  saved now.
+- Removed option `make_immutable` from `read_params_from_cmdline`.  Returned parameters
+  are always immutable now.  If needed, a mutable copy can be created with
+  `smart_settings.param_classes.AttributeDict(params)`.
+
 ### Added
 - Setting `generate_report` to control automatic report generation (See
   {ref}`config.general_settings`).
@@ -86,6 +97,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - The package has been renamed from "cluster" to "cluster_utils", please update your
   imports accordingly.  There is still a wrapper package with the old name (so existing
   code should still work) but it will be removed in the next major release.
+- `read_params_from_cmdline` is deprecated.  Use `initialize_job` instead.
+- `save_metrics_params` is deprecated.  Use `finalize_job` instead.
 
 
 ## 2.5 - 2023-10-05

README.md

@@ -72,7 +72,7 @@ def main(
 If you don't want to use a decorator, use the following:
 
 ```python
-from cluster_utils import read_params_from_cmdline, save_metrics_params
+import cluster_utils
 
 def main(params):
     results = ...  # Code that computes something interesting
@@ -81,12 +81,12 @@ def main(params):
 if __name__ == "__main__":
     # Dictionary that contains parameters passed by cluster_utils. This call also establishes 
     # communication with the cluster_utils server. Also contains "working_dir" and "id", as above.
-    params = read_params_from_cmdline()
+    params = cluster_utils.initialize_job()
 
     results = main(params)
 
     # Report results back to cluster_utils.
-    save_metrics_params(results)
+    cluster_utils.finalize_job(results)
 ```
 
 To start a cluster run, start the cluster_utils server on the login node of the cluster.

cluster_utils/__init__.py

@@ -6,6 +6,8 @@
     announce_fraction_finished,
     cluster_main,
     exit_for_resume,
+    finalize_job,
+    initialize_job,
     read_params_from_cmdline,
     save_metrics_params,
 )
@@ -24,6 +26,8 @@
     "announce_fraction_finished",
     "cluster_main",
     "exit_for_resume",
+    "finalize_job",
+    "initialize_job",
     "save_metrics_params",
     "read_params_from_cmdline",
 ]

cluster_utils/client/__init__.py

@@ -19,6 +19,7 @@
 import pathlib
 import sys
 import time
+import warnings
 from typing import Mapping, MutableMapping, Optional
 
 import smart_settings
@@ -122,7 +123,42 @@ def read_params_from_cmdline(
     verbose: bool = True,
     dynamic: bool = True,
     save_params: bool = True,
-) -> smart_settings.AttributeDict:
+) -> smart_settings.param_classes.AttributeDict:
+    """Alias for :func:`initialize_job`.
+
+    Deprecated:
+        This function is deprecated and will be removed in a future release.  Use
+        :func:`initialize_job` instead.
+    """
+    warnings.warn(
+        "`read_params_from_cmdline` is deprecated!  Use `initialize_job` instead.",
+        FutureWarning,
+        stacklevel=2,
+    )
+
+    if not make_immutable:
+        msg = (
+            "The option `make_immutable=False` is not supported anymore."
+            " You can create a mutable copy of the parameters with"
+            " `smart_settings.param_classes.AttributeDict(params)`"
+        )
+        raise RuntimeError(msg)
+
+    if not save_params:
+        msg = (
+            "The option `save_params=False` is not supported anymore."
+            " Parameters will always be saved."
+        )
+        raise RuntimeError(msg)
+
+    return initialize_job(cmd_line, verbose=verbose, dynamic=dynamic)
+
+
+def initialize_job(
+    cmd_line: Optional[list[str]] = None,
+    verbose: bool = True,
+    dynamic: bool = True,
+) -> smart_settings.param_classes.AttributeDict:
     """Read parameters from command line and register at cluster_utils server.
 
     This function is intended to be called at the beginning of your job scripts.  It
@@ -135,10 +171,8 @@ def read_params_from_cmdline(
 
     Args:
         cmd_line:  Command line arguments (defaults to sys.argv).
-        make_immutable:  See ``smart_settings.loads()``
         verbose:  If true, print the loaded parameters.
         dynamic:  See ``smart_settings.loads()``
-        save_params:  If true, save the settings as JSON file in the working_dir.
 
     Returns:
         Parameters as loaded from the command line arguments with smart_settings.
@@ -174,7 +208,7 @@ def add_cmd_params(orig_dict):
 
         final_params = smart_settings.loads(
             json.dumps(parameter_dict),
-            make_immutable=make_immutable,
+            make_immutable=True,
             dynamic=dynamic,
             post_unpack_hooks=([add_cmd_params, check_reserved_params]),
         )
@@ -186,7 +220,7 @@ def add_cmd_params(orig_dict):
 
         final_params = smart_settings.load(
             os.fspath(parameter_file),
-            make_immutable=make_immutable,
+            make_immutable=True,
             dynamic=dynamic,
             post_unpack_hooks=([add_cmd_params, check_reserved_params]),
         )
@@ -205,14 +239,31 @@ def add_cmd_params(orig_dict):
 
     submission_state.start_time = time.time()
 
-    if save_params and "working_dir" in final_params:
+    # TODO should probably rather be an assert, there should always be a working dir
+    if "working_dir" in final_params:
         os.makedirs(final_params.working_dir, exist_ok=True)
         _save_settings_to_json(final_params, final_params.working_dir)
 
     return final_params
 
 
 def save_metrics_params(metrics: MutableMapping[str, float], params) -> None:
+    """Alias for :func:`finalize_job`.
+
+    Deprecated:
+        This function is deprecated and will be removed in a future release.  Use
+        :func:`finalize_job` instead.
+    """
+    warnings.warn(
+        "`save_metric_params` is deprecated!  Use `finalize_job` instead.",
+        FutureWarning,
+        stacklevel=2,
+    )
+
+    finalize_job(metrics, params)
+
+
+def finalize_job(metrics: MutableMapping[str, float], params) -> None:
     """Save metrics and parameters and send metrics to the cluster_utils server.
 
     Save the used parameters and resulting metrics to CSV files (filenames defined by
@@ -339,9 +390,9 @@ def wrapper():
         """Saves settings file on beginning, calls wrapped function with params from cmd
         and saves metrics to working_dir
         """
-        params = read_params_from_cmdline(**read_params_args)
+        params = initialize_job(**read_params_args)
         metrics = main_func(**params)
-        save_metrics_params(metrics, params)
+        finalize_job(metrics, params)
         return metrics
 
     return wrapper
@@ -352,6 +403,8 @@ def wrapper():
     "announce_fraction_finished",
     "cluster_main",
     "exit_for_resume",
+    "finalize_job",
+    "initialize_job",
     "save_metrics_params",
     "read_params_from_cmdline",
 ]

docs/configuration.rst

@@ -497,7 +497,7 @@ settings (i.e. the ones independent of the optimisation method set in
     **Required.**
 
     Name of the metric that is used for the optimisation.  Has to match the name of one
-    of the metrics that are saved with :func:`cluster_utils.save_metrics_params`.
+    of the metrics that are saved with :func:`~cluster_utils.client.finalize_job`.
 
 .. confval:: optimization_setting.minimize: bool
 

docs/troubleshooting.rst

@@ -8,7 +8,7 @@ Below is a list of error messages that may occur with potential solutions.
 
 **Pandas DataError: No numeric types to aggregate**
 
-If one of the values stored with :func:`~cluster_utils.save_metrics_params` has a
+If one of the values stored with :func:`~cluster_utils.client.finalize_job` has a
 non-numeric type (e.g. string).
 
 

examples/basic/main.py

@@ -3,7 +3,7 @@
 
 import numpy as np
 
-from cluster_utils import exit_for_resume, read_params_from_cmdline, save_metrics_params
+from cluster_utils import exit_for_resume, finalize_job, initialize_job
 
 
 def fn_to_optimize(*, u, v, w, x, y, sharp_penalty, tuple_input=None):
@@ -46,7 +46,7 @@ def fn_to_optimize(*, u, v, w, x, y, sharp_penalty, tuple_input=None):
     if np.random.rand() < 0.05:
         raise ValueError("5 percent of all jobs die early for testing")
 
-    params = read_params_from_cmdline()
+    params = initialize_job()
 
     # simulate that the jobs take some time
     max_sleep_time = params.get("max_sleep_time", 10)
@@ -68,5 +68,5 @@ def fn_to_optimize(*, u, v, w, x, y, sharp_penalty, tuple_input=None):
 
     noisy_result = noiseless_result + 0.5 * np.random.normal()
     metrics = {"result": noisy_result, "noiseless_result": noiseless_result}
-    save_metrics_params(metrics, params)
+    finalize_job(metrics, params)
     print(noiseless_result)

examples/basic/main_no_fail.py

@@ -5,7 +5,7 @@
 
 import numpy as np
 
-from cluster_utils import exit_for_resume, read_params_from_cmdline, save_metrics_params
+from cluster_utils import exit_for_resume, finalize_job, initialize_job
 
 
 def fn_to_optimize(*, u, v, w, x, y, sharp_penalty, tuple_input=None):
@@ -41,7 +41,7 @@ def fn_to_optimize(*, u, v, w, x, y, sharp_penalty, tuple_input=None):
 
 
 if __name__ == "__main__":
-    params = read_params_from_cmdline()
+    params = initialize_job()
 
     # simulate that the jobs take some time
     max_sleep_time = params.get("max_sleep_time", 10)
@@ -63,5 +63,5 @@ def fn_to_optimize(*, u, v, w, x, y, sharp_penalty, tuple_input=None):
 
     noisy_result = noiseless_result + 0.5 * np.random.normal()
     metrics = {"result": noisy_result, "noiseless_result": noiseless_result}
-    save_metrics_params(metrics, params)
+    finalize_job(metrics, params)
     print(noiseless_result)

examples/checkpointing/checkpoint_example.py

@@ -5,8 +5,8 @@
 
 from cluster_utils import (
     exit_for_resume,
-    read_params_from_cmdline,
-    save_metrics_params,
+    finalize_job,
+    initialize_job,
 )
 
 
@@ -41,7 +41,7 @@ def load_checkpoint(load_path, model, optim):
 
 if __name__ == "__main__":
     # parameters are loaded from json file
-    params = read_params_from_cmdline()
+    params = initialize_job()
     # a folder for each run is created
     os.makedirs(params.working_dir, exist_ok=True)
     checkpoint_path = os.path.join(params.working_dir, "checkpoint.pt")
@@ -88,5 +88,5 @@ def load_checkpoint(load_path, model, optim):
 
     metrics = {"loss": loss, "iterations": iteration}
     # save final metrics, you will only see the resuming in the cluster_run.log file
-    save_metrics_params(metrics, params)
+    finalize_job(metrics, params)
     print(f"Training finished, final loss {loss} at episode {iteration}")

examples/slurm_timeout_signal/main.py

@@ -21,7 +21,7 @@ def timeout_signal_handler(sig, frame):
 
 def main() -> int:
     """Main function."""
-    params = cluster_utils.read_params_from_cmdline()
+    params = cluster_utils.initialize_job()
 
     n_training_iterations = 60
     start_iteration = 0
@@ -53,7 +53,7 @@ def main() -> int:
 
     # just return some dummy metric value here
     metrics = {"result": params.x + params.y, "n_iterations": i}
-    cluster_utils.save_metrics_params(metrics, params)
+    cluster_utils.finalize_job(metrics, params)
 
     return 0
 

tests/main_no_save_metrics.py

@@ -1,9 +1,9 @@
 import time
 
-from cluster_utils import read_params_from_cmdline
+from cluster_utils import initialize_job
 
 if __name__ == "__main__":
-    params = read_params_from_cmdline()
+    params = initialize_job()
     time.sleep(2)
     # Here we exit without sending result to cluster utils. We want cluster utils to count the job
     # as failed.