discrete_optimization.generic_tools.hyperparameters package

Submodules

discrete_optimization.generic_tools.hyperparameters.hyperparameter module

class discrete_optimization.generic_tools.hyperparameters.hyperparameter.CategoricalHyperparameter(name: str, default: ~typing.Any | None = None, choices: ~typing.List[~typing.Any] = <factory>)

Bases: Hyperparameter

Categorical hyperparameter.

choices: List[Any]

List of possible choices.

suggest_with_optuna(trial: optuna.trial.Trial, choices: Iterable[Any] | None = None, prefix: str = '', **kwargs: Any) → Any

Suggest hyperparameter value for an Optuna trial.

Parameters:

• trial – optuna Trial used for choosing the hyperparameter value

• choices – restricts list of choices

• prefix – prefix to add to optuna corresponding parameter name (useful for disambiguating hyperparameters from subsolvers in case of meta-solvers)

• **kwargs – passed to trial.suggest_categorical()

Returns:

class discrete_optimization.generic_tools.hyperparameters.hyperparameter.EnumHyperparameter(name: str, enum: Type[Enum], default: Any | None = None)

Bases: CategoricalHyperparameter

Hyperparameter taking value among an enumeration.

Parameters:

enum – enumeration used to create the hyperparameter

suggest_with_optuna(trial: optuna.trial.Trial, choices: Iterable[Enum] | None = None, prefix: str = '', **kwargs: Any) → Enum

Suggest hyperparameter value for an Optuna trial.

Parameters:

• trial – optuna Trial used for choosing the hyperparameter value

• choices – restricts list of choices among the enumeration self.enum

• prefix – prefix to add to optuna corresponding parameter name (useful for disambiguating hyperparameters from subsolvers in case of meta-solvers)

• **kwargs – passed to trial.suggest_categorical()

Returns:

class discrete_optimization.generic_tools.hyperparameters.hyperparameter.FloatHyperparameter(name: str, default: float | None = None, low: float | None = None, high: float | None = None)

Bases: Hyperparameter

Float parameter.

default: float | None = None

Default value for the hyperparameter.

None means “no default value”.

high: float | None = None

Upper bound.

If None, the hyperparameter value has no upper bound.

low: float | None = None

Lower bound.

If None, the hyperparameter value has no lower bound.

suggest_with_optuna(trial: optuna.trial.Trial, low: float | None = None, high: float | None = None, prefix: str = '', **kwargs: Any) → Any

Suggest hyperparameter value for an Optuna trial.

Parameters:

• trial – optuna Trial used for choosing the hyperparameter value

• low – can be used to restrict lower bound

• high – can be used to restrict upper bound

• prefix – prefix to add to optuna corresponding parameter name (useful for disambiguating hyperparameters from subsolvers in case of meta-solvers)

• **kwargs – passed to trial.suggest_float()

Returns:

class discrete_optimization.generic_tools.hyperparameters.hyperparameter.Hyperparameter(name: str, default: Any | None = None)

Bases: object

Hyperparameter base class used to specify d-o solver hyperparameters.

default: Any | None = None

Default value for the hyperparameter.

None means “no default value”.

name: str

Name of the hyperparameter.

Should correspond to how the hyperparameter is specified in the solver __init__(), init_model(), or solve() keywords arguments.

suggest_with_optuna(trial: optuna.trial.Trial, prefix: str = '', **kwargs: Any) → Any

Suggest hyperparameter value for an Optuna trial.

Parameters:

• trial – optuna Trial used for choosing the hyperparameter value

• prefix – prefix to add to optuna corresponding parameter name (useful for disambiguating hyperparameters from subsolvers in case of meta-solvers)

• **kwargs – passed to trial.suggest_xxx()

Returns:

class discrete_optimization.generic_tools.hyperparameters.hyperparameter.IntegerHyperparameter(name: str, default: int | None = None, low: int | None = None, high: int | None = None)

Bases: Hyperparameter

Integer hyperparameter.

default: int | None = None

Default value for the hyperparameter.

None means “no default value”.

high: int | None = None

Upper bound.

If None, the hyperparameter value has no upper bound.

low: int | None = None

Lower bound.

If None, the hyperparameter value has no lower bound.

suggest_with_optuna(trial: optuna.trial.Trial, low: int | None = None, high: int | None = None, prefix: str = '', **kwargs: Any) → Any

Suggest hyperparameter value for an Optuna trial.

Parameters:

• trial – optuna Trial used for choosing the hyperparameter value

• low – can be used to restrict lower bound

• high – can be used to restrict upper bound

• prefix – prefix to add to optuna corresponding parameter name (useful for disambiguating hyperparameters from subsolvers in case of meta-solvers)

• **kwargs – passed to trial.suggest_int()

Returns:

class discrete_optimization.generic_tools.hyperparameters.hyperparameter.SubBrickHyperparameter(name: str, choices: List[Type[Hyperparametrizable]], default: Any | None = None)

Bases: CategoricalHyperparameter

Hyperparameter whose values are Hyperparametrizable subclasses themselves.

For instance subsolvers for meta-solvers.

choices: List[Type[Hyperparametrizable]]

List of Hyperparametrizable subclasses to choose from for the subbrick.

NB: for now, it is not possible to pick the metasolver itself as a choice for its subbrick, in order to avoid infinite recursivity issues.

suggest_with_optuna(trial: optuna.trial.Trial, choices: Iterable[Type[Hyperparametrizable]] | None = None, prefix: str = '', **kwargs: Any) → Type[Hyperparametrizable]

Suggest hyperparameter value for an Optuna trial.

Parameters:

• trial – optuna Trial used for choosing the hyperparameter value

• choices – restricts list of subbricks to choose from

• prefix – prefix to add to optuna corresponding parameter name (useful for disambiguating hyperparameters from subsolvers in case of meta-solvers)

• **kwargs – passed to trial.suggest_categorical()

Returns:

class discrete_optimization.generic_tools.hyperparameters.hyperparameter.SubBrickKwargsHyperparameter(name: str, subbrick_hyperparameter: str, default: Dict[str, Any] | None = None)

Bases: Hyperparameter

Keyword arguments for subbricks.

This hyperparameter defines kwargs to be passed to the subbrick defined by another hyperparameter.

Parameters:

subbrick_hyperparameter – name of the SubBrickHyperparameter this hyperparameter corresponds to.

suggest_with_optuna(trial: optuna.trial.Trial, subbrick: Type[Hyperparametrizable], names: List[str] | None = None, kwargs_by_name: Dict[str, Dict[str, Any]] | None = None, fixed_hyperparameters: Dict[str, Any] | None = None, prefix: str = '', **kwargs) → Dict[str, Any]

Suggest hyperparameter value for an Optuna trial.

Parameters:

• trial – optuna Trial used for choosing the hyperparameter value

• subbrick – subbrick chosen as hyperparameter value for self.subbrick_hyperparameter

• names – names of the hyperparameters to choose for the subbrick. Only relevant names will be considered (i.e. corresponding to existing hyperparameters names for the chosen subbrick), the other will be discarded (potentially, being meaningful for other subbricks). By default, all available hyperparameters will be suggested. Passed to subbrick.suggest_hyperparameters_with_optuna().

• kwargs_by_name – options for optuna hyperparameter suggestions, by hyperparameter name. Passed to subbrick.suggest_hyperparameters_with_optuna().

• fixed_hyperparameters – values of fixed hyperparameters, useful for suggesting subbrick hyperparameters, if the subbrick class is not suggested by this method, but already fixed.

• prefix – prefix to add to optuna corresponding parameter name (useful for disambiguating hyperparameters from subsolvers in case of meta-solvers)

• **kwargs – passed to trial.suggest_categorical()

Returns:

discrete_optimization.generic_tools.hyperparameters.hyperparametrizable module

class discrete_optimization.generic_tools.hyperparameters.hyperparametrizable.Hyperparametrizable

Bases: object

Base class for classes like SolverDO having (tunable) hyperparmeters.

They have utility methods to - retrieve available hyperparameters - fill kwargs with default hyperparameters values - suggest hyperparameters by making use of optuna trials methods

classmethod complete_with_default_hyperparameters(kwargs: Dict[str, Any], names: List[str] | None = None)

Add missing hyperparameters to kwargs by using default values

Parameters:

• kwargs – keyword arguments to complete (for __init__, init_model, or solve)

• names – names of the hyperparameters to add if missing. By default, all available hyperparameters.

Returns:

a new dictionary, completion of kwargs

classmethod copy_and_update_hyperparameters(names: List[str] | None = None, **kwargs_by_name: Dict[str, Any]) → List[Hyperparameter]

Copy hyperparameters definition of this class and update them with specified kwargs.

This is useful to define hyperparameters for a child class for which only choices of the hyperparameter change for instance.

Parameters:

• names – names of hyperparameters to copy. Default to all.

• **kwargs_by_name – for each hyperparameter specified by its name, the attributes to update. If a given hyperparameter name is not specified, the hyperparameter is copied without further update.

Returns:

classmethod get_default_hyperparameters(names: List[str] | None = None) → Dict[str, Any]

Get hyperparameters default values.

Parameters:

names – names of the hyperparameters to choose. By default, all available hyperparameters will be suggested.

Returns:

a mapping between hyperparameter name and its default value (None if not specified)

classmethod get_hyperparameter(name: str) → Hyperparameter

Get hyperparameter from given name.

classmethod get_hyperparameters_by_name() → Dict[str, Hyperparameter]

Mapping from name to corresponding hyperparameter.

classmethod get_hyperparameters_names() → List[str]

List of hyperparameters names.

hyperparameters: List[Hyperparameter] = []

Hyperparameters available for this solver.

These hyperparameters are to be feed to **kwargs found in

• __init__()

• init_model() (when available)

• solve()

classmethod suggest_hyperparameter_with_optuna(trial: optuna.trial.Trial, name: str, prefix: str = '', **kwargs) → Any

Suggest hyperparameter value during an Optuna trial.

This can be used during Optuna hyperparameters tuning.

Parameters:

• trial – optuna trial during hyperparameters tuning

• name – name of the hyperparameter to choose

• prefix – prefix to add to optuna corresponding parameter name (useful for disambiguating hyperparameters from subsolvers in case of meta-solvers)

• **kwargs – options for optuna hyperparameter suggestions

Returns:

kwargs can be used to pass relevant arguments to - trial.suggest_float() - trial.suggest_int() - trial.suggest_categorical()

For instance it can - add a low/high value if not existing for the hyperparameter

or override it to narrow the search. (for float or int hyperparameters)

• add a step or log argument (for float or int hyperparameters, see optuna.trial.Trial.suggest_float())

• override choices for categorical or enum parameters to narrow the search

classmethod suggest_hyperparameters_with_optuna(trial: optuna.trial.Trial, names: List[str] | None = None, kwargs_by_name: Dict[str, Dict[str, Any]] | None = None, fixed_hyperparameters: Dict[str, Any] | None = None, prefix: str = '') → Dict[str, Any]

Suggest hyperparameters values during an Optuna trial.

Parameters:

• trial – optuna trial during hyperparameters tuning

• names – names of the hyperparameters to choose. By default, all available hyperparameters will be suggested.

• kwargs_by_name – options for optuna hyperparameter suggestions, by hyperparameter name

• fixed_hyperparameters – values of fixed hyperparameters, useful for suggesting subbrick hyperparameters, if the subbrick class is not suggested by this method, but already fixed.

• prefix – prefix to add to optuna corresponding parameters (useful for disambiguating hyperparameters from subsolvers in case of meta-solvers)

Returns:

mapping between the hyperparameter name and its suggested value

kwargs_by_name[some_name] will be passed as **kwargs to suggest_hyperparameter_with_optuna(name=some_name)

Module contents