discrete_optimization.generic_tools.hyperparameters package

Submodules

discrete_optimization.generic_tools.hyperparameters.hyperparameter module

class discrete_optimization.generic_tools.hyperparameters.hyperparameter.BaseListWithoutReplacementHyperparameter(name: str, hyperparameter_template: CategoricalHyperparameter | SubBrickHyperparameter, length_high: int | None = None, length_low: int = 0, numbering_start: int = 0, default: list[Any] | None = None, depends_on: tuple[str, Container[Any]] | None = None, name_in_kwargs: str | None = None)

Bases: ListHyperparameter, ABC

Base class for variable list of categorical or subbrick hyperparameters, without replacement.

This represents a list of hyperparameters that are copies of a given template, with a bounded variable length. Hyperparameters in the list cannot have twice the same value.

As we cannot dynamically restrict the choices with optuna (because it would modify the underlying distribution of second element of the list), illicit suggestion (repeating same choices) will raise a TrialDropped exception, sot that the study generated by generic_optuna_experiment_monoproblem() or generic_optuna_experiment_multiproblem() will skip such cases.

To achieve this, we use study.optimize(…, catch=TrialDropped), so that the study carry on after such exceptions.

Child classes need to implement has_duplicates().

abstract has_duplicates(list_choices: list[Any]) → True

Check if the list contains duplicates

Parameters:

list_choices – list of values taken from choices

Returns:

hyperparameter_template: CategoricalHyperparameter | SubBrickHyperparameter

Hyperparameter template to fill the list.

length_high: int

Upper bound on list length.

NB: the list length will also be limited by the number of available choices.

suggest_with_optuna(trial: optuna.trial.Trial, length_low: int | None = None, length_high: int | None = None, numbering_start: int | None = None, prefix: str = '', **kwargs: Any) → list[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)

• length_low – overrides self.length_low

• length_high – overrides self.length_high

• numbering_start – overrides self.numbering_start

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

Returns:

class discrete_optimization.generic_tools.hyperparameters.hyperparameter.CategoricalHyperparameter(name: str, choices: Iterable[bool | int | float | str | None] | Mapping[bool | int | float | str | None, Any], default: Any | None = None, depends_on: tuple[str, Container[Any]] | None = None, name_in_kwargs: str | None = None)

Bases: Hyperparameter

Categorical hyperparameter.

choices: Mapping[bool | int | float | str | None, Any]

Mapping lables to corresponding possible choices.

suggest_with_optuna(trial: optuna.trial.Trial, choices: Iterable[LabelType] | Mapping[LabelType, 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 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.CategoricalListWithoutReplacementHyperparameter(name: str, hyperparameter_template: CategoricalHyperparameter | SubBrickHyperparameter, length_high: int | None = None, length_low: int = 0, numbering_start: int = 0, default: list[Any] | None = None, depends_on: tuple[str, Container[Any]] | None = None, name_in_kwargs: str | None = None)

Bases: BaseListWithoutReplacementHyperparameter

Variable list of categorical hyperparameters, without replacement.

This represents a list of hyperparameters that are copies of a given template, with a bounded variable length. Hyperparameters in the list cannot have twice the same value.

As we cannot dynamically restrict the choices with optuna (because it would modify the underlying distribution of second element of the list), illicit suggestion (repeating same choices) will raise a TrialDropped exception, sot that the study generated by generic_optuna_experiment_monoproblem() or generic_optuna_experiment_multiproblem() will skip such cases.

To achieve this, we use study.optimize(…, catch=TrialDropped), so that the study carry on after such exceptions.

has_duplicates(list_choices: list[Any]) → True

Check if the list contains duplicates

Parameters:

list_choices – list of values taken from choices

Returns:

hyperparameter_template: CategoricalHyperparameter

Hyperparameter template to fill the list.

class discrete_optimization.generic_tools.hyperparameters.hyperparameter.EnumHyperparameter(name: str, enum: type[Enum], choices: Iterable[Enum] | dict[str, Enum] | None = None, default: Any | None = None, depends_on: tuple[str, Container[Any]] | None = None, name_in_kwargs: str | None = None)

Bases: CategoricalHyperparameter

Hyperparameter taking value among an enumeration.

Parameters:

• enum – enumeration used to create the hyperparameter

• choices – subset of the enumeration allowed. By default, the whole enumeration.

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, depends_on: tuple[str, Container[Any]] | None = None, name_in_kwargs: str | None = None, low: float | None = None, high: float | None = None, suggest_low: bool = False, suggest_high: bool = False, step: float | None = None, log: bool = False)

Bases: Hyperparameter

Float parameter.

default: float | None = None

Default value for the hyperparameter.

None means “no default value”.

depends_on: tuple[str, Container[Any]] | None = None

Other hyperparameter on which this ones depends on.

If None: this hyperparameter is always needed. Else:

depends_on = hyperparameter2.name, possible_values this hyperparameter is needed if hyperparameter2 value is in possible_values.

Warning: For now, the hyperparameter on which this one depends on cannot be a SubBrickKwargsHyperparameter.

Notes

• How to define possible_values? - Usually a set or a list can be used. But sometime we need something smarter. - For integer or float hyperparameters, possible_values could be an interval (e.g. by using pandas.Interval)

• For now, only simple dependency on a single hyperparameter, and a “set” of values is possible. The api could evolve to emcompass dependency on several other hyperparameters and more complex condition.

high: float | None = None

Upper bound.

If None, the hyperparameter value has no upper bound.

log: bool = False

Whether to sample the value in a logarithmic scale.

low: float | None = None

Lower bound.

If None, the hyperparameter value has no lower bound.

name_in_kwargs: str | None = None

Corresponding key in kwargs when suggested via solver.suggest_hyperparameters_with_optuna().

Default to hyperparemeter name. Can be used to have several hyperparameter with different limits/types depending on other hyperparameters value but supposed to share the same name in kwargs for solver initialization.

step: float | None = None

step to discretize if not None.

suggest_high: bool = False

Whether to potentially suggest the upper bound.

If step is None, optuna will suggest a float inside the range (low, high), but will never suggest exactly the upper bound by default. To force the behaviour, we will introduce a derived categorical hyperparameter whose name will be the hyperparameter name suffixed with “.suggest_bound”.

If step is not None, this attribute should probably be let to False.

suggest_low: bool = False

Whether to potentially suggest the lower bound.

If step is None, optuna will suggest a float inside the range (low, high), but will never suggest exactly the lower bound by default. To force the behaviour, we will introduce a derived categorical hyperparameter whose name will be the hyperparameter name suffixed with “.suggest_bound”.

If step is not None, this attribute should probably be let to False.

suggest_with_optuna(trial: optuna.trial.Trial, low: float | None = None, high: float | None = None, log: bool | None = None, suggest_low: bool | None = None, suggest_high: bool | 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

• log – whether to sample the value in a logarithmic scale

• step – step of discretization if specified. If explicitely set to None, no discretization performed. By default, use self.step (and thus default discretization only if self.step not None)

• suggest_low – if set, will override suggest_low attribute. See its documentation.

• suggest_high – if set, will override suggest_high attribute. See its documentation.

• 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, depends_on: tuple[str, Container[Any]] | None = None, name_in_kwargs: str | None = None)

Bases: object

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

copy_and_update_attributes(**kwargs) → Hyperparameter

default: Any | None = None

Default value for the hyperparameter.

None means “no default value”.

depends_on: tuple[str, Container[Any]] | None = None

Other hyperparameter on which this ones depends on.

If None: this hyperparameter is always needed. Else:

depends_on = hyperparameter2.name, possible_values this hyperparameter is needed if hyperparameter2 value is in possible_values.

Warning: For now, the hyperparameter on which this one depends on cannot be a SubBrickKwargsHyperparameter.

Notes

• How to define possible_values? - Usually a set or a list can be used. But sometime we need something smarter. - For integer or float hyperparameters, possible_values could be an interval (e.g. by using pandas.Interval)

• For now, only simple dependency on a single hyperparameter, and a “set” of values is possible. The api could evolve to emcompass dependency on several other hyperparameters and more complex condition.

name: str

Name of the hyperparameter.

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

name_in_kwargs: str | None = None

Corresponding key in generated kwargs.

Used for kwargs generated by - solver.suggest_hyperparameters_with_optuna() - solver.get_default_hyperparameters() - solver.complete_with_default_hyperparameters()

Default to hyperparemeter name. Can be used to have several hyperparameter with different limits/types depending on other hyperparameters value but supposed to share the same name in kwargs for solver initialization.

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, depends_on: tuple[str, Container[Any]] | None = None, name_in_kwargs: str | None = None, low: int | None = None, high: int | None = None, step: int = 1, log: bool = False)

Bases: Hyperparameter

Integer hyperparameter.

default: int | None = None

Default value for the hyperparameter.

None means “no default value”.

depends_on: tuple[str, Container[Any]] | None = None

Other hyperparameter on which this ones depends on.

If None: this hyperparameter is always needed. Else:

depends_on = hyperparameter2.name, possible_values this hyperparameter is needed if hyperparameter2 value is in possible_values.

Warning: For now, the hyperparameter on which this one depends on cannot be a SubBrickKwargsHyperparameter.

Notes

• How to define possible_values? - Usually a set or a list can be used. But sometime we need something smarter. - For integer or float hyperparameters, possible_values could be an interval (e.g. by using pandas.Interval)

• For now, only simple dependency on a single hyperparameter, and a “set” of values is possible. The api could evolve to emcompass dependency on several other hyperparameters and more complex condition.

high: int | None = None

Upper bound.

If None, the hyperparameter value has no upper bound.

log: bool = False

Whether to sample the value in a logarithmic scale.

low: int | None = None

Lower bound.

If None, the hyperparameter value has no lower bound.

name_in_kwargs: str | None = None

Corresponding key in kwargs when suggested via solver.suggest_hyperparameters_with_optuna().

Default to hyperparemeter name. Can be used to have several hyperparameter with different limits/types depending on other hyperparameters value but supposed to share the same name in kwargs for solver initialization.

step: int = 1

step to discretize.

suggest_with_optuna(trial: optuna.trial.Trial, low: int | None = None, high: int | None = None, step: int | None = None, log: bool | 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

• step – can be used to discretize by a given step

• log – whether to sample the value in a logarithmic scale

• 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:

discrete_optimization.generic_tools.hyperparameters.hyperparameter.LabelType

Licit labels type for categorical hyperparameter.

alias of bool | int | float | str | None

class discrete_optimization.generic_tools.hyperparameters.hyperparameter.ListHyperparameter(name: str, hyperparameter_template: Hyperparameter, length_high: int, length_low: int = 0, numbering_start: int = 0, default: list[Any] | None = None, depends_on: tuple[str, Container[Any]] | None = None, name_in_kwargs: str | None = None)

Bases: Hyperparameter

Variable list of hyperparameters.

This represents a list of hyperparameters that are copies of a given template, with a bounded variable length.

default: Any | None = None

Default value for the hyperparameter.

None means “no default value”.

depends_on: tuple[str, Container[Any]] | None = None

Other hyperparameter on which this ones depends on.

If None: this hyperparameter is always needed. Else:

depends_on = hyperparameter2.name, possible_values this hyperparameter is needed if hyperparameter2 value is in possible_values.

Warning: For now, the hyperparameter on which this one depends on cannot be a SubBrickKwargsHyperparameter.

Notes

• How to define possible_values? - Usually a set or a list can be used. But sometime we need something smarter. - For integer or float hyperparameters, possible_values could be an interval (e.g. by using pandas.Interval)

• For now, only simple dependency on a single hyperparameter, and a “set” of values is possible. The api could evolve to emcompass dependency on several other hyperparameters and more complex condition.

hyperparameter_template: Hyperparameter

Hyperparameter template to fill the list.

length_high: int

Upper bound on list length.

length_low: int = 0

Lower bound for list length.

name_in_kwargs: str | None = None

Corresponding key in generated kwargs.

Used for kwargs generated by - solver.suggest_hyperparameters_with_optuna() - solver.get_default_hyperparameters() - solver.complete_with_default_hyperparameters()

Default to hyperparemeter name. Can be used to have several hyperparameter with different limits/types depending on other hyperparameters value but supposed to share the same name in kwargs for solver initialization.

numbering_start: int = 0

The numbering of the generated hyperparameters will start from this number.

suggest_with_optuna(trial: optuna.trial.Trial, length_low: int | None = None, length_high: int | None = None, numbering_start: int | None = None, prefix: str = '', **kwargs: Any) → list[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)

• length_low – overrides self.length_low

• length_high – overrides self.length_high

• numbering_start – overrides self.numbering_start

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

Returns:

class discrete_optimization.generic_tools.hyperparameters.hyperparameter.SubBrick(cls: type[Hyperparametrizable], kwargs: dict[str, Any], kwargs_from_solution: dict[str, Callable[..., Any]] | None = None)

Bases: object

Wrapper class for a hyperparametrizable class and its kwargs.

Meant to be used as output by SubBrickHyperparameter.suggest_with_optuna().

cls: type[Hyperparametrizable]

kwargs: dict[str, Any]

kwargs_from_solution: dict[str, Callable[..., Any]] | None = None

class discrete_optimization.generic_tools.hyperparameters.hyperparameter.SubBrickClsHyperparameter(name: str, choices: dict[str, type[Hyperparametrizable]] | Iterable[type[Hyperparametrizable]], default: type[Hyperparametrizable] | None = None, depends_on: tuple[str, Container[Any]] | None = None, name_in_kwargs: str | None = None, include_module_in_labels: bool = False)

Bases: CategoricalHyperparameter

Hyperparameter whose values are Hyperparametrizable subclasses themselves.

For instance subsolvers for meta-solvers.

choices: dict[str, type[Hyperparametrizable]]

Mapping of labelled 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.

include_module_in_labels: bool

Flag to include module path in Hyperparametrizable labels used by optuna to select the value.

This is useful if 2 hypermarametrizable classes share the same name but come from different modules.

suggest_with_optuna(trial: optuna.trial.Trial, choices: dict[str, type[Hyperparametrizable]] | 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.SubBrickHyperparameter(name: str, choices: dict[str, type[Hyperparametrizable]] | Iterable[type[Hyperparametrizable]], default: SubBrick | None = None, depends_on: tuple[str, Container[Any]] | None = None, name_in_kwargs: str | None = None, include_module_in_labels: bool = False)

Bases: Hyperparameter

Hyperparameter whose values are SubBrick instances.

That is to say

• a hyperparametrizable class

• a kwargs dict to be used for it in __init_(), init_model(), solve(), …

This is useful to suggest subsolvers for meta-solvers.

Under the hood, this hyperparameter will generate the corresponding SubBrickClsHyperparameter and SubBrickKwargsHyperparameter.

suggest_with_optuna(trial: optuna.trial.Trial, choices: dict[str, type[Hyperparametrizable]] | Iterable[type[Hyperparametrizable]] | None = None, names: list[str] | None = None, names_by_subbrick: dict[type[Hyperparametrizable], list[str]] | None = None, kwargs_by_name: dict[str, dict[str, Any]] | None = None, kwargs_by_name_by_subbrick: dict[type[Hyperparametrizable], dict[str, dict[str, Any]]] | None = None, fixed_hyperparameters: dict[str, Any] | None = None, fixed_hyperparameters_by_subbrick: dict[type[Hyperparametrizable], dict[str, Any]] | None = None, prefix: str = '', **kwargs: Any) → SubBrick

Parameters:

• trial – see Hyperparameter doc

• choices – used by underlying SubBrickClsHyperparameter.suggest_with_optuna

• names – used by underlying SubBrickKwargsHyperparameter.suggest_with_optuna

• names_by_subbrick – used by underlying SubBrickKwargsHyperparameter.suggest_with_optuna

• kwargs_by_name – used by underlying SubBrickKwargsHyperparameter.suggest_with_optuna

• kwargs_by_name_by_subbrick – used by underlying SubBrickKwargsHyperparameter.suggest_with_optuna

• fixed_hyperparameters – used by underlying SubBrickKwargsHyperparameter.suggest_with_optuna

• fixed_hyperparameters_by_subbrick – used by underlying SubBrickKwargsHyperparameter.suggest_with_optuna

• prefix – see Hyperparameter doc.

• **kwargs – passed to SubBrickClsHyperparameter.suggest_with_optuna and SubBrickKwargsHyperparameter.suggest_with_optuna

Returns:

class discrete_optimization.generic_tools.hyperparameters.hyperparameter.SubBrickKwargsHyperparameter(name: str, subbrick_hyperparameter: str | None = None, subbrick_cls: type[Hyperparametrizable] | None = None, default: dict[str, Any] | None = None, depends_on: tuple[str, Container[Any]] | None = None, name_in_kwargs: str | 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. If None, this means the subbrick is always constructed from the same class which should be then specified via subbrick_cls.

• subbrick_cls – class of the subbrick. Relevant only if subbrick_hyperparmeter is None. This means the class of the subbrick is always the same.

suggest_with_optuna(trial: optuna.trial.Trial, subbrick: type[Hyperparametrizable] | None = None, names: list[str] | None = None, names_by_subbrick: dict[type[Hyperparametrizable], list[str]] | None = None, kwargs_by_name: dict[str, dict[str, Any]] | None = None, kwargs_by_name_by_subbrick: dict[type[Hyperparametrizable], dict[str, dict[str, Any]]] | None = None, fixed_hyperparameters: dict[str, Any] | None = None, fixed_hyperparameters_by_subbrick: dict[type[Hyperparametrizable], 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. Can be None only if self.subbrick_hyperparameter is None and the subbrick class has already been specified by self.subbrick_cls.

• 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().

• names_by_subbrick – similar to names but depending on type of subbrick chosen. names will be extended by names_by_subbrick[subbrick] (if the key exists) where subbrick is either the argument of this function, or (if None) self.subbrick_cls.

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

• kwargs_by_name_by_subbrick – same as kwargs_by_name but depending on type of subbrick chosen. kwargs_by_name will be updated by kwargs_by_name_by_subbrick[subbrick] (if the key exists) where subbrick is either the argument of this function, or (if None) self.subbrick_cls.

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

• fixed_hyperparameters_by_subbrick – same as fixed_hyperparameters but depending on type of subbrick chosen. fixed_hyperparameters will be updated by fixed_hyperparameters_by_subbrick[subbrick] (if the key exists) where subbrick is either the argument of this function, or (if None) self.subbrick_cls.

• 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.SubBrickListWithoutReplacementHyperparameter(name: str, hyperparameter_template: CategoricalHyperparameter | SubBrickHyperparameter, length_high: int | None = None, length_low: int = 0, numbering_start: int = 0, default: list[Any] | None = None, depends_on: tuple[str, Container[Any]] | None = None, name_in_kwargs: str | None = None)

Bases: BaseListWithoutReplacementHyperparameter

Variable list of subbrick hyperparameters, without replacement.

This represents a list of hyperparameters that are copies of a given template, with a bounded variable length. Hyperparameters in the list cannot have twice the same value.

As we cannot dynamically restrict the choices with optuna (because it would modify the underlying distribution of second element of the list), illicit suggestion (repeating same choices) will raise a TrialDropped exception, sot that the study generated by generic_optuna_experiment_monoproblem() or generic_optuna_experiment_multiproblem() will skip such cases.

To achieve this, we use study.optimize(…, catch=TrialDropped), so that the study carry on after such exceptions.

has_duplicates(list_choices: list[Any]) → True

Check if the list contains duplicates

Parameters:

list_choices – list of subbricks as produced by hyperparameter_template.suggest_with_optuna()

Returns:

NB: subbrick.kwargs can contain any kind of values, potentially not hashable. So this is easier to check equality (more often implemented than hash)

hyperparameter_template: SubBrickHyperparameter

Hyperparameter template to fill the list.

exception discrete_optimization.generic_tools.hyperparameters.hyperparameter.TrialDropped

Bases: Exception

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 (e.g. 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’s name_in_kwargs 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. If fixed_hyperparameters is provided, the corresponding names are removed from names.

• 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. Will be added to the suggested hyperparameters.

• 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. If the hyperparameter has an attribute name_in_kwargs, this is used as the key in the mapping instead of the actual hyperparameter name. the mapping is updated with fixed_hyperparameters.

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

Module contents