Tune Internals#

TunerInternal#

class ray.tune.impl.tuner_internal.TunerInternal(restore_path: str = None, storage_filesystem: Optional[pyarrow._fs.FileSystem] = None, resume_config: Optional[ray.tune.execution.experiment_state._ResumeConfig] = None, trainable: Optional[Union[str, Callable, Type[ray.tune.trainable.trainable.Trainable], BaseTrainer]] = None, param_space: Optional[Dict[str, Any]] = None, tune_config: Optional[ray.tune.tune_config.TuneConfig] = None, run_config: Optional[ray.train.RunConfig] = None, _tuner_kwargs: Optional[Dict] = None, _entrypoint: ray.air._internal.usage.AirEntrypoint = AirEntrypoint.TUNER)[source]#

The real implementation behind external facing Tuner.

The external facing Tuner multiplexes between local Tuner and remote Tuner depending on whether in Ray client mode.

In Ray client mode, external Tuner wraps TunerInternal into a remote actor, which is guaranteed to be placed on head node.

TunerInternal can be constructed from fresh, in which case, trainable needs to be provided, together with optional param_space, tune_config and run_config.

It can also be restored from a previous failed run (given restore_path).

Parameters

  • restore_path – The path from where the Tuner can be restored. If provided, None of the rest args are needed.

  • resume_config – Resume config to configure which trials to continue.

  • trainable – The trainable to be tuned.

  • param_space – Search space of the tuning job. One thing to note is that both preprocessor and dataset can be tuned here.

  • tune_config – Tuning algorithm specific configs. Refer to ray.tune.tune_config.TuneConfig for more info.

  • run_config – Runtime configuration that is specific to individual trials. If passed, this will overwrite the run config passed to the Trainer, if applicable. Refer to ray.train.RunConfig for more info.

classmethod setup_create_experiment_checkpoint_dir(trainable: Union[str, Callable, Type[ray.tune.trainable.trainable.Trainable]], run_config: Optional[ray.train.RunConfig]) → Tuple[str, str][source]#

Sets up and creates the local experiment checkpoint dir. This is so that the tuner.pkl file gets stored in the same directory and gets synced with other experiment results.

Returns

(experiment_path, experiment_dir_name)

Return type

Tuple

Trial#

class ray.tune.experiment.trial.Trial(trainable_name: str, *, config: Optional[Dict] = None, trial_id: Optional[str] = None, storage: Optional[ray.train._internal.storage.StorageContext] = None, experiment_path: Optional[str] = None, experiment_dir_name: Optional[str] = None, evaluated_params: Optional[Dict] = None, experiment_tag: str = '', placement_group_factory: Optional[ray.tune.execution.placement_groups.PlacementGroupFactory] = None, stopping_criterion: Optional[Dict[str, float]] = None, sync_config: Optional[ray.train.SyncConfig] = None, checkpoint_config: Optional[ray.train.CheckpointConfig] = None, export_formats: Optional[List[str]] = None, restore_path: Optional[str] = None, trial_name_creator: Optional[Callable[[ray.tune.experiment.trial.Trial], str]] = None, trial_dirname_creator: Optional[Callable[[ray.tune.experiment.trial.Trial], str]] = None, log_to_file: Union[str, None, Tuple[Optional[str], Optional[str]]] = None, max_failures: int = 0, stub: bool = False, _setup_default_resource: bool = True, local_dir: Optional[str] = None)[source]#

A trial object holds the state for one model training run.

Trials are themselves managed by the TrialRunner class, which implements the event loop for submitting trial runs to a Ray cluster.

Trials start in the PENDING state, and transition to RUNNING once started. On error, it transitions to ERROR, otherwise TERMINATED on success.

There are resources allocated to each trial. These should be specified using PlacementGroupFactory.

trainable_name#

Name of the trainable object to be executed.

config#

Provided configuration dictionary with evaluated params.

trial_id#

Unique identifier for the trial.

path#

Path where results for this trial are stored. Can be on the local node or on cloud storage.

local_path#

Path on the local disk where results are stored.

remote_path#

Path on cloud storage where results are stored, or None if not set.

relative_logdir#

Directory of the trial relative to its experiment directory.

evaluated_params#

Evaluated parameters by search algorithm,

experiment_tag#

Identifying trial name to show in the console

status#

One of PENDING, RUNNING, PAUSED, TERMINATED, ERROR/

error_file#

Path to the errors that this trial has raised.

DeveloperAPI: This API may change across minor Ray releases.

create_placement_group_factory()[source]#

Compute placement group factory if needed.

Note: this must be called after all the placeholders in self.config are resolved.

property local_dir#

Warning

DEPRECATED: This API is deprecated and may be removed in future Ray releases.

property logdir: Optional[str]#

Warning

DEPRECATED: This API is deprecated and may be removed in future Ray releases.

property remote_checkpoint_dir: Optional[str]#

Warning

DEPRECATED: This API is deprecated and may be removed in future Ray releases.

property checkpoint: Optional[ray.train.Checkpoint]#

Returns the most recent checkpoint if one has been saved.

init_logdir()[source]#

Warning

DEPRECATED: This API is deprecated and may be removed in future Ray releases.

init_local_path()[source]#

Init logdir.

update_resources(resources: Union[dict, ray.tune.execution.placement_groups.PlacementGroupFactory])[source]#

EXPERIMENTAL: Updates the resource requirements.

Should only be called when the trial is not running.

Raises

ValueError if trial status is running. –

set_location(location)[source]#

Sets the location of the trial.

set_status(status)[source]#

Sets the status of the trial.

should_stop(result)[source]#

Whether the given result meets this trial’s stopping criteria.

should_checkpoint()[source]#

Whether this trial is due for checkpointing.

on_checkpoint(checkpoint: Union[ray.air._internal.checkpoint_manager._TrackedCheckpoint, ray.train._internal.session._TrainingResult])[source]#

Hook for handling checkpoints taken by the Trainable.

Parameters

checkpoint – Checkpoint taken.

on_restore()[source]#

Handles restoration completion.

should_recover()[source]#

Returns whether the trial qualifies for retrying.

This is if the trial has not failed more than max_failures. Note this may return true even when there is no checkpoint, either because self.checkpoint_freq is 0 or because the trial failed before a checkpoint has been made.

FunctionTrainable#

class ray.tune.trainable.function_trainable.FunctionTrainable(config: Dict[str, Any] = None, logger_creator: Callable[[Dict[str, Any]], Logger] = None, remote_checkpoint_dir: Optional[str] = None, sync_config: Optional[ray.train.SyncConfig] = None, storage: Optional[ray.train._internal.storage.StorageContext] = None)[source]#

Trainable that runs a user function reporting results.

This mode of execution does not support checkpoint/restore.

DeveloperAPI: This API may change across minor Ray releases.

ray.tune.trainable.function_trainable.wrap_function(train_func: Callable[[Any], Any], warn: bool = True, name: Optional[str] = None) → Type[ray.tune.trainable.function_trainable.FunctionTrainable][source]#

DeveloperAPI: This API may change across minor Ray releases.

Registry#

ray.tune.register_trainable(name: str, trainable: Union[Callable, Type], warn: bool = True)[source]#

Register a trainable function or class.

This enables a class or function to be accessed on every Ray process in the cluster.

Parameters

  • name – Name to register.

  • trainable – Function or tune.Trainable class. Functions must take (config, status_reporter) as arguments and will be automatically converted into a class during registration.

DeveloperAPI: This API may change across minor Ray releases.

ray.tune.register_env(name: str, env_creator: Callable)[source]#

Register a custom environment for use with RLlib.

This enables the environment to be accessed on every Ray process in the cluster.

Parameters

  • name – Name to register.

  • env_creator – Callable that creates an env.

DeveloperAPI: This API may change across minor Ray releases.