hex.grid

Class GridSearch<MP extends Model.Parameters>

java.lang.Object

hex.grid.GridSearch<MP>

public final class GridSearch<MP extends Model.Parameters>
extends java.lang.Object

Grid search job. This job represents a generic interface to launch "any" hyper space search. It triggers sub-jobs for each point in hyper space. It produces Grid object which contains a list of build models. A triggered model builder job can fail! Grid search is parametrized by hyper space walk strategy (HyperSpaceWalker which defines how the space of hyper parameters is traversed. The job is started by the startGridSearch method which create a new grid search, put representation of Grid into distributed KV store, and for each parameter in hyper space of possible parameters, it launches a separated model building job. The launch of jobs is sequential and blocking. So after finish the last model, whole grid search job is done as well. By default, the grid search invokes cartesian grid search, but it can be modified by passing explicit hyper space walk strategy via the startGridSearch(Key, Key, HyperSpaceWalker, Recovery, int) method. If any of forked jobs fails then the failure is ignored, and grid search normally continue in traversing the hyper space. Typical usage from Java is:

 // Create initial parameters and fill them by references to data
 GBMModel.GBMParameters params = new GBMModel.GBMParameters();
 params._train = fr._key;
 params._response_column = "cylinders";

 // Define hyper-space to search
 HashMap<String,Object[]> hyperParms = new HashMap<>();
 hyperParms.put("_ntrees", new Integer[]{1, 2});
 hyperParms.put("_distribution",new DistributionFamily[] {DistributionFamily.multinomial});
 hyperParms.put("_max_depth",new Integer[]{1,2,5});
 hyperParms.put("_learn_rate",new Float[]{0.01f,0.1f,0.3f});

 // Launch grid search job creating GBM models
 GridSearch gridSearchJob = GridSearch.startGridSearch(params, hyperParms, GBM_MODEL_FACTORY);

 // Block till the end of the job and get result
 Grid grid = gridSearchJob.get()

 // Get built models
 Model[] models = grid.getModels()
 

See Also:

HyperSpaceWalker, startGridSearch(Key, Key, HyperSpaceWalker, Recovery, int)

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	GridSearch.Builder<MP extends Model.Parameters>
static class	GridSearch.SimpleParametersBuilderFactory<MP extends Model.Parameters> The factory is producing a parameters builder which uses reflection to setup field values.

Field Summary

Fields

Modifier and Type	Field and Description
static int	ADAPTIVE_PARALLELISM_LEVEL Constant for adaptive parallelism level - number of models built in parallel is decided by H2O.
static int	SEQUENTIAL_MODEL_BUILDING

Method Summary

Modifier and Type	Method and Description
static <MP extends Model.Parameters> GridSearch.Builder<MP>	create(Key<Grid> destKey, HyperSpaceWalker<MP,?> walker)
static <MP extends Model.Parameters> GridSearch.Builder<MP>	create(Key<Grid> destKey, MP params, java.util.Map<java.lang.String,java.lang.Object[]> hyperParams)
static int	getAdaptiveParallelism()
long	getModelCount() Returns expected number of models in resulting Grid object.
static int	getParallelismLevel(int parallelism) Converts user-given number representing parallelism level and regime to a final number, representing the number of models built in parallel.
protected static Key<Grid>	gridKeyName(java.lang.String modelName, Frame fr) Defines a key for a new Grid object holding results of grid search.
static <MP extends Model.Parameters> Job<Grid>	resumeGridSearch(Key<Job> jobKey, Grid<MP> grid, ModelParametersBuilderFactory<MP> paramsBuilderFactory, Recovery<Grid> recovery)
static <MP extends Model.Parameters> Job<Grid>	startGridSearch(Key<Grid> destKey, HyperSpaceWalker<MP,?> hyperSpaceWalker, int parallelism) Deprecated. Prefer use of create(Key, HyperSpaceWalker)
static <MP extends Model.Parameters> Job<Grid>	startGridSearch(Key<Grid> destKey, MP params, java.util.Map<java.lang.String,java.lang.Object[]> hyperParams) Deprecated. Prefer use of create(Key, Model.Parameters, Map))}
static <MP extends Model.Parameters> Job<Grid>	startGridSearch(Key<Grid> destKey, MP params, java.util.Map<java.lang.String,java.lang.Object[]> hyperParams, int parallelism) Deprecated. Prefer use of create(Key, Model.Parameters, Map))}
static <MP extends Model.Parameters> Job<Grid>	startGridSearch(Key<Grid> destKey, MP params, java.util.Map<java.lang.String,java.lang.Object[]> hyperParams, ModelParametersBuilderFactory<MP> paramsBuilderFactory, HyperSpaceSearchCriteria searchCriteria, int parallelism) Deprecated. Prefer use of create(Key, HyperSpaceWalker)
static <MP extends Model.Parameters> Job<Grid>	startGridSearch(Key<Job> jobKey, Key<Grid> destKey, HyperSpaceWalker<MP,?> hyperSpaceWalker, Recovery<Grid> recovery, int parallelism) Deprecated. Prefer use of create(Key, HyperSpaceWalker)
static <MP extends Model.Parameters> Job<Grid>	startGridSearch(Key<Job> jobKey, Key<Grid> destKey, MP params, java.util.Map<java.lang.String,java.lang.Object[]> hyperParams, ModelParametersBuilderFactory<MP> paramsBuilderFactory, HyperSpaceSearchCriteria searchCriteria, Recovery<Grid> recovery, int parallelism) Deprecated. Prefer use of create(Key, HyperSpaceWalker)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

ADAPTIVE_PARALLELISM_LEVEL

public static final int ADAPTIVE_PARALLELISM_LEVEL

Constant for adaptive parallelism level - number of models built in parallel is decided by H2O.

See Also:

Constant Field Values

SEQUENTIAL_MODEL_BUILDING

public static final int SEQUENTIAL_MODEL_BUILDING

See Also:

Constant Field Values

Method Detail

create

public static <MP extends Model.Parameters> GridSearch.Builder<MP> create(Key<Grid> destKey,
                                                                          HyperSpaceWalker<MP,?> walker)

create

public static <MP extends Model.Parameters> GridSearch.Builder<MP> create(Key<Grid> destKey,
                                                                          MP params,
                                                                          java.util.Map<java.lang.String,java.lang.Object[]> hyperParams)

getModelCount

public long getModelCount()

Returns expected number of models in resulting Grid object. The number can differ from final number of models due to visiting duplicate points in hyper space.

Returns:

expected number of models produced by this grid search

gridKeyName

protected static Key<Grid> gridKeyName(java.lang.String modelName,
                                       Frame fr)

Defines a key for a new Grid object holding results of grid search.

Returns:

a grid key for a particular modeling class and frame.

Throws:

java.lang.IllegalArgumentException - if frame is not saved to distributed store.

startGridSearch

@Deprecated
public static <MP extends Model.Parameters> Job<Grid> startGridSearch(Key<Grid> destKey,
                                                                                  MP params,
                                                                                  java.util.Map<java.lang.String,java.lang.Object[]> hyperParams,
                                                                                  ModelParametersBuilderFactory<MP> paramsBuilderFactory,
                                                                                  HyperSpaceSearchCriteria searchCriteria,
                                                                                  int parallelism)

Deprecated. Prefer use of create(Key, HyperSpaceWalker)

Start a new grid search job. This is the method that gets called by GridSearchHandler.do_train().

This method launches a "classical" grid search traversing cartesian grid of parameters point-by-point, or a random hyperparameter search, depending on the value of the strategy parameter.

Parameters:

destKey - A key to store result of grid search under.

params - Default parameters for model builder. This object is used to create a specific model parameters for a combination of hyper parameters.

hyperParams - A set of arrays of hyper parameter values, used to specify a simple fully-filled-in grid search.

paramsBuilderFactory - defines a strategy for creating a new model parameters based on common parameters and list of hyper-parameters

parallelism - Level of model-building parallelism

Returns:

GridSearch Job, with models run with these parameters, built as needed - expected to be an expensive operation. If the models in question are "in progress", a 2nd build will NOT be kicked off. This is a non-blocking call.

startGridSearch

@Deprecated
public static <MP extends Model.Parameters> Job<Grid> startGridSearch(Key<Job> jobKey,
                                                                                  Key<Grid> destKey,
                                                                                  MP params,
                                                                                  java.util.Map<java.lang.String,java.lang.Object[]> hyperParams,
                                                                                  ModelParametersBuilderFactory<MP> paramsBuilderFactory,
                                                                                  HyperSpaceSearchCriteria searchCriteria,
                                                                                  Recovery<Grid> recovery,
                                                                                  int parallelism)

Deprecated. Prefer use of create(Key, HyperSpaceWalker)

Start a new grid search job. This is the method that gets called by GridSearchHandler.do_train().

This method launches a "classical" grid search traversing cartesian grid of parameters point-by-point, or a random hyperparameter search, depending on the value of the strategy parameter.

Parameters:

destKey - A key to store result of grid search under.

params - Default parameters for model builder. This object is used to create a specific model parameters for a combination of hyper parameters.

hyperParams - A set of arrays of hyper parameter values, used to specify a simple fully-filled-in grid search.

paramsBuilderFactory - defines a strategy for creating a new model parameters based on common parameters and list of hyper-parameters

recovery - Defines recovery strategy for when the cluster crashes while grid is training models.

parallelism - Level of model-building parallelism

Returns:

GridSearch Job, with models run with these parameters, built as needed - expected to be an expensive operation. If the models in question are "in progress", a 2nd build will NOT be kicked off. This is a non-blocking call.

startGridSearch

@Deprecated
public static <MP extends Model.Parameters> Job<Grid> startGridSearch(Key<Grid> destKey,
                                                                                  MP params,
                                                                                  java.util.Map<java.lang.String,java.lang.Object[]> hyperParams)

Deprecated. Prefer use of create(Key, Model.Parameters, Map))}

Start a new sequential grid search job.

This method launches "classical" grid search traversing cartesian grid of parameters point-by-point. For more advanced hyperparameter search behavior call the referenced method.

Parameters:

destKey - A key to store result of grid search under.

params - Default parameters for model builder. This object is used to create a specific model parameters for a combination of hyper parameters.

hyperParams - A set of arrays of hyper parameter values, used to specify a simple fully-filled-in grid search.

Returns:

GridSearch Job, with models run with these parameters, built as needed - expected to be an expensive operation. If the models in question are "in progress", a 2nd build will NOT be kicked off. This is a non-blocking call.

startGridSearch

@Deprecated
public static <MP extends Model.Parameters> Job<Grid> startGridSearch(Key<Grid> destKey,
                                                                                  MP params,
                                                                                  java.util.Map<java.lang.String,java.lang.Object[]> hyperParams,
                                                                                  int parallelism)

Deprecated. Prefer use of create(Key, Model.Parameters, Map))}

Start a new grid search job.

This method launches "classical" grid search traversing cartesian grid of parameters point-by-point. For more advanced hyperparameter search behavior call the referenced method.

Parameters:

destKey - A key to store result of grid search under.

params - Default parameters for model builder. This object is used to create a specific model parameters for a combination of hyper parameters.

hyperParams - A set of arrays of hyper parameter values, used to specify a simple fully-filled-in grid search.

parallelism - Level of parallelism during the process of building this grid's models

Returns:

GridSearch Job, with models run with these parameters, built as needed - expected to be an expensive operation. If the models in question are "in progress", a 2nd build will NOT be kicked off. This is a non-blocking call.

startGridSearch

@Deprecated
public static <MP extends Model.Parameters> Job<Grid> startGridSearch(Key<Grid> destKey,
                                                                                  HyperSpaceWalker<MP,?> hyperSpaceWalker,
                                                                                  int parallelism)

Deprecated. Prefer use of create(Key, HyperSpaceWalker)

Start a new grid search job.

This method launches any grid search traversing space of hyper parameters based on specified strategy.

Parameters:

destKey - A key to store result of grid search under.

hyperSpaceWalker - Defines a strategy for traversing a hyper space. The object itself holds definition of hyper space.

parallelism - Level of parallelism during the process of building of the grid models

Returns:

GridSearch Job, with models run with these parameters, built as needed - expected to be an expensive operation. If the models in question are "in progress", a 2nd build will NOT be kicked off. This is a non-blocking call.

startGridSearch

@Deprecated
public static <MP extends Model.Parameters> Job<Grid> startGridSearch(Key<Job> jobKey,
                                                                                  Key<Grid> destKey,
                                                                                  HyperSpaceWalker<MP,?> hyperSpaceWalker,
                                                                                  Recovery<Grid> recovery,
                                                                                  int parallelism)

Deprecated. Prefer use of create(Key, HyperSpaceWalker)

Start a new grid search job.

This method launches any grid search traversing space of hyper parameters based on specified strategy.

Parameters:

destKey - A key to store result of grid search under.

hyperSpaceWalker - Defines a strategy for traversing a hyper space. The object itself holds definition of hyper space.

recovery - Defines recovery strategy for when the cluster crashes while grid is training models.

parallelism - Level of parallelism during the process of building of the grid models

Returns:

GridSearch Job, with models run with these parameters, built as needed - expected to be an expensive operation. If the models in question are "in progress", a 2nd build will NOT be kicked off. This is a non-blocking call.

resumeGridSearch

public static <MP extends Model.Parameters> Job<Grid> resumeGridSearch(Key<Job> jobKey,
                                                                       Grid<MP> grid,
                                                                       ModelParametersBuilderFactory<MP> paramsBuilderFactory,
                                                                       Recovery<Grid> recovery)

getParallelismLevel

public static int getParallelismLevel(int parallelism)

Converts user-given number representing parallelism level and regime to a final number, representing the number of models built in parallel.

Parameters:

parallelism - User-desired parallelism, the frontend/client API representation.

Returns:

An integer >= 1, representing the final number of models to be built in parallel. 1 effectively means sequential (no parallelism).

getAdaptiveParallelism

public static int getAdaptiveParallelism()

Returns:

An integer with dynamically calculated level of parallelism based on Cluster's properties.