Search Object#

class pyhopper.Search(*args, **kwargs)[source]#

Creates a new search object.

The recommended way to to simply pass named arguments

Examples:

>>> search = pyhopper.Search(
>>>     x = pyhopper.float(0,1),
>>>     y = pyhopper.int(0,10),
>>>     z = 2,
>>> )

which is equivalent to having a single dict

Examples:

>>> search = pyhopper.Search({
>>>     "x": pyhopper.float(0,1),
>>>     "y": pyhopper.int(0,10),
>>>     "z": 2,
>>> })
Parameters

  • args (Union[dict, Sequence[dict]]) – dict defining the search space. If multiple dicts are provided the dicts will be merged.

  • kwargs – key-value pairs defining the search space. Will be merged with the numbered arguments if some are provided

Inherited-members

property best: Optional[dict]#

A dict object containing the best found parameter so far. None if no candidate has been evaluated yet.

property best_f: Optional[float]#

The objective value of the best found parameter so far. None if no candidate has been evaluated yet.

property checkpoint_path: Optional[str]#

Path to the checkpoint file in which the intermediate state of the search will be stored. Equals the checkpoint_path argument of search.run() if the argument was a file. If the checkpoint_path argument of search.run() was a directory, then the newly created file checkpoint file will be returned. None if search.run was called without providing a checkpoint_path

clear_cache()[source]#

Forgets all values of already evaluated parameters.

enqueue(candidate)[source]#

Queues a guess for the optimal parameters to the search queue.

Parameters

candidate (dict) – dict representing a subset of the parameters assigned to a value

Return type

None

forget_cached(candidate)[source]#

Removes the given parameter candidate from the evaluation cache. This might be useful if a parameter value should be reevaluated.

Parameters

candidate (dict) – Parameter candidate to be wiped from the evaluation cache

property free_param_count: int#

Number of free (optimizable) parameters

property history: History#

Contains a list of all evaluated candidates and corresponding objective values so far.

Examples:

>>> search = pyhopper.Search(...)
>>> search.run(...)
>>>
>>> import matplotlib.pyplot as plt
>>> fig, ax = plt.subplots(figsize=(8, 5))
>>> ax.scatter(
>>>     x=search.history.steps,
>>>     y=search.history.fs,
>>>     label="Sampled",
>>> )
>>> ax.plot(
>>>     search.history.steps,
>>>     search.history.best_fs,
>>>     label="Best so far",
>>> )
>>> fig.show()
load(checkpoint_path, pruner=None)[source]#

Loads the internal state of the hyperparameter search (history, current best, etc.) at the given checkpoint path.

Parameters

  • checkpoint_path – File from which to load the checkpoint

  • pruner – Pruner object whose internal state should also be loaded from the checkpoint

property manual_queue_count: int#

Number of candidate parameters that are manually added by the user and will be evaluated first when run is called

run(objective_function, direction='maximize', runtime=None, steps=None, endless_mode=False, seeding_steps=None, seeding_runtime=None, seeding_ratio=0.25, pruner=None, n_jobs=1, quiet=False, ignore_nans=False, mp_backend='auto', enable_rejection_cache=True, callbacks=None, start_temperature=1, end_temperature=0.2, kwargs=None, checkpoint_path=None, overwrite_checkpoint=False, keep_history=True)[source]#

Starts the hyperparameter tuning process.

Examples:

>>> def obj_func(param):
>>>     return -(param["x"]-3)**2
>>>
>>> search = pyhopper.Search(
>>>     x = pyhopper.float(-5,5),
>>> )
>>> search.run(obj_func,"max","10s")
Parameters

  • objective_function – The objective function that should be optimized. Can be a generator function that yields estimates of the true objective function to prune unpromising candidates early on.

  • direction (str) – String defining if the objective function should be minimized or maximize (admissible values are ‘min’,’minimize’, or ‘max’,’maximize’)

  • runtime (Optional[Union[int, float, str]]) – Search runtime in seconds or a string, e.g., “1h 30min”, “4d 12h”.

  • steps (Optional[Union[int, str]]) – Number of search steps. Must be left None if a value for runtime is provided.

  • endless_mode (bool) – Setting this argument to True runs the search until the user interrupts (via CTRL+C). Must be left Noen if a value for runtime or steps is provided

  • seeding_steps (Optional[int]) –

  • seeding_runtime (Optional[Union[int, float, str]]) –

  • seeding_ratio (Optional[float]) –

  • pruner – A pyhopper.pruners.Pruner instance that cancels the evaluation of unpromising candidates. If a pruner is provided, the objective function must be a generator that yield intermediate estimates of the objective value.

  • n_jobs – Number of parallel execution process. n_jobs=-1 spawns a process for each CPU core, n_jobs=”per-gpu” spawns a process for each GPU (and sets the visibility of the GPU in the environment variables accordingly).

  • quiet – If True, then a progress bar is shown during the search and a short summary at the end.

  • ignore_nans – If True, NaN (not-a-number) values returned by the objective function will be ignored (parameters will be treated the same as pruned parameter values). If False (default), NaN values returned by the objective function will raise an exception (this might be important for finding bugs in the objective function)

  • mp_backend –

  • enable_rejection_cache – If True (default), generated parameter candidates will be filtered by removing duplicates (= don’t evaluate a parameter if the same parameter has been already evaluated before). If False, no such check/filtering is performed.

  • callbacks (Optional[Union[callable, list]]) – A list of pyhopper.callbacks.Callback instances that will be called throughout the search.

  • start_temperature (float) –

  • end_temperature (float) –

  • kwargs – A dict that will be passed to the objective function as named arguments.

  • checkpoint_path – A file or directory for storing the intermediate state of the search. If checkpoint_path is an existing directory, Pyhopper will save the state in a new file “pyhopper_run_XXXXX.ckpt”.

  • overwrite_checkpoint – If True, the file provided by the checkpoint_path argument will be overwritten if it already exists. If False (default), Pyhopper will try to restore and continue the search from the checkpoint provided by the checkpoint_path. If the file provided in the checkpoint_path argument does not exist, this argument will be ignored.

  • keep_history – If True (default), the all evaluated candidate parameters and correspondign objective values will be stored in the pyhopper.Search.history property. If False, no such history is created (this might save some memory).

Returns

A dict containing the best found parameters

save(checkpoint_path, pruner=None)[source]#

Saves the internal state of the hyperparameter search (history, current best, etc.) at the given checkpoint path.

Return type

str