hone-python 0.12.1__py3-none-any.whl → 0.13.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- hone/__init__.py +5 -0
- hone/config/bayesian_config.py +5 -2
- hone/config/cmaes_config.py +8 -4
- hone/config/genetic_optimizer_config.py +23 -15
- hone/config/multi_objective_config.py +19 -8
- hone/config/optimizer_config.py +21 -12
- hone/sensitivity_analysis.py +523 -0
- {hone_python-0.12.1.dist-info → hone_python-0.13.0.dist-info}/METADATA +51 -2
- {hone_python-0.12.1.dist-info → hone_python-0.13.0.dist-info}/RECORD +11 -10
- {hone_python-0.12.1.dist-info → hone_python-0.13.0.dist-info}/WHEEL +0 -0
- {hone_python-0.12.1.dist-info → hone_python-0.13.0.dist-info}/licenses/LICENSE +0 -0
hone/__init__.py
CHANGED
|
@@ -18,6 +18,7 @@ from hone.optimizers import (
|
|
|
18
18
|
from hone.parameters import ChoiceParameter, Condition, Constraint, FixedParameter, InfeasibleSearchSpace, RangeParameter, SearchSpace
|
|
19
19
|
from hone.pareto import Front, ParetoGenerationStats, ParetoPoint, ParetoProgress, ParetoResult
|
|
20
20
|
from hone.result import GenerationStats, Progress, Result, RunInfo, print_progress
|
|
21
|
+
from hone.sensitivity_analysis import Interval, ParameterSensitivity, SensitivityReport, sensitivity
|
|
21
22
|
|
|
22
23
|
__all__ = [
|
|
23
24
|
"BayesianConfig",
|
|
@@ -36,6 +37,7 @@ __all__ = [
|
|
|
36
37
|
"GeneticOptimizer",
|
|
37
38
|
"GeneticOptimizerConfig",
|
|
38
39
|
"InfeasibleSearchSpace",
|
|
40
|
+
"Interval",
|
|
39
41
|
"MultiObjectiveBayesian",
|
|
40
42
|
"MultiObjectiveBayesianConfig",
|
|
41
43
|
"MultiObjectiveConfig",
|
|
@@ -45,6 +47,7 @@ __all__ = [
|
|
|
45
47
|
"NSGA2Config",
|
|
46
48
|
"Optimizer",
|
|
47
49
|
"OptimizerConfig",
|
|
50
|
+
"ParameterSensitivity",
|
|
48
51
|
"ParetoGenerationStats",
|
|
49
52
|
"ParetoPoint",
|
|
50
53
|
"ParetoProgress",
|
|
@@ -57,6 +60,8 @@ __all__ = [
|
|
|
57
60
|
"RunInfo",
|
|
58
61
|
"SearchSpace",
|
|
59
62
|
"SelectionMethod",
|
|
63
|
+
"sensitivity",
|
|
64
|
+
"SensitivityReport",
|
|
60
65
|
"Trial",
|
|
61
66
|
"UnsupportedSearchSpace",
|
|
62
67
|
]
|
hone/config/bayesian_config.py
CHANGED
|
@@ -11,9 +11,12 @@ class BayesianConfig(OptimizerConfig):
|
|
|
11
11
|
Each generation is a batch of candidates chosen together. When max_evaluations is set and
|
|
12
12
|
generations isn't, generations defaults to the budget, so the run ends when the budget is spent.
|
|
13
13
|
"""
|
|
14
|
-
population_size: int | None = Field(default=None, ge=1) # type: ignore[assignment]
|
|
14
|
+
population_size: int | None = Field(default=None, ge=1) # type: ignore[assignment]
|
|
15
|
+
"""Candidates per batch. None: 1, or the number of workers."""
|
|
15
16
|
generations: int = Field(default=100, ge=1)
|
|
16
|
-
|
|
17
|
+
"""Batches to run, unless the run stops sooner."""
|
|
18
|
+
initial_samples: int | None = Field(default=None, ge=1)
|
|
19
|
+
"""Spread-out candidates evaluated before the model is used. None: 2 × (variables + 1)."""
|
|
17
20
|
|
|
18
21
|
@model_validator(mode="before")
|
|
19
22
|
@classmethod
|
hone/config/cmaes_config.py
CHANGED
|
@@ -5,7 +5,11 @@ from .optimizer_config import OptimizerConfig
|
|
|
5
5
|
|
|
6
6
|
class CMAESConfig(OptimizerConfig):
|
|
7
7
|
"""Configuration for CMA-ES. The defaults suit most problems; usually only the budget needs setting."""
|
|
8
|
-
population_size: int | None = Field(default=None, ge=2) # type: ignore[assignment]
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
8
|
+
population_size: int | None = Field(default=None, ge=2) # type: ignore[assignment]
|
|
9
|
+
"""Candidates per generation. None: 4 + 3 ln(n) for n variables, or twice the workers if more."""
|
|
10
|
+
generations: int = Field(default=1000, ge=1)
|
|
11
|
+
"""An upper bound; max_evaluations is the usual way to set a budget."""
|
|
12
|
+
initial_step: float = Field(default=0.3, gt=0, le=1)
|
|
13
|
+
"""Starting step size, as a fraction of each range."""
|
|
14
|
+
restarts: bool = True
|
|
15
|
+
"""Restart with double the population when a run converges or stalls (IPOP-CMA-ES)."""
|
|
@@ -27,30 +27,38 @@ class GeneticOptimizerConfig(OptimizerConfig):
|
|
|
27
27
|
population to about a twentieth of the budget, between 16 and 50, and generations to
|
|
28
28
|
as many as the budget allows. Without a budget they default to 100 and 25.
|
|
29
29
|
"""
|
|
30
|
-
# Chance each gene of a child is mutated. None: 1 / the number of variables, at least 0.1;
|
|
31
|
-
# with noise, 0.1, which the benchmark's noisy problems favour at large budgets.
|
|
32
30
|
mutation_rate: float | None = Field(default=None, ge=0, le=1)
|
|
33
|
-
|
|
34
|
-
|
|
31
|
+
"""Chance each gene of a child is mutated. None: 1 / the number of variables, at least 0.1;
|
|
32
|
+
with noise, 0.1, which the benchmark's noisy problems favour at large budgets."""
|
|
35
33
|
mutation_scale: float = Field(default=0.1, gt=0)
|
|
36
|
-
|
|
37
|
-
|
|
34
|
+
"""Size of a range mutation, as a fraction of the range width: the starting size when
|
|
35
|
+
mutation adapts, and the size throughout when it doesn't."""
|
|
38
36
|
adaptive_mutation: bool | None = None
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
37
|
+
"""Each individual carries its own mutation size, which its children inherit and vary, so
|
|
38
|
+
selection tunes it as the run goes. None: on, except with noise, where it didn't help."""
|
|
39
|
+
crossover_rate: float = Field(default=0.8, ge=0, le=1)
|
|
40
|
+
"""Chance each gene of a child comes from its first parent."""
|
|
42
41
|
blend_crossover: bool = True
|
|
42
|
+
"""Draw each range value of a child from between its parents' values, widened by blend_alpha
|
|
43
|
+
times their distance on each side, rather than copying one."""
|
|
43
44
|
blend_alpha: float = Field(default=0.1, ge=0)
|
|
45
|
+
"""How far beyond its parents' values a blended range value may fall, as a multiple of
|
|
46
|
+
their distance."""
|
|
44
47
|
elitism: bool = True
|
|
45
|
-
|
|
48
|
+
"""Carry the fittest individuals over to the next generation unchanged."""
|
|
49
|
+
elitism_rate: float = Field(default=0.1, ge=0, lt=1)
|
|
50
|
+
"""Share of each generation carried over unchanged, at most all but one individual."""
|
|
46
51
|
selection_method: SelectionMethod = SelectionMethod.TOURNAMENT
|
|
52
|
+
"""How parents are chosen."""
|
|
47
53
|
tournament_size: int = Field(default=4, ge=2)
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
# late, on large budgets; costs on small ones. 0 turns niches off. None, the default, means
|
|
52
|
-
# 0.5 for a search space with conditions, where each branch is a niche, and 0 otherwise.
|
|
54
|
+
"""Individuals drawn for each tournament; the fittest of them becomes a parent."""
|
|
55
|
+
tournament_p: float = Field(default=1.0, ge=0, le=1)
|
|
56
|
+
"""Chance a tournament picks its best rather than its worst."""
|
|
53
57
|
niche_share: float | None = Field(default=None, ge=0, lt=1)
|
|
58
|
+
"""Share of children bred within niches of parents with the same choice parameter values, so
|
|
59
|
+
each option keeps tuning its own numbers. Helps problems where the best choice is found
|
|
60
|
+
late, on large budgets; costs on small ones. 0 turns niches off. None, the default, means
|
|
61
|
+
0.5 for a search space with conditions, where each branch is a niche, and 0 otherwise."""
|
|
54
62
|
|
|
55
63
|
@model_validator(mode="before")
|
|
56
64
|
@classmethod
|
|
@@ -18,9 +18,10 @@ class MultiObjectiveConfig(OptimizerConfig):
|
|
|
18
18
|
don't apply.
|
|
19
19
|
"""
|
|
20
20
|
objectives: dict[str, Direction] = Field(min_length=2)
|
|
21
|
-
|
|
22
|
-
# the worst value of each objective in the first generation, a tenth of its range further out.
|
|
21
|
+
"""Each objective's name, and whether to minimize or maximize it."""
|
|
23
22
|
reference: dict[str, float] | None = None
|
|
23
|
+
"""A point every objective must be better than to count toward hypervolume, by objective. None:
|
|
24
|
+
the worst value of each objective in the first generation, a tenth of its range further out."""
|
|
24
25
|
|
|
25
26
|
@model_validator(mode="after")
|
|
26
27
|
def _check_objectives(self):
|
|
@@ -42,13 +43,20 @@ class NSGA2Config(MultiObjectiveConfig):
|
|
|
42
43
|
are NSGA-II's own. With max_evaluations set, population_size and generations default as
|
|
43
44
|
for the genetic optimizer.
|
|
44
45
|
"""
|
|
45
|
-
mutation_rate: float | None = Field(default=None, ge=0, le=1)
|
|
46
|
+
mutation_rate: float | None = Field(default=None, ge=0, le=1)
|
|
47
|
+
"""As in GeneticOptimizerConfig: chance each gene of a child is mutated."""
|
|
46
48
|
mutation_scale: float = Field(default=0.1, gt=0)
|
|
49
|
+
"""As in GeneticOptimizerConfig: size of a range mutation, as a fraction of the range width."""
|
|
47
50
|
adaptive_mutation: bool | None = None
|
|
51
|
+
"""As in GeneticOptimizerConfig: each individual carries its own mutation size."""
|
|
48
52
|
crossover_rate: float = Field(default=0.8, ge=0, le=1)
|
|
53
|
+
"""As in GeneticOptimizerConfig: chance each gene of a child comes from its first parent."""
|
|
49
54
|
blend_crossover: bool = True
|
|
55
|
+
"""As in GeneticOptimizerConfig: draw each range value of a child from between its parents' values."""
|
|
50
56
|
blend_alpha: float = Field(default=0.1, ge=0)
|
|
57
|
+
"""As in GeneticOptimizerConfig: how far beyond its parents' values a blended value may fall."""
|
|
51
58
|
niche_share: float | None = Field(default=None, ge=0, lt=1)
|
|
59
|
+
"""As in GeneticOptimizerConfig: share of children bred within niches of parents with the same choices."""
|
|
52
60
|
|
|
53
61
|
@model_validator(mode="before")
|
|
54
62
|
@classmethod
|
|
@@ -70,13 +78,16 @@ class MultiObjectiveBayesianConfig(MultiObjectiveConfig):
|
|
|
70
78
|
As with BayesianConfig, each generation is a batch of candidates chosen together, and with
|
|
71
79
|
max_evaluations set, generations defaults to the budget.
|
|
72
80
|
"""
|
|
73
|
-
population_size: int | None = Field(default=None, ge=1) # type: ignore[assignment]
|
|
81
|
+
population_size: int | None = Field(default=None, ge=1) # type: ignore[assignment]
|
|
82
|
+
"""Candidates per batch. None: 1, or the number of workers."""
|
|
74
83
|
generations: int = Field(default=100, ge=1)
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
# with the weighting applied to their predictions.
|
|
84
|
+
"""Batches to run, unless the run stops sooner."""
|
|
85
|
+
initial_samples: int | None = Field(default=None, ge=1)
|
|
86
|
+
"""Spread-out candidates evaluated before the models are used. None: 2 × (variables + 1)."""
|
|
79
87
|
method: Literal["parego", "models"] = "parego"
|
|
88
|
+
"""How candidates are chosen. "parego": a random weighting of the scaled objectives per
|
|
89
|
+
candidate, scored by one Gaussian process. "models": one Gaussian process per objective,
|
|
90
|
+
with the weighting applied to their predictions."""
|
|
80
91
|
|
|
81
92
|
@model_validator(mode="before")
|
|
82
93
|
@classmethod
|
hone/config/optimizer_config.py
CHANGED
|
@@ -7,23 +7,32 @@ from pydantic import BaseModel, ConfigDict, Field, model_validator
|
|
|
7
7
|
|
|
8
8
|
class OptimizerConfig(BaseModel):
|
|
9
9
|
"""Settings shared by every optimizer."""
|
|
10
|
-
|
|
10
|
+
# use_attribute_docstrings makes each field's docstring its description, in the JSON schema
|
|
11
|
+
# and in the documentation.
|
|
12
|
+
model_config = ConfigDict(extra="forbid", frozen=True, use_attribute_docstrings=True)
|
|
11
13
|
|
|
12
|
-
population_size: int = Field(default=100, ge=2)
|
|
14
|
+
population_size: int = Field(default=100, ge=2)
|
|
15
|
+
"""Individuals evaluated per generation."""
|
|
13
16
|
generations: int = Field(default=25, ge=1)
|
|
14
|
-
|
|
17
|
+
"""Generations to run, unless the run stops sooner."""
|
|
18
|
+
max_evaluations: int | None = Field(default=None, ge=1)
|
|
19
|
+
"""Stop after this many evaluations, even partway through a generation."""
|
|
15
20
|
maximize: bool = False
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
+
"""Maximize the objective instead of minimizing it."""
|
|
22
|
+
threshold: float | None = None
|
|
23
|
+
"""Stop once the best fitness reaches this."""
|
|
24
|
+
seed: int | None = None
|
|
25
|
+
"""Fixes the random number generator, so runs can be repeated."""
|
|
26
|
+
noise: bool = False
|
|
27
|
+
"""The objective is noisy: evaluating the same point twice can give different values."""
|
|
21
28
|
final_evaluations: int = Field(default=0, ge=0)
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
# and their results join the generation under way when they arrive. Results then depend on
|
|
25
|
-
# timing, so runs are no longer exactly repeatable.
|
|
29
|
+
"""With noise, evaluations kept back to re-evaluate the most promising points at the end, so
|
|
30
|
+
the result is chosen, and its value reported, from averages rather than single lucky values."""
|
|
26
31
|
min_finished: float = Field(default=1.0, gt=0, le=1)
|
|
32
|
+
"""The share of each generation's evaluations that must finish before the next generation is
|
|
33
|
+
bred. Below 1, the slowest evaluations don't hold up the run: they finish in the background,
|
|
34
|
+
and their results join the generation under way when they arrive. Results then depend on
|
|
35
|
+
timing, so runs are no longer exactly repeatable."""
|
|
27
36
|
|
|
28
37
|
@model_validator(mode="after")
|
|
29
38
|
def _check_final_evaluations(self):
|
|
@@ -0,0 +1,523 @@
|
|
|
1
|
+
"""Which parameters matter: global sensitivity analysis, before or instead of optimizing.
|
|
2
|
+
|
|
3
|
+
sensitivity() evaluates the objective at points chosen to measure each parameter's effect,
|
|
4
|
+
through the same workers, time limits and failure handling as optimize(), and reports each
|
|
5
|
+
parameter's importance. On small budgets it uses Morris screening, which ranks the
|
|
6
|
+
parameters; on larger ones Sobol indices, which say what share of the objective's variance
|
|
7
|
+
each parameter accounts for, alone and with its interactions.
|
|
8
|
+
|
|
9
|
+
Every parameter is measured on the scale the optimizers search it on: a log range evenly in
|
|
10
|
+
its logarithm, an integer range rounded, and a choice parameter by picking among its choices,
|
|
11
|
+
so an effect is the change across the parameter's whole range. Fixed parameters aren't
|
|
12
|
+
measured. A parameter a condition switches off isn't passed to the objective at that point,
|
|
13
|
+
so it has no effect there, which its indices include.
|
|
14
|
+
"""
|
|
15
|
+
import math
|
|
16
|
+
from functools import partial
|
|
17
|
+
from typing import Any, Callable, Literal, Sequence
|
|
18
|
+
|
|
19
|
+
import numpy as np
|
|
20
|
+
from pydantic import BaseModel, ConfigDict
|
|
21
|
+
from scipy.stats import qmc
|
|
22
|
+
|
|
23
|
+
from hone.objective_function import ObjectiveFunction
|
|
24
|
+
from hone.optimizers.core import UnsupportedSearchSpace, _evaluate
|
|
25
|
+
from hone.optimizers._pool import EvaluationPool
|
|
26
|
+
from hone.parameters import ChoiceParameter, FixedParameter, Parameter, RangeParameter, SearchSpace
|
|
27
|
+
|
|
28
|
+
type Method = Literal["morris", "sobol"]
|
|
29
|
+
|
|
30
|
+
MORRIS_LEVELS = 4 # grid levels per parameter; the step is half the grid, so each level pairs with another
|
|
31
|
+
MORRIS_STEP = MORRIS_LEVELS / (2 * (MORRIS_LEVELS - 1)) # 2/3 of the range
|
|
32
|
+
MIN_TRAJECTORIES = 2 # Morris needs at least two trajectories to estimate sigma
|
|
33
|
+
MIN_SOBOL_SAMPLES = 16 # Sobol rows below which its indices are too noisy to report
|
|
34
|
+
AUTO_SOBOL_SAMPLES = 64 # rows at which sensitivity() picks Sobol over Morris by itself
|
|
35
|
+
BOOTSTRAP_RESAMPLES = 1000
|
|
36
|
+
DEFAULT_SOBOL_THRESHOLD = 0.05 # a total index below which reduced() fixes a parameter
|
|
37
|
+
DEFAULT_MORRIS_THRESHOLD = 0.1 # a share of the largest mu_star below which reduced() fixes a parameter
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
class Interval(BaseModel):
|
|
41
|
+
"""A confidence interval."""
|
|
42
|
+
model_config = ConfigDict(frozen=True, use_attribute_docstrings=True)
|
|
43
|
+
|
|
44
|
+
low: float
|
|
45
|
+
"""The lower end."""
|
|
46
|
+
high: float
|
|
47
|
+
"""The upper end."""
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
class ParameterSensitivity(BaseModel):
|
|
51
|
+
"""How much one parameter matters.
|
|
52
|
+
|
|
53
|
+
importance ranks the parameters: mu_star for Morris, the total index for Sobol. The
|
|
54
|
+
other fields are None for the method that wasn't used.
|
|
55
|
+
"""
|
|
56
|
+
model_config = ConfigDict(frozen=True, use_attribute_docstrings=True)
|
|
57
|
+
|
|
58
|
+
name: str
|
|
59
|
+
"""The parameter's name."""
|
|
60
|
+
importance: float
|
|
61
|
+
"""mu_star for Morris, the total index for Sobol."""
|
|
62
|
+
interval: Interval | None = None
|
|
63
|
+
"""The confidence interval of importance; None when too few evaluations succeeded to estimate it."""
|
|
64
|
+
mu_star: float | None = None
|
|
65
|
+
"""Morris: the mean size of the parameter's effect, the change in the objective across its whole
|
|
66
|
+
range, whichever way it goes. Small means the parameter barely matters."""
|
|
67
|
+
mu: float | None = None
|
|
68
|
+
"""Morris: the mean effect with its sign. Well below mu_star means the effect changes direction."""
|
|
69
|
+
sigma: float | None = None
|
|
70
|
+
"""Morris: the standard deviation of the effect. Large against mu_star means the effect depends on
|
|
71
|
+
the other parameters, through interactions or a curved response."""
|
|
72
|
+
first: float | None = None
|
|
73
|
+
"""Sobol: the share of the objective's variance the parameter accounts for alone."""
|
|
74
|
+
first_interval: Interval | None = None
|
|
75
|
+
"""Sobol: the confidence interval of first."""
|
|
76
|
+
total: float | None = None
|
|
77
|
+
"""Sobol: the share of the variance the parameter accounts for with all its interactions; near 0
|
|
78
|
+
means it can be fixed at any value with little effect. Estimates can fall slightly below 0."""
|
|
79
|
+
total_interval: Interval | None = None
|
|
80
|
+
"""Sobol: the confidence interval of total, the same as interval."""
|
|
81
|
+
|
|
82
|
+
|
|
83
|
+
class SensitivityReport(BaseModel):
|
|
84
|
+
"""What sensitivity() measured: each parameter's importance, most important first."""
|
|
85
|
+
model_config = ConfigDict(frozen=True, use_attribute_docstrings=True)
|
|
86
|
+
|
|
87
|
+
method: Method
|
|
88
|
+
"""How the parameters were measured: "morris" or "sobol"."""
|
|
89
|
+
parameters: list[ParameterSensitivity]
|
|
90
|
+
"""Each parameter measured, most important first."""
|
|
91
|
+
evaluations: int
|
|
92
|
+
"""Evaluations made, failed ones included."""
|
|
93
|
+
failures: int
|
|
94
|
+
"""Evaluations that failed, timed out or crashed their worker."""
|
|
95
|
+
confidence: float
|
|
96
|
+
"""The confidence level of the intervals."""
|
|
97
|
+
best_params: dict[str, Any] | None
|
|
98
|
+
"""The best point evaluated, as the objective was called with it; None if every evaluation failed."""
|
|
99
|
+
best_value: float | None
|
|
100
|
+
"""The objective's value at best_params; None if every evaluation failed."""
|
|
101
|
+
maximize: bool
|
|
102
|
+
"""Whether higher values were counted as better in choosing best_params."""
|
|
103
|
+
|
|
104
|
+
@property
|
|
105
|
+
def ranking(self) -> list[str]:
|
|
106
|
+
"""The parameters' names, most important first."""
|
|
107
|
+
return [parameter.name for parameter in self.parameters]
|
|
108
|
+
|
|
109
|
+
def __getitem__(self, name: str) -> ParameterSensitivity:
|
|
110
|
+
for parameter in self.parameters:
|
|
111
|
+
if parameter.name == name:
|
|
112
|
+
return parameter
|
|
113
|
+
raise KeyError(name)
|
|
114
|
+
|
|
115
|
+
def unimportant(self, threshold: float | None = None) -> list[str]:
|
|
116
|
+
"""The parameters that can be fixed with little effect: those whose whole interval is below threshold.
|
|
117
|
+
|
|
118
|
+
For Sobol, threshold is a total index, 0.05 unless given: the parameter accounts for
|
|
119
|
+
under 5% of the objective's variance, interactions included. For Morris it is a share of
|
|
120
|
+
the largest mu_star, 0.1 unless given. Only the upper end of each interval is compared,
|
|
121
|
+
so a parameter whose importance is uncertain is kept. A parameter without an interval,
|
|
122
|
+
because too few of its evaluations succeeded, is kept too.
|
|
123
|
+
"""
|
|
124
|
+
if threshold is None:
|
|
125
|
+
threshold = DEFAULT_SOBOL_THRESHOLD if self.method == "sobol" else DEFAULT_MORRIS_THRESHOLD
|
|
126
|
+
if threshold < 0:
|
|
127
|
+
raise ValueError(f"threshold must be at least 0, got {threshold}")
|
|
128
|
+
if self.method == "morris":
|
|
129
|
+
largest = max((p.importance for p in self.parameters if math.isfinite(p.importance)), default=0.0)
|
|
130
|
+
threshold *= largest
|
|
131
|
+
return [p.name for p in self.parameters if p.interval is not None and p.interval.high < threshold]
|
|
132
|
+
|
|
133
|
+
def reduced(
|
|
134
|
+
self,
|
|
135
|
+
search_space: SearchSpace | Sequence[Parameter],
|
|
136
|
+
*,
|
|
137
|
+
threshold: float | None = None,
|
|
138
|
+
keep: int | None = None,
|
|
139
|
+
at: dict[str, Any] | None = None,
|
|
140
|
+
) -> SearchSpace:
|
|
141
|
+
"""The search space with its unimportant parameters fixed, ready for choose_optimizer.
|
|
142
|
+
|
|
143
|
+
The parameters unimportant() names are fixed, or with keep, every parameter but the
|
|
144
|
+
keep most important. Each is fixed at its value in at, if given, and otherwise at the best
|
|
145
|
+
point evaluated; one the conditions switched off there, or every parameter if every
|
|
146
|
+
evaluation failed, is fixed at the middle of its range, or its middle choice.
|
|
147
|
+
|
|
148
|
+
A fixed parameter is still passed to the objective, so the objective doesn't change.
|
|
149
|
+
Conditions and constraints are kept: a parameter one of them tests stays a range or
|
|
150
|
+
choice parameter, narrowed to its one value, so they still apply.
|
|
151
|
+
|
|
152
|
+
Args:
|
|
153
|
+
search_space: The search space the report measured.
|
|
154
|
+
threshold: Passed to unimportant(). Not with keep.
|
|
155
|
+
keep: Keep this many of the most important parameters, and fix the rest.
|
|
156
|
+
at: Values to fix parameters at, by name.
|
|
157
|
+
"""
|
|
158
|
+
space = search_space if isinstance(search_space, SearchSpace) else SearchSpace(search_space)
|
|
159
|
+
measured = [p.name for p in space.parameters if not isinstance(p, FixedParameter)]
|
|
160
|
+
if sorted(measured) != sorted(self.ranking):
|
|
161
|
+
raise ValueError(f"this report measured {', '.join(self.ranking)}, but the search space's parameters are {', '.join(measured)}")
|
|
162
|
+
if keep is not None:
|
|
163
|
+
if threshold is not None:
|
|
164
|
+
raise ValueError("give threshold or keep, not both")
|
|
165
|
+
if keep < 1:
|
|
166
|
+
raise ValueError(f"keep must be at least 1, got {keep}")
|
|
167
|
+
dropped = self.ranking[keep:]
|
|
168
|
+
else:
|
|
169
|
+
dropped = self.unimportant(threshold)
|
|
170
|
+
unknown = sorted(set(at or {}) - set(space.names))
|
|
171
|
+
if unknown:
|
|
172
|
+
raise ValueError(f"at names parameters the search space doesn't have: {', '.join(unknown)}")
|
|
173
|
+
tested = {name for c in space.conditions for name in c.when.names()} | {name for c in space.constraints for name in c.names()}
|
|
174
|
+
parameters = []
|
|
175
|
+
for parameter in space.parameters:
|
|
176
|
+
if parameter.name not in dropped:
|
|
177
|
+
parameters.append(parameter)
|
|
178
|
+
continue
|
|
179
|
+
if at is not None and parameter.name in at:
|
|
180
|
+
value = parameter.check(at[parameter.name])
|
|
181
|
+
elif self.best_params is not None and parameter.name in self.best_params:
|
|
182
|
+
value = self.best_params[parameter.name]
|
|
183
|
+
else:
|
|
184
|
+
value = _from_unit(parameter, 0.5)
|
|
185
|
+
parameters.append(_fixed(parameter, value, keep_kind=parameter.name in tested))
|
|
186
|
+
return SearchSpace(parameters, space.constraints, space.conditions)
|
|
187
|
+
|
|
188
|
+
def __str__(self) -> str:
|
|
189
|
+
if self.method == "morris":
|
|
190
|
+
header = ("parameter", "mu_star", "interval", "mu", "sigma")
|
|
191
|
+
rows = [
|
|
192
|
+
(p.name, _number(p.mu_star), _interval(p.interval), _number(p.mu), _number(p.sigma))
|
|
193
|
+
for p in self.parameters
|
|
194
|
+
]
|
|
195
|
+
else:
|
|
196
|
+
header = ("parameter", "total", "interval", "first", "interval")
|
|
197
|
+
rows = [
|
|
198
|
+
(p.name, _number(p.total), _interval(p.total_interval), _number(p.first), _interval(p.first_interval))
|
|
199
|
+
for p in self.parameters
|
|
200
|
+
]
|
|
201
|
+
widths = [max(len(row[i]) for row in [header, *rows]) for i in range(len(header))]
|
|
202
|
+
lines = [
|
|
203
|
+
f"{'Morris screening' if self.method == 'morris' else 'Sobol indices'}: {self.evaluations} evaluations, "
|
|
204
|
+
f"{self.failures} failed; {self.confidence:.0%} intervals"
|
|
205
|
+
]
|
|
206
|
+
for row in [header, *rows]:
|
|
207
|
+
lines.append(" ".join(cell.ljust(width) if i == 0 else cell.rjust(width) for i, (cell, width) in enumerate(zip(row, widths))))
|
|
208
|
+
return "\n".join(lines)
|
|
209
|
+
|
|
210
|
+
|
|
211
|
+
def sensitivity(
|
|
212
|
+
objective_function: Callable,
|
|
213
|
+
search_space: SearchSpace | Sequence[Parameter],
|
|
214
|
+
*,
|
|
215
|
+
max_evaluations: int = 500,
|
|
216
|
+
method: Method | None = None,
|
|
217
|
+
maximize: bool = False,
|
|
218
|
+
seed: int | None = None,
|
|
219
|
+
workers: int = 1,
|
|
220
|
+
timeout: float | None = None,
|
|
221
|
+
confidence: float = 0.95,
|
|
222
|
+
) -> SensitivityReport:
|
|
223
|
+
"""Measure how much each parameter of the search space matters to the objective.
|
|
224
|
+
|
|
225
|
+
Morris screening needs about 10 × (parameters + 1) evaluations to rank the parameters.
|
|
226
|
+
Sobol indices need about 64 × (parameters + 2) or more, and say what share of the
|
|
227
|
+
objective's variance each parameter accounts for. Without method, Sobol is used when
|
|
228
|
+
max_evaluations allows it, and Morris otherwise. Neither uses more than max_evaluations.
|
|
229
|
+
|
|
230
|
+
The objective is called as optimize() calls it: with one keyword argument per parameter
|
|
231
|
+
switched on, raising EvaluationFailed or returning NaN or infinity to record a failed
|
|
232
|
+
evaluation. Failed evaluations are left out of the indices.
|
|
233
|
+
|
|
234
|
+
Args:
|
|
235
|
+
objective_function: The function to measure.
|
|
236
|
+
search_space: The parameters, with any conditions; constraints aren't supported yet.
|
|
237
|
+
max_evaluations: The most evaluations to make.
|
|
238
|
+
method: "morris" or "sobol", rather than choosing from max_evaluations.
|
|
239
|
+
maximize: Whether higher values are better, which only decides best_params.
|
|
240
|
+
seed: Fixes the points evaluated and the intervals, so a run can be repeated.
|
|
241
|
+
workers: Evaluate this many points at once in background processes.
|
|
242
|
+
timeout: The longest, in seconds, one evaluation may take, as in optimize().
|
|
243
|
+
confidence: The confidence level of the intervals, from bootstrapping.
|
|
244
|
+
|
|
245
|
+
With workers > 1 or a timeout, each evaluation runs in a separate process, so the
|
|
246
|
+
function must be defined at the top level of a module.
|
|
247
|
+
"""
|
|
248
|
+
space = search_space if isinstance(search_space, SearchSpace) else SearchSpace(search_space)
|
|
249
|
+
if space.constraints:
|
|
250
|
+
raise UnsupportedSearchSpace(
|
|
251
|
+
"sensitivity() doesn't support constraints yet: Morris and Sobol assume each parameter can take any of its "
|
|
252
|
+
"values whatever the others are"
|
|
253
|
+
)
|
|
254
|
+
if workers < 1:
|
|
255
|
+
raise ValueError(f"workers must be at least 1, got {workers}")
|
|
256
|
+
if timeout is not None and timeout <= 0:
|
|
257
|
+
raise ValueError(f"timeout must be positive, got {timeout}")
|
|
258
|
+
if not 0 < confidence < 1:
|
|
259
|
+
raise ValueError(f"confidence must be between 0 and 1, got {confidence}")
|
|
260
|
+
measured = [parameter for parameter in space.parameters if not isinstance(parameter, FixedParameter)]
|
|
261
|
+
if not measured:
|
|
262
|
+
raise ValueError("every parameter is fixed, so there is nothing to measure")
|
|
263
|
+
k = len(measured)
|
|
264
|
+
method = method or ("sobol" if _sobol_samples(max_evaluations, k) >= AUTO_SOBOL_SAMPLES else "morris")
|
|
265
|
+
if method not in ("morris", "sobol"):
|
|
266
|
+
raise ValueError(f"method must be 'morris' or 'sobol', got {method!r}")
|
|
267
|
+
rng = np.random.default_rng(seed)
|
|
268
|
+
|
|
269
|
+
if method == "morris":
|
|
270
|
+
trajectories = max_evaluations // (k + 1)
|
|
271
|
+
if trajectories < MIN_TRAJECTORIES:
|
|
272
|
+
raise ValueError(
|
|
273
|
+
f"Morris screening of {k} parameters needs at least {MIN_TRAJECTORIES * (k + 1)} evaluations, "
|
|
274
|
+
f"and about {10 * (k + 1)} to rank them reliably; max_evaluations is {max_evaluations}"
|
|
275
|
+
)
|
|
276
|
+
units, steps = _morris_design(trajectories, k, rng)
|
|
277
|
+
else:
|
|
278
|
+
n = _sobol_samples(max_evaluations, k)
|
|
279
|
+
if n < MIN_SOBOL_SAMPLES:
|
|
280
|
+
raise ValueError(
|
|
281
|
+
f"Sobol indices of {k} parameters need at least {MIN_SOBOL_SAMPLES * (k + 2)} evaluations, "
|
|
282
|
+
f"and about {AUTO_SOBOL_SAMPLES * (k + 2)} to be reliable; max_evaluations is {max_evaluations}. "
|
|
283
|
+
"method='morris' ranks the parameters with fewer"
|
|
284
|
+
)
|
|
285
|
+
units = _sobol_design(n, k, rng)
|
|
286
|
+
|
|
287
|
+
points = [_point(space, measured, row) for row in units]
|
|
288
|
+
values = _evaluate_all(objective_function, space, points, workers, timeout)
|
|
289
|
+
ok = np.isfinite(values)
|
|
290
|
+
|
|
291
|
+
if method == "morris":
|
|
292
|
+
results = _morris_indices(measured, values, steps, confidence, rng)
|
|
293
|
+
else:
|
|
294
|
+
results = _sobol_indices(measured, values, n, confidence, rng)
|
|
295
|
+
results.sort(key=lambda parameter: -parameter.importance if math.isfinite(parameter.importance) else math.inf)
|
|
296
|
+
|
|
297
|
+
best_params, best_value = None, None
|
|
298
|
+
if ok.any():
|
|
299
|
+
best = int(np.nanargmax(values) if maximize else np.nanargmin(values))
|
|
300
|
+
best_params, best_value = space.active(points[best]), float(values[best])
|
|
301
|
+
return SensitivityReport(
|
|
302
|
+
method=method,
|
|
303
|
+
parameters=results,
|
|
304
|
+
evaluations=len(points),
|
|
305
|
+
failures=int((~ok).sum()),
|
|
306
|
+
confidence=confidence,
|
|
307
|
+
best_params=best_params,
|
|
308
|
+
best_value=best_value,
|
|
309
|
+
maximize=maximize,
|
|
310
|
+
)
|
|
311
|
+
|
|
312
|
+
|
|
313
|
+
# --- from the unit cube to points ----------------------------------------------
|
|
314
|
+
|
|
315
|
+
|
|
316
|
+
def _point(space: SearchSpace, measured: Sequence[Parameter], unit: np.ndarray) -> dict[str, Any]:
|
|
317
|
+
"""The point of space at position unit, one coordinate in [0, 1] per measured parameter."""
|
|
318
|
+
values = {parameter.name: _from_unit(parameter, float(u)) for parameter, u in zip(measured, unit)}
|
|
319
|
+
return {
|
|
320
|
+
parameter.name: parameter.value if isinstance(parameter, FixedParameter) else values[parameter.name]
|
|
321
|
+
for parameter in space.parameters
|
|
322
|
+
}
|
|
323
|
+
|
|
324
|
+
|
|
325
|
+
def _from_unit(parameter: Parameter, u: float) -> Any:
|
|
326
|
+
"""The parameter's value at u in [0, 1], on the scale the optimizers search it on."""
|
|
327
|
+
if isinstance(parameter, RangeParameter):
|
|
328
|
+
return parameter.from_unit(u)
|
|
329
|
+
assert isinstance(parameter, ChoiceParameter)
|
|
330
|
+
if parameter.choose_n is None:
|
|
331
|
+
return parameter.choices[min(int(u * len(parameter.choices)), len(parameter.choices) - 1)]
|
|
332
|
+
count = math.comb(len(parameter.choices), parameter.choose_n)
|
|
333
|
+
indices = _unrank_combination(min(int(u * count), count - 1), len(parameter.choices), parameter.choose_n)
|
|
334
|
+
return [parameter.choices[i] for i in indices]
|
|
335
|
+
|
|
336
|
+
|
|
337
|
+
def _fixed(parameter: Parameter, value: Any, keep_kind: bool) -> Parameter:
|
|
338
|
+
"""parameter held at value: a FixedParameter, or with keep_kind, a range or choice of that one value."""
|
|
339
|
+
if isinstance(parameter, RangeParameter):
|
|
340
|
+
if keep_kind:
|
|
341
|
+
return RangeParameter(parameter.name, value, value, integer=parameter.integer, log=parameter.log)
|
|
342
|
+
return FixedParameter(parameter.name, value)
|
|
343
|
+
assert isinstance(parameter, ChoiceParameter)
|
|
344
|
+
if parameter.choose_n is not None:
|
|
345
|
+
return ChoiceParameter(parameter.name, list(value), choose_n=parameter.choose_n)
|
|
346
|
+
return ChoiceParameter(parameter.name, [value]) if keep_kind else FixedParameter(parameter.name, value)
|
|
347
|
+
|
|
348
|
+
|
|
349
|
+
def _unrank_combination(rank: int, n: int, k: int) -> list[int]:
|
|
350
|
+
"""The rank-th k-element subset of range(n), in lexicographic order."""
|
|
351
|
+
chosen: list[int] = []
|
|
352
|
+
candidate = 0
|
|
353
|
+
while len(chosen) < k:
|
|
354
|
+
with_candidate = math.comb(n - candidate - 1, k - len(chosen) - 1)
|
|
355
|
+
if rank < with_candidate:
|
|
356
|
+
chosen.append(candidate)
|
|
357
|
+
else:
|
|
358
|
+
rank -= with_candidate
|
|
359
|
+
candidate += 1
|
|
360
|
+
return chosen
|
|
361
|
+
|
|
362
|
+
|
|
363
|
+
def _evaluate_all(
|
|
364
|
+
objective_function: Callable, space: SearchSpace, points: list[dict[str, Any]], workers: int, timeout: float | None
|
|
365
|
+
) -> np.ndarray:
|
|
366
|
+
"""Each point's value, NaN where the evaluation failed, as optimize() evaluates them."""
|
|
367
|
+
objective = ObjectiveFunction(
|
|
368
|
+
name=getattr(objective_function, "__name__", "objective"), function=objective_function, search_space=space
|
|
369
|
+
)
|
|
370
|
+
evaluate = partial(_evaluate, objective)
|
|
371
|
+
called = [space.active(point) for point in points]
|
|
372
|
+
if workers == 1 and timeout is None:
|
|
373
|
+
outcomes = [evaluate(point) for point in called]
|
|
374
|
+
else:
|
|
375
|
+
with EvaluationPool(evaluate, workers, timeout) as pool:
|
|
376
|
+
outcomes = pool.map(called)
|
|
377
|
+
values = np.array([math.nan if outcome is None else outcome for outcome in outcomes], dtype=float)
|
|
378
|
+
values[~np.isfinite(values)] = math.nan
|
|
379
|
+
return values
|
|
380
|
+
|
|
381
|
+
|
|
382
|
+
# --- Morris screening ------------------------------------------------------------
|
|
383
|
+
|
|
384
|
+
|
|
385
|
+
def _morris_design(trajectories: int, k: int, rng: np.random.Generator) -> tuple[np.ndarray, list[list[tuple[int, int, float]]]]:
|
|
386
|
+
"""Morris's one-at-a-time trajectories through a grid of MORRIS_LEVELS levels.
|
|
387
|
+
|
|
388
|
+
Returns the points, trajectories × (k + 1) rows of k unit coordinates, and for each
|
|
389
|
+
trajectory its steps: (parameter, row it steps from, signed step size).
|
|
390
|
+
"""
|
|
391
|
+
levels = np.arange(MORRIS_LEVELS) / (MORRIS_LEVELS - 1)
|
|
392
|
+
rows: list[np.ndarray] = []
|
|
393
|
+
steps: list[list[tuple[int, int, float]]] = []
|
|
394
|
+
for _ in range(trajectories):
|
|
395
|
+
x = rng.choice(levels, size=k)
|
|
396
|
+
start = len(rows)
|
|
397
|
+
rows.append(x.copy())
|
|
398
|
+
trajectory = []
|
|
399
|
+
for position, i in enumerate(rng.permutation(k)):
|
|
400
|
+
step = MORRIS_STEP if x[i] + MORRIS_STEP <= 1 + 1e-12 else -MORRIS_STEP
|
|
401
|
+
x[i] = round(x[i] + step, 12)
|
|
402
|
+
rows.append(x.copy())
|
|
403
|
+
trajectory.append((int(i), start + position, step))
|
|
404
|
+
steps.append(trajectory)
|
|
405
|
+
return np.array(rows), steps
|
|
406
|
+
|
|
407
|
+
|
|
408
|
+
def _morris_indices(
|
|
409
|
+
measured: Sequence[Parameter], values: np.ndarray, steps: list[list[tuple[int, int, float]]], confidence: float, rng: np.random.Generator
|
|
410
|
+
) -> list[ParameterSensitivity]:
|
|
411
|
+
effects: list[list[float]] = [[] for _ in measured]
|
|
412
|
+
for trajectory in steps:
|
|
413
|
+
for i, row, step in trajectory:
|
|
414
|
+
before, after = values[row], values[row + 1]
|
|
415
|
+
if math.isfinite(before) and math.isfinite(after):
|
|
416
|
+
effects[i].append((after - before) / step)
|
|
417
|
+
results = []
|
|
418
|
+
for parameter, found in zip(measured, effects):
|
|
419
|
+
e = np.array(found)
|
|
420
|
+
if not len(e):
|
|
421
|
+
results.append(ParameterSensitivity(name=parameter.name, importance=math.nan))
|
|
422
|
+
continue
|
|
423
|
+
mu_star = float(np.mean(np.abs(e)))
|
|
424
|
+
interval = None
|
|
425
|
+
if len(e) >= 2:
|
|
426
|
+
resampled = np.abs(e[rng.integers(len(e), size=(BOOTSTRAP_RESAMPLES, len(e)))]).mean(axis=1)
|
|
427
|
+
interval = _percentiles(resampled, confidence)
|
|
428
|
+
results.append(
|
|
429
|
+
ParameterSensitivity(
|
|
430
|
+
name=parameter.name,
|
|
431
|
+
importance=mu_star,
|
|
432
|
+
interval=interval,
|
|
433
|
+
mu_star=mu_star,
|
|
434
|
+
mu=float(np.mean(e)),
|
|
435
|
+
sigma=float(np.std(e, ddof=1)) if len(e) >= 2 else None,
|
|
436
|
+
)
|
|
437
|
+
)
|
|
438
|
+
return results
|
|
439
|
+
|
|
440
|
+
|
|
441
|
+
# --- Sobol indices -----------------------------------------------------------------
|
|
442
|
+
|
|
443
|
+
|
|
444
|
+
def _sobol_samples(max_evaluations: int, k: int) -> int:
|
|
445
|
+
"""The most rows of Sobol's design that fit in max_evaluations: a power of 2, as its sequence needs."""
|
|
446
|
+
rows = max_evaluations // (k + 2)
|
|
447
|
+
return 2 ** int(math.log2(rows)) if rows >= 1 else 0
|
|
448
|
+
|
|
449
|
+
|
|
450
|
+
def _sobol_design(n: int, k: int, rng: np.random.Generator) -> np.ndarray:
|
|
451
|
+
"""Saltelli's design: matrices A and B, then for each parameter A with that column from B.
|
|
452
|
+
|
|
453
|
+
A and B are the two halves of one scrambled Sobol sequence of 2k dimensions, as scipy's
|
|
454
|
+
sobol_indices draws them. Returns the (k + 2) n rows in that order.
|
|
455
|
+
"""
|
|
456
|
+
a_b = qmc.Sobol(d=2 * k, scramble=True, seed=rng).random(n)
|
|
457
|
+
a, b = a_b[:, :k], a_b[:, k:]
|
|
458
|
+
blocks = [a, b]
|
|
459
|
+
for i in range(k):
|
|
460
|
+
ab = a.copy()
|
|
461
|
+
ab[:, i] = b[:, i]
|
|
462
|
+
blocks.append(ab)
|
|
463
|
+
return np.vstack(blocks)
|
|
464
|
+
|
|
465
|
+
|
|
466
|
+
def _saltelli(f_a: np.ndarray, f_b: np.ndarray, f_ab: np.ndarray) -> tuple[np.ndarray, np.ndarray]:
|
|
467
|
+
"""First and total indices by Saltelli et al. (2010), as scipy's sobol_indices computes them.
|
|
468
|
+
|
|
469
|
+
The last axis is the rows; f_ab has one more leading axis, the parameter.
|
|
470
|
+
"""
|
|
471
|
+
mean = np.mean([f_a, f_b], axis=(0, -1), keepdims=True)[0]
|
|
472
|
+
f_a, f_b, f_ab = f_a - mean, f_b - mean, f_ab - mean
|
|
473
|
+
var = np.var([f_a, f_b], axis=(0, -1))
|
|
474
|
+
with np.errstate(divide="ignore", invalid="ignore"):
|
|
475
|
+
first = np.mean(f_b * (f_ab - f_a), axis=-1) / var
|
|
476
|
+
total = 0.5 * np.mean((f_a - f_ab) ** 2, axis=-1) / var
|
|
477
|
+
# An objective that doesn't vary has no variance to share out.
|
|
478
|
+
return np.where(np.isfinite(first), first, 0.0), np.where(np.isfinite(total), total, 0.0)
|
|
479
|
+
|
|
480
|
+
|
|
481
|
+
def _sobol_indices(measured: Sequence[Parameter], values: np.ndarray, n: int, confidence: float, rng: np.random.Generator) -> list[ParameterSensitivity]:
|
|
482
|
+
k = len(measured)
|
|
483
|
+
f_a, f_b = values[:n], values[n:2 * n]
|
|
484
|
+
f_ab = values[2 * n:].reshape(k, n)
|
|
485
|
+
# A failed evaluation spoils its row: keep the rows where every evaluation succeeded.
|
|
486
|
+
rows = np.flatnonzero(np.isfinite(f_a) & np.isfinite(f_b) & np.isfinite(f_ab).all(axis=0))
|
|
487
|
+
if len(rows) < 2:
|
|
488
|
+
return [ParameterSensitivity(name=parameter.name, importance=math.nan) for parameter in measured]
|
|
489
|
+
first, total = _saltelli(f_a[rows], f_b[rows], f_ab[:, rows])
|
|
490
|
+
firsts, totals = [], []
|
|
491
|
+
for start in range(0, BOOTSTRAP_RESAMPLES, 100):
|
|
492
|
+
picks = rows[rng.integers(len(rows), size=(min(100, BOOTSTRAP_RESAMPLES - start), len(rows)))]
|
|
493
|
+
s, t = _saltelli(f_a[picks], f_b[picks], f_ab[:, picks]) # (k, resamples) each
|
|
494
|
+
firsts.append(s)
|
|
495
|
+
totals.append(t)
|
|
496
|
+
first_samples, total_samples = np.concatenate(firsts, axis=-1), np.concatenate(totals, axis=-1)
|
|
497
|
+
return [
|
|
498
|
+
ParameterSensitivity(
|
|
499
|
+
name=parameter.name,
|
|
500
|
+
importance=float(total[i]),
|
|
501
|
+
interval=(total_interval := _percentiles(total_samples[i], confidence)),
|
|
502
|
+
first=float(first[i]),
|
|
503
|
+
first_interval=_percentiles(first_samples[i], confidence),
|
|
504
|
+
total=float(total[i]),
|
|
505
|
+
total_interval=total_interval,
|
|
506
|
+
)
|
|
507
|
+
for i, parameter in enumerate(measured)
|
|
508
|
+
]
|
|
509
|
+
|
|
510
|
+
|
|
511
|
+
def _percentiles(samples: np.ndarray, confidence: float) -> Interval:
|
|
512
|
+
"""The percentile bootstrap interval of samples."""
|
|
513
|
+
tail = (1 - confidence) / 2 * 100
|
|
514
|
+
low, high = np.percentile(samples, [tail, 100 - tail])
|
|
515
|
+
return Interval(low=float(low), high=float(high))
|
|
516
|
+
|
|
517
|
+
|
|
518
|
+
def _number(value: float | None) -> str:
|
|
519
|
+
return "-" if value is None or not math.isfinite(value) else f"{value:.4g}"
|
|
520
|
+
|
|
521
|
+
|
|
522
|
+
def _interval(interval: Interval | None) -> str:
|
|
523
|
+
return "-" if interval is None else f"[{interval.low:.3g}, {interval.high:.3g}]"
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: hone-python
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.13.0
|
|
4
4
|
Summary: A python-based optimization engine/library.
|
|
5
5
|
License-Expression: BSD-3-Clause
|
|
6
6
|
License-File: LICENSE
|
|
@@ -14,14 +14,19 @@ Classifier: Programming Language :: Python :: 3.14
|
|
|
14
14
|
Classifier: Programming Language :: Python :: 3.15
|
|
15
15
|
Requires-Dist: numpy (>=1.26.2)
|
|
16
16
|
Requires-Dist: pydantic (>=2.7,<3.0.0)
|
|
17
|
-
Requires-Dist: pyyaml (>=6.0.
|
|
17
|
+
Requires-Dist: pyyaml (>=6.0.3,<7.0.0)
|
|
18
18
|
Requires-Dist: scipy (>=1.13)
|
|
19
19
|
Requires-Dist: threadpoolctl (>=3.5)
|
|
20
|
+
Project-URL: Changelog, https://github.com/GreatEmuWar/hone/blob/main/CHANGELOG.md
|
|
21
|
+
Project-URL: Documentation, https://hone-python.dev/
|
|
22
|
+
Project-URL: Source, https://github.com/GreatEmuWar/hone
|
|
20
23
|
Description-Content-Type: text/markdown
|
|
21
24
|
|
|
22
25
|
# hone
|
|
23
26
|
Python-based optimization engine.
|
|
24
27
|
|
|
28
|
+
Documentation: https://hone-python.dev/
|
|
29
|
+
|
|
25
30
|
## Install
|
|
26
31
|
|
|
27
32
|
```
|
|
@@ -377,6 +382,34 @@ Everything else works as with one objective: constraints, conditions, workers an
|
|
|
377
382
|
|
|
378
383
|
[examples/cantilever_beam.py](examples/cantilever_beam.py) designs a beam in steel, aluminium or carbon fibre that is light, cheap and stiff, three objectives, under a stress limit that depends on the material, and chooses the stiffest design under a mass and a cost limit. Tuning for more than three objectives is out of scope for now: with many objectives nearly every design is on the front, and the search loses its pull.
|
|
379
384
|
|
|
385
|
+
### Which parameters matter
|
|
386
|
+
|
|
387
|
+
Before optimizing a dozen parameters, it can pay to find out which of them matter. `sensitivity()` evaluates the objective at points chosen to measure each parameter's effect, through the same `workers`, `timeout` and failure handling as `optimize()`, and reports them most important first:
|
|
388
|
+
|
|
389
|
+
```python
|
|
390
|
+
from hone import choose_optimizer, sensitivity
|
|
391
|
+
|
|
392
|
+
report = sensitivity(run_simulation, search_space, max_evaluations=500, workers=8, seed=0)
|
|
393
|
+
print(report)
|
|
394
|
+
reduced = report.reduced(search_space) # the unimportant parameters fixed
|
|
395
|
+
result = choose_optimizer(reduced, max_evaluations=200).optimize(run_simulation, workers=8)
|
|
396
|
+
```
|
|
397
|
+
|
|
398
|
+
How it measures depends on the budget:
|
|
399
|
+
|
|
400
|
+
| Method | Evaluations | Reports |
|
|
401
|
+
| --- | --- | --- |
|
|
402
|
+
| Morris screening | About 10 × (parameters + 1), at least 2 × (parameters + 1) | `mu_star`, the mean size of each parameter's effect: the change in the objective across its whole range. `mu` is the mean with its sign, and `sigma` large against `mu_star` means the effect depends on the other parameters |
|
|
403
|
+
| Sobol indices | 64 × (parameters + 2) or more, in powers of 2 | `total`, the share of the objective's variance the parameter accounts for with its interactions, and `first`, the share it accounts for alone. A `total` near 0 means the parameter can be fixed with little effect |
|
|
404
|
+
|
|
405
|
+
Without `method=`, Sobol is used when at least 64 × (parameters + 2) evaluations fit in `max_evaluations`, and Morris otherwise. Each index comes with a 95% bootstrap interval. `report.ranking` lists the names, most important first, `report["fillet"]` gives one parameter, and `report.best_params` is the best point evaluated (`maximize=True` for the highest).
|
|
406
|
+
|
|
407
|
+
`report.reduced(search_space)` returns the search space with the parameters `report.unimportant()` names fixed: those whose whole interval is below 0.05 for Sobol, or a tenth of the largest `mu_star` for Morris. `threshold=` changes that, and `keep=4` keeps the four most important instead. A fixed parameter is still passed to the objective, at its value in the best point evaluated unless `at={...}` gives one. A parameter can barely change the objective and still have a best value, so fixing it can cost a little; fix one you know the best value of with `at=`.
|
|
408
|
+
|
|
409
|
+
Every kind of parameter is measured on the scale the optimizers search it on: a log range in its logarithm, an integer range rounded, and a choice parameter among its choices. A conditional parameter is passed only while switched on, so its indices include the points where it has no effect. Search spaces with constraints aren't supported yet.
|
|
410
|
+
|
|
411
|
+
[examples/heat_sink.py](examples/heat_sink.py) finds which of a heat sink's eight settings drive a chip's temperature, fixes the four that don't, and on a budget of 60 evaluations finds a cooler design than a search over all eight.
|
|
412
|
+
|
|
380
413
|
### Benchmarks
|
|
381
414
|
|
|
382
415
|
`hone.benchmarks` runs optimizers on test problems with known optima and reports how close each one gets:
|
|
@@ -434,6 +467,8 @@ Requires Python 3.12 or later and [Poetry](https://python-poetry.org/) 2.
|
|
|
434
467
|
| --- | --- |
|
|
435
468
|
| `make test` | Install the dependencies and run the tests with coverage |
|
|
436
469
|
| `make lint` | Run ruff, then mypy to check types |
|
|
470
|
+
| `make docs` | Serve the documentation site at http://127.0.0.1:8000, rebuilding as files change (see [Docs](#docs)) |
|
|
471
|
+
| `make docs-build` | Build the documentation site into `site/`, failing on any warning, as CI does |
|
|
437
472
|
| `make docker-test` | Build the Docker image and run the tests inside it (see [Running in Docker](#running-in-docker)) |
|
|
438
473
|
| `make benchmark` | Run the full benchmark suite and update `benchmarks/results.md` |
|
|
439
474
|
| `make benchmark-noisy` | Run the noisy problems and update `benchmarks/noisy-results.md` |
|
|
@@ -442,6 +477,20 @@ Requires Python 3.12 or later and [Poetry](https://python-poetry.org/) 2.
|
|
|
442
477
|
| `make benchmark-conditional` | Run the conditional problems and update `benchmarks/conditional-results.md` |
|
|
443
478
|
| `make benchmark-multi` | Run the multi-objective problems and update `benchmarks/multi-results.md` |
|
|
444
479
|
|
|
480
|
+
### Docs
|
|
481
|
+
|
|
482
|
+
The documentation site is built with [MkDocs Material](https://squidfunk.github.io/mkdocs-material/) from `mkdocs.yml` and the pages in `docs/`. Most pages hold no text of their own: a line such as `<!-- include README.md#constraints level=2 -->` pulls in a section of this README, and others pull in `CHANGELOG.md`, the benchmark results and the examples, so each is written once. `docs/hooks.py` does the including and points links at the site's own pages. The API reference is generated from docstrings by mkdocstrings; a config field is documented by a docstring on the line after it. `docs/design/` holds design notes and isn't published.
|
|
483
|
+
|
|
484
|
+
On every push to `main`, CI builds the site and publishes it to the `gh-pages` branch with [mike](https://github.com/jimporter/mike), as the version `latest`, which GitHub Pages serves at https://hone-python.dev. The repository's Pages settings publish from the `gh-pages` branch with `hone-python.dev` as the custom domain, which GitHub keeps in a `CNAME` file on that branch; mike leaves it in place when it deploys. The domain's DNS is at Cloudflare.
|
|
485
|
+
|
|
486
|
+
Only `latest` is kept for now. To keep the docs of each release once that's needed:
|
|
487
|
+
|
|
488
|
+
1. Add `extra: {version: {provider: mike}}` to `mkdocs.yml`, for the version menu.
|
|
489
|
+
2. Change the deploy step to publish each release as its own version, with `latest` as an alias: `mike deploy --update-aliases 0.13 latest`, run when a version is released.
|
|
490
|
+
3. The first time, run `mike delete latest` just before that deploy, in the same job, since a version and an alias can't share a name.
|
|
491
|
+
|
|
492
|
+
Links to `/latest/...` keep working throughout, now pointing at the newest release.
|
|
493
|
+
|
|
445
494
|
### Running in Docker
|
|
446
495
|
|
|
447
496
|
With [Docker](https://docs.docker.com/get-docker/) installed you can run hone without Python or Poetry on your machine. The image holds hone with its development dependencies, the tests, the examples and the saved benchmark summaries, on Python 3.14.
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
hone/__init__.py,sha256=
|
|
1
|
+
hone/__init__.py,sha256=gO_LL5VPdE1BMl2k2dp1VrlfYQqvqT5rhwvDxT3ppPs,1898
|
|
2
2
|
hone/benchmarks/__init__.py,sha256=dYjoSBrYSWcCCpk4w4uF_KqcQYbF7JyfpfOTZHLhg9o,608
|
|
3
3
|
hone/benchmarks/__main__.py,sha256=1-rzY3ZxmPQ8OZDxCQ1u7Y2IARiF3_cBfj-G4Gl89wc,5711
|
|
4
4
|
hone/benchmarks/conditional.py,sha256=m1Q_UQ_qUVbpOwaabxSWKjBQszCoWV_yJWfq-q9E3ko,5031
|
|
@@ -8,11 +8,11 @@ hone/benchmarks/multi.py,sha256=bAVnby_s_tNx-UmmAPI7-Qso0_rr-4Wbss42QSzStJQ,1982
|
|
|
8
8
|
hone/benchmarks/problems.py,sha256=Qi00Myt13ORzqxXq-ia-GLRmDIprkcm4J5uqufNx0Ug,9043
|
|
9
9
|
hone/benchmarks/runner.py,sha256=yURYCnSFKhwWvd1gZGv2yW1j8qPbKMDHcumJ1KwvpAU,12614
|
|
10
10
|
hone/config/__init__.py,sha256=uDzN8ETsACdf1orkV0SZFxj9gsHp3YJ_Ejryz_iqE4o,306
|
|
11
|
-
hone/config/bayesian_config.py,sha256=
|
|
12
|
-
hone/config/cmaes_config.py,sha256=
|
|
13
|
-
hone/config/genetic_optimizer_config.py,sha256=
|
|
14
|
-
hone/config/multi_objective_config.py,sha256=
|
|
15
|
-
hone/config/optimizer_config.py,sha256=
|
|
11
|
+
hone/config/bayesian_config.py,sha256=xCLF9R1RokiV7P_5RB8BFTJIfXvO65N7qUc9GM5scVQ,1193
|
|
12
|
+
hone/config/cmaes_config.py,sha256=hBFcxC4JtYNH6eyGiht1ie_XhvetLzkWJO3pCPUAIMw,768
|
|
13
|
+
hone/config/genetic_optimizer_config.py,sha256=bxHHH2hULp0gHSeTGcISdSgDaGLLsVKHKayDqN10LMM,4034
|
|
14
|
+
hone/config/multi_objective_config.py,sha256=bjLNVZHmj5kl6BLCemcOIQiHV_rDIi3s1w96Yi04ncY,5057
|
|
15
|
+
hone/config/optimizer_config.py,sha256=8DbpLm-SxoGix-uArHL2TBvwtt6SYrhI4iYlQVC061w,2777
|
|
16
16
|
hone/objective_function/__init__.py,sha256=OiMpuLasgVIwPVBiOIbL5neuKPftUKl2jRA8Ba9n4hI,49
|
|
17
17
|
hone/objective_function/objective_function.py,sha256=t6BI7A2tfZe2l9J99wCg_nAzK7VfSkUpb2mmd6O99zk,3058
|
|
18
18
|
hone/optimizers/__init__.py,sha256=VQWVkwKPxdxSj1_Xus-A2P8Oy-u7aPapjW6EwxF5LSw,423
|
|
@@ -39,7 +39,8 @@ hone/parameters/parameters.py,sha256=b6m9PlJtIYGvrJeLv4tktX-wa6ksPqbJOeJULXGlWBQ
|
|
|
39
39
|
hone/pareto.py,sha256=IFfvd5idY1ZFyXi_SnqhNFex5-B3B0Xc-BHDX0YLZRE,12452
|
|
40
40
|
hone/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
|
|
41
41
|
hone/result.py,sha256=-x3OGPC95nyTPsnbUqI6LSjC5rp0fIL-VBPRMkbRALc,5923
|
|
42
|
-
|
|
43
|
-
hone_python-0.
|
|
44
|
-
hone_python-0.
|
|
45
|
-
hone_python-0.
|
|
42
|
+
hone/sensitivity_analysis.py,sha256=OYsRSL04kOrIp2cSAbpJIUm7vx4z56_OmOkVtKKjTTg,25026
|
|
43
|
+
hone_python-0.13.0.dist-info/METADATA,sha256=-dzyd1OuXV091RYjh1A1UR7Sm3HMjAgThyPnUm5qbYE,41307
|
|
44
|
+
hone_python-0.13.0.dist-info/WHEEL,sha256=L-WvLdSBvJWHXv5zrQxDvNRnIgoBzLUpcbuiw19KCuQ,88
|
|
45
|
+
hone_python-0.13.0.dist-info/licenses/LICENSE,sha256=M0sVPvCyGe4r-7bmB9znW4yTKe2joCIdF3tq0ht9vb4,1503
|
|
46
|
+
hone_python-0.13.0.dist-info/RECORD,,
|
|
File without changes
|
|
File without changes
|