From 906b6c1aa55ba76e48160088c72beb7928471a22 Mon Sep 17 00:00:00 2001 From: Jerry Lin Date: Wed, 5 Feb 2025 18:49:35 -0800 Subject: [PATCH] Migrate GS usages to new module location (#3311) Summary: X-link: https://github.com/facebookresearch/aepsych/pull/623 Pull Request resolved: https://github.com/facebook/Ax/pull/3311 Removing the following old files from `ax/modelbridge/` in favor of the new `ax/generation_strategy` directory. ``` best_model_selector.py dispatch_utils.py external_generation_node.py generation_node_input_constructors.py generation_node.py generation_strategy.py model_spec.py transition_criterion.py ``` Reviewed By: saitcakmak Differential Revision: D68645075 --- .../healthcheck/constraints_feasibility.py | 2 +- .../tests/test_constraints_feasibility.py | 6 +- .../plotly/arm_effects/insample_effects.py | 2 +- .../plotly/arm_effects/predicted_effects.py | 2 +- ax/analysis/plotly/cross_validation.py | 2 +- ax/analysis/plotly/surface/contour.py | 2 +- ax/analysis/plotly/surface/slice.py | 2 +- .../plotly/tests/test_predicted_effects.py | 2 +- ax/benchmark/benchmark_method.py | 2 +- ax/benchmark/methods/modular_botorch.py | 4 +- ax/benchmark/methods/sobol.py | 5 +- ax/benchmark/tests/test_benchmark.py | 9 +- .../tests/test_aepsych_criterion.py | 10 +- .../tests/test_best_model_selector.py | 4 +- .../tests/test_dispatch_utils.py | 2 +- .../tests/test_external_generation_node.py | 4 +- .../tests/test_generation_node.py | 15 +- ...test_generation_node_input_constructors.py | 8 +- .../tests/test_generation_strategy.py | 27 +- .../tests/test_model_spec.py | 5 +- .../tests/test_transition_criterion.py | 8 +- .../tests/test_model_fit_metrics.py | 5 +- ax/preview/api/client.py | 2 +- ax/preview/modelbridge/dispatch_utils.py | 9 +- ...tils.py => test_preview_dispatch_utils.py} | 2 +- ax/runners/tests/test_torchx.py | 3 +- ax/service/ax_client.py | 4 +- ax/service/managed_loop.py | 4 +- ax/service/scheduler.py | 2 +- ax/service/tests/scheduler_test_utils.py | 7 +- ax/service/tests/test_ax_client.py | 10 +- ax/service/tests/test_interactive_loop.py | 5 +- ax/service/tests/test_managed_loop.py | 5 +- ax/service/tests/test_report_utils.py | 4 +- ax/service/tests/test_scheduler.py | 7 +- .../tests/test_with_db_settings_base.py | 2 +- ax/service/utils/best_point.py | 2 +- ax/service/utils/best_point_mixin.py | 2 +- ax/service/utils/report_utils.py | 2 +- ax/service/utils/with_db_settings_base.py | 2 +- ax/storage/json_store/decoder.py | 12 +- ax/storage/json_store/encoders.py | 16 +- ax/storage/json_store/registry.py | 36 +- .../json_store/tests/test_json_store.py | 4 +- ax/storage/sqa_store/decoder.py | 2 +- ax/storage/sqa_store/delete.py | 2 +- ax/storage/sqa_store/encoder.py | 2 +- ax/storage/sqa_store/load.py | 2 +- ax/storage/sqa_store/save.py | 2 +- ax/storage/sqa_store/sqa_config.py | 2 +- ax/storage/sqa_store/tests/test_sqa_store.py | 2 +- ax/utils/testing/benchmark_stubs.py | 4 +- ax/utils/testing/core_stubs.py | 25 +- ax/utils/testing/modeling_stubs.py | 31 +- ax/utils/testing/tests/test_utils.py | 7 +- ax/utils/testing/utils.py | 2 +- docs/api.md | 2 +- docs/glossary.md | 2 +- sphinx/source/generation_strategy.rst | 2 +- tutorials/early_stopping/early_stopping.ipynb | 9 +- .../external_generation_node.ipynb | 810 +++-- .../generation_strategy.ipynb | 929 +++--- tutorials/modular_botax/modular_botax.ipynb | 2825 +++++++++-------- tutorials/scheduler/scheduler.ipynb | 1849 +++++------ tutorials/sebo/sebo.ipynb | 1286 ++++---- 65 files changed, 4061 insertions(+), 4006 deletions(-) rename ax/{modelbridge => generation_strategy}/tests/test_aepsych_criterion.py (96%) rename ax/{modelbridge => generation_strategy}/tests/test_best_model_selector.py (97%) rename ax/{modelbridge => generation_strategy}/tests/test_dispatch_utils.py (99%) rename ax/{modelbridge => generation_strategy}/tests/test_external_generation_node.py (96%) rename ax/{modelbridge => generation_strategy}/tests/test_generation_node.py (97%) rename ax/{modelbridge => generation_strategy}/tests/test_generation_node_input_constructors.py (98%) rename ax/{modelbridge => generation_strategy}/tests/test_generation_strategy.py (99%) rename ax/{modelbridge => generation_strategy}/tests/test_model_spec.py (98%) rename ax/{modelbridge => generation_strategy}/tests/test_transition_criterion.py (99%) rename ax/preview/modelbridge/tests/{test_dispatch_utils.py => test_preview_dispatch_utils.py} (99%) diff --git a/ax/analysis/healthcheck/constraints_feasibility.py b/ax/analysis/healthcheck/constraints_feasibility.py index 61b050ecd1f..552a0843aaa 100644 --- a/ax/analysis/healthcheck/constraints_feasibility.py +++ b/ax/analysis/healthcheck/constraints_feasibility.py @@ -23,8 +23,8 @@ from ax.core.generation_strategy_interface import GenerationStrategyInterface from ax.core.optimization_config import OptimizationConfig from ax.exceptions.core import UserInputError +from ax.generation_strategy.generation_strategy import GenerationStrategy from ax.modelbridge.base import Adapter -from ax.modelbridge.generation_strategy import GenerationStrategy from ax.modelbridge.transforms.derelativize import Derelativize from pyre_extensions import assert_is_instance, none_throws diff --git a/ax/analysis/healthcheck/tests/test_constraints_feasibility.py b/ax/analysis/healthcheck/tests/test_constraints_feasibility.py index a6e95609685..92067cca5ac 100644 --- a/ax/analysis/healthcheck/tests/test_constraints_feasibility.py +++ b/ax/analysis/healthcheck/tests/test_constraints_feasibility.py @@ -23,10 +23,10 @@ from ax.core.objective import Objective from ax.core.optimization_config import OptimizationConfig from ax.exceptions.core import UserInputError +from ax.generation_strategy.generation_node import GenerationNode +from ax.generation_strategy.generation_strategy import GenerationStrategy +from ax.generation_strategy.model_spec import GeneratorSpec from ax.modelbridge.factory import get_sobol -from ax.modelbridge.generation_node import GenerationNode -from ax.modelbridge.generation_strategy import GenerationStrategy -from ax.modelbridge.model_spec import GeneratorSpec from ax.modelbridge.registry import Generators from ax.utils.common.testutils import TestCase from ax.utils.testing.core_stubs import ( diff --git a/ax/analysis/plotly/arm_effects/insample_effects.py b/ax/analysis/plotly/arm_effects/insample_effects.py index b556ec6a22d..666b6ba9a78 100644 --- a/ax/analysis/plotly/arm_effects/insample_effects.py +++ b/ax/analysis/plotly/arm_effects/insample_effects.py @@ -22,8 +22,8 @@ from ax.core.generator_run import GeneratorRun from ax.core.outcome_constraint import OutcomeConstraint from ax.exceptions.core import DataRequiredError, UserInputError +from ax.generation_strategy.generation_strategy import GenerationStrategy from ax.modelbridge.base import Adapter -from ax.modelbridge.generation_strategy import GenerationStrategy from ax.modelbridge.registry import Generators from ax.modelbridge.transforms.derelativize import Derelativize from ax.utils.common.logger import get_logger diff --git a/ax/analysis/plotly/arm_effects/predicted_effects.py b/ax/analysis/plotly/arm_effects/predicted_effects.py index 75155257dc6..4e04e4e32e8 100644 --- a/ax/analysis/plotly/arm_effects/predicted_effects.py +++ b/ax/analysis/plotly/arm_effects/predicted_effects.py @@ -23,8 +23,8 @@ from ax.core.experiment import Experiment from ax.core.generation_strategy_interface import GenerationStrategyInterface from ax.exceptions.core import UserInputError +from ax.generation_strategy.generation_strategy import GenerationStrategy from ax.modelbridge.base import Adapter -from ax.modelbridge.generation_strategy import GenerationStrategy from ax.modelbridge.transforms.derelativize import Derelativize from pyre_extensions import assert_is_instance, none_throws diff --git a/ax/analysis/plotly/cross_validation.py b/ax/analysis/plotly/cross_validation.py index 08a7cfdf5f8..f210dd1f438 100644 --- a/ax/analysis/plotly/cross_validation.py +++ b/ax/analysis/plotly/cross_validation.py @@ -14,8 +14,8 @@ from ax.core.experiment import Experiment from ax.core.generation_strategy_interface import GenerationStrategyInterface from ax.exceptions.core import UserInputError +from ax.generation_strategy.generation_strategy import GenerationStrategy from ax.modelbridge.cross_validation import cross_validate -from ax.modelbridge.generation_strategy import GenerationStrategy from plotly import express as px, graph_objects as go from pyre_extensions import assert_is_instance, none_throws diff --git a/ax/analysis/plotly/surface/contour.py b/ax/analysis/plotly/surface/contour.py index 3ce17133302..47139c0ac56 100644 --- a/ax/analysis/plotly/surface/contour.py +++ b/ax/analysis/plotly/surface/contour.py @@ -22,8 +22,8 @@ from ax.core.generation_strategy_interface import GenerationStrategyInterface from ax.core.observation import ObservationFeatures from ax.exceptions.core import UserInputError +from ax.generation_strategy.generation_strategy import GenerationStrategy from ax.modelbridge.base import Adapter -from ax.modelbridge.generation_strategy import GenerationStrategy from plotly import graph_objects as go from pyre_extensions import none_throws diff --git a/ax/analysis/plotly/surface/slice.py b/ax/analysis/plotly/surface/slice.py index 282c19c7c26..b031b022a94 100644 --- a/ax/analysis/plotly/surface/slice.py +++ b/ax/analysis/plotly/surface/slice.py @@ -22,8 +22,8 @@ from ax.core.generation_strategy_interface import GenerationStrategyInterface from ax.core.observation import ObservationFeatures from ax.exceptions.core import UserInputError +from ax.generation_strategy.generation_strategy import GenerationStrategy from ax.modelbridge.base import Adapter -from ax.modelbridge.generation_strategy import GenerationStrategy from plotly import express as px, graph_objects as go from pyre_extensions import none_throws diff --git a/ax/analysis/plotly/tests/test_predicted_effects.py b/ax/analysis/plotly/tests/test_predicted_effects.py index 862274a3003..da402240e67 100644 --- a/ax/analysis/plotly/tests/test_predicted_effects.py +++ b/ax/analysis/plotly/tests/test_predicted_effects.py @@ -15,7 +15,7 @@ from ax.core.observation import ObservationFeatures from ax.core.trial import Trial from ax.exceptions.core import UserInputError -from ax.modelbridge.dispatch_utils import choose_generation_strategy +from ax.generation_strategy.dispatch_utils import choose_generation_strategy from ax.modelbridge.prediction_utils import predict_at_point from ax.modelbridge.registry import Generators from ax.utils.common.testutils import TestCase diff --git a/ax/benchmark/benchmark_method.py b/ax/benchmark/benchmark_method.py index 767a49322e0..a00993b6b02 100644 --- a/ax/benchmark/benchmark_method.py +++ b/ax/benchmark/benchmark_method.py @@ -15,7 +15,7 @@ from ax.core.types import TParameterization from ax.early_stopping.strategies.base import BaseEarlyStoppingStrategy -from ax.modelbridge.generation_strategy import GenerationStrategy +from ax.generation_strategy.generation_strategy import GenerationStrategy from ax.service.utils.best_point_mixin import BestPointMixin from ax.utils.common.base import Base from pyre_extensions import none_throws diff --git a/ax/benchmark/methods/modular_botorch.py b/ax/benchmark/methods/modular_botorch.py index 693927fcee5..1e21665b27a 100644 --- a/ax/benchmark/methods/modular_botorch.py +++ b/ax/benchmark/methods/modular_botorch.py @@ -8,8 +8,8 @@ from typing import Any from ax.benchmark.benchmark_method import BenchmarkMethod -from ax.modelbridge.generation_node import GenerationStep -from ax.modelbridge.generation_strategy import GenerationStrategy +from ax.generation_strategy.generation_node import GenerationStep +from ax.generation_strategy.generation_strategy import GenerationStrategy from ax.modelbridge.registry import Generators from ax.models.torch.botorch_modular.surrogate import SurrogateSpec from botorch.acquisition.acquisition import AcquisitionFunction diff --git a/ax/benchmark/methods/sobol.py b/ax/benchmark/methods/sobol.py index 666cccceecd..05a1d8fa66d 100644 --- a/ax/benchmark/methods/sobol.py +++ b/ax/benchmark/methods/sobol.py @@ -7,7 +7,10 @@ from ax.benchmark.benchmark_method import BenchmarkMethod -from ax.modelbridge.generation_strategy import GenerationStep, GenerationStrategy +from ax.generation_strategy.generation_strategy import ( + GenerationStep, + GenerationStrategy, +) from ax.modelbridge.registry import Generators diff --git a/ax/benchmark/tests/test_benchmark.py b/ax/benchmark/tests/test_benchmark.py index 4f744976ea5..8f55c5bc1a8 100644 --- a/ax/benchmark/tests/test_benchmark.py +++ b/ax/benchmark/tests/test_benchmark.py @@ -47,9 +47,12 @@ from ax.core.parameter import ChoiceParameter, ParameterType, RangeParameter from ax.core.search_space import SearchSpace from ax.early_stopping.strategies.threshold import ThresholdEarlyStoppingStrategy -from ax.modelbridge.external_generation_node import ExternalGenerationNode -from ax.modelbridge.generation_strategy import GenerationNode, GenerationStrategy -from ax.modelbridge.model_spec import GeneratorSpec +from ax.generation_strategy.external_generation_node import ExternalGenerationNode +from ax.generation_strategy.generation_strategy import ( + GenerationNode, + GenerationStrategy, +) +from ax.generation_strategy.model_spec import GeneratorSpec from ax.modelbridge.registry import Generators from ax.service.utils.scheduler_options import TrialType from ax.storage.json_store.load import load_experiment diff --git a/ax/modelbridge/tests/test_aepsych_criterion.py b/ax/generation_strategy/tests/test_aepsych_criterion.py similarity index 96% rename from ax/modelbridge/tests/test_aepsych_criterion.py rename to ax/generation_strategy/tests/test_aepsych_criterion.py index 0d7e9f584c9..6d488fa3615 100644 --- a/ax/modelbridge/tests/test_aepsych_criterion.py +++ b/ax/generation_strategy/tests/test_aepsych_criterion.py @@ -10,9 +10,15 @@ import pandas as pd from ax.core.base_trial import TrialStatus from ax.core.data import Data -from ax.modelbridge.generation_strategy import GenerationStep, GenerationStrategy +from ax.generation_strategy.generation_strategy import ( + GenerationStep, + GenerationStrategy, +) +from ax.generation_strategy.transition_criterion import ( + MinimumPreferenceOccurances, + MinTrials, +) from ax.modelbridge.registry import Generators -from ax.modelbridge.transition_criterion import MinimumPreferenceOccurances, MinTrials from ax.utils.common.testutils import TestCase from ax.utils.testing.core_stubs import get_experiment diff --git a/ax/modelbridge/tests/test_best_model_selector.py b/ax/generation_strategy/tests/test_best_model_selector.py similarity index 97% rename from ax/modelbridge/tests/test_best_model_selector.py rename to ax/generation_strategy/tests/test_best_model_selector.py index 6247058a7b3..30aee768195 100644 --- a/ax/modelbridge/tests/test_best_model_selector.py +++ b/ax/generation_strategy/tests/test_best_model_selector.py @@ -9,11 +9,11 @@ from unittest.mock import Mock, patch from ax.exceptions.core import UserInputError -from ax.modelbridge.best_model_selector import ( +from ax.generation_strategy.best_model_selector import ( ReductionCriterion, SingleDiagnosticBestModelSelector, ) -from ax.modelbridge.model_spec import GeneratorSpec +from ax.generation_strategy.model_spec import GeneratorSpec from ax.modelbridge.registry import Generators from ax.utils.common.testutils import TestCase diff --git a/ax/modelbridge/tests/test_dispatch_utils.py b/ax/generation_strategy/tests/test_dispatch_utils.py similarity index 99% rename from ax/modelbridge/tests/test_dispatch_utils.py rename to ax/generation_strategy/tests/test_dispatch_utils.py index 4792ea96004..b77d12f3db9 100644 --- a/ax/modelbridge/tests/test_dispatch_utils.py +++ b/ax/generation_strategy/tests/test_dispatch_utils.py @@ -13,7 +13,7 @@ import torch from ax.core.objective import MultiObjective from ax.core.optimization_config import MultiObjectiveOptimizationConfig -from ax.modelbridge.dispatch_utils import ( +from ax.generation_strategy.dispatch_utils import ( _make_botorch_step, calculate_num_initialization_trials, choose_generation_strategy, diff --git a/ax/modelbridge/tests/test_external_generation_node.py b/ax/generation_strategy/tests/test_external_generation_node.py similarity index 96% rename from ax/modelbridge/tests/test_external_generation_node.py rename to ax/generation_strategy/tests/test_external_generation_node.py index caadf25475e..7b188d57073 100644 --- a/ax/modelbridge/tests/test_external_generation_node.py +++ b/ax/generation_strategy/tests/test_external_generation_node.py @@ -14,8 +14,8 @@ from ax.core.observation import ObservationFeatures from ax.core.types import TParameterization from ax.exceptions.core import UnsupportedError -from ax.modelbridge.external_generation_node import ExternalGenerationNode -from ax.modelbridge.generation_strategy import GenerationStrategy +from ax.generation_strategy.external_generation_node import ExternalGenerationNode +from ax.generation_strategy.generation_strategy import GenerationStrategy from ax.modelbridge.random import RandomAdapter from ax.utils.common.testutils import TestCase from ax.utils.testing.core_stubs import ( diff --git a/ax/modelbridge/tests/test_generation_node.py b/ax/generation_strategy/tests/test_generation_node.py similarity index 97% rename from ax/modelbridge/tests/test_generation_node.py rename to ax/generation_strategy/tests/test_generation_node.py index ccbb702ba70..3be75b01ffb 100644 --- a/ax/modelbridge/tests/test_generation_node.py +++ b/ax/generation_strategy/tests/test_generation_node.py @@ -14,23 +14,26 @@ from ax.core.base_trial import TrialStatus from ax.core.observation import ObservationFeatures from ax.exceptions.core import UserInputError -from ax.modelbridge.best_model_selector import ( +from ax.generation_strategy.best_model_selector import ( ReductionCriterion, SingleDiagnosticBestModelSelector, ) -from ax.modelbridge.factory import get_sobol -from ax.modelbridge.generation_node import ( +from ax.generation_strategy.generation_node import ( GenerationNode, GenerationStep, MISSING_MODEL_SELECTOR_MESSAGE, ) -from ax.modelbridge.generation_node_input_constructors import ( +from ax.generation_strategy.generation_node_input_constructors import ( InputConstructorPurpose, NodeInputConstructors, ) -from ax.modelbridge.model_spec import FactoryFunctionGeneratorSpec, GeneratorSpec +from ax.generation_strategy.model_spec import ( + FactoryFunctionGeneratorSpec, + GeneratorSpec, +) +from ax.generation_strategy.transition_criterion import MinTrials +from ax.modelbridge.factory import get_sobol from ax.modelbridge.registry import Generators -from ax.modelbridge.transition_criterion import MinTrials from ax.utils.common.constants import Keys from ax.utils.common.logger import get_logger from ax.utils.common.testutils import TestCase diff --git a/ax/modelbridge/tests/test_generation_node_input_constructors.py b/ax/generation_strategy/tests/test_generation_node_input_constructors.py similarity index 98% rename from ax/modelbridge/tests/test_generation_node_input_constructors.py rename to ax/generation_strategy/tests/test_generation_node_input_constructors.py index de6164870f2..1a55c284e17 100644 --- a/ax/modelbridge/tests/test_generation_node_input_constructors.py +++ b/ax/generation_strategy/tests/test_generation_node_input_constructors.py @@ -16,13 +16,13 @@ from ax.core.generator_run import GeneratorRun from ax.core.observation import ObservationFeatures from ax.exceptions.generation_strategy import AxGenerationException -from ax.modelbridge.generation_node import GenerationNode -from ax.modelbridge.generation_node_input_constructors import ( +from ax.generation_strategy.generation_node import GenerationNode +from ax.generation_strategy.generation_node_input_constructors import ( InputConstructorPurpose, NodeInputConstructors, ) -from ax.modelbridge.generation_strategy import GenerationStrategy -from ax.modelbridge.model_spec import GeneratorSpec +from ax.generation_strategy.generation_strategy import GenerationStrategy +from ax.generation_strategy.model_spec import GeneratorSpec from ax.modelbridge.registry import Generators from ax.utils.common.constants import Keys from ax.utils.common.testutils import TestCase diff --git a/ax/modelbridge/tests/test_generation_strategy.py b/ax/generation_strategy/tests/test_generation_strategy.py similarity index 99% rename from ax/modelbridge/tests/test_generation_strategy.py rename to ax/generation_strategy/tests/test_generation_strategy.py index a61199028ad..3ef13f543f0 100644 --- a/ax/modelbridge/tests/test_generation_strategy.py +++ b/ax/generation_strategy/tests/test_generation_strategy.py @@ -29,16 +29,24 @@ GenerationStrategyRepeatedPoints, MaxParallelismReachedException, ) -from ax.modelbridge.best_model_selector import SingleDiagnosticBestModelSelector -from ax.modelbridge.discrete import DiscreteAdapter -from ax.modelbridge.factory import get_sobol -from ax.modelbridge.generation_node import GenerationNode -from ax.modelbridge.generation_node_input_constructors import ( +from ax.generation_strategy.best_model_selector import SingleDiagnosticBestModelSelector +from ax.generation_strategy.generation_node import GenerationNode +from ax.generation_strategy.generation_node_input_constructors import ( InputConstructorPurpose, NodeInputConstructors, ) -from ax.modelbridge.generation_strategy import GenerationStep, GenerationStrategy -from ax.modelbridge.model_spec import GeneratorSpec +from ax.generation_strategy.generation_strategy import ( + GenerationStep, + GenerationStrategy, +) +from ax.generation_strategy.model_spec import GeneratorSpec +from ax.generation_strategy.transition_criterion import ( + AutoTransitionAfterGen, + MaxGenerationParallelism, + MinTrials, +) +from ax.modelbridge.discrete import DiscreteAdapter +from ax.modelbridge.factory import get_sobol from ax.modelbridge.random import RandomAdapter from ax.modelbridge.registry import ( _extract_model_state_after_gen, @@ -48,11 +56,6 @@ MODEL_KEY_TO_MODEL_SETUP, ) from ax.modelbridge.torch import TorchAdapter -from ax.modelbridge.transition_criterion import ( - AutoTransitionAfterGen, - MaxGenerationParallelism, - MinTrials, -) from ax.models.random.sobol import SobolGenerator from ax.utils.common.constants import Keys from ax.utils.common.equality import same_elements diff --git a/ax/modelbridge/tests/test_model_spec.py b/ax/generation_strategy/tests/test_model_spec.py similarity index 98% rename from ax/modelbridge/tests/test_model_spec.py rename to ax/generation_strategy/tests/test_model_spec.py index 15911344919..8278aaced60 100644 --- a/ax/modelbridge/tests/test_model_spec.py +++ b/ax/generation_strategy/tests/test_model_spec.py @@ -12,8 +12,11 @@ from ax.core.observation import ObservationFeatures from ax.exceptions.core import UserInputError +from ax.generation_strategy.model_spec import ( + FactoryFunctionGeneratorSpec, + GeneratorSpec, +) from ax.modelbridge.factory import get_sobol -from ax.modelbridge.model_spec import FactoryFunctionGeneratorSpec, GeneratorSpec from ax.modelbridge.modelbridge_utils import extract_search_space_digest from ax.modelbridge.registry import Generators from ax.utils.common.testutils import TestCase diff --git a/ax/modelbridge/tests/test_transition_criterion.py b/ax/generation_strategy/tests/test_transition_criterion.py similarity index 99% rename from ax/modelbridge/tests/test_transition_criterion.py rename to ax/generation_strategy/tests/test_transition_criterion.py index 92b0709143e..a62a7fb9d03 100644 --- a/ax/modelbridge/tests/test_transition_criterion.py +++ b/ax/generation_strategy/tests/test_transition_criterion.py @@ -15,14 +15,13 @@ from ax.core.base_trial import TrialStatus from ax.core.data import Data from ax.exceptions.core import UserInputError -from ax.modelbridge.generation_strategy import ( +from ax.generation_strategy.generation_strategy import ( GenerationNode, GenerationStep, GenerationStrategy, ) -from ax.modelbridge.model_spec import GeneratorSpec -from ax.modelbridge.registry import Generators -from ax.modelbridge.transition_criterion import ( +from ax.generation_strategy.model_spec import GeneratorSpec +from ax.generation_strategy.transition_criterion import ( AutoTransitionAfterGen, AuxiliaryExperimentCheck, IsSingleObjective, @@ -32,6 +31,7 @@ MinimumTrialsInStatus, MinTrials, ) +from ax.modelbridge.registry import Generators from ax.utils.common.logger import get_logger from ax.utils.common.testutils import TestCase from ax.utils.testing.core_stubs import ( diff --git a/ax/modelbridge/tests/test_model_fit_metrics.py b/ax/modelbridge/tests/test_model_fit_metrics.py index c425bf925cc..659fd28e183 100644 --- a/ax/modelbridge/tests/test_model_fit_metrics.py +++ b/ax/modelbridge/tests/test_model_fit_metrics.py @@ -14,6 +14,10 @@ from ax.core.experiment import Experiment from ax.core.objective import Objective from ax.core.optimization_config import OptimizationConfig +from ax.generation_strategy.generation_strategy import ( + GenerationStep, + GenerationStrategy, +) from ax.metrics.branin import BraninMetric from ax.modelbridge.cross_validation import ( _predict_on_cross_validation_data, @@ -21,7 +25,6 @@ compute_model_fit_metrics_from_modelbridge, get_fit_and_std_quality_and_generalization_dict, ) -from ax.modelbridge.generation_strategy import GenerationStep, GenerationStrategy from ax.modelbridge.registry import Generators from ax.runners.synthetic import SyntheticRunner from ax.service.scheduler import get_fitted_model_bridge, Scheduler, SchedulerOptions diff --git a/ax/preview/api/client.py b/ax/preview/api/client.py index c53161377cd..f489a3664dc 100644 --- a/ax/preview/api/client.py +++ b/ax/preview/api/client.py @@ -34,7 +34,7 @@ PercentileEarlyStoppingStrategy, ) from ax.exceptions.core import ObjectNotFoundError, UnsupportedError -from ax.modelbridge.generation_strategy import GenerationStrategy +from ax.generation_strategy.generation_strategy import GenerationStrategy from ax.preview.api.configs import ( ExperimentConfig, GenerationStrategyConfig, diff --git a/ax/preview/modelbridge/dispatch_utils.py b/ax/preview/modelbridge/dispatch_utils.py index 47e743cd3ed..d7853290d64 100644 --- a/ax/preview/modelbridge/dispatch_utils.py +++ b/ax/preview/modelbridge/dispatch_utils.py @@ -9,10 +9,13 @@ import torch from ax.core.base_trial import TrialStatus from ax.exceptions.core import UnsupportedError -from ax.modelbridge.generation_strategy import GenerationNode, GenerationStrategy -from ax.modelbridge.model_spec import GeneratorSpec +from ax.generation_strategy.generation_strategy import ( + GenerationNode, + GenerationStrategy, +) +from ax.generation_strategy.model_spec import GeneratorSpec +from ax.generation_strategy.transition_criterion import MinTrials from ax.modelbridge.registry import Generators -from ax.modelbridge.transition_criterion import MinTrials from ax.models.torch.botorch_modular.surrogate import ModelConfig, SurrogateSpec from ax.preview.api.configs import GenerationMethod, GenerationStrategyConfig from botorch.models.transforms.input import Normalize, Warp diff --git a/ax/preview/modelbridge/tests/test_dispatch_utils.py b/ax/preview/modelbridge/tests/test_preview_dispatch_utils.py similarity index 99% rename from ax/preview/modelbridge/tests/test_dispatch_utils.py rename to ax/preview/modelbridge/tests/test_preview_dispatch_utils.py index fb13853d0a3..a655632580f 100644 --- a/ax/preview/modelbridge/tests/test_dispatch_utils.py +++ b/ax/preview/modelbridge/tests/test_preview_dispatch_utils.py @@ -8,8 +8,8 @@ import torch from ax.core.base_trial import TrialStatus from ax.core.trial import Trial +from ax.generation_strategy.transition_criterion import MinTrials from ax.modelbridge.registry import Generators -from ax.modelbridge.transition_criterion import MinTrials from ax.models.torch.botorch_modular.surrogate import ModelConfig, SurrogateSpec from ax.preview.api.configs import GenerationMethod, GenerationStrategyConfig from ax.preview.modelbridge.dispatch_utils import choose_generation_strategy diff --git a/ax/runners/tests/test_torchx.py b/ax/runners/tests/test_torchx.py index 9c38df614b1..00e8642e67b 100644 --- a/ax/runners/tests/test_torchx.py +++ b/ax/runners/tests/test_torchx.py @@ -20,8 +20,9 @@ RangeParameter, SearchSpace, ) + +from ax.generation_strategy.dispatch_utils import choose_generation_strategy from ax.metrics.torchx import TorchXMetric -from ax.modelbridge.dispatch_utils import choose_generation_strategy from ax.runners.torchx import TorchXRunner from ax.service.scheduler import FailureRateExceededError, Scheduler, SchedulerOptions from ax.utils.common.constants import Keys diff --git a/ax/service/ax_client.py b/ax/service/ax_client.py index 4821dd67cb1..76d92b5c221 100644 --- a/ax/service/ax_client.py +++ b/ax/service/ax_client.py @@ -56,10 +56,10 @@ UserInputError, ) from ax.exceptions.generation_strategy import MaxParallelismReachedException +from ax.generation_strategy.dispatch_utils import choose_generation_strategy +from ax.generation_strategy.generation_strategy import GenerationStrategy from ax.global_stopping.strategies.base import BaseGlobalStoppingStrategy from ax.global_stopping.strategies.improvement import constraint_satisfaction -from ax.modelbridge.dispatch_utils import choose_generation_strategy -from ax.modelbridge.generation_strategy import GenerationStrategy from ax.modelbridge.prediction_utils import predict_by_features from ax.plot.base import AxPlotConfig from ax.plot.contour import plot_contour diff --git a/ax/service/managed_loop.py b/ax/service/managed_loop.py index ee1f9733fe4..379f91c74ab 100644 --- a/ax/service/managed_loop.py +++ b/ax/service/managed_loop.py @@ -27,9 +27,9 @@ from ax.core.utils import get_pending_observation_features from ax.exceptions.constants import CHOLESKY_ERROR_ANNOTATION from ax.exceptions.core import SearchSpaceExhausted, UserInputError +from ax.generation_strategy.dispatch_utils import choose_generation_strategy +from ax.generation_strategy.generation_strategy import GenerationStrategy from ax.modelbridge.base import Adapter -from ax.modelbridge.dispatch_utils import choose_generation_strategy -from ax.modelbridge.generation_strategy import GenerationStrategy from ax.modelbridge.registry import Generators from ax.service.utils.best_point import ( get_best_parameters_from_model_predictions_with_trial_index, diff --git a/ax/service/scheduler.py b/ax/service/scheduler.py index df1fe924441..7e81c06ca46 100644 --- a/ax/service/scheduler.py +++ b/ax/service/scheduler.py @@ -48,8 +48,8 @@ MaxParallelismReachedException, OptimizationConfigRequired, ) +from ax.generation_strategy.generation_strategy import GenerationStrategy from ax.modelbridge.base import Adapter -from ax.modelbridge.generation_strategy import GenerationStrategy from ax.modelbridge.modelbridge_utils import get_fixed_features_from_experiment from ax.service.utils.analysis_base import AnalysisBase from ax.service.utils.best_point_mixin import BestPointMixin diff --git a/ax/service/tests/scheduler_test_utils.py b/ax/service/tests/scheduler_test_utils.py index 2c758413ac1..becba865fa3 100644 --- a/ax/service/tests/scheduler_test_utils.py +++ b/ax/service/tests/scheduler_test_utils.py @@ -44,11 +44,14 @@ UserInputError, ) from ax.exceptions.generation_strategy import AxGenerationException +from ax.generation_strategy.dispatch_utils import choose_generation_strategy +from ax.generation_strategy.generation_strategy import ( + GenerationStep, + GenerationStrategy, +) from ax.metrics.branin import BraninMetric from ax.metrics.branin_map import BraninTimestampMapMetric from ax.modelbridge.cross_validation import compute_model_fit_metrics_from_modelbridge -from ax.modelbridge.dispatch_utils import choose_generation_strategy -from ax.modelbridge.generation_strategy import GenerationStep, GenerationStrategy from ax.modelbridge.registry import Generators, MBM_MTGP_trans from ax.runners.single_running_trial_mixin import SingleRunningTrialMixin from ax.runners.synthetic import SyntheticRunner diff --git a/ax/service/tests/test_ax_client.py b/ax/service/tests/test_ax_client.py index 2d217a5c096..349367d1b33 100644 --- a/ax/service/tests/test_ax_client.py +++ b/ax/service/tests/test_ax_client.py @@ -48,14 +48,14 @@ UserInputError, ) from ax.exceptions.generation_strategy import MaxParallelismReachedException -from ax.metrics.branin import branin, BraninMetric -from ax.modelbridge.dispatch_utils import DEFAULT_BAYESIAN_PARALLELISM -from ax.modelbridge.generation_strategy import ( +from ax.generation_strategy.dispatch_utils import DEFAULT_BAYESIAN_PARALLELISM +from ax.generation_strategy.generation_strategy import ( GenerationNode, GenerationStep, GenerationStrategy, ) -from ax.modelbridge.model_spec import GeneratorSpec +from ax.generation_strategy.model_spec import GeneratorSpec +from ax.metrics.branin import branin, BraninMetric from ax.modelbridge.random import RandomAdapter from ax.modelbridge.registry import Cont_X_trans, Generators from ax.runners.synthetic import SyntheticRunner @@ -3048,7 +3048,7 @@ def test_SingleTaskGP_log_unordered_categorical_parameters(self) -> None: ] with mock.patch( - "ax.modelbridge.dispatch_utils.logger.info", + "ax.generation_strategy.dispatch_utils.logger.info", side_effect=(lambda log: logs.append(log)), ): ax_client.create_experiment( diff --git a/ax/service/tests/test_interactive_loop.py b/ax/service/tests/test_interactive_loop.py index 8a734ebf8f5..5ef08d05e3f 100644 --- a/ax/service/tests/test_interactive_loop.py +++ b/ax/service/tests/test_interactive_loop.py @@ -16,7 +16,10 @@ import numpy as np from ax.core.types import TEvaluationOutcome, TParameterization -from ax.modelbridge.generation_strategy import GenerationStep, GenerationStrategy +from ax.generation_strategy.generation_strategy import ( + GenerationStep, + GenerationStrategy, +) from ax.modelbridge.registry import Generators from ax.service.ax_client import AxClient from ax.service.interactive_loop import ( diff --git a/ax/service/tests/test_managed_loop.py b/ax/service/tests/test_managed_loop.py index 7a0cc14d82f..73a4d06d834 100644 --- a/ax/service/tests/test_managed_loop.py +++ b/ax/service/tests/test_managed_loop.py @@ -11,8 +11,11 @@ import numpy as np import numpy.typing as npt from ax.exceptions.core import UserInputError +from ax.generation_strategy.generation_strategy import ( + GenerationStep, + GenerationStrategy, +) from ax.metrics.branin import branin -from ax.modelbridge.generation_strategy import GenerationStep, GenerationStrategy from ax.modelbridge.registry import Generators from ax.service.managed_loop import OptimizationLoop, optimize from ax.utils.common.testutils import TestCase diff --git a/ax/service/tests/test_report_utils.py b/ax/service/tests/test_report_utils.py index 6245fd6ff7b..b6a4d9f825b 100644 --- a/ax/service/tests/test_report_utils.py +++ b/ax/service/tests/test_report_utils.py @@ -22,8 +22,8 @@ ) from ax.core.outcome_constraint import ObjectiveThreshold from ax.core.types import ComparisonOp -from ax.modelbridge.generation_node import GenerationStep -from ax.modelbridge.generation_strategy import GenerationStrategy +from ax.generation_strategy.generation_node import GenerationStep +from ax.generation_strategy.generation_strategy import GenerationStrategy from ax.modelbridge.registry import Generators from ax.service.scheduler import Scheduler from ax.service.utils.report_utils import ( diff --git a/ax/service/tests/test_scheduler.py b/ax/service/tests/test_scheduler.py index 95cbd3cb916..c7d3941889c 100644 --- a/ax/service/tests/test_scheduler.py +++ b/ax/service/tests/test_scheduler.py @@ -9,9 +9,12 @@ from ax.core.multi_type_experiment import MultiTypeExperiment from ax.core.objective import Objective from ax.core.optimization_config import OptimizationConfig +from ax.generation_strategy.dispatch_utils import choose_generation_strategy +from ax.generation_strategy.generation_strategy import ( + GenerationStep, + GenerationStrategy, +) from ax.metrics.branin import BraninMetric -from ax.modelbridge.dispatch_utils import choose_generation_strategy -from ax.modelbridge.generation_strategy import GenerationStep, GenerationStrategy from ax.modelbridge.registry import Generators from ax.service.tests.scheduler_test_utils import ( AxSchedulerTestCase, diff --git a/ax/service/tests/test_with_db_settings_base.py b/ax/service/tests/test_with_db_settings_base.py index 6a6b48f21e3..4fa00749fbf 100644 --- a/ax/service/tests/test_with_db_settings_base.py +++ b/ax/service/tests/test_with_db_settings_base.py @@ -12,7 +12,7 @@ from ax.core.base_trial import TrialStatus from ax.core.experiment import Experiment -from ax.modelbridge.generation_strategy import GenerationStrategy +from ax.generation_strategy.generation_strategy import GenerationStrategy from ax.service.utils.with_db_settings_base import ( try_load_generation_strategy, WithDBSettingsBase, diff --git a/ax/service/utils/best_point.py b/ax/service/utils/best_point.py index d50aa1fbfc3..bbd1a5e8d66 100644 --- a/ax/service/utils/best_point.py +++ b/ax/service/utils/best_point.py @@ -30,13 +30,13 @@ from ax.core.trial import Trial from ax.core.types import ComparisonOp, TModelPredictArm, TParameterization from ax.exceptions.core import UnsupportedError, UserInputError +from ax.generation_strategy.generation_strategy import GenerationStrategy from ax.modelbridge.base import Adapter from ax.modelbridge.cross_validation import ( assess_model_fit, compute_diagnostics, cross_validate, ) -from ax.modelbridge.generation_strategy import GenerationStrategy from ax.modelbridge.modelbridge_utils import ( observed_pareto_frontier as observed_pareto, predicted_pareto_frontier as predicted_pareto, diff --git a/ax/service/utils/best_point_mixin.py b/ax/service/utils/best_point_mixin.py index 4090e026e8d..4d72cfe8df6 100644 --- a/ax/service/utils/best_point_mixin.py +++ b/ax/service/utils/best_point_mixin.py @@ -23,7 +23,7 @@ from ax.core.trial import Trial from ax.core.types import TModelPredictArm, TParameterization from ax.exceptions.core import UserInputError -from ax.modelbridge.generation_strategy import GenerationStrategy +from ax.generation_strategy.generation_strategy import GenerationStrategy from ax.modelbridge.modelbridge_utils import ( extract_objective_thresholds, extract_objective_weights, diff --git a/ax/service/utils/report_utils.py b/ax/service/utils/report_utils.py index a9e7cb6b47c..cb1730149c9 100644 --- a/ax/service/utils/report_utils.py +++ b/ax/service/utils/report_utils.py @@ -35,12 +35,12 @@ from ax.core.trial import BaseTrial from ax.early_stopping.strategies.base import BaseEarlyStoppingStrategy from ax.exceptions.core import DataRequiredError, UserInputError +from ax.generation_strategy.generation_strategy import GenerationStrategy from ax.modelbridge import Adapter from ax.modelbridge.cross_validation import ( compute_model_fit_metrics_from_modelbridge, cross_validate, ) -from ax.modelbridge.generation_strategy import GenerationStrategy from ax.modelbridge.random import RandomAdapter from ax.modelbridge.torch import TorchAdapter from ax.plot.contour import interact_contour_plotly diff --git a/ax/service/utils/with_db_settings_base.py b/ax/service/utils/with_db_settings_base.py index fa8df73c864..31010da5cb6 100644 --- a/ax/service/utils/with_db_settings_base.py +++ b/ax/service/utils/with_db_settings_base.py @@ -25,7 +25,7 @@ ObjectNotFoundError, UnsupportedError, ) -from ax.modelbridge.generation_strategy import GenerationStrategy +from ax.generation_strategy.generation_strategy import GenerationStrategy from ax.utils.common.executils import retry_on_exception from ax.utils.common.logger import _round_floats_for_logging, get_logger from pyre_extensions import none_throws diff --git a/ax/storage/json_store/decoder.py b/ax/storage/json_store/decoder.py index fa5d1e69471..cb0e435ed94 100644 --- a/ax/storage/json_store/decoder.py +++ b/ax/storage/json_store/decoder.py @@ -33,19 +33,21 @@ ) from ax.core.search_space import SearchSpace from ax.exceptions.storage import JSONDecodeError, STORAGE_DOCS_SUFFIX -from ax.modelbridge.generation_node_input_constructors import InputConstructorPurpose -from ax.modelbridge.generation_strategy import ( +from ax.generation_strategy.generation_node_input_constructors import ( + InputConstructorPurpose, +) +from ax.generation_strategy.generation_strategy import ( GenerationNode, GenerationStep, GenerationStrategy, ) -from ax.modelbridge.model_spec import GeneratorSpec -from ax.modelbridge.registry import _decode_callables_from_references, ModelRegistryBase -from ax.modelbridge.transition_criterion import ( +from ax.generation_strategy.model_spec import GeneratorSpec +from ax.generation_strategy.transition_criterion import ( AuxiliaryExperimentCheck, TransitionCriterion, TrialBasedCriterion, ) +from ax.modelbridge.registry import _decode_callables_from_references, ModelRegistryBase from ax.models.torch.botorch_modular.surrogate import Surrogate, SurrogateSpec from ax.models.torch.botorch_modular.utils import ModelConfig from ax.storage.json_store.decoders import ( diff --git a/ax/storage/json_store/encoders.py b/ax/storage/json_store/encoders.py index 7279021cc4c..03448f72431 100644 --- a/ax/storage/json_store/encoders.py +++ b/ax/storage/json_store/encoders.py @@ -43,14 +43,20 @@ ) from ax.exceptions.core import AxStorageWarning from ax.exceptions.storage import JSONEncodeError, STORAGE_DOCS_SUFFIX +from ax.generation_strategy.best_model_selector import BestModelSelector +from ax.generation_strategy.generation_node import GenerationNode +from ax.generation_strategy.generation_strategy import ( + GenerationStep, + GenerationStrategy, +) +from ax.generation_strategy.model_spec import ( + FactoryFunctionGeneratorSpec, + GeneratorSpec, +) +from ax.generation_strategy.transition_criterion import TransitionCriterion from ax.global_stopping.strategies.improvement import ImprovementGlobalStoppingStrategy -from ax.modelbridge.best_model_selector import BestModelSelector -from ax.modelbridge.generation_node import GenerationNode -from ax.modelbridge.generation_strategy import GenerationStep, GenerationStrategy -from ax.modelbridge.model_spec import FactoryFunctionGeneratorSpec, GeneratorSpec from ax.modelbridge.registry import _encode_callables_as_references from ax.modelbridge.transforms.base import Transform -from ax.modelbridge.transition_criterion import TransitionCriterion from ax.models.torch.botorch_modular.model import BoTorchGenerator from ax.models.torch.botorch_modular.surrogate import Surrogate from ax.models.winsorization_config import WinsorizationConfig diff --git a/ax/storage/json_store/registry.py b/ax/storage/json_store/registry.py index 149a3712dbb..7f05d636e11 100644 --- a/ax/storage/json_store/registry.py +++ b/ax/storage/json_store/registry.py @@ -67,30 +67,18 @@ AndEarlyStoppingStrategy, OrEarlyStoppingStrategy, ) -from ax.global_stopping.strategies.improvement import ImprovementGlobalStoppingStrategy -from ax.metrics.branin import BraninMetric, NegativeBraninMetric -from ax.metrics.branin_map import BraninTimestampMapMetric -from ax.metrics.chemistry import ChemistryMetric, ChemistryProblemType -from ax.metrics.factorial import FactorialMetric -from ax.metrics.hartmann6 import Hartmann6Metric -from ax.metrics.l2norm import L2NormMetric -from ax.metrics.noisy_function import NoisyFunctionMetric -from ax.metrics.sklearn import SklearnDataset, SklearnMetric, SklearnModelType -from ax.modelbridge.best_model_selector import ( +from ax.generation_strategy.best_model_selector import ( ReductionCriterion, SingleDiagnosticBestModelSelector, ) -from ax.modelbridge.factory import Generators -from ax.modelbridge.generation_node import GenerationNode, GenerationStep -from ax.modelbridge.generation_node_input_constructors import ( +from ax.generation_strategy.generation_node import GenerationNode, GenerationStep +from ax.generation_strategy.generation_node_input_constructors import ( InputConstructorPurpose, NodeInputConstructors, ) -from ax.modelbridge.generation_strategy import GenerationStrategy -from ax.modelbridge.model_spec import GeneratorSpec -from ax.modelbridge.registry import ModelRegistryBase -from ax.modelbridge.transforms.base import Transform -from ax.modelbridge.transition_criterion import ( +from ax.generation_strategy.generation_strategy import GenerationStrategy +from ax.generation_strategy.model_spec import GeneratorSpec +from ax.generation_strategy.transition_criterion import ( AutoTransitionAfterGen, AuxiliaryExperimentCheck, IsSingleObjective, @@ -101,6 +89,18 @@ MinTrials, TransitionCriterion, ) +from ax.global_stopping.strategies.improvement import ImprovementGlobalStoppingStrategy +from ax.metrics.branin import BraninMetric, NegativeBraninMetric +from ax.metrics.branin_map import BraninTimestampMapMetric +from ax.metrics.chemistry import ChemistryMetric, ChemistryProblemType +from ax.metrics.factorial import FactorialMetric +from ax.metrics.hartmann6 import Hartmann6Metric +from ax.metrics.l2norm import L2NormMetric +from ax.metrics.noisy_function import NoisyFunctionMetric +from ax.metrics.sklearn import SklearnDataset, SklearnMetric, SklearnModelType +from ax.modelbridge.factory import Generators +from ax.modelbridge.registry import ModelRegistryBase +from ax.modelbridge.transforms.base import Transform from ax.models.torch.botorch_modular.acquisition import Acquisition from ax.models.torch.botorch_modular.model import BoTorchGenerator from ax.models.torch.botorch_modular.surrogate import Surrogate, SurrogateSpec diff --git a/ax/storage/json_store/tests/test_json_store.py b/ax/storage/json_store/tests/test_json_store.py index 295ff949365..9eda3b31617 100644 --- a/ax/storage/json_store/tests/test_json_store.py +++ b/ax/storage/json_store/tests/test_json_store.py @@ -19,8 +19,8 @@ from ax.core.runner import Runner from ax.exceptions.core import AxStorageWarning from ax.exceptions.storage import JSONDecodeError, JSONEncodeError -from ax.modelbridge.generation_node import GenerationStep -from ax.modelbridge.generation_strategy import GenerationStrategy +from ax.generation_strategy.generation_node import GenerationStep +from ax.generation_strategy.generation_strategy import GenerationStrategy from ax.modelbridge.registry import Generators from ax.models.torch.botorch_modular.kernels import ScaleMaternKernel from ax.models.torch.botorch_modular.surrogate import SurrogateSpec diff --git a/ax/storage/sqa_store/decoder.py b/ax/storage/sqa_store/decoder.py index a6e1a24d24f..bad3318389c 100644 --- a/ax/storage/sqa_store/decoder.py +++ b/ax/storage/sqa_store/decoder.py @@ -47,7 +47,7 @@ from ax.core.search_space import HierarchicalSearchSpace, RobustSearchSpace, SearchSpace from ax.core.trial import Trial from ax.exceptions.storage import JSONDecodeError, SQADecodeError -from ax.modelbridge.generation_strategy import GenerationStrategy +from ax.generation_strategy.generation_strategy import GenerationStrategy from ax.storage.json_store.decoder import object_from_json from ax.storage.sqa_store.db import session_scope from ax.storage.sqa_store.sqa_classes import ( diff --git a/ax/storage/sqa_store/delete.py b/ax/storage/sqa_store/delete.py index 8d719f4f825..a68d05800dc 100644 --- a/ax/storage/sqa_store/delete.py +++ b/ax/storage/sqa_store/delete.py @@ -8,7 +8,7 @@ from logging import Logger from ax.core.experiment import Experiment -from ax.modelbridge.generation_strategy import GenerationStrategy +from ax.generation_strategy.generation_strategy import GenerationStrategy from ax.storage.sqa_store.db import session_scope from ax.storage.sqa_store.decoder import Decoder from ax.storage.sqa_store.sqa_classes import SQAExperiment diff --git a/ax/storage/sqa_store/encoder.py b/ax/storage/sqa_store/encoder.py index 76372fa5e92..aab1a486e26 100644 --- a/ax/storage/sqa_store/encoder.py +++ b/ax/storage/sqa_store/encoder.py @@ -45,7 +45,7 @@ from ax.core.search_space import RobustSearchSpace, SearchSpace from ax.core.trial import Trial from ax.exceptions.storage import SQAEncodeError -from ax.modelbridge.generation_strategy import GenerationStrategy +from ax.generation_strategy.generation_strategy import GenerationStrategy from ax.storage.json_store.encoder import object_to_json from ax.storage.sqa_store.sqa_classes import ( SQAAbandonedArm, diff --git a/ax/storage/sqa_store/load.py b/ax/storage/sqa_store/load.py index 58ebdcce10a..0ea39e8787a 100644 --- a/ax/storage/sqa_store/load.py +++ b/ax/storage/sqa_store/load.py @@ -16,7 +16,7 @@ from ax.core.metric import Metric from ax.core.trial import Trial from ax.exceptions.core import ExperimentNotFoundError, ObjectNotFoundError -from ax.modelbridge.generation_strategy import GenerationStrategy +from ax.generation_strategy.generation_strategy import GenerationStrategy from ax.storage.sqa_store.db import session_scope from ax.storage.sqa_store.decoder import Decoder from ax.storage.sqa_store.reduced_state import ( diff --git a/ax/storage/sqa_store/save.py b/ax/storage/sqa_store/save.py index a60bb666cf5..05b3deb9a4b 100644 --- a/ax/storage/sqa_store/save.py +++ b/ax/storage/sqa_store/save.py @@ -25,7 +25,7 @@ from ax.core.trial import Trial from ax.exceptions.core import UserInputError from ax.exceptions.storage import SQADecodeError -from ax.modelbridge.generation_strategy import GenerationStrategy +from ax.generation_strategy.generation_strategy import GenerationStrategy from ax.storage.sqa_store.db import session_scope, SQABase from ax.storage.sqa_store.decoder import Decoder from ax.storage.sqa_store.encoder import Encoder diff --git a/ax/storage/sqa_store/sqa_config.py b/ax/storage/sqa_store/sqa_config.py index 3e615151fbf..9b7eb640762 100644 --- a/ax/storage/sqa_store/sqa_config.py +++ b/ax/storage/sqa_store/sqa_config.py @@ -24,7 +24,7 @@ from ax.core.parameter_constraint import ParameterConstraint from ax.core.runner import Runner from ax.core.trial import Trial -from ax.modelbridge.generation_strategy import GenerationStrategy +from ax.generation_strategy.generation_strategy import GenerationStrategy from ax.storage.json_store.registry import ( CORE_CLASS_DECODER_REGISTRY, CORE_CLASS_ENCODER_REGISTRY, diff --git a/ax/storage/sqa_store/tests/test_sqa_store.py b/ax/storage/sqa_store/tests/test_sqa_store.py index d98bf51c1e2..84984875d13 100644 --- a/ax/storage/sqa_store/tests/test_sqa_store.py +++ b/ax/storage/sqa_store/tests/test_sqa_store.py @@ -33,8 +33,8 @@ from ax.core.types import ComparisonOp from ax.exceptions.core import ObjectNotFoundError from ax.exceptions.storage import JSONDecodeError, SQADecodeError, SQAEncodeError +from ax.generation_strategy.dispatch_utils import choose_generation_strategy from ax.metrics.branin import BraninMetric -from ax.modelbridge.dispatch_utils import choose_generation_strategy from ax.modelbridge.registry import Generators from ax.models.torch.botorch_modular.surrogate import Surrogate, SurrogateSpec from ax.runners.synthetic import SyntheticRunner diff --git a/ax/utils/testing/benchmark_stubs.py b/ax/utils/testing/benchmark_stubs.py index faf5a0053ae..fdd52a05c1f 100644 --- a/ax/utils/testing/benchmark_stubs.py +++ b/ax/utils/testing/benchmark_stubs.py @@ -38,8 +38,8 @@ from ax.core.trial import Trial from ax.core.types import TParameterization, TParamValue from ax.early_stopping.strategies.base import BaseEarlyStoppingStrategy -from ax.modelbridge.external_generation_node import ExternalGenerationNode -from ax.modelbridge.generation_strategy import GenerationStrategy +from ax.generation_strategy.external_generation_node import ExternalGenerationNode +from ax.generation_strategy.generation_strategy import GenerationStrategy from ax.modelbridge.torch import TorchAdapter from ax.models.torch.botorch_modular.model import BoTorchGenerator from ax.models.torch.botorch_modular.surrogate import Surrogate diff --git a/ax/utils/testing/core_stubs.py b/ax/utils/testing/core_stubs.py index 922693619d1..5c4c19f6214 100644 --- a/ax/utils/testing/core_stubs.py +++ b/ax/utils/testing/core_stubs.py @@ -78,24 +78,27 @@ OrEarlyStoppingStrategy, ) from ax.exceptions.core import UserInputError -from ax.global_stopping.strategies.base import BaseGlobalStoppingStrategy -from ax.global_stopping.strategies.improvement import ImprovementGlobalStoppingStrategy -from ax.metrics.branin import BraninMetric -from ax.metrics.branin_map import BraninTimestampMapMetric -from ax.metrics.factorial import FactorialMetric -from ax.metrics.hartmann6 import Hartmann6Metric -from ax.modelbridge.factory import Cont_X_trans, Generators, get_factorial, get_sobol -from ax.modelbridge.generation_node_input_constructors import ( +from ax.generation_strategy.generation_node_input_constructors import ( InputConstructorPurpose, NodeInputConstructors, ) -from ax.modelbridge.generation_strategy import GenerationNode, GenerationStrategy -from ax.modelbridge.model_spec import GeneratorSpec -from ax.modelbridge.transition_criterion import ( +from ax.generation_strategy.generation_strategy import ( + GenerationNode, + GenerationStrategy, +) +from ax.generation_strategy.model_spec import GeneratorSpec +from ax.generation_strategy.transition_criterion import ( MaxGenerationParallelism, MinTrials, TrialBasedCriterion, ) +from ax.global_stopping.strategies.base import BaseGlobalStoppingStrategy +from ax.global_stopping.strategies.improvement import ImprovementGlobalStoppingStrategy +from ax.metrics.branin import BraninMetric +from ax.metrics.branin_map import BraninTimestampMapMetric +from ax.metrics.factorial import FactorialMetric +from ax.metrics.hartmann6 import Hartmann6Metric +from ax.modelbridge.factory import Cont_X_trans, Generators, get_factorial, get_sobol from ax.models.torch.botorch_modular.acquisition import Acquisition from ax.models.torch.botorch_modular.kernels import ScaleMaternKernel from ax.models.torch.botorch_modular.model import BoTorchGenerator diff --git a/ax/utils/testing/modeling_stubs.py b/ax/utils/testing/modeling_stubs.py index d117afa0265..5eb93e38c66 100644 --- a/ax/utils/testing/modeling_stubs.py +++ b/ax/utils/testing/modeling_stubs.py @@ -17,33 +17,36 @@ from ax.core.parameter import FixedParameter, RangeParameter from ax.core.search_space import SearchSpace from ax.exceptions.core import UserInputError -from ax.modelbridge.base import Adapter -from ax.modelbridge.best_model_selector import ( +from ax.generation_strategy.best_model_selector import ( ReductionCriterion, SingleDiagnosticBestModelSelector, ) -from ax.modelbridge.cross_validation import FISHER_EXACT_TEST_P -from ax.modelbridge.dispatch_utils import choose_generation_strategy -from ax.modelbridge.factory import get_sobol -from ax.modelbridge.generation_node import GenerationNode +from ax.generation_strategy.dispatch_utils import choose_generation_strategy +from ax.generation_strategy.generation_node import GenerationNode -from ax.modelbridge.generation_node_input_constructors import ( +from ax.generation_strategy.generation_node_input_constructors import ( InputConstructorPurpose, NodeInputConstructors, ) -from ax.modelbridge.generation_strategy import GenerationStep, GenerationStrategy -from ax.modelbridge.model_spec import GeneratorSpec -from ax.modelbridge.registry import Generators -from ax.modelbridge.transforms.base import Transform -from ax.modelbridge.transforms.int_to_float import IntToFloat -from ax.modelbridge.transforms.transform_to_new_sq import TransformToNewSQ -from ax.modelbridge.transition_criterion import ( +from ax.generation_strategy.generation_strategy import ( + GenerationStep, + GenerationStrategy, +) +from ax.generation_strategy.model_spec import GeneratorSpec +from ax.generation_strategy.transition_criterion import ( AutoTransitionAfterGen, IsSingleObjective, MaxGenerationParallelism, MinimumPreferenceOccurances, MinTrials, ) +from ax.modelbridge.base import Adapter +from ax.modelbridge.cross_validation import FISHER_EXACT_TEST_P +from ax.modelbridge.factory import get_sobol +from ax.modelbridge.registry import Generators +from ax.modelbridge.transforms.base import Transform +from ax.modelbridge.transforms.int_to_float import IntToFloat +from ax.modelbridge.transforms.transform_to_new_sq import TransformToNewSQ from ax.models.torch.botorch_modular.surrogate import Surrogate from ax.utils.common.constants import Keys from ax.utils.common.logger import get_logger diff --git a/ax/utils/testing/tests/test_utils.py b/ax/utils/testing/tests/test_utils.py index edf936545ac..a47530d22da 100644 --- a/ax/utils/testing/tests/test_utils.py +++ b/ax/utils/testing/tests/test_utils.py @@ -8,8 +8,11 @@ import numpy as np import torch -from ax.modelbridge.generation_strategy import GenerationNode, GenerationStrategy -from ax.modelbridge.model_spec import GeneratorSpec +from ax.generation_strategy.generation_strategy import ( + GenerationNode, + GenerationStrategy, +) +from ax.generation_strategy.model_spec import GeneratorSpec from ax.modelbridge.registry import Generators from ax.utils.common.testutils import TestCase from ax.utils.testing.core_stubs import get_experiment_with_observations diff --git a/ax/utils/testing/utils.py b/ax/utils/testing/utils.py index 49f9be7711e..fb8840ac337 100644 --- a/ax/utils/testing/utils.py +++ b/ax/utils/testing/utils.py @@ -14,7 +14,7 @@ from ax.core.data import Data from ax.core.experiment import Experiment from ax.exceptions.core import UnsupportedError -from ax.modelbridge.generation_strategy import GenerationStrategy +from ax.generation_strategy.generation_strategy import GenerationStrategy from pyre_extensions import none_throws from torch import Tensor diff --git a/docs/api.md b/docs/api.md index d5e3a79e34c..bb93f02a08c 100644 --- a/docs/api.md +++ b/docs/api.md @@ -184,7 +184,7 @@ best_parameters = best_arm.parameters ```py from ax import * -from ax.modelbridge.generation_strategy import GenerationStrategy +from ax.generation_strategy.generation_strategy import GenerationStrategy from ax.service import Scheduler # Full `Experiment` and `GenerationStrategy` instantiation diff --git a/docs/glossary.md b/docs/glossary.md index 39a451021a7..ba08d22e312 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -29,7 +29,7 @@ Object that keeps track of the whole optimization process. Contains a [search sp ### Generation strategy -Abstraction that allows to declaratively specify one or multiple models to use in the course of the optimization and automate transition between them (relevant [tutorial](/docs/tutorials/scheduler)). [`[GenerationStrategy]`](https://ax.readthedocs.io/en/latest/modelbridge.html#module-ax.modelbridge.generation_strategy) +Abstraction that allows to declaratively specify one or multiple models to use in the course of the optimization and automate transition between them (relevant [tutorial](/docs/tutorials/scheduler)). [`[GenerationStrategy]`](https://ax.readthedocs.io/en/latest/modelbridge.html#module-ax.generation_strategy.generation_strategy) ### Generator run diff --git a/sphinx/source/generation_strategy.rst b/sphinx/source/generation_strategy.rst index 096b10cdb85..8e61dcc8d8a 100644 --- a/sphinx/source/generation_strategy.rst +++ b/sphinx/source/generation_strategy.rst @@ -8,7 +8,7 @@ ax.generation_strategy .. currentmodule:: ax.generation_strategy -Generation Strategy, Registry, and Factory +Generation Strategy ------------------------------------------ Generation Strategy diff --git a/tutorials/early_stopping/early_stopping.ipynb b/tutorials/early_stopping/early_stopping.ipynb index 2c1541f8cda..685a108eede 100644 --- a/tutorials/early_stopping/early_stopping.ipynb +++ b/tutorials/early_stopping/early_stopping.ipynb @@ -49,7 +49,7 @@ "from ax.early_stopping.strategies import PercentileEarlyStoppingStrategy\n", "from ax.metrics.tensorboard import TensorboardMetric\n", "\n", - "from ax.modelbridge.dispatch_utils import choose_generation_strategy\n", + "from ax.generation_strategy.dispatch_utils import choose_generation_strategy\n", "\n", "from ax.runners.torchx import TorchXRunner\n", "\n", @@ -658,6 +658,9 @@ } ], "metadata": { + "fileHeader": "", + "fileUid": "6c4a9128-1e1c-49eb-be46-3d989d565ff4", + "isAdHoc": false, "kernelspec": { "display_name": "Python 3 (ipykernel)", "language": "python", @@ -675,7 +678,5 @@ "pygments_lexer": "ipython3", "version": "3.10.8" } - }, - "nbformat": 4, - "nbformat_minor": 5 + } } diff --git a/tutorials/external_generation_node/external_generation_node.ipynb b/tutorials/external_generation_node/external_generation_node.ipynb index 0f87fdc3be7..0283509c792 100644 --- a/tutorials/external_generation_node/external_generation_node.ipynb +++ b/tutorials/external_generation_node/external_generation_node.ipynb @@ -1,414 +1,408 @@ { - "cells": [ - { - "cell_type": "markdown", - "metadata": { - "customInput": null, - "originalKey": "448bd7a0-af5a-43b4-a4fa-6a43577193b5", - "outputsInitialized": false, - "showInput": false - }, - "source": [ - "# Using external methods for candidate generation in Ax\n", - "\n", - "Out of the box, Ax offers many options for candidate generation, most of which utilize Bayesian optimization algorithms built using [BoTorch](https://botorch.org/). For users that want to leverage Ax for experiment orchestration (via `AxClient` or `Scheduler`) and other features (e.g., early stopping), while relying on other methods for candidate generation, we introduced `ExternalGenerationNode`. \n", - "\n", - "A `GenerationNode` is a building block of a `GenerationStrategy`. They can be combined together utilize different methods for generating candidates at different stages of an experiment. `ExternalGenerationNode` exposes a lightweight interface to allow the users to easily integrate their methods into Ax, and use them as standalone or with other `GenerationNode`s in a `GenerationStrategy`.\n", - "\n", - "In this tutorial, we will implement a simple generation node using `RandomForestRegressor` from sklearn, and combine it with Sobol (for initialization) to optimize the Hartmann6 problem.\n", - "\n", - "NOTE: This is for illustration purposes only. We do not recommend using this strategy as it typically does not perform well compared to Ax's default algorithms due to it's overly greedy behavior." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "import sys\n", - "import plotly.io as pio\n", - "if 'google.colab' in sys.modules:\n", - " pio.renderers.default = \"colab\"\n", - " %pip install ax-platform" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "executionStartTime": 1710539298590, - "executionStopTime": 1710539307671, - "originalKey": "d07e3074-f374-40e8-af49-a018a00288b5", - "output": { - "id": "314819867912827", - "loadingStatus": "before loading" + "cells": [ + { + "cell_type": "markdown", + "metadata": { + "customInput": null, + "originalKey": "448bd7a0-af5a-43b4-a4fa-6a43577193b5", + "outputsInitialized": false, + "showInput": false + }, + "source": [ + "# Using external methods for candidate generation in Ax\n", + "\n", + "Out of the box, Ax offers many options for candidate generation, most of which utilize Bayesian optimization algorithms built using [BoTorch](https://botorch.org/). For users that want to leverage Ax for experiment orchestration (via `AxClient` or `Scheduler`) and other features (e.g., early stopping), while relying on other methods for candidate generation, we introduced `ExternalGenerationNode`. \n", + "\n", + "A `GenerationNode` is a building block of a `GenerationStrategy`. They can be combined together utilize different methods for generating candidates at different stages of an experiment. `ExternalGenerationNode` exposes a lightweight interface to allow the users to easily integrate their methods into Ax, and use them as standalone or with other `GenerationNode`s in a `GenerationStrategy`.\n", + "\n", + "In this tutorial, we will implement a simple generation node using `RandomForestRegressor` from sklearn, and combine it with Sobol (for initialization) to optimize the Hartmann6 problem.\n", + "\n", + "NOTE: This is for illustration purposes only. We do not recommend using this strategy as it typically does not perform well compared to Ax's default algorithms due to it's overly greedy behavior." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "import sys\n", + "import plotly.io as pio\n", + "if 'google.colab' in sys.modules:\n", + " pio.renderers.default = \"colab\"\n", + " %pip install ax-platform" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "executionStartTime": 1710539298590, + "executionStopTime": 1710539307671, + "originalKey": "d07e3074-f374-40e8-af49-a018a00288b5", + "outputsInitialized": true, + "requestMsgId": "d07e3074-f374-40e8-af49-a018a00288b5", + "serverExecutionDuration": 4039.838102879 + }, + "outputs": [], + "source": [ + "import time\n", + "from typing import Any, Dict, List, Optional, Tuple\n", + "\n", + "import numpy as np\n", + "from ax.core.base_trial import TrialStatus\n", + "from ax.core.data import Data\n", + "from ax.core.experiment import Experiment\n", + "from ax.core.parameter import RangeParameter\n", + "from ax.core.types import TParameterization\n", + "from ax.generation_strategy.external_generation_node import ExternalGenerationNode\n", + "from ax.generation_strategy.generation_node import GenerationNode\n", + "from ax.generation_strategy.generation_strategy import GenerationStrategy\n", + "from ax.generation_strategy.model_spec import GeneratorSpec\n", + "from ax.generation_strategy.transition_criterion import MaxTrials\n", + "from ax.modelbridge.registry import Generators\n", + "from ax.plot.trace import plot_objective_value_vs_trial_index\n", + "from ax.service.ax_client import AxClient, ObjectiveProperties\n", + "from ax.service.utils.report_utils import exp_to_df\n", + "from ax.utils.measurement.synthetic_functions import hartmann6\n", + "from sklearn.ensemble import RandomForestRegressor\n", + "from pyre_extensions import assert_is_instance\n", + "\n", + "\n", + "class RandomForestGenerationNode(ExternalGenerationNode):\n", + " \"\"\"A generation node that uses the RandomForestRegressor\n", + " from sklearn to predict candidate performance and picks the\n", + " next point as the random sample that has the best prediction.\n", + "\n", + " To leverage external methods for candidate generation, the user must\n", + " create a subclass that implements ``update_generator_state`` and\n", + " ``get_next_candidate`` methods. This can then be provided\n", + " as a node into a ``GenerationStrategy``, either as standalone or as\n", + " part of a larger generation strategy with other generation nodes,\n", + " e.g., with a Sobol node for initialization.\n", + " \"\"\"\n", + "\n", + " def __init__(self, num_samples: int, regressor_options: Dict[str, Any]) -> None:\n", + " \"\"\"Initialize the generation node.\n", + "\n", + " Args:\n", + " regressor_options: Options to pass to the random forest regressor.\n", + " num_samples: Number of random samples from the search space\n", + " used during candidate generation. The sample with the best\n", + " prediction is recommended as the next candidate.\n", + " \"\"\"\n", + " t_init_start = time.monotonic()\n", + " super().__init__(node_name=\"RandomForest\")\n", + " self.num_samples: int = num_samples\n", + " self.regressor: RandomForestRegressor = RandomForestRegressor(\n", + " **regressor_options\n", + " )\n", + " # We will set these later when updating the state.\n", + " # Alternatively, we could have required experiment as an input\n", + " # and extracted them here.\n", + " self.parameters: Optional[List[RangeParameter]] = None\n", + " self.minimize: Optional[bool] = None\n", + " # Recording time spent in initializing the generator. This is\n", + " # used to compute the time spent in candidate generation.\n", + " self.fit_time_since_gen: float = time.monotonic() - t_init_start\n", + "\n", + " def update_generator_state(self, experiment: Experiment, data: Data) -> None:\n", + " \"\"\"A method used to update the state of the generator. This includes any\n", + " models, predictors or any other custom state used by the generation node.\n", + " This method will be called with the up-to-date experiment and data before\n", + " ``get_next_candidate`` is called to generate the next trial(s). Note\n", + " that ``get_next_candidate`` may be called multiple times (to generate\n", + " multiple candidates) after a call to ``update_generator_state``.\n", + "\n", + " For this example, we will train the regressor using the latest data from\n", + " the experiment.\n", + "\n", + " Args:\n", + " experiment: The ``Experiment`` object representing the current state of the\n", + " experiment. The key properties includes ``trials``, ``search_space``,\n", + " and ``optimization_config``. The data is provided as a separate arg.\n", + " data: The data / metrics collected on the experiment so far.\n", + " \"\"\"\n", + " search_space = experiment.search_space\n", + " parameter_names = list(search_space.parameters.keys())\n", + " metric_names = list(experiment.optimization_config.metrics.keys())\n", + " if any(\n", + " not isinstance(p, RangeParameter) for p in search_space.parameters.values()\n", + " ):\n", + " raise NotImplementedError(\n", + " \"This example only supports RangeParameters in the search space.\"\n", + " )\n", + " if search_space.parameter_constraints:\n", + " raise NotImplementedError(\n", + " \"This example does not support parameter constraints.\"\n", + " )\n", + " if len(metric_names) != 1:\n", + " raise NotImplementedError(\n", + " \"This example only supports single-objective optimization.\"\n", + " )\n", + " # Get the data for the completed trials.\n", + " num_completed_trials = len(experiment.trials_by_status[TrialStatus.COMPLETED])\n", + " x = np.zeros([num_completed_trials, len(parameter_names)])\n", + " y = np.zeros([num_completed_trials, 1])\n", + " for t_idx, trial in experiment.trials.items():\n", + " if trial.status == \"COMPLETED\":\n", + " trial_parameters = trial.arm.parameters\n", + " x[t_idx, :] = np.array([trial_parameters[p] for p in parameter_names])\n", + " trial_df = data.df[data.df[\"trial_index\"] == t_idx]\n", + " y[t_idx, 0] = trial_df[trial_df[\"metric_name\"] == metric_names[0]][\n", + " \"mean\"\n", + " ].item()\n", + "\n", + " # Train the regressor.\n", + " self.regressor.fit(x, y)\n", + " # Update the attributes not set in __init__.\n", + " self.parameters = search_space.parameters\n", + " self.minimize = experiment.optimization_config.objective.minimize\n", + "\n", + " def get_next_candidate(\n", + " self, pending_parameters: List[TParameterization]\n", + " ) -> TParameterization:\n", + " \"\"\"Get the parameters for the next candidate configuration to evaluate.\n", + "\n", + " We will draw ``self.num_samples`` random samples from the search space\n", + " and predict the objective value for each sample. We will then return\n", + " the sample with the best predicted value.\n", + "\n", + " Args:\n", + " pending_parameters: A list of parameters of the candidates pending\n", + " evaluation. This is often used to avoid generating duplicate candidates.\n", + " We ignore this here for simplicity.\n", + "\n", + " Returns:\n", + " A dictionary mapping parameter names to parameter values for the next\n", + " candidate suggested by the method.\n", + " \"\"\"\n", + " bounds = np.array([[p.lower, p.upper] for p in self.parameters.values()])\n", + " unit_samples = np.random.random_sample([self.num_samples, len(bounds)])\n", + " samples = bounds[:, 0] + (bounds[:, 1] - bounds[:, 0]) * unit_samples\n", + " # Predict the objective value for each sample.\n", + " y_pred = self.regressor.predict(samples)\n", + " # Find the best sample.\n", + " best_idx = np.argmin(y_pred) if self.minimize else np.argmax(y_pred)\n", + " best_sample = samples[best_idx, :]\n", + " # Convert the sample to a parameterization.\n", + " candidate = {\n", + " p_name: best_sample[i].item()\n", + " for i, p_name in enumerate(self.parameters.keys())\n", + " }\n", + " return candidate" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "customInput": null, + "originalKey": "e1c194ea-53f9-466b-a04a-d1e222751a62", + "outputsInitialized": false, + "showInput": false + }, + "source": [ + "## Construct the GenerationStrategy\n", + "\n", + "We will use Sobol for the first 5 trials and defer to random forest for the rest." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "customInput": null, + "executionStartTime": 1710539307673, + "executionStopTime": 1710539307752, + "originalKey": "389cb09c-adeb-4724-82b0-903806b6b403", + "outputsInitialized": true, + "requestMsgId": "389cb09c-adeb-4724-82b0-903806b6b403", + "serverExecutionDuration": 5.2677921485156, + "showInput": true + }, + "outputs": [], + "source": [ + "generation_strategy = GenerationStrategy(\n", + " name=\"Sobol+RandomForest\",\n", + " nodes=[\n", + " GenerationNode(\n", + " node_name=\"Sobol\",\n", + " model_specs=[GeneratorSpec(Generators.SOBOL)],\n", + " transition_criteria=[\n", + " MaxTrials(\n", + " # This specifies the maximum number of trials to generate from this node,\n", + " # and the next node in the strategy.\n", + " threshold=5,\n", + " block_transition_if_unmet=True,\n", + " transition_to=\"RandomForest\"\n", + " )\n", + " ],\n", + " ),\n", + " RandomForestGenerationNode(num_samples=128, regressor_options={}),\n", + " ],\n", + ")" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "customInput": null, + "originalKey": "7bcf0a8e-39f7-4ceb-a791-c5453024bcfd", + "outputsInitialized": false, + "showInput": false + }, + "source": [ + "## Run a simple experiment using AxClient\n", + "\n", + "More details on how to use AxClient can be found in the [tutorial](https://ax.dev/tutorials/gpei_hartmann_service.html)." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "customInput": null, + "executionStartTime": 1710539307754, + "executionStopTime": 1710539307854, + "originalKey": "4be26fc1-6183-40c4-a45e-79adb613b950", + "outputsInitialized": true, + "requestMsgId": "4be26fc1-6183-40c4-a45e-79adb613b950", + "serverExecutionDuration": 15.909331152216, + "showInput": true + }, + "outputs": [], + "source": [ + "ax_client = AxClient(generation_strategy=generation_strategy)\n", + "\n", + "ax_client.create_experiment(\n", + " name=\"hartmann_test_experiment\",\n", + " parameters=[\n", + " {\n", + " \"name\": f\"x{i}\",\n", + " \"type\": \"range\",\n", + " \"bounds\": [0.0, 1.0],\n", + " \"value_type\": \"float\", # Optional, defaults to inference from type of \"bounds\".\n", + " }\n", + " for i in range(1, 7)\n", + " ],\n", + " objectives={\"hartmann6\": ObjectiveProperties(minimize=True)},\n", + ")\n", + "\n", + "\n", + "def evaluate(parameterization: TParameterization) -> Dict[str, Tuple[float, float]]:\n", + " x = np.array([parameterization.get(f\"x{i+1}\") for i in range(6)])\n", + " return {\"hartmann6\": (assert_is_instance(hartmann6(x), float), 0.0)}" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "customInput": null, + "originalKey": "a470eb3e-40a0-45d2-9d53-13a98a137ec2", + "outputsInitialized": false, + "showInput": false + }, + "source": [ + "### Run the optimization loop" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "customInput": null, + "executionStartTime": 1710539307855, + "executionStopTime": 1710539309651, + "originalKey": "f67454e1-2a1a-4e87-ba3b-038c3134b09d", + "outputsInitialized": false, + "requestMsgId": "f67454e1-2a1a-4e87-ba3b-038c3134b09d", + "serverExecutionDuration": 1679.0952710435, + "showInput": true + }, + "outputs": [ + { + "name": "stderr", + "output_type": "stream", + "text": [ + "[INFO 02-03 18:39:20] ax.service.ax_client: Generated new trial 14 with parameters {'x1': 0.722061, 'x2': 0.537668, 'x3': 0.340365, 'x4': 0.187451, 'x5': 0.27493, 'x6': 0.107343} using model RandomForest.\n", + "[INFO 02-03 18:39:20] ax.service.ax_client: Completed trial 14 with data: {'hartmann6': (-0.110032, 0.0)}.\n" + ] + } + ], + "source": [ + "for i in range(15):\n", + " parameterization, trial_index = ax_client.get_next_trial()\n", + " ax_client.complete_trial(\n", + " trial_index=trial_index, raw_data=evaluate(parameterization)\n", + " )" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "customInput": null, + "originalKey": "d0655321-4875-46d7-a4bf-ac2c4e166d94", + "outputsInitialized": false, + "showInput": false + }, + "source": [ + "### View the trials generated during optimization" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "customInput": null, + "executionStartTime": 1710539309652, + "executionStopTime": 1710539309824, + "originalKey": "ba69ed8c-7ee2-49ef-9ccf-0aad2bc5ac61", + "outputsInitialized": true, + "requestMsgId": "ba69ed8c-7ee2-49ef-9ccf-0aad2bc5ac61", + "serverExecutionDuration": 73.840260040015, + "showInput": true + }, + "outputs": [], + "source": [ + "exp_df = exp_to_df(ax_client.experiment)\n", + "exp_df" + ] }, - "outputsInitialized": true, - "requestMsgId": "d07e3074-f374-40e8-af49-a018a00288b5", - "serverExecutionDuration": 4039.838102879 - }, - "outputs": [], - "source": [ - "import time\n", - "from typing import Any, Dict, List, Optional, Tuple\n", - "\n", - "import numpy as np\n", - "from ax.core.base_trial import TrialStatus\n", - "from ax.core.data import Data\n", - "from ax.core.experiment import Experiment\n", - "from ax.core.parameter import RangeParameter\n", - "from ax.core.types import TParameterization\n", - "from ax.modelbridge.external_generation_node import ExternalGenerationNode\n", - "from ax.modelbridge.generation_node import GenerationNode\n", - "from ax.modelbridge.generation_strategy import GenerationStrategy\n", - "from ax.modelbridge.model_spec import GeneratorSpec\n", - "from ax.modelbridge.registry import Generators\n", - "from ax.modelbridge.transition_criterion import MaxTrials\n", - "from ax.plot.trace import plot_objective_value_vs_trial_index\n", - "from ax.service.ax_client import AxClient, ObjectiveProperties\n", - "from ax.service.utils.report_utils import exp_to_df\n", - "from ax.utils.measurement.synthetic_functions import hartmann6\n", - "from sklearn.ensemble import RandomForestRegressor\n", - "from pyre_extensions import assert_is_instance\n", - "\n", - "\n", - "class RandomForestGenerationNode(ExternalGenerationNode):\n", - " \"\"\"A generation node that uses the RandomForestRegressor\n", - " from sklearn to predict candidate performance and picks the\n", - " next point as the random sample that has the best prediction.\n", - "\n", - " To leverage external methods for candidate generation, the user must\n", - " create a subclass that implements ``update_generator_state`` and\n", - " ``get_next_candidate`` methods. This can then be provided\n", - " as a node into a ``GenerationStrategy``, either as standalone or as\n", - " part of a larger generation strategy with other generation nodes,\n", - " e.g., with a Sobol node for initialization.\n", - " \"\"\"\n", - "\n", - " def __init__(self, num_samples: int, regressor_options: Dict[str, Any]) -> None:\n", - " \"\"\"Initialize the generation node.\n", - "\n", - " Args:\n", - " regressor_options: Options to pass to the random forest regressor.\n", - " num_samples: Number of random samples from the search space\n", - " used during candidate generation. The sample with the best\n", - " prediction is recommended as the next candidate.\n", - " \"\"\"\n", - " t_init_start = time.monotonic()\n", - " super().__init__(node_name=\"RandomForest\")\n", - " self.num_samples: int = num_samples\n", - " self.regressor: RandomForestRegressor = RandomForestRegressor(\n", - " **regressor_options\n", - " )\n", - " # We will set these later when updating the state.\n", - " # Alternatively, we could have required experiment as an input\n", - " # and extracted them here.\n", - " self.parameters: Optional[List[RangeParameter]] = None\n", - " self.minimize: Optional[bool] = None\n", - " # Recording time spent in initializing the generator. This is\n", - " # used to compute the time spent in candidate generation.\n", - " self.fit_time_since_gen: float = time.monotonic() - t_init_start\n", - "\n", - " def update_generator_state(self, experiment: Experiment, data: Data) -> None:\n", - " \"\"\"A method used to update the state of the generator. This includes any\n", - " models, predictors or any other custom state used by the generation node.\n", - " This method will be called with the up-to-date experiment and data before\n", - " ``get_next_candidate`` is called to generate the next trial(s). Note\n", - " that ``get_next_candidate`` may be called multiple times (to generate\n", - " multiple candidates) after a call to ``update_generator_state``.\n", - "\n", - " For this example, we will train the regressor using the latest data from\n", - " the experiment.\n", - "\n", - " Args:\n", - " experiment: The ``Experiment`` object representing the current state of the\n", - " experiment. The key properties includes ``trials``, ``search_space``,\n", - " and ``optimization_config``. The data is provided as a separate arg.\n", - " data: The data / metrics collected on the experiment so far.\n", - " \"\"\"\n", - " search_space = experiment.search_space\n", - " parameter_names = list(search_space.parameters.keys())\n", - " metric_names = list(experiment.optimization_config.metrics.keys())\n", - " if any(\n", - " not isinstance(p, RangeParameter) for p in search_space.parameters.values()\n", - " ):\n", - " raise NotImplementedError(\n", - " \"This example only supports RangeParameters in the search space.\"\n", - " )\n", - " if search_space.parameter_constraints:\n", - " raise NotImplementedError(\n", - " \"This example does not support parameter constraints.\"\n", - " )\n", - " if len(metric_names) != 1:\n", - " raise NotImplementedError(\n", - " \"This example only supports single-objective optimization.\"\n", - " )\n", - " # Get the data for the completed trials.\n", - " num_completed_trials = len(experiment.trials_by_status[TrialStatus.COMPLETED])\n", - " x = np.zeros([num_completed_trials, len(parameter_names)])\n", - " y = np.zeros([num_completed_trials, 1])\n", - " for t_idx, trial in experiment.trials.items():\n", - " if trial.status == \"COMPLETED\":\n", - " trial_parameters = trial.arm.parameters\n", - " x[t_idx, :] = np.array([trial_parameters[p] for p in parameter_names])\n", - " trial_df = data.df[data.df[\"trial_index\"] == t_idx]\n", - " y[t_idx, 0] = trial_df[trial_df[\"metric_name\"] == metric_names[0]][\n", - " \"mean\"\n", - " ].item()\n", - "\n", - " # Train the regressor.\n", - " self.regressor.fit(x, y)\n", - " # Update the attributes not set in __init__.\n", - " self.parameters = search_space.parameters\n", - " self.minimize = experiment.optimization_config.objective.minimize\n", - "\n", - " def get_next_candidate(\n", - " self, pending_parameters: List[TParameterization]\n", - " ) -> TParameterization:\n", - " \"\"\"Get the parameters for the next candidate configuration to evaluate.\n", - "\n", - " We will draw ``self.num_samples`` random samples from the search space\n", - " and predict the objective value for each sample. We will then return\n", - " the sample with the best predicted value.\n", - "\n", - " Args:\n", - " pending_parameters: A list of parameters of the candidates pending\n", - " evaluation. This is often used to avoid generating duplicate candidates.\n", - " We ignore this here for simplicity.\n", - "\n", - " Returns:\n", - " A dictionary mapping parameter names to parameter values for the next\n", - " candidate suggested by the method.\n", - " \"\"\"\n", - " bounds = np.array([[p.lower, p.upper] for p in self.parameters.values()])\n", - " unit_samples = np.random.random_sample([self.num_samples, len(bounds)])\n", - " samples = bounds[:, 0] + (bounds[:, 1] - bounds[:, 0]) * unit_samples\n", - " # Predict the objective value for each sample.\n", - " y_pred = self.regressor.predict(samples)\n", - " # Find the best sample.\n", - " best_idx = np.argmin(y_pred) if self.minimize else np.argmax(y_pred)\n", - " best_sample = samples[best_idx, :]\n", - " # Convert the sample to a parameterization.\n", - " candidate = {\n", - " p_name: best_sample[i].item()\n", - " for i, p_name in enumerate(self.parameters.keys())\n", - " }\n", - " return candidate" - ] - }, - { - "cell_type": "markdown", - "metadata": { - "customInput": null, - "originalKey": "e1c194ea-53f9-466b-a04a-d1e222751a62", - "outputsInitialized": false, - "showInput": false - }, - "source": [ - "## Construct the GenerationStrategy\n", - "\n", - "We will use Sobol for the first 5 trials and defer to random forest for the rest." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "customInput": null, - "executionStartTime": 1710539307673, - "executionStopTime": 1710539307752, - "originalKey": "389cb09c-adeb-4724-82b0-903806b6b403", - "outputsInitialized": true, - "requestMsgId": "389cb09c-adeb-4724-82b0-903806b6b403", - "serverExecutionDuration": 5.2677921485156, - "showInput": true - }, - "outputs": [], - "source": [ - "generation_strategy = GenerationStrategy(\n", - " name=\"Sobol+RandomForest\",\n", - " nodes=[\n", - " GenerationNode(\n", - " node_name=\"Sobol\",\n", - " model_specs=[GeneratorSpec(Generators.SOBOL)],\n", - " transition_criteria=[\n", - " MaxTrials(\n", - " # This specifies the maximum number of trials to generate from this node, \n", - " # and the next node in the strategy.\n", - " threshold=5,\n", - " block_transition_if_unmet=True,\n", - " transition_to=\"RandomForest\"\n", - " )\n", - " ],\n", - " ),\n", - " RandomForestGenerationNode(num_samples=128, regressor_options={}),\n", - " ],\n", - ")" - ] - }, - { - "cell_type": "markdown", - "metadata": { - "customInput": null, - "originalKey": "7bcf0a8e-39f7-4ceb-a791-c5453024bcfd", - "outputsInitialized": false, - "showInput": false - }, - "source": [ - "## Run a simple experiment using AxClient\n", - "\n", - "More details on how to use AxClient can be found in the [tutorial](https://ax.dev/tutorials/gpei_hartmann_service.html)." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "customInput": null, - "executionStartTime": 1710539307754, - "executionStopTime": 1710539307854, - "originalKey": "4be26fc1-6183-40c4-a45e-79adb613b950", - "outputsInitialized": true, - "requestMsgId": "4be26fc1-6183-40c4-a45e-79adb613b950", - "serverExecutionDuration": 15.909331152216, - "showInput": true - }, - "outputs": [], - "source": [ - "ax_client = AxClient(generation_strategy=generation_strategy)\n", - "\n", - "ax_client.create_experiment(\n", - " name=\"hartmann_test_experiment\",\n", - " parameters=[\n", - " {\n", - " \"name\": f\"x{i}\",\n", - " \"type\": \"range\",\n", - " \"bounds\": [0.0, 1.0],\n", - " \"value_type\": \"float\", # Optional, defaults to inference from type of \"bounds\".\n", - " }\n", - " for i in range(1, 7)\n", - " ],\n", - " objectives={\"hartmann6\": ObjectiveProperties(minimize=True)},\n", - ")\n", - "\n", - "\n", - "def evaluate(parameterization: TParameterization) -> Dict[str, Tuple[float, float]]:\n", - " x = np.array([parameterization.get(f\"x{i+1}\") for i in range(6)])\n", - " return {\"hartmann6\": (assert_is_instance(hartmann6(x), float), 0.0)}" - ] - }, - { - "cell_type": "markdown", - "metadata": { - "customInput": null, - "originalKey": "a470eb3e-40a0-45d2-9d53-13a98a137ec2", - "outputsInitialized": false, - "showInput": false - }, - "source": [ - "### Run the optimization loop" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "customInput": null, - "executionStartTime": 1710539307855, - "executionStopTime": 1710539309651, - "originalKey": "f67454e1-2a1a-4e87-ba3b-038c3134b09d", - "outputsInitialized": false, - "requestMsgId": "f67454e1-2a1a-4e87-ba3b-038c3134b09d", - "serverExecutionDuration": 1679.0952710435, - "showInput": true - }, - "outputs": [ { - "name": "stderr", - "output_type": "stream", - "text": [ - "[INFO 02-03 18:39:20] ax.service.ax_client: Generated new trial 14 with parameters {'x1': 0.722061, 'x2': 0.537668, 'x3': 0.340365, 'x4': 0.187451, 'x5': 0.27493, 'x6': 0.107343} using model RandomForest.\n", - "[INFO 02-03 18:39:20] ax.service.ax_client: Completed trial 14 with data: {'hartmann6': (-0.110032, 0.0)}.\n" - ] + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "plot_objective_value_vs_trial_index(\n", + " exp_df=exp_df,\n", + " metric_colname=\"hartmann6\",\n", + " minimize=True,\n", + " title=\"Hartmann6 Objective Value vs. Trial Index\",\n", + ")" + ] + } + ], + "metadata": { + "fileHeader": "", + "fileUid": "1ab8b45a-525c-4c25-b142-f7ef9fffb1c5", + "isAdHoc": false, + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.10.16" } - ], - "source": [ - "for i in range(15):\n", - " parameterization, trial_index = ax_client.get_next_trial()\n", - " ax_client.complete_trial(\n", - " trial_index=trial_index, raw_data=evaluate(parameterization)\n", - " )" - ] - }, - { - "cell_type": "markdown", - "metadata": { - "customInput": null, - "originalKey": "d0655321-4875-46d7-a4bf-ac2c4e166d94", - "outputsInitialized": false, - "showInput": false - }, - "source": [ - "### View the trials generated during optimization" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "customInput": null, - "executionStartTime": 1710539309652, - "executionStopTime": 1710539309824, - "originalKey": "ba69ed8c-7ee2-49ef-9ccf-0aad2bc5ac61", - "outputsInitialized": true, - "requestMsgId": "ba69ed8c-7ee2-49ef-9ccf-0aad2bc5ac61", - "serverExecutionDuration": 73.840260040015, - "showInput": true - }, - "outputs": [], - "source": [ - "exp_df = exp_to_df(ax_client.experiment)\n", - "exp_df" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "plot_objective_value_vs_trial_index(\n", - " exp_df=exp_df,\n", - " metric_colname=\"hartmann6\",\n", - " minimize=True,\n", - " title=\"Hartmann6 Objective Value vs. Trial Index\",\n", - ")" - ] - } - ], - "metadata": { - "fileHeader": "", - "fileUid": "1ab8b45a-525c-4c25-b142-f7ef9fffb1c5", - "isAdHoc": false, - "kernelspec": { - "display_name": "Python 3 (ipykernel)", - "language": "python", - "name": "python3" - }, - "language_info": { - "codemirror_mode": { - "name": "ipython", - "version": 3 - }, - "file_extension": ".py", - "mimetype": "text/x-python", - "name": "python", - "nbconvert_exporter": "python", - "pygments_lexer": "ipython3", - "version": "3.10.16" } - }, - "nbformat": 4, - "nbformat_minor": 4 } diff --git a/tutorials/generation_strategy/generation_strategy.ipynb b/tutorials/generation_strategy/generation_strategy.ipynb index 704a1432b7e..b510f5c86c5 100644 --- a/tutorials/generation_strategy/generation_strategy.ipynb +++ b/tutorials/generation_strategy/generation_strategy.ipynb @@ -1,467 +1,468 @@ { - "cells": [ - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "import sys\n", - "import plotly.io as pio\n", - "if 'google.colab' in sys.modules:\n", - " pio.renderers.default = \"colab\"\n", - " %pip install ax-platform" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "from ax.modelbridge.dispatch_utils import choose_generation_strategy\n", - "from ax.modelbridge.generation_strategy import GenerationStep, GenerationStrategy\n", - "from ax.modelbridge.modelbridge_utils import get_pending_observation_features\n", - "from ax.modelbridge.registry import ModelRegistryBase, Generators\n", - "\n", - "from ax.utils.testing.core_stubs import get_branin_experiment, get_branin_search_space" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "# Generation Strategy (GS) Tutorial\n", - "\n", - "`GenerationStrategy` ([API reference](https://ax.dev/api/modelbridge.html#ax.modelbridge.generation_strategy.GenerationStrategy)) is a key abstraction in Ax:\n", - "- It allows for specifying multiple optimization algorithms to chain one after another in the course of the optimization. \n", - "- Many higher-level APIs in Ax use generation strategies: Service and Loop APIs, `Scheduler` etc. (tutorials for all those higher-level APIs are here: https://ax.dev/tutorials/).\n", - "- Generation strategy allows for storage and resumption of modeling setups, making optimization resumable from SQL or JSON snapshots.\n", - "\n", - "This tutorial walks through a few examples of generation strategies and discusses its important settings. Before reading it, we recommend familiarizing yourself with how `Generator` and `Adapter` work in Ax: https://ax.dev/docs/models.html#deeper-dive-organization-of-the-modeling-stack.\n", - "\n", - "**Contents:**\n", - "1. Quick-start examples\n", - " 1. Manually configured GS\n", - " 2. Auto-selected GS\n", - " 3. Candidate generation from a GS\n", - "2. Deep dive: `GenerationStep` a building block of the generation strategy\n", - " 1. Describing a model\n", - " 2. Other `GenerationStep` settings\n", - " 3. Chaining `GenerationStep`-s together\n", - " 4. `max_parallelism` enforcement and handling the `MaxParallelismReachedException`\n", - "3. `GenerationStrategy` storage\n", - " 1. JSON storage\n", - " 2. SQL storage\n", - "4. Advanced considerations / \"gotchas\"\n", - " 1. Generation strategy produces `GeneratorRun`-s, not `Trial`-s\n", - " 2. `model_kwargs` elements that don't have associated serialization logic in Ax\n", - " 3. Why prefer `Models` registry enum entries over a factory function?\n", - " 4. How to request more modeling setups in `Models`?\n", - " \n", - "----" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## 1. Quick-start examples\n", - "\n", - "### 1A. Manually configured generation strategy\n", - "\n", - "Below is a typical generation strategy used for most single-objective optimization cases in Ax:" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "gs = GenerationStrategy(\n", - " steps=[\n", - " # 1. Initialization step (does not require pre-existing data and is well-suited for\n", - " # initial sampling of the search space)\n", - " GenerationStep(\n", - " model=Generators.SOBOL,\n", - " num_trials=5, # How many trials should be produced from this generation step\n", - " min_trials_observed=3, # How many trials need to be completed to move to next model\n", - " max_parallelism=5, # Max parallelism for this step\n", - " model_kwargs={\"seed\": 999}, # Any kwargs you want passed into the model\n", - " model_gen_kwargs={}, # Any kwargs you want passed to `modelbridge.gen`\n", - " ),\n", - " # 2. Bayesian optimization step (requires data obtained from previous phase and learns\n", - " # from all data available at the time of each new candidate generation call)\n", - " GenerationStep(\n", - " model=Generators.BOTORCH_MODULAR,\n", - " num_trials=-1, # No limitation on how many trials should be produced from this step\n", - " max_parallelism=3, # Parallelism limit for this step, often lower than for Sobol\n", - " # More on parallelism vs. required samples in BayesOpt:\n", - " # https://ax.dev/docs/bayesopt.html#tradeoff-between-parallelism-and-total-number-of-trials\n", - " ),\n", - " ]\n", - ")" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "### 1B. Auto-selected generation strategy\n", - "\n", - "Ax provides a [`choose_generation_strategy`](https://github.com/facebook/Ax/blob/main/ax/modelbridge/dispatch_utils.py#L115) utility, which can auto-select a suitable generation strategy given a search space and an array of other optional settings. The utility is fairly simple at the moment, but additional development (support for multi-objective optimization, multi-fidelity optimization, Bayesian optimization with categorical kernels etc.) is coming soon." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "gs = choose_generation_strategy(\n", - " # Required arguments:\n", - " search_space=get_branin_search_space(), # Ax `SearchSpace`\n", - " # Some optional arguments (shown with their defaults), see API docs for more settings:\n", - " # https://ax.dev/api/modelbridge.html#module-ax.modelbridge.dispatch_utils\n", - " use_batch_trials=False, # Whether this GS will be used to generate 1-arm `Trial`-s or `BatchTrials`\n", - " no_bayesian_optimization=False, # Use quasi-random candidate generation without BayesOpt\n", - " max_parallelism_override=None, # Integer, to which to set the `max_parallelism` setting of all steps in this GS\n", - ")\n", - "gs" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "### 1C. Candidate generation from a generation strategy\n", - "\n", - "While often used through Service or Loop API or other higher-order abstractions like the Ax `Scheduler` (where the generation strategy is used to fit models and produce candidates from them under-the-hood), it's also possible to use the GS directly, in place of a `Adapter` instance. The interface of `GenerationStrategy.gen` is the same as `Adapter.gen`.\n" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "experiment = get_branin_experiment()" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Note that it's important to **specify pending observations** to the call to `gen` to avoid getting the same points re-suggested. Without `pending_observations` argument, Ax models are not aware of points that should be excluded from generation. Points are considered \"pending\" when they belong to `STAGED`, `RUNNING`, or `ABANDONED` trials (with the latter included so model does not re-suggest points that are considered \"bad\" and should not be re-suggested).\n", - "\n", - "If the call to `get_pending_obervation_features` becomes slow in your setup (since it performs data-fetching etc.), you can opt for `get_pending_observation_features_based_on_trial_status` (also from `ax.modelbridge.modelbridge_utils`), but note the limitations of that utility (detailed in its docstring)." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "generator_run = gs.gen(\n", - " experiment=experiment, # Ax `Experiment`, for which to generate new candidates\n", - " data=None, # Ax `Data` to use for model training, optional.\n", - " n=1, # Number of candidate arms to produce\n", - " pending_observations=get_pending_observation_features(\n", - " experiment\n", - " ), # Points that should not be re-generated\n", - " # Any other kwargs specified will be passed through to `ModelBridge.gen` along with `GenerationStep.model_gen_kwargs`\n", - ")\n", - "generator_run" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Then we can add the newly produced [`GeneratorRun`](https://ax.dev/docs/glossary.html#generator-run) to the experiment as a [`Trial` (or `BatchTrial` if `n` > 1)](https://ax.dev/docs/glossary.html#trial):" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "trial = experiment.new_trial(generator_run)\n", - "trial" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "**Important notes on `GenerationStrategy.gen`:**\n", - "- if `data` argument above is not specified, GS will pull experiment data from cache via `experiment.lookup_data`,\n", - "- without specifying `pending_observations`, the GS (and any model in Ax) could produce the same candidate over and over, as without that argument the model is not 'aware' that the candidate is part of a `RUNNING` or `ABANDONED` trial and should not be re-suggested again.\n", - "\n", - "In cases where `get_pending_observation_features` is too slow and the experiment consists of 1-arm `Trial`-s only, it's possible to use `get_pending_observation_features_based_on_trial_status` instead (found in the same file)." - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Note that when using the Ax Service API, one of the arguments to `AxClient` is `choose_generation_strategy_kwargs`; specifying that argument is a convenient way to influence the choice of generation strategy in `AxClient` without manually specifying a full `GenerationStrategy`." - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "-----" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## 2. `GenerationStep` as a building block of generation strategy" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "### 2A. Describing a generator to use in a given `GenerationStep`\n", - "\n", - "There are two ways of specifying a generator for a generation step: via an entry in a `Models` enum or via a 'factory function' –– a callable generator constructor (e.g. [`get_GPEI`](https://github.com/facebook/Ax/blob/0e454b71d5e07b183c0866855555b6a21ddd5da1/ax/modelbridge/factory.py#L154) and other factory functions in the same file). Note that using the latter path, a factory function, will prohibit `GenerationStrategy` storage and is generally discouraged. " - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "### 2B. Other `GenerationStep` settings\n", - "\n", - "All of the available settings are described in the documentation:" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "print(GenerationStep.__doc__)" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## 2C. Chaining `GenerationStep`-s together\n", - "\n", - "A `GenerationStrategy` moves from one step to another when: \n", - "1. `N=num_trials` generator runs were produced and attached as trials to the experiment AND \n", - "2. `M=min_trials_observed` have been completed and have data.\n", - "\n", - "**Caveat: `enforce_num_trials` setting**:\n", - "\n", - "1. If `enforce_num_trials=True` for a given generation step, if 1) is reached but 2) is not yet reached, the generation strategy will raise a `DataRequiredError`, indicating that more trials need to be completed before the next step.\n", - "2. If `enforce_num_trials=False`, the GS will continue producing generator runs from the current step until 2) is reached." - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## 2D. `max_parallelism` enforcement\n", - "\n", - "Generation strategy can restrict the number of trials that can be ran simultaneously (to encourage sequential optimization, which benefits Bayesian optimization performance). When the parallelism limit is reached, a call to `GenerationStrategy.gen` will result in a `MaxParallelismReachedException`.\n", - "\n", - "The correct way to handle this exception:\n", - "1. Make sure that `GenerationStep.max_parallelism` is configured correctly for all steps in your generation strategy (to disable it completely, configure `GenerationStep.max_parallelism=None`),\n", - "2. When encountering the exception, wait to produce more generator runs until more trial evluations complete and log the trial completion via `trial.mark_completed`." - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "----\n", - "\n", - "## 3. SQL and JSON storage of a generation strategy" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "When used through Service API or `Scheduler`, generation strategy will be automatically stored to SQL or JSON via specifying `DBSettings` to either `AxClient` or `Scheduler` (details in respective tutorials in the [\"Tutorials\" page](https://ax.dev/tutorials/)). Generation strategy can also be stored to SQL or JSON individually, as shown below.\n", - "\n", - "More detail on SQL and JSON storage in Ax generally can be [found in \"Building Blocks of Ax\" tutorial](https://ax.dev/tutorials/building_blocks.html#9.-Save-to-JSON-or-SQL)." - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "### 3A. SQL storage\n", - "For SQL storage setup in Ax, read through the [\"Storage\" documentation page](https://ax.dev/docs/storage.html).\n", - "\n", - "Note that unlike an Ax experiment, a generation strategy does not have a name or another unique identifier. Therefore, a generation strategy is stored in association with experiment and can be retrieved by the associated experiment's name." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "from ax.storage.sqa_store.db import (\n", - " create_all_tables,\n", - " get_engine,\n", - " init_engine_and_session_factory,\n", - ")\n", - "from ax.storage.sqa_store.load import (\n", - " load_experiment,\n", - " load_generation_strategy_by_experiment_name,\n", - ")\n", - "from ax.storage.sqa_store.save import save_experiment, save_generation_strategy\n", - "\n", - "init_engine_and_session_factory(url=\"sqlite:///foo2.db\")\n", - "\n", - "engine = get_engine()\n", - "create_all_tables(engine)\n", - "\n", - "save_experiment(experiment)\n", - "save_generation_strategy(gs)\n", - "\n", - "experiment = load_experiment(experiment_name=experiment.name)\n", - "gs = load_generation_strategy_by_experiment_name(\n", - " experiment_name=experiment.name,\n", - " experiment=experiment, # Can optionally specify experiment object to avoid loading it from database twice\n", - ")\n", - "gs" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "### 3B. JSON storage" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "from ax.storage.json_store.decoder import object_from_json\n", - "from ax.storage.json_store.encoder import object_to_json\n", - "\n", - "gs_json = object_to_json(gs) # Can be written to a file or string via `json.dump` etc.\n", - "gs = object_from_json(\n", - " gs_json\n", - ") # Decoded back from JSON (can be loaded from file, string via `json.load` etc.)\n", - "gs" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "------" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## 3. Advanced considerations\n", - "\n", - "Below is a list of important \"gotchas\" of using generation strategy (especially outside of the higher-level APIs like the Service API or the `Scheduler`):\n", - "\n", - "### 3A. `GenerationStrategy.gen` produces `GeneratorRun`-s, not trials\n", - "\n", - "Since `GenerationStrategy.gen` mimics `Adapter.gen` and allows for human-in-the-loop usage mode, a call to `gen` produces a `GeneratorRun`, which can then be added (or altered before addition or not added at all) to a `Trial` or `BatchTrial` on a given experiment. So it's important to add the generator run to a trial, since otherwise it will not be attached to the experiment on its own." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "generator_run = gs.gen(\n", - " experiment=experiment,\n", - " n=1,\n", - " pending_observations=get_pending_observation_features(experiment),\n", - ")\n", - "experiment.new_trial(generator_run)" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "### 3B. `model_kwargs` elements that do not define serialization logic in Ax" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Note that passing objects that are not yet serializable in Ax (e.g. a BoTorch `Prior` object) as part of `GenerationStep.model_kwargs` or `GenerationStep.model_gen_kwargs` will prevent correct generation strategy storage. If this becomes a problem, feel free to open an issue on our Github: https://github.com/facebook/Ax/issues to get help with adding storage support for a given object." - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "### 3C. Why prefer `Generators` enum entries over a factory function?" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "1. **Storage potential:** a call to, for example, `Generators.GPEI` captures all arguments to the model and model bridge and stores them on a generator runs, subsequently produced by the model. Since the capturing logic is part of `Generators.__call__` function, it is not present in a factory function. Furthermore, there is no safe and flexible way to serialize callables in Python.\n", - "2. **Standardization:** While a 'factory function' is by default more flexible (accepts any specified inputs and produces a `Adapter` with an underlying `Generator` instance based on them), it is not standard in terms of its inputs. `Generators` introduces a standardized interface, making it easy to adapt any example to one's specific case." - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "### 3D. How can I request more modeling setups added to `Generators` and natively supported in Ax?" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Please open a [Github issue](https://github.com/facebook/Ax/issues) to request a new modeling setup in Ax (or for any other questions or requests)." - ] + "cells": [ + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "import sys\n", + "import plotly.io as pio\n", + "if 'google.colab' in sys.modules:\n", + " pio.renderers.default = \"colab\"\n", + " %pip install ax-platform" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "from ax.generation_strategy.dispatch_utils import choose_generation_strategy\n", + "from ax.generation_strategy.generation_strategy import GenerationStep, GenerationStrategy\n", + "from ax.modelbridge.modelbridge_utils import get_pending_observation_features\n", + "from ax.modelbridge.registry import ModelRegistryBase, Generators\n", + "\n", + "from ax.utils.testing.core_stubs import get_branin_experiment, get_branin_search_space" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Generation Strategy (GS) Tutorial\n", + "\n", + "`GenerationStrategy` ([API reference](https://ax.dev/api/modelbridge.html#ax.modelbridge.generation_strategy.GenerationStrategy)) is a key abstraction in Ax:\n", + "- It allows for specifying multiple optimization algorithms to chain one after another in the course of the optimization. \n", + "- Many higher-level APIs in Ax use generation strategies: Service and Loop APIs, `Scheduler` etc. (tutorials for all those higher-level APIs are here: https://ax.dev/tutorials/).\n", + "- Generation strategy allows for storage and resumption of modeling setups, making optimization resumable from SQL or JSON snapshots.\n", + "\n", + "This tutorial walks through a few examples of generation strategies and discusses its important settings. Before reading it, we recommend familiarizing yourself with how `Generator` and `Adapter` work in Ax: https://ax.dev/docs/models.html#deeper-dive-organization-of-the-modeling-stack.\n", + "\n", + "**Contents:**\n", + "1. Quick-start examples\n", + " 1. Manually configured GS\n", + " 2. Auto-selected GS\n", + " 3. Candidate generation from a GS\n", + "2. Deep dive: `GenerationStep` a building block of the generation strategy\n", + " 1. Describing a model\n", + " 2. Other `GenerationStep` settings\n", + " 3. Chaining `GenerationStep`-s together\n", + " 4. `max_parallelism` enforcement and handling the `MaxParallelismReachedException`\n", + "3. `GenerationStrategy` storage\n", + " 1. JSON storage\n", + " 2. SQL storage\n", + "4. Advanced considerations / \"gotchas\"\n", + " 1. Generation strategy produces `GeneratorRun`-s, not `Trial`-s\n", + " 2. `model_kwargs` elements that don't have associated serialization logic in Ax\n", + " 3. Why prefer `Models` registry enum entries over a factory function?\n", + " 4. How to request more modeling setups in `Models`?\n", + " \n", + "----" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## 1. Quick-start examples\n", + "\n", + "### 1A. Manually configured generation strategy\n", + "\n", + "Below is a typical generation strategy used for most single-objective optimization cases in Ax:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "gs = GenerationStrategy(\n", + " steps=[\n", + " # 1. Initialization step (does not require pre-existing data and is well-suited for\n", + " # initial sampling of the search space)\n", + " GenerationStep(\n", + " model=Generators.SOBOL,\n", + " num_trials=5, # How many trials should be produced from this generation step\n", + " min_trials_observed=3, # How many trials need to be completed to move to next model\n", + " max_parallelism=5, # Max parallelism for this step\n", + " model_kwargs={\"seed\": 999}, # Any kwargs you want passed into the model\n", + " model_gen_kwargs={}, # Any kwargs you want passed to `modelbridge.gen`\n", + " ),\n", + " # 2. Bayesian optimization step (requires data obtained from previous phase and learns\n", + " # from all data available at the time of each new candidate generation call)\n", + " GenerationStep(\n", + " model=Generators.BOTORCH_MODULAR,\n", + " num_trials=-1, # No limitation on how many trials should be produced from this step\n", + " max_parallelism=3, # Parallelism limit for this step, often lower than for Sobol\n", + " # More on parallelism vs. required samples in BayesOpt:\n", + " # https://ax.dev/docs/bayesopt.html#tradeoff-between-parallelism-and-total-number-of-trials\n", + " ),\n", + " ]\n", + ")" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### 1B. Auto-selected generation strategy\n", + "\n", + "Ax provides a [`choose_generation_strategy`](https://github.com/facebook/Ax/blob/main/ax/modelbridge/dispatch_utils.py#L115) utility, which can auto-select a suitable generation strategy given a search space and an array of other optional settings. The utility is fairly simple at the moment, but additional development (support for multi-objective optimization, multi-fidelity optimization, Bayesian optimization with categorical kernels etc.) is coming soon." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "gs = choose_generation_strategy(\n", + " # Required arguments:\n", + " search_space=get_branin_search_space(), # Ax `SearchSpace`\n", + " # Some optional arguments (shown with their defaults), see API docs for more settings:\n", + " # https://ax.dev/api/modelbridge.html#module-ax.modelbridge.dispatch_utils\n", + " use_batch_trials=False, # Whether this GS will be used to generate 1-arm `Trial`-s or `BatchTrials`\n", + " no_bayesian_optimization=False, # Use quasi-random candidate generation without BayesOpt\n", + " max_parallelism_override=None, # Integer, to which to set the `max_parallelism` setting of all steps in this GS\n", + ")\n", + "gs" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### 1C. Candidate generation from a generation strategy\n", + "\n", + "While often used through Service or Loop API or other higher-order abstractions like the Ax `Scheduler` (where the generation strategy is used to fit models and produce candidates from them under-the-hood), it's also possible to use the GS directly, in place of a `Adapter` instance. The interface of `GenerationStrategy.gen` is the same as `Adapter.gen`.\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "experiment = get_branin_experiment()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Note that it's important to **specify pending observations** to the call to `gen` to avoid getting the same points re-suggested. Without `pending_observations` argument, Ax models are not aware of points that should be excluded from generation. Points are considered \"pending\" when they belong to `STAGED`, `RUNNING`, or `ABANDONED` trials (with the latter included so model does not re-suggest points that are considered \"bad\" and should not be re-suggested).\n", + "\n", + "If the call to `get_pending_obervation_features` becomes slow in your setup (since it performs data-fetching etc.), you can opt for `get_pending_observation_features_based_on_trial_status` (also from `ax.modelbridge.modelbridge_utils`), but note the limitations of that utility (detailed in its docstring)." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "generator_run = gs.gen(\n", + " experiment=experiment, # Ax `Experiment`, for which to generate new candidates\n", + " data=None, # Ax `Data` to use for model training, optional.\n", + " n=1, # Number of candidate arms to produce\n", + " pending_observations=get_pending_observation_features(\n", + " experiment\n", + " ), # Points that should not be re-generated\n", + " # Any other kwargs specified will be passed through to `ModelBridge.gen` along with `GenerationStep.model_gen_kwargs`\n", + ")\n", + "generator_run" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Then we can add the newly produced [`GeneratorRun`](https://ax.dev/docs/glossary.html#generator-run) to the experiment as a [`Trial` (or `BatchTrial` if `n` > 1)](https://ax.dev/docs/glossary.html#trial):" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "trial = experiment.new_trial(generator_run)\n", + "trial" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "**Important notes on `GenerationStrategy.gen`:**\n", + "- if `data` argument above is not specified, GS will pull experiment data from cache via `experiment.lookup_data`,\n", + "- without specifying `pending_observations`, the GS (and any model in Ax) could produce the same candidate over and over, as without that argument the model is not 'aware' that the candidate is part of a `RUNNING` or `ABANDONED` trial and should not be re-suggested again.\n", + "\n", + "In cases where `get_pending_observation_features` is too slow and the experiment consists of 1-arm `Trial`-s only, it's possible to use `get_pending_observation_features_based_on_trial_status` instead (found in the same file)." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Note that when using the Ax Service API, one of the arguments to `AxClient` is `choose_generation_strategy_kwargs`; specifying that argument is a convenient way to influence the choice of generation strategy in `AxClient` without manually specifying a full `GenerationStrategy`." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "-----" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## 2. `GenerationStep` as a building block of generation strategy" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### 2A. Describing a generator to use in a given `GenerationStep`\n", + "\n", + "There are two ways of specifying a generator for a generation step: via an entry in a `Models` enum or via a 'factory function' –– a callable generator constructor (e.g. [`get_GPEI`](https://github.com/facebook/Ax/blob/0e454b71d5e07b183c0866855555b6a21ddd5da1/ax/modelbridge/factory.py#L154) and other factory functions in the same file). Note that using the latter path, a factory function, will prohibit `GenerationStrategy` storage and is generally discouraged. " + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### 2B. Other `GenerationStep` settings\n", + "\n", + "All of the available settings are described in the documentation:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "print(GenerationStep.__doc__)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## 2C. Chaining `GenerationStep`-s together\n", + "\n", + "A `GenerationStrategy` moves from one step to another when: \n", + "1. `N=num_trials` generator runs were produced and attached as trials to the experiment AND \n", + "2. `M=min_trials_observed` have been completed and have data.\n", + "\n", + "**Caveat: `enforce_num_trials` setting**:\n", + "\n", + "1. If `enforce_num_trials=True` for a given generation step, if 1) is reached but 2) is not yet reached, the generation strategy will raise a `DataRequiredError`, indicating that more trials need to be completed before the next step.\n", + "2. If `enforce_num_trials=False`, the GS will continue producing generator runs from the current step until 2) is reached." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## 2D. `max_parallelism` enforcement\n", + "\n", + "Generation strategy can restrict the number of trials that can be ran simultaneously (to encourage sequential optimization, which benefits Bayesian optimization performance). When the parallelism limit is reached, a call to `GenerationStrategy.gen` will result in a `MaxParallelismReachedException`.\n", + "\n", + "The correct way to handle this exception:\n", + "1. Make sure that `GenerationStep.max_parallelism` is configured correctly for all steps in your generation strategy (to disable it completely, configure `GenerationStep.max_parallelism=None`),\n", + "2. When encountering the exception, wait to produce more generator runs until more trial evluations complete and log the trial completion via `trial.mark_completed`." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "----\n", + "\n", + "## 3. SQL and JSON storage of a generation strategy" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "When used through Service API or `Scheduler`, generation strategy will be automatically stored to SQL or JSON via specifying `DBSettings` to either `AxClient` or `Scheduler` (details in respective tutorials in the [\"Tutorials\" page](https://ax.dev/tutorials/)). Generation strategy can also be stored to SQL or JSON individually, as shown below.\n", + "\n", + "More detail on SQL and JSON storage in Ax generally can be [found in \"Building Blocks of Ax\" tutorial](https://ax.dev/tutorials/building_blocks.html#9.-Save-to-JSON-or-SQL)." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### 3A. SQL storage\n", + "For SQL storage setup in Ax, read through the [\"Storage\" documentation page](https://ax.dev/docs/storage.html).\n", + "\n", + "Note that unlike an Ax experiment, a generation strategy does not have a name or another unique identifier. Therefore, a generation strategy is stored in association with experiment and can be retrieved by the associated experiment's name." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "from ax.storage.sqa_store.db import (\n", + " create_all_tables,\n", + " get_engine,\n", + " init_engine_and_session_factory,\n", + ")\n", + "from ax.storage.sqa_store.load import (\n", + " load_experiment,\n", + " load_generation_strategy_by_experiment_name,\n", + ")\n", + "from ax.storage.sqa_store.save import save_experiment, save_generation_strategy\n", + "\n", + "init_engine_and_session_factory(url=\"sqlite:///foo2.db\")\n", + "\n", + "engine = get_engine()\n", + "create_all_tables(engine)\n", + "\n", + "save_experiment(experiment)\n", + "save_generation_strategy(gs)\n", + "\n", + "experiment = load_experiment(experiment_name=experiment.name)\n", + "gs = load_generation_strategy_by_experiment_name(\n", + " experiment_name=experiment.name,\n", + " experiment=experiment, # Can optionally specify experiment object to avoid loading it from database twice\n", + ")\n", + "gs" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### 3B. JSON storage" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "from ax.storage.json_store.decoder import object_from_json\n", + "from ax.storage.json_store.encoder import object_to_json\n", + "\n", + "gs_json = object_to_json(gs) # Can be written to a file or string via `json.dump` etc.\n", + "gs = object_from_json(\n", + " gs_json\n", + ") # Decoded back from JSON (can be loaded from file, string via `json.load` etc.)\n", + "gs" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "------" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## 3. Advanced considerations\n", + "\n", + "Below is a list of important \"gotchas\" of using generation strategy (especially outside of the higher-level APIs like the Service API or the `Scheduler`):\n", + "\n", + "### 3A. `GenerationStrategy.gen` produces `GeneratorRun`-s, not trials\n", + "\n", + "Since `GenerationStrategy.gen` mimics `Adapter.gen` and allows for human-in-the-loop usage mode, a call to `gen` produces a `GeneratorRun`, which can then be added (or altered before addition or not added at all) to a `Trial` or `BatchTrial` on a given experiment. So it's important to add the generator run to a trial, since otherwise it will not be attached to the experiment on its own." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "generator_run = gs.gen(\n", + " experiment=experiment,\n", + " n=1,\n", + " pending_observations=get_pending_observation_features(experiment),\n", + ")\n", + "experiment.new_trial(generator_run)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### 3B. `model_kwargs` elements that do not define serialization logic in Ax" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Note that passing objects that are not yet serializable in Ax (e.g. a BoTorch `Prior` object) as part of `GenerationStep.model_kwargs` or `GenerationStep.model_gen_kwargs` will prevent correct generation strategy storage. If this becomes a problem, feel free to open an issue on our Github: https://github.com/facebook/Ax/issues to get help with adding storage support for a given object." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### 3C. Why prefer `Generators` enum entries over a factory function?" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "1. **Storage potential:** a call to, for example, `Generators.GPEI` captures all arguments to the model and model bridge and stores them on a generator runs, subsequently produced by the model. Since the capturing logic is part of `Generators.__call__` function, it is not present in a factory function. Furthermore, there is no safe and flexible way to serialize callables in Python.\n", + "2. **Standardization:** While a 'factory function' is by default more flexible (accepts any specified inputs and produces a `Adapter` with an underlying `Generator` instance based on them), it is not standard in terms of its inputs. `Generators` introduces a standardized interface, making it easy to adapt any example to one's specific case." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### 3D. How can I request more modeling setups added to `Generators` and natively supported in Ax?" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Please open a [Github issue](https://github.com/facebook/Ax/issues) to request a new modeling setup in Ax (or for any other questions or requests)." + ] + } + ], + "metadata": { + "fileHeader": "", + "fileUid": "c4c08c05-f1da-4986-bd41-fe7baa26d589", + "isAdHoc": false, + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.10.16" + } } - ], - "metadata": { - "kernelspec": { - "display_name": "Python 3 (ipykernel)", - "language": "python", - "name": "python3" - }, - "language_info": { - "codemirror_mode": { - "name": "ipython", - "version": 3 - }, - "file_extension": ".py", - "mimetype": "text/x-python", - "name": "python", - "nbconvert_exporter": "python", - "pygments_lexer": "ipython3", - "version": "3.10.16" - } - }, - "nbformat": 4, - "nbformat_minor": 4 } diff --git a/tutorials/modular_botax/modular_botax.ipynb b/tutorials/modular_botax/modular_botax.ipynb index 8b822a6e6c3..c2f924fdb16 100644 --- a/tutorials/modular_botax/modular_botax.ipynb +++ b/tutorials/modular_botax/modular_botax.ipynb @@ -1,1471 +1,1472 @@ { - "cells": [ - { - "cell_type": "code", - "execution_count": null, - "id": "dc0b0d48", - "metadata": {}, - "outputs": [], - "source": [ - "import sys\n", - "import plotly.io as pio\n", - "if 'google.colab' in sys.modules:\n", - " pio.renderers.default = \"colab\"\n", - " %pip install ax-platform" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "eda150e5", - "metadata": { - "collapsed": false, - "customOutput": null, - "executionStartTime": 1730916291451, - "executionStopTime": 1730916298337, - "id": "about-preview", - "isAgentGenerated": false, - "jupyter": { - "outputs_hidden": false - }, - "language": "python", - "metadata": { - "originalKey": "cca773d8-5e94-4b5a-ae54-22295be8936a" - }, - "originalKey": "f4e8ae18-2aa3-4943-a15a-29851889445c", - "outputsInitialized": true, - "requestMsgId": "f4e8ae18-2aa3-4943-a15a-29851889445c", - "serverExecutionDuration": 4531.2523420434 - }, - "outputs": [], - "source": [ - "from typing import Any, Dict, Optional, Tuple, Type\n", - "\n", - "from ax.modelbridge.registry import Generators\n", - "\n", - "# Ax data tranformation layer\n", - "from ax.models.torch.botorch_modular.acquisition import Acquisition\n", - "\n", - "# Ax wrappers for BoTorch components\n", - "from ax.models.torch.botorch_modular.model import BoTorchGenerator\n", - "from ax.models.torch.botorch_modular.surrogate import Surrogate, SurrogateSpec\n", - "from ax.models.torch.botorch_modular.utils import ModelConfig\n", - "\n", - "# Experiment examination utilities\n", - "from ax.service.utils.report_utils import exp_to_df\n", - "\n", - "# Test Ax objects\n", - "from ax.utils.testing.core_stubs import (\n", - " get_branin_data,\n", - " get_branin_data_multi_objective,\n", - " get_branin_experiment,\n", - " get_branin_experiment_with_multi_objective,\n", - ")\n", - "from botorch.acquisition.logei import (\n", - " qLogExpectedImprovement,\n", - " qLogNoisyExpectedImprovement,\n", - ")\n", - "from botorch.models.gp_regression import SingleTaskGP\n", - "\n", - "# BoTorch components\n", - "from botorch.models.model import Model\n", - "from gpytorch.mlls.exact_marginal_log_likelihood import ExactMarginalLogLikelihood" - ] - }, - { - "cell_type": "markdown", - "id": "d6f55f44", - "metadata": { - "id": "northern-affairs", - "isAgentGenerated": false, - "language": "markdown", - "metadata": { - "originalKey": "58ea5ebf-ff3a-40b4-8be3-1b85c99d1c4a" - }, - "originalKey": "c9a665ca-497e-4d7c-bbb5-1b9f8d1d311c", - "outputsInitialized": false, - "showInput": false - }, - "source": [ - "# Setup and Usage of BoTorch Models in Ax\n", - "\n", - "Ax provides a set of flexible wrapper abstractions to mix-and-match BoTorch components like `Model` and `AcquisitionFunction` and combine them into a single `Generator` object in Ax. The wrapper abstractions: `Surrogate`, `Acquisition`, and `BoTorchGenerator` – are located in `ax/models/torch/botorch_modular` directory and aim to encapsulate boilerplate code that interfaces between Ax and BoTorch. This functionality is in beta-release and still evolving.\n", - "\n", - "This tutorial walks through setting up a custom combination of BoTorch components in Ax in following steps:\n", - "\n", - "1. **Quick-start example of `BoTorchGenerator` use**\n", - "1. **`BoTorchGenerator` = `Surrogate` + `Acquisition` (overview)**\n", - " 1. Example with minimal options that uses the defaults\n", - " 2. Example showing all possible options\n", - " 3. Surrogate and Acquisition Q&A\n", - "2. **I know which Botorch Model and AcquisitionFunction I'd like to combine in Ax. How do set this up?**\n", - " 1. Making a `Surrogate` from BoTorch `Model`\n", - " 2. Using an arbitrary BoTorch `AcquisitionFunction` in Ax\n", - "3. **Using `Generators.BOTORCH_MODULAR`** (convenience wrapper that enables storage and resumability)\n", - "4. **Utilizing `BoTorchGenerator` in generation strategies** (abstraction that allows to chain models together and use them in Ax Service API etc.)\n", - " 1. Specifying `pending_observations` to avoid the model re-suggesting points that are part of `RUNNING` or `ABANDONED` trials.\n", - "5. **Customizing a `Surrogate` or `Acquisition`** (for cases where existing subcomponent classes are not sufficient)" - ] - }, - { - "cell_type": "markdown", - "id": "835d6cf9", - "metadata": { - "id": "pending-support", - "isAgentGenerated": false, - "language": "markdown", - "metadata": { - "originalKey": "c06d1b5c-067d-4618-977e-c8269a98bd0a" - }, - "originalKey": "4706d02e-6b3f-4161-9e08-f5a31328b1d1", - "outputsInitialized": false, - "showInput": false - }, - "source": [ - "## 1. Quick-start example\n", - "\n", - "Here we set up a `BoTorchGenerator` with `SingleTaskGP` with `qLogNoisyExpectedImprovement`, one of the most popular combinations in Ax:" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "6a2d738c", - "metadata": { - "collapsed": false, - "customOutput": null, - "executionStartTime": 1730916294801, - "executionStopTime": 1730916298389, - "id": "parental-sending", - "isAgentGenerated": false, - "jupyter": { - "outputs_hidden": false - }, - "language": "python", - "metadata": { - "originalKey": "72934cf2-4ecf-483a-93bd-4df88b19a7b8" - }, - "originalKey": "20f25ded-5aae-47ee-955e-a2d5a2a1fe09", - "outputsInitialized": true, - "requestMsgId": "20f25ded-5aae-47ee-955e-a2d5a2a1fe09", - "serverExecutionDuration": 22.605526028201 - }, - "outputs": [], - "source": [ - "experiment = get_branin_experiment(with_trial=True)\n", - "data = get_branin_data(trials=[experiment.trials[0]])" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "b60e1c29", - "metadata": { - "collapsed": false, - "executionStartTime": 1730916295849, - "executionStopTime": 1730916299900, - "id": "rough-somerset", - "isAgentGenerated": false, - "jupyter": { - "outputs_hidden": false - }, - "language": "python", - "metadata": { - "originalKey": "e571212c-7872-4ebc-b646-8dad8d4266fd" - }, - "originalKey": "c0806cce-a1d3-41b8-96fc-678aa3c9dd92", - "outputsInitialized": true, - "requestMsgId": "c0806cce-a1d3-41b8-96fc-678aa3c9dd92", - "serverExecutionDuration": 852.73489891551 - }, - "outputs": [], - "source": [ - "# `Generators` automatically selects a model + model bridge combination.\n", - "# For `BOTORCH_MODULAR`, it will select `BoTorchModel` and `TorchModelBridge`.\n", - "adapter_with_GPEI = Generators.BOTORCH_MODULAR(\n", - " experiment=experiment,\n", - " data=data,\n", - " surrogate_spec=SurrogateSpec(\n", - " model_configs=[ModelConfig(botorch_model_class=SingleTaskGP)]\n", - " ), # Optional, will use default if unspecified\n", - " botorch_acqf_class=qLogNoisyExpectedImprovement, # Optional, will use default if unspecified\n", - ")" - ] - }, - { - "cell_type": "markdown", - "id": "154ef580", - "metadata": { - "id": "hairy-wiring", - "isAgentGenerated": false, - "language": "markdown", - "metadata": { - "originalKey": "fba91372-7aa6-456d-a22b-78ab30c26cd8" + "cells": [ + { + "cell_type": "code", + "execution_count": null, + "id": "dc0b0d48", + "metadata": {}, + "outputs": [], + "source": [ + "import sys\n", + "import plotly.io as pio\n", + "if 'google.colab' in sys.modules:\n", + " pio.renderers.default = \"colab\"\n", + " %pip install ax-platform" + ] }, - "originalKey": "46f5c2c7-400d-4d8d-b0b9-a241657b173f", - "outputsInitialized": false, - "showInput": false - }, - "source": [ - "Now we can use this model to generate candidates (`gen`), predict outcome at a point (`predict`), or evaluate acquisition function value at a given point (`evaluate_acquisition_function`)." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "72dee941", - "metadata": { - "collapsed": false, - "executionStartTime": 1730916299852, - "executionStopTime": 1730916300305, - "id": "consecutive-summary", - "isAgentGenerated": false, - "jupyter": { - "outputs_hidden": false + { + "cell_type": "code", + "execution_count": null, + "id": "eda150e5", + "metadata": { + "collapsed": false, + "customOutput": null, + "executionStartTime": 1730916291451, + "executionStopTime": 1730916298337, + "id": "about-preview", + "isAgentGenerated": false, + "jupyter": { + "outputs_hidden": false + }, + "language": "python", + "metadata": { + "originalKey": "cca773d8-5e94-4b5a-ae54-22295be8936a" + }, + "originalKey": "f4e8ae18-2aa3-4943-a15a-29851889445c", + "outputsInitialized": true, + "requestMsgId": "f4e8ae18-2aa3-4943-a15a-29851889445c", + "serverExecutionDuration": 4531.2523420434 + }, + "outputs": [], + "source": [ + "from typing import Any, Dict, Optional, Tuple, Type\n", + "\n", + "from ax.modelbridge.registry import Generators\n", + "\n", + "# Ax data tranformation layer\n", + "from ax.models.torch.botorch_modular.acquisition import Acquisition\n", + "\n", + "# Ax wrappers for BoTorch components\n", + "from ax.models.torch.botorch_modular.model import BoTorchGenerator\n", + "from ax.models.torch.botorch_modular.surrogate import Surrogate, SurrogateSpec\n", + "from ax.models.torch.botorch_modular.utils import ModelConfig\n", + "\n", + "# Experiment examination utilities\n", + "from ax.service.utils.report_utils import exp_to_df\n", + "\n", + "# Test Ax objects\n", + "from ax.utils.testing.core_stubs import (\n", + " get_branin_data,\n", + " get_branin_data_multi_objective,\n", + " get_branin_experiment,\n", + " get_branin_experiment_with_multi_objective,\n", + ")\n", + "from botorch.acquisition.logei import (\n", + " qLogExpectedImprovement,\n", + " qLogNoisyExpectedImprovement,\n", + ")\n", + "from botorch.models.gp_regression import SingleTaskGP\n", + "\n", + "# BoTorch components\n", + "from botorch.models.model import Model\n", + "from gpytorch.mlls.exact_marginal_log_likelihood import ExactMarginalLogLikelihood" + ] }, - "language": "python", - "metadata": { - "originalKey": "59582fc6-8089-4320-864e-d98ee271d4f7" + { + "cell_type": "markdown", + "id": "d6f55f44", + "metadata": { + "id": "northern-affairs", + "isAgentGenerated": false, + "language": "markdown", + "metadata": { + "originalKey": "58ea5ebf-ff3a-40b4-8be3-1b85c99d1c4a" + }, + "originalKey": "c9a665ca-497e-4d7c-bbb5-1b9f8d1d311c", + "outputsInitialized": false, + "showInput": false + }, + "source": [ + "# Setup and Usage of BoTorch Models in Ax\n", + "\n", + "Ax provides a set of flexible wrapper abstractions to mix-and-match BoTorch components like `Model` and `AcquisitionFunction` and combine them into a single `Generator` object in Ax. The wrapper abstractions: `Surrogate`, `Acquisition`, and `BoTorchGenerator` – are located in `ax/models/torch/botorch_modular` directory and aim to encapsulate boilerplate code that interfaces between Ax and BoTorch. This functionality is in beta-release and still evolving.\n", + "\n", + "This tutorial walks through setting up a custom combination of BoTorch components in Ax in following steps:\n", + "\n", + "1. **Quick-start example of `BoTorchGenerator` use**\n", + "1. **`BoTorchGenerator` = `Surrogate` + `Acquisition` (overview)**\n", + " 1. Example with minimal options that uses the defaults\n", + " 2. Example showing all possible options\n", + " 3. Surrogate and Acquisition Q&A\n", + "2. **I know which Botorch Model and AcquisitionFunction I'd like to combine in Ax. How do set this up?**\n", + " 1. Making a `Surrogate` from BoTorch `Model`\n", + " 2. Using an arbitrary BoTorch `AcquisitionFunction` in Ax\n", + "3. **Using `Generators.BOTORCH_MODULAR`** (convenience wrapper that enables storage and resumability)\n", + "4. **Utilizing `BoTorchGenerator` in generation strategies** (abstraction that allows to chain models together and use them in Ax Service API etc.)\n", + " 1. Specifying `pending_observations` to avoid the model re-suggesting points that are part of `RUNNING` or `ABANDONED` trials.\n", + "5. **Customizing a `Surrogate` or `Acquisition`** (for cases where existing subcomponent classes are not sufficient)" + ] }, - "originalKey": "f64e9d2e-bfd4-47da-8292-dbe7e70cbe1f", - "outputsInitialized": true, - "requestMsgId": "f64e9d2e-bfd4-47da-8292-dbe7e70cbe1f", - "serverExecutionDuration": 233.20194100961 - }, - "outputs": [], - "source": [ - "generator_run = adapter_with_GPEI.gen(n=1)\n", - "generator_run.arms[0]" - ] - }, - { - "cell_type": "markdown", - "id": "b0096e71", - "metadata": { - "id": "diverse-richards", - "isAgentGenerated": false, - "language": "markdown", - "metadata": { - "originalKey": "8cfe0fa9-8cce-4718-ba43-e8a63744d626" + { + "cell_type": "markdown", + "id": "835d6cf9", + "metadata": { + "id": "pending-support", + "isAgentGenerated": false, + "language": "markdown", + "metadata": { + "originalKey": "c06d1b5c-067d-4618-977e-c8269a98bd0a" + }, + "originalKey": "4706d02e-6b3f-4161-9e08-f5a31328b1d1", + "outputsInitialized": false, + "showInput": false + }, + "source": [ + "## 1. Quick-start example\n", + "\n", + "Here we set up a `BoTorchGenerator` with `SingleTaskGP` with `qLogNoisyExpectedImprovement`, one of the most popular combinations in Ax:" + ] }, - "originalKey": "804bac30-db07-4444-98a2-7a5f05007495", - "outputsInitialized": false, - "showInput": false - }, - "source": [ - "-----\n", - "Before you read the rest of this tutorial:\n", - "\n", - "- We use ['Generator'](https://ax.dev/docs/glossary.html#model) to refer to an optimization setup capable of producing candidate points for optimization (and often capable of being fit to data, with exception for quasi-random generators). See [Generators documentation page](https://ax.dev/docs/models.html) for more information.\n", - "- Learn about `Adapter` in Ax, as users should rarely be interacting with a `Generator` object directly (more about Adapter, a data transformation layer in Ax, [here](https://ax.dev/docs/models.html#deeper-dive-organization-of-the-modeling-stack))." - ] - }, - { - "cell_type": "markdown", - "id": "e3fc3685", - "metadata": { - "id": "grand-committee", - "isAgentGenerated": false, - "language": "markdown", - "metadata": { - "originalKey": "7037fd14-bcfe-44f9-b915-c23915d2bda9" + { + "cell_type": "code", + "execution_count": null, + "id": "6a2d738c", + "metadata": { + "collapsed": false, + "customOutput": null, + "executionStartTime": 1730916294801, + "executionStopTime": 1730916298389, + "id": "parental-sending", + "isAgentGenerated": false, + "jupyter": { + "outputs_hidden": false + }, + "language": "python", + "metadata": { + "originalKey": "72934cf2-4ecf-483a-93bd-4df88b19a7b8" + }, + "originalKey": "20f25ded-5aae-47ee-955e-a2d5a2a1fe09", + "outputsInitialized": true, + "requestMsgId": "20f25ded-5aae-47ee-955e-a2d5a2a1fe09", + "serverExecutionDuration": 22.605526028201 + }, + "outputs": [], + "source": [ + "experiment = get_branin_experiment(with_trial=True)\n", + "data = get_branin_data(trials=[experiment.trials[0]])" + ] }, - "originalKey": "31b54ce5-2590-4617-b10c-d24ed3cce51d", - "outputsInitialized": false, - "showInput": false - }, - "source": [ - "## 2. BoTorchGenerator = Surrogate + Acquisition\n", - "\n", - "A `BoTorchGenerator` in Ax consists of two main subcomponents: a surrogate model and an acquisition function. A surrogate model is represented as an instance of Ax’s `Surrogate` class, which is a wrapper around BoTorch's `Model` class. The Surrogate is defined by a `SurrogateSpec`. The acquisition function is represented as an instance of Ax’s `Acquisition` class, a wrapper around BoTorch's `AcquisitionFunction` class." - ] - }, - { - "cell_type": "markdown", - "id": "2a3f2ed1", - "metadata": { - "id": "thousand-blanket", - "isAgentGenerated": false, - "language": "markdown", - "metadata": { - "originalKey": "08b12c6c-14da-4342-95bd-f607a131ce9d" + { + "cell_type": "code", + "execution_count": null, + "id": "b60e1c29", + "metadata": { + "collapsed": false, + "executionStartTime": 1730916295849, + "executionStopTime": 1730916299900, + "id": "rough-somerset", + "isAgentGenerated": false, + "jupyter": { + "outputs_hidden": false + }, + "language": "python", + "metadata": { + "originalKey": "e571212c-7872-4ebc-b646-8dad8d4266fd" + }, + "originalKey": "c0806cce-a1d3-41b8-96fc-678aa3c9dd92", + "outputsInitialized": true, + "requestMsgId": "c0806cce-a1d3-41b8-96fc-678aa3c9dd92", + "serverExecutionDuration": 852.73489891551 + }, + "outputs": [], + "source": [ + "# `Generators` automatically selects a model + model bridge combination.\n", + "# For `BOTORCH_MODULAR`, it will select `BoTorchModel` and `TorchModelBridge`.\n", + "adapter_with_GPEI = Generators.BOTORCH_MODULAR(\n", + " experiment=experiment,\n", + " data=data,\n", + " surrogate_spec=SurrogateSpec(\n", + " model_configs=[ModelConfig(botorch_model_class=SingleTaskGP)]\n", + " ), # Optional, will use default if unspecified\n", + " botorch_acqf_class=qLogNoisyExpectedImprovement, # Optional, will use default if unspecified\n", + ")" + ] }, - "originalKey": "4a4e006e-07fa-4d63-8b9a-31b67075e40e", - "outputsInitialized": false, - "showInput": false - }, - "source": [ - "### 2A. Example that uses defaults and requires no options\n", - "\n", - "`BoTorchGenerator` does not always require surrogate and acquisition specification. If instantiated without one or both components specified, defaults are selected based on properties of experiment and data (see Appendix 2 for auto-selection logic)." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "65469897", - "metadata": { - "collapsed": false, - "executionStartTime": 1730916302730, - "executionStopTime": 1730916304031, - "id": "changing-xerox", - "isAgentGenerated": false, - "jupyter": { - "outputs_hidden": false + { + "cell_type": "markdown", + "id": "154ef580", + "metadata": { + "id": "hairy-wiring", + "isAgentGenerated": false, + "language": "markdown", + "metadata": { + "originalKey": "fba91372-7aa6-456d-a22b-78ab30c26cd8" + }, + "originalKey": "46f5c2c7-400d-4d8d-b0b9-a241657b173f", + "outputsInitialized": false, + "showInput": false + }, + "source": [ + "Now we can use this model to generate candidates (`gen`), predict outcome at a point (`predict`), or evaluate acquisition function value at a given point (`evaluate_acquisition_function`)." + ] }, - "language": "python", - "metadata": { - "originalKey": "b1bca702-07b2-4818-b2b9-2107268c383c" + { + "cell_type": "code", + "execution_count": null, + "id": "72dee941", + "metadata": { + "collapsed": false, + "executionStartTime": 1730916299852, + "executionStopTime": 1730916300305, + "id": "consecutive-summary", + "isAgentGenerated": false, + "jupyter": { + "outputs_hidden": false + }, + "language": "python", + "metadata": { + "originalKey": "59582fc6-8089-4320-864e-d98ee271d4f7" + }, + "originalKey": "f64e9d2e-bfd4-47da-8292-dbe7e70cbe1f", + "outputsInitialized": true, + "requestMsgId": "f64e9d2e-bfd4-47da-8292-dbe7e70cbe1f", + "serverExecutionDuration": 233.20194100961 + }, + "outputs": [], + "source": [ + "generator_run = adapter_with_GPEI.gen(n=1)\n", + "generator_run.arms[0]" + ] }, - "originalKey": "fa86552a-0b80-4040-a0c4-61a0de37bdc1", - "outputsInitialized": true, - "requestMsgId": "fa86552a-0b80-4040-a0c4-61a0de37bdc1", - "serverExecutionDuration": 1.7747740494087 - }, - "outputs": [], - "source": [ - "# The surrogate is not specified, so it will be auto-selected\n", - "# during `model.fit`.\n", - "GPEI_model = BoTorchGenerator(botorch_acqf_class=qLogExpectedImprovement)\n", - "\n", - "# The acquisition class is not specified, so it will be\n", - "# auto-selected during `model.gen` or `model.evaluate_acquisition`\n", - "GPEI_model = BoTorchGenerator(\n", - " surrogate_spec=SurrogateSpec(\n", - " model_configs=[ModelConfig(botorch_model_class=SingleTaskGP)]\n", - " )\n", - ")\n", - "\n", - "# Both the surrogate and acquisition class will be auto-selected.\n", - "GPEI_model = BoTorchGenerator()" - ] - }, - { - "cell_type": "markdown", - "id": "5b63129f", - "metadata": { - "id": "lovely-mechanics", - "isAgentGenerated": false, - "language": "markdown", - "metadata": { - "originalKey": "5cec0f06-ae2c-47d3-bd95-441c45762e38" + { + "cell_type": "markdown", + "id": "b0096e71", + "metadata": { + "id": "diverse-richards", + "isAgentGenerated": false, + "language": "markdown", + "metadata": { + "originalKey": "8cfe0fa9-8cce-4718-ba43-e8a63744d626" + }, + "originalKey": "804bac30-db07-4444-98a2-7a5f05007495", + "outputsInitialized": false, + "showInput": false + }, + "source": [ + "-----\n", + "Before you read the rest of this tutorial:\n", + "\n", + "- We use ['Generator'](https://ax.dev/docs/glossary.html#model) to refer to an optimization setup capable of producing candidate points for optimization (and often capable of being fit to data, with exception for quasi-random generators). See [Generators documentation page](https://ax.dev/docs/models.html) for more information.\n", + "- Learn about `Adapter` in Ax, as users should rarely be interacting with a `Generator` object directly (more about Adapter, a data transformation layer in Ax, [here](https://ax.dev/docs/models.html#deeper-dive-organization-of-the-modeling-stack))." + ] }, - "originalKey": "7b9fae38-fe5d-4e5b-8b5f-2953c1ef09d2", - "outputsInitialized": false, - "showInput": false - }, - "source": [ - "### 2B. Example with all the options\n", - "Below are the full set of configurable settings of a `BoTorchGenerator` with their descriptions:" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "06f04d49", - "metadata": { - "collapsed": false, - "executionStartTime": 1730916305930, - "executionStopTime": 1730916306168, - "id": "twenty-greek", - "isAgentGenerated": false, - "jupyter": { - "outputs_hidden": false + { + "cell_type": "markdown", + "id": "e3fc3685", + "metadata": { + "id": "grand-committee", + "isAgentGenerated": false, + "language": "markdown", + "metadata": { + "originalKey": "7037fd14-bcfe-44f9-b915-c23915d2bda9" + }, + "originalKey": "31b54ce5-2590-4617-b10c-d24ed3cce51d", + "outputsInitialized": false, + "showInput": false + }, + "source": [ + "## 2. BoTorchGenerator = Surrogate + Acquisition\n", + "\n", + "A `BoTorchGenerator` in Ax consists of two main subcomponents: a surrogate model and an acquisition function. A surrogate model is represented as an instance of Ax’s `Surrogate` class, which is a wrapper around BoTorch's `Model` class. The Surrogate is defined by a `SurrogateSpec`. The acquisition function is represented as an instance of Ax’s `Acquisition` class, a wrapper around BoTorch's `AcquisitionFunction` class." + ] }, - "language": "python", - "metadata": { - "originalKey": "25b13c48-edb0-4b3f-ba34-4f4a4176162a" + { + "cell_type": "markdown", + "id": "2a3f2ed1", + "metadata": { + "id": "thousand-blanket", + "isAgentGenerated": false, + "language": "markdown", + "metadata": { + "originalKey": "08b12c6c-14da-4342-95bd-f607a131ce9d" + }, + "originalKey": "4a4e006e-07fa-4d63-8b9a-31b67075e40e", + "outputsInitialized": false, + "showInput": false + }, + "source": [ + "### 2A. Example that uses defaults and requires no options\n", + "\n", + "`BoTorchGenerator` does not always require surrogate and acquisition specification. If instantiated without one or both components specified, defaults are selected based on properties of experiment and data (see Appendix 2 for auto-selection logic)." + ] }, - "originalKey": "8d824e37-b087-4bab-9b16-4354e9509df7", - "outputsInitialized": true, - "requestMsgId": "8d824e37-b087-4bab-9b16-4354e9509df7", - "serverExecutionDuration": 2.6916969800368 - }, - "outputs": [], - "source": [ - "model = BoTorchGenerator(\n", - " # Optional `Surrogate` specification to use instead of default\n", - " surrogate_spec=SurrogateSpec(\n", - " model_configs=[\n", - " ModelConfig(\n", - " # BoTorch `Model` type\n", - " botorch_model_class=SingleTaskGP,\n", - " # Optional, MLL class with which to optimize model parameters\n", - " mll_class=ExactMarginalLogLikelihood,\n", - " # Optional, dictionary of keyword arguments to underlying\n", - " # BoTorch `Model` constructor\n", - " model_options={},\n", - " )\n", - " ]\n", - " ),\n", - " # Optional BoTorch `AcquisitionFunction` to use instead of default\n", - " botorch_acqf_class=qLogExpectedImprovement,\n", - " # Optional dict of keyword arguments, passed to the input\n", - " # constructor for the given BoTorch `AcquisitionFunction`\n", - " acquisition_options={},\n", - " # Optional Ax `Acquisition` subclass (if the given BoTorch\n", - " # `AcquisitionFunction` requires one, which is rare)\n", - " acquisition_class=None,\n", - " # Less common model settings shown with default values, refer\n", - " # to `BoTorchModel` documentation for detail\n", - " refit_on_cv=False,\n", - " warm_start_refit=True,\n", - ")" - ] - }, - { - "cell_type": "markdown", - "id": "91771a7f", - "metadata": { - "id": "fourth-material", - "isAgentGenerated": false, - "language": "markdown", - "metadata": { - "originalKey": "db0feafe-8af9-40a3-9f67-72c7d1fd808e" + { + "cell_type": "code", + "execution_count": null, + "id": "65469897", + "metadata": { + "collapsed": false, + "executionStartTime": 1730916302730, + "executionStopTime": 1730916304031, + "id": "changing-xerox", + "isAgentGenerated": false, + "jupyter": { + "outputs_hidden": false + }, + "language": "python", + "metadata": { + "originalKey": "b1bca702-07b2-4818-b2b9-2107268c383c" + }, + "originalKey": "fa86552a-0b80-4040-a0c4-61a0de37bdc1", + "outputsInitialized": true, + "requestMsgId": "fa86552a-0b80-4040-a0c4-61a0de37bdc1", + "serverExecutionDuration": 1.7747740494087 + }, + "outputs": [], + "source": [ + "# The surrogate is not specified, so it will be auto-selected\n", + "# during `model.fit`.\n", + "GPEI_model = BoTorchGenerator(botorch_acqf_class=qLogExpectedImprovement)\n", + "\n", + "# The acquisition class is not specified, so it will be\n", + "# auto-selected during `model.gen` or `model.evaluate_acquisition`\n", + "GPEI_model = BoTorchGenerator(\n", + " surrogate_spec=SurrogateSpec(\n", + " model_configs=[ModelConfig(botorch_model_class=SingleTaskGP)]\n", + " )\n", + ")\n", + "\n", + "# Both the surrogate and acquisition class will be auto-selected.\n", + "GPEI_model = BoTorchGenerator()" + ] }, - "originalKey": "7140bb19-09b4-4abe-951d-53902ae07833", - "outputsInitialized": false, - "showInput": false - }, - "source": [ - "## 2C. `Surrogate` and `Acquisition` Q&A\n", - "\n", - "**Why is the `surrogate` argument expected to be an instance, but `botorch_acqf_class` –– a class?** Because a BoTorch `AcquisitionFunction` object (and therefore its Ax wrapper, `Acquisition`) is ephemeral: it is constructed, immediately used, and destroyed during `BoTorchGenerator.gen`, so there is no reason to keep around an `Acquisition` instance. A `Surrogate`, on another hand, is kept in memory as long as its parent `BoTorchGenerator` is.\n", - "\n", - "**How to know when to use specify acquisition_class (and thereby a non-default Acquisition type) instead of just passing in botorch_acqf_class?** In short, custom `Acquisition` subclasses are needed when a given `AcquisitionFunction` in BoTorch needs some non-standard subcomponents or inputs (e.g. a custom BoTorch `MCAcquisitionObjective`). \n", - "\n", - "**Please post any other questions you have to our dedicated issue on Github: https://github.com/facebook/Ax/issues/363.** This functionality is in beta-release and your feedback will be of great help to us!" - ] - }, - { - "cell_type": "markdown", - "id": "f801bfce", - "metadata": { - "id": "violent-course", - "isAgentGenerated": false, - "language": "markdown", - "metadata": { - "originalKey": "86018ee5-f7b8-41ae-8e2d-460fe5f0c15b" + { + "cell_type": "markdown", + "id": "5b63129f", + "metadata": { + "id": "lovely-mechanics", + "isAgentGenerated": false, + "language": "markdown", + "metadata": { + "originalKey": "5cec0f06-ae2c-47d3-bd95-441c45762e38" + }, + "originalKey": "7b9fae38-fe5d-4e5b-8b5f-2953c1ef09d2", + "outputsInitialized": false, + "showInput": false + }, + "source": [ + "### 2B. Example with all the options\n", + "Below are the full set of configurable settings of a `BoTorchGenerator` with their descriptions:" + ] }, - "originalKey": "71f92895-874d-4fc7-ae87-a5519b18d1a0", - "outputsInitialized": false, - "showInput": false - }, - "source": [ - "## 3. I know which Botorch `Model` and `AcquisitionFunction` I'd like to combine in Ax. How do set this up?" - ] - }, - { - "cell_type": "markdown", - "id": "1a08a274", - "metadata": { - "id": "unlike-football", - "isAgentGenerated": false, - "language": "markdown", - "metadata": { - "code_folding": [], - "hidden_ranges": [], - "originalKey": "b29a846d-d7bc-4143-8318-10170c9b4298", - "showInput": false + { + "cell_type": "code", + "execution_count": null, + "id": "06f04d49", + "metadata": { + "collapsed": false, + "executionStartTime": 1730916305930, + "executionStopTime": 1730916306168, + "id": "twenty-greek", + "isAgentGenerated": false, + "jupyter": { + "outputs_hidden": false + }, + "language": "python", + "metadata": { + "originalKey": "25b13c48-edb0-4b3f-ba34-4f4a4176162a" + }, + "originalKey": "8d824e37-b087-4bab-9b16-4354e9509df7", + "outputsInitialized": true, + "requestMsgId": "8d824e37-b087-4bab-9b16-4354e9509df7", + "serverExecutionDuration": 2.6916969800368 + }, + "outputs": [], + "source": [ + "model = BoTorchGenerator(\n", + " # Optional `Surrogate` specification to use instead of default\n", + " surrogate_spec=SurrogateSpec(\n", + " model_configs=[\n", + " ModelConfig(\n", + " # BoTorch `Model` type\n", + " botorch_model_class=SingleTaskGP,\n", + " # Optional, MLL class with which to optimize model parameters\n", + " mll_class=ExactMarginalLogLikelihood,\n", + " # Optional, dictionary of keyword arguments to underlying\n", + " # BoTorch `Model` constructor\n", + " model_options={},\n", + " )\n", + " ]\n", + " ),\n", + " # Optional BoTorch `AcquisitionFunction` to use instead of default\n", + " botorch_acqf_class=qLogExpectedImprovement,\n", + " # Optional dict of keyword arguments, passed to the input\n", + " # constructor for the given BoTorch `AcquisitionFunction`\n", + " acquisition_options={},\n", + " # Optional Ax `Acquisition` subclass (if the given BoTorch\n", + " # `AcquisitionFunction` requires one, which is rare)\n", + " acquisition_class=None,\n", + " # Less common model settings shown with default values, refer\n", + " # to `BoTorchModel` documentation for detail\n", + " refit_on_cv=False,\n", + " warm_start_refit=True,\n", + ")" + ] }, - "originalKey": "4af8afa2-5056-46be-b7b9-428127e668cc", - "outputsInitialized": false, - "showInput": false - }, - "source": [ - "### 3a. Making a `Surrogate` from BoTorch `Model`:\n", - "Most models should work with base `Surrogate` in Ax, except for BoTorch `ModelListGP`. `ModelListGP` is a special case because its purpose is to combine multiple sub-models into a single `Model` in BoTorch. It is most commonly used for multi-objective and constrained optimization. Whether or not `ModelListGP` is used is determined automatically based on the `Model` class and the data being used via the `ax.models.torch.botorch_modular.utils.use_model_list` function.\n", - "\n", - "If your `Model` is not a `ModelListGP`, the steps to set it up as a `Surrogate` are:\n", - "1. Implement a [`construct_inputs` class method](https://github.com/pytorch/botorch/blob/main/botorch/models/model.py#L143). The purpose of this method is to produce arguments to a particular model from a standardized set of inputs passed to BoTorch `Model`-s from [`Surrogate.construct`](https://github.com/facebook/Ax/blob/main/ax/models/torch/botorch_modular/surrogate.py#L148) in Ax. It should accept training data in form of a `SupervisedDataset` container and optionally other keyword arguments and produce a dictionary of arguments to `__init__` of the `Model`. See [`SingleTaskMultiFidelityGP.construct_inputs`](https://github.com/pytorch/botorch/blob/5b3172f3daa22f6ea2f6f4d1d0a378a9518dcd8d/botorch/models/gp_regression_fidelity.py#L131) for an example.\n", - "2. Pass any additional needed keyword arguments for the `Model` constructor (that cannot be constructed from the training data and other arguments to `construct_inputs`) via the `model_options` argument to `ModelConfig` in `SurrogateSpec`." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "0eaa0481", - "metadata": { - "collapsed": false, - "executionStartTime": 1730916308518, - "executionStopTime": 1730916308769, - "id": "dynamic-university", - "isAgentGenerated": false, - "jupyter": { - "outputs_hidden": false + { + "cell_type": "markdown", + "id": "91771a7f", + "metadata": { + "id": "fourth-material", + "isAgentGenerated": false, + "language": "markdown", + "metadata": { + "originalKey": "db0feafe-8af9-40a3-9f67-72c7d1fd808e" + }, + "originalKey": "7140bb19-09b4-4abe-951d-53902ae07833", + "outputsInitialized": false, + "showInput": false + }, + "source": [ + "## 2C. `Surrogate` and `Acquisition` Q&A\n", + "\n", + "**Why is the `surrogate` argument expected to be an instance, but `botorch_acqf_class` –– a class?** Because a BoTorch `AcquisitionFunction` object (and therefore its Ax wrapper, `Acquisition`) is ephemeral: it is constructed, immediately used, and destroyed during `BoTorchGenerator.gen`, so there is no reason to keep around an `Acquisition` instance. A `Surrogate`, on another hand, is kept in memory as long as its parent `BoTorchGenerator` is.\n", + "\n", + "**How to know when to use specify acquisition_class (and thereby a non-default Acquisition type) instead of just passing in botorch_acqf_class?** In short, custom `Acquisition` subclasses are needed when a given `AcquisitionFunction` in BoTorch needs some non-standard subcomponents or inputs (e.g. a custom BoTorch `MCAcquisitionObjective`). \n", + "\n", + "**Please post any other questions you have to our dedicated issue on Github: https://github.com/facebook/Ax/issues/363.** This functionality is in beta-release and your feedback will be of great help to us!" + ] }, - "language": "python", - "metadata": { - "code_folding": [], - "hidden_ranges": [], - "originalKey": "6c2ea955-c7a4-42ff-a4d7-f787113d4d53" + { + "cell_type": "markdown", + "id": "f801bfce", + "metadata": { + "id": "violent-course", + "isAgentGenerated": false, + "language": "markdown", + "metadata": { + "originalKey": "86018ee5-f7b8-41ae-8e2d-460fe5f0c15b" + }, + "originalKey": "71f92895-874d-4fc7-ae87-a5519b18d1a0", + "outputsInitialized": false, + "showInput": false + }, + "source": [ + "## 3. I know which Botorch `Model` and `AcquisitionFunction` I'd like to combine in Ax. How do set this up?" + ] }, - "originalKey": "746fc2a3-0e0e-4ab4-84d9-32434eb1fc34", - "outputsInitialized": true, - "requestMsgId": "746fc2a3-0e0e-4ab4-84d9-32434eb1fc34", - "serverExecutionDuration": 2.4644429795444 - }, - "outputs": [], - "source": [ - "from botorch.models.model import Model\n", - "from botorch.utils.datasets import SupervisedDataset\n", - "\n", - "\n", - "class MyModelClass(Model):\n", - "\n", - " ... # Implementation of `MyModelClass`\n", - "\n", - " @classmethod\n", - " def construct_inputs(\n", - " cls, training_data: SupervisedDataset, **kwargs\n", - " ) -> Dict[str, Any]:\n", - " fidelity_features = kwargs.get(\"fidelity_features\")\n", - " if fidelity_features is None:\n", - " raise ValueError(f\"Fidelity features required for {cls.__name__}.\")\n", - "\n", - " return {\n", - " **super().construct_inputs(training_data=training_data, **kwargs),\n", - " \"fidelity_features\": fidelity_features,\n", - " }\n", - "\n", - "\n", - "surrogate_spec = SurrogateSpec(\n", - " model_configs=[\n", - " ModelConfig(\n", - " botorch_model_class=MyModelClass, # Must implement `construct_inputs`\n", - " # Optional dict of additional keyword arguments to `MyModelClass`\n", - " model_options={},\n", - " )\n", - " ]\n", - ")" - ] - }, - { - "cell_type": "markdown", - "id": "bd78ae03", - "metadata": { - "id": "otherwise-context", - "isAgentGenerated": false, - "language": "markdown", - "metadata": { - "originalKey": "b9072296-956d-4add-b1f6-e7e0415ba65c" + { + "cell_type": "markdown", + "id": "1a08a274", + "metadata": { + "id": "unlike-football", + "isAgentGenerated": false, + "language": "markdown", + "metadata": { + "code_folding": [], + "hidden_ranges": [], + "originalKey": "b29a846d-d7bc-4143-8318-10170c9b4298", + "showInput": false + }, + "originalKey": "4af8afa2-5056-46be-b7b9-428127e668cc", + "outputsInitialized": false, + "showInput": false + }, + "source": [ + "### 3a. Making a `Surrogate` from BoTorch `Model`:\n", + "Most models should work with base `Surrogate` in Ax, except for BoTorch `ModelListGP`. `ModelListGP` is a special case because its purpose is to combine multiple sub-models into a single `Model` in BoTorch. It is most commonly used for multi-objective and constrained optimization. Whether or not `ModelListGP` is used is determined automatically based on the `Model` class and the data being used via the `ax.models.torch.botorch_modular.utils.use_model_list` function.\n", + "\n", + "If your `Model` is not a `ModelListGP`, the steps to set it up as a `Surrogate` are:\n", + "1. Implement a [`construct_inputs` class method](https://github.com/pytorch/botorch/blob/main/botorch/models/model.py#L143). The purpose of this method is to produce arguments to a particular model from a standardized set of inputs passed to BoTorch `Model`-s from [`Surrogate.construct`](https://github.com/facebook/Ax/blob/main/ax/models/torch/botorch_modular/surrogate.py#L148) in Ax. It should accept training data in form of a `SupervisedDataset` container and optionally other keyword arguments and produce a dictionary of arguments to `__init__` of the `Model`. See [`SingleTaskMultiFidelityGP.construct_inputs`](https://github.com/pytorch/botorch/blob/5b3172f3daa22f6ea2f6f4d1d0a378a9518dcd8d/botorch/models/gp_regression_fidelity.py#L131) for an example.\n", + "2. Pass any additional needed keyword arguments for the `Model` constructor (that cannot be constructed from the training data and other arguments to `construct_inputs`) via the `model_options` argument to `ModelConfig` in `SurrogateSpec`." + ] }, - "originalKey": "5a27fd2c-4c4c-41fe-a634-f6d0ec4f1666", - "outputsInitialized": false, - "showInput": false - }, - "source": [ - "NOTE: if you run into a case where base `Surrogate` does not work with your BoTorch `Model`, please let us know in this Github issue: https://github.com/facebook/Ax/issues/363, so we can find the right solution and augment this tutorial." - ] - }, - { - "cell_type": "markdown", - "id": "415c682c", - "metadata": { - "id": "northern-invite", - "isAgentGenerated": false, - "language": "markdown", - "metadata": { - "originalKey": "335cabdf-2bf6-48e8-ba0c-1404a8ef47f9" + { + "cell_type": "code", + "execution_count": null, + "id": "0eaa0481", + "metadata": { + "collapsed": false, + "executionStartTime": 1730916308518, + "executionStopTime": 1730916308769, + "id": "dynamic-university", + "isAgentGenerated": false, + "jupyter": { + "outputs_hidden": false + }, + "language": "python", + "metadata": { + "code_folding": [], + "hidden_ranges": [], + "originalKey": "6c2ea955-c7a4-42ff-a4d7-f787113d4d53" + }, + "originalKey": "746fc2a3-0e0e-4ab4-84d9-32434eb1fc34", + "outputsInitialized": true, + "requestMsgId": "746fc2a3-0e0e-4ab4-84d9-32434eb1fc34", + "serverExecutionDuration": 2.4644429795444 + }, + "outputs": [], + "source": [ + "from botorch.models.model import Model\n", + "from botorch.utils.datasets import SupervisedDataset\n", + "\n", + "\n", + "class MyModelClass(Model):\n", + "\n", + " ... # Implementation of `MyModelClass`\n", + "\n", + " @classmethod\n", + " def construct_inputs(\n", + " cls, training_data: SupervisedDataset, **kwargs\n", + " ) -> Dict[str, Any]:\n", + " fidelity_features = kwargs.get(\"fidelity_features\")\n", + " if fidelity_features is None:\n", + " raise ValueError(f\"Fidelity features required for {cls.__name__}.\")\n", + "\n", + " return {\n", + " **super().construct_inputs(training_data=training_data, **kwargs),\n", + " \"fidelity_features\": fidelity_features,\n", + " }\n", + "\n", + "\n", + "surrogate_spec = SurrogateSpec(\n", + " model_configs=[\n", + " ModelConfig(\n", + " botorch_model_class=MyModelClass, # Must implement `construct_inputs`\n", + " # Optional dict of additional keyword arguments to `MyModelClass`\n", + " model_options={},\n", + " )\n", + " ]\n", + ")" + ] }, - "originalKey": "df06d02b-95cb-4d34-aac6-773231f1a129", - "outputsInitialized": false, - "showInput": false - }, - "source": [ - "### 3B. Using an arbitrary BoTorch `AcquisitionFunction` in Ax" - ] - }, - { - "cell_type": "markdown", - "id": "3d04c34c", - "metadata": { - "id": "surrounded-denial", - "isAgentGenerated": false, - "language": "markdown", - "metadata": { - "code_folding": [], - "hidden_ranges": [], - "originalKey": "e3f0c788-2131-4116-9518-4ae7daeb991f", - "showInput": false + { + "cell_type": "markdown", + "id": "bd78ae03", + "metadata": { + "id": "otherwise-context", + "isAgentGenerated": false, + "language": "markdown", + "metadata": { + "originalKey": "b9072296-956d-4add-b1f6-e7e0415ba65c" + }, + "originalKey": "5a27fd2c-4c4c-41fe-a634-f6d0ec4f1666", + "outputsInitialized": false, + "showInput": false + }, + "source": [ + "NOTE: if you run into a case where base `Surrogate` does not work with your BoTorch `Model`, please let us know in this Github issue: https://github.com/facebook/Ax/issues/363, so we can find the right solution and augment this tutorial." + ] }, - "originalKey": "d4861847-b757-4fcd-9f35-ba258080812c", - "outputsInitialized": false, - "showInput": false - }, - "source": [ - "Steps to set up any `AcquisitionFunction` in Ax are:\n", - "1. Define an input constructor function. The purpose of this method is to produce arguments to a acquisition function from a standardized set of inputs passed to BoTorch `AcquisitionFunction`-s from `Acquisition.__init__` in Ax. For example, see [`construct_inputs_qEHVI`](https://github.com/pytorch/botorch/blob/main/botorch/acquisition/input_constructors.py#L477), which creates a fairly complex set of arguments needed by `qExpectedHypervolumeImprovement` –– a popular multi-objective optimization acquisition function offered in Ax and BoTorch. For more examples, see this collection in BoTorch: [botorch/acquisition/input_constructors.py](https://github.com/pytorch/botorch/blob/main/botorch/acquisition/input_constructors.py) \n", - " 1. Note that the new input constructor needs to be decorated with `@acqf_input_constructor(AcquisitionFunctionClass)` to register it.\n", - "3. Specify the BoTorch `AcquisitionFunction` class as `botorch_acqf_class` to `BoTorchGenerator`\n", - "4. (Optional) Pass any additional keyword arguments to acquisition function constructor or to the optimizer function via `acquisition_options` argument to `BoTorchGenerator`." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "602ec648", - "metadata": { - "collapsed": false, - "customOutput": null, - "executionStartTime": 1730916310518, - "executionStopTime": 1730916310772, - "id": "interested-search", - "isAgentGenerated": false, - "jupyter": { - "outputs_hidden": false + { + "cell_type": "markdown", + "id": "415c682c", + "metadata": { + "id": "northern-invite", + "isAgentGenerated": false, + "language": "markdown", + "metadata": { + "originalKey": "335cabdf-2bf6-48e8-ba0c-1404a8ef47f9" + }, + "originalKey": "df06d02b-95cb-4d34-aac6-773231f1a129", + "outputsInitialized": false, + "showInput": false + }, + "source": [ + "### 3B. Using an arbitrary BoTorch `AcquisitionFunction` in Ax" + ] }, - "language": "python", - "metadata": { - "code_folding": [], - "hidden_ranges": [], - "originalKey": "6967ce3e-929b-4d9a-8cd1-72bf94f0be3a" + { + "cell_type": "markdown", + "id": "3d04c34c", + "metadata": { + "id": "surrounded-denial", + "isAgentGenerated": false, + "language": "markdown", + "metadata": { + "code_folding": [], + "hidden_ranges": [], + "originalKey": "e3f0c788-2131-4116-9518-4ae7daeb991f", + "showInput": false + }, + "originalKey": "d4861847-b757-4fcd-9f35-ba258080812c", + "outputsInitialized": false, + "showInput": false + }, + "source": [ + "Steps to set up any `AcquisitionFunction` in Ax are:\n", + "1. Define an input constructor function. The purpose of this method is to produce arguments to a acquisition function from a standardized set of inputs passed to BoTorch `AcquisitionFunction`-s from `Acquisition.__init__` in Ax. For example, see [`construct_inputs_qEHVI`](https://github.com/pytorch/botorch/blob/main/botorch/acquisition/input_constructors.py#L477), which creates a fairly complex set of arguments needed by `qExpectedHypervolumeImprovement` –– a popular multi-objective optimization acquisition function offered in Ax and BoTorch. For more examples, see this collection in BoTorch: [botorch/acquisition/input_constructors.py](https://github.com/pytorch/botorch/blob/main/botorch/acquisition/input_constructors.py) \n", + " 1. Note that the new input constructor needs to be decorated with `@acqf_input_constructor(AcquisitionFunctionClass)` to register it.\n", + "3. Specify the BoTorch `AcquisitionFunction` class as `botorch_acqf_class` to `BoTorchGenerator`\n", + "4. (Optional) Pass any additional keyword arguments to acquisition function constructor or to the optimizer function via `acquisition_options` argument to `BoTorchGenerator`." + ] }, - "originalKey": "f188f40b-64ba-4b0c-b216-f3dea8c7465e", - "outputsInitialized": true, - "requestMsgId": "f188f40b-64ba-4b0c-b216-f3dea8c7465e", - "serverExecutionDuration": 4.9752569757402 - }, - "outputs": [], - "source": [ - "from ax.models.torch.botorch_modular.optimizer_argparse import optimizer_argparse\n", - "from botorch.acquisition.acquisition import AcquisitionFunction\n", - "from botorch.acquisition.input_constructors import acqf_input_constructor, MaybeDict\n", - "from botorch.utils.datasets import SupervisedDataset\n", - "from torch import Tensor\n", - "\n", - "\n", - "class MyAcquisitionFunctionClass(AcquisitionFunction):\n", - " ... # Actual contents of the acquisition function class.\n", - "\n", - "\n", - "# 1. Add input constructor\n", - "@acqf_input_constructor(MyAcquisitionFunctionClass)\n", - "def construct_inputs_my_acqf(\n", - " model: Model,\n", - " training_data: MaybeDict[SupervisedDataset],\n", - " objective_thresholds: Tensor,\n", - " **kwargs: Any,\n", - ") -> Dict[str, Any]:\n", - " pass\n", - "\n", - "\n", - "\n", - "# 2-3. Specifying `botorch_acqf_class` and `acquisition_options`\n", - "BoTorchGenerator(\n", - " botorch_acqf_class=MyAcquisitionFunctionClass,\n", - " acquisition_options={\n", - " \"alpha\": 10**-6,\n", - " # The sub-dict by the key \"optimizer_options\" can be passed\n", - " # to propagate options to `optimize_acqf`, used in\n", - " # `Acquisition.optimize`, to add/override the default\n", - " # optimizer options registered above.\n", - " \"optimizer_options\": {\"sequential\": False},\n", - " },\n", - ")" - ] - }, - { - "cell_type": "markdown", - "id": "508948ac", - "metadata": { - "id": "metallic-imaging", - "isAgentGenerated": false, - "language": "markdown", - "metadata": { - "originalKey": "29256ab1-f214-4604-a423-4c7b4b36baa0" + { + "cell_type": "code", + "execution_count": null, + "id": "602ec648", + "metadata": { + "collapsed": false, + "customOutput": null, + "executionStartTime": 1730916310518, + "executionStopTime": 1730916310772, + "id": "interested-search", + "isAgentGenerated": false, + "jupyter": { + "outputs_hidden": false + }, + "language": "python", + "metadata": { + "code_folding": [], + "hidden_ranges": [], + "originalKey": "6967ce3e-929b-4d9a-8cd1-72bf94f0be3a" + }, + "originalKey": "f188f40b-64ba-4b0c-b216-f3dea8c7465e", + "outputsInitialized": true, + "requestMsgId": "f188f40b-64ba-4b0c-b216-f3dea8c7465e", + "serverExecutionDuration": 4.9752569757402 + }, + "outputs": [], + "source": [ + "from ax.models.torch.botorch_modular.optimizer_argparse import optimizer_argparse\n", + "from botorch.acquisition.acquisition import AcquisitionFunction\n", + "from botorch.acquisition.input_constructors import acqf_input_constructor, MaybeDict\n", + "from botorch.utils.datasets import SupervisedDataset\n", + "from torch import Tensor\n", + "\n", + "\n", + "class MyAcquisitionFunctionClass(AcquisitionFunction):\n", + " ... # Actual contents of the acquisition function class.\n", + "\n", + "\n", + "# 1. Add input constructor\n", + "@acqf_input_constructor(MyAcquisitionFunctionClass)\n", + "def construct_inputs_my_acqf(\n", + " model: Model,\n", + " training_data: MaybeDict[SupervisedDataset],\n", + " objective_thresholds: Tensor,\n", + " **kwargs: Any,\n", + ") -> Dict[str, Any]:\n", + " pass\n", + "\n", + "\n", + "\n", + "# 2-3. Specifying `botorch_acqf_class` and `acquisition_options`\n", + "BoTorchGenerator(\n", + " botorch_acqf_class=MyAcquisitionFunctionClass,\n", + " acquisition_options={\n", + " \"alpha\": 10**-6,\n", + " # The sub-dict by the key \"optimizer_options\" can be passed\n", + " # to propagate options to `optimize_acqf`, used in\n", + " # `Acquisition.optimize`, to add/override the default\n", + " # optimizer options registered above.\n", + " \"optimizer_options\": {\"sequential\": False},\n", + " },\n", + ")" + ] }, - "originalKey": "b057722d-b8ca-47dd-b2c8-1ff4a71c4863", - "outputsInitialized": false, - "showInput": false - }, - "source": [ - "See section 2A for combining the resulting `Surrogate` instance and `Acquisition` type into a `BoTorchGenerator`. You can also leverage `Generators.BOTORCH_MODULAR` for ease of use; more on it in section 4 below or in section 1 quick-start example." - ] - }, - { - "cell_type": "markdown", - "id": "8f840899", - "metadata": { - "id": "descending-australian", - "isAgentGenerated": false, - "language": "markdown", - "metadata": { - "originalKey": "1d15082f-1df7-4cdb-958b-300483eb7808" + { + "cell_type": "markdown", + "id": "508948ac", + "metadata": { + "id": "metallic-imaging", + "isAgentGenerated": false, + "language": "markdown", + "metadata": { + "originalKey": "29256ab1-f214-4604-a423-4c7b4b36baa0" + }, + "originalKey": "b057722d-b8ca-47dd-b2c8-1ff4a71c4863", + "outputsInitialized": false, + "showInput": false + }, + "source": [ + "See section 2A for combining the resulting `Surrogate` instance and `Acquisition` type into a `BoTorchGenerator`. You can also leverage `Generators.BOTORCH_MODULAR` for ease of use; more on it in section 4 below or in section 1 quick-start example." + ] }, - "originalKey": "a7406f13-1468-487d-ac5e-7d2a45394850", - "outputsInitialized": false, - "showInput": false - }, - "source": [ - "## 4. Using `Generators.BOTORCH_MODULAR` \n", - "\n", - "To simplify the instantiation of an Ax `Adapter` and its undelying `Generator`, Ax provides a [`Generator` registry enum](https://github.com/facebook/Ax/blob/main/ax/modelbridge/registry.py#L355). When calling entries of that enum (e.g. `Generators.BOTORCH_MODULAR(experiment, data)`), the inputs are automatically distributed between a `Generator` and an `Adapter` for a given setup. A call to a `Model` enum member yields an `Adapter` with an underlying `Generator`, ready for use to generate candidates.\n", - "\n", - "Here we use `Generators.BOTORCH_MODULAR` to set up a model with all-default subcomponents:" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "a879268e", - "metadata": { - "collapsed": false, - "executionStartTime": 1730916311983, - "executionStopTime": 1730916312395, - "id": "attached-border", - "isAgentGenerated": false, - "jupyter": { - "outputs_hidden": false + { + "cell_type": "markdown", + "id": "8f840899", + "metadata": { + "id": "descending-australian", + "isAgentGenerated": false, + "language": "markdown", + "metadata": { + "originalKey": "1d15082f-1df7-4cdb-958b-300483eb7808" + }, + "originalKey": "a7406f13-1468-487d-ac5e-7d2a45394850", + "outputsInitialized": false, + "showInput": false + }, + "source": [ + "## 4. Using `Generators.BOTORCH_MODULAR` \n", + "\n", + "To simplify the instantiation of an Ax `Adapter` and its undelying `Generator`, Ax provides a [`Generator` registry enum](https://github.com/facebook/Ax/blob/main/ax/modelbridge/registry.py#L355). When calling entries of that enum (e.g. `Generators.BOTORCH_MODULAR(experiment, data)`), the inputs are automatically distributed between a `Generator` and an `Adapter` for a given setup. A call to a `Model` enum member yields an `Adapter` with an underlying `Generator`, ready for use to generate candidates.\n", + "\n", + "Here we use `Generators.BOTORCH_MODULAR` to set up a model with all-default subcomponents:" + ] }, - "language": "python", - "metadata": { - "originalKey": "385b2f30-fd86-4d88-8784-f238ea8a6abb" + { + "cell_type": "code", + "execution_count": null, + "id": "a879268e", + "metadata": { + "collapsed": false, + "executionStartTime": 1730916311983, + "executionStopTime": 1730916312395, + "id": "attached-border", + "isAgentGenerated": false, + "jupyter": { + "outputs_hidden": false + }, + "language": "python", + "metadata": { + "originalKey": "385b2f30-fd86-4d88-8784-f238ea8a6abb" + }, + "originalKey": "052cf2e4-8de0-4ec3-a3f9-478194b10928", + "outputsInitialized": true, + "requestMsgId": "052cf2e4-8de0-4ec3-a3f9-478194b10928", + "serverExecutionDuration": 202.78578903526 + }, + "outputs": [], + "source": [ + "adapter_with_GPEI = Generators.BOTORCH_MODULAR(\n", + " experiment=experiment,\n", + " data=data,\n", + ")\n", + "adapter_with_GPEI.gen(1)" + ] }, - "originalKey": "052cf2e4-8de0-4ec3-a3f9-478194b10928", - "outputsInitialized": true, - "requestMsgId": "052cf2e4-8de0-4ec3-a3f9-478194b10928", - "serverExecutionDuration": 202.78578903526 - }, - "outputs": [], - "source": [ - "adapter_with_GPEI = Generators.BOTORCH_MODULAR(\n", - " experiment=experiment,\n", - " data=data,\n", - ")\n", - "adapter_with_GPEI.gen(1)" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "666089a4", - "metadata": { - "collapsed": false, - "executionStartTime": 1730916312432, - "executionStopTime": 1730916312657, - "id": "powerful-gamma", - "isAgentGenerated": false, - "jupyter": { - "outputs_hidden": false + { + "cell_type": "code", + "execution_count": null, + "id": "666089a4", + "metadata": { + "collapsed": false, + "executionStartTime": 1730916312432, + "executionStopTime": 1730916312657, + "id": "powerful-gamma", + "isAgentGenerated": false, + "jupyter": { + "outputs_hidden": false + }, + "language": "python", + "metadata": { + "originalKey": "89930a31-e058-434b-b587-181931e247b6" + }, + "originalKey": "b7f924fe-f3d9-4211-b402-421f4c90afe5", + "outputsInitialized": true, + "requestMsgId": "b7f924fe-f3d9-4211-b402-421f4c90afe5", + "serverExecutionDuration": 3.1334219966084 + }, + "outputs": [], + "source": [ + "adapter_with_GPEI.model.botorch_acqf_class" + ] }, - "language": "python", - "metadata": { - "originalKey": "89930a31-e058-434b-b587-181931e247b6" + { + "cell_type": "code", + "execution_count": null, + "id": "0462b383", + "metadata": { + "collapsed": false, + "executionStartTime": 1730916312847, + "executionStopTime": 1730916313093, + "id": "improved-replication", + "isAgentGenerated": false, + "jupyter": { + "outputs_hidden": false + }, + "language": "python", + "metadata": { + "originalKey": "f9a9cb14-20c3-4e1d-93a3-6a35c281ae01" + }, + "originalKey": "942f1817-8d40-48f8-8725-90c25a079e4c", + "outputsInitialized": true, + "requestMsgId": "942f1817-8d40-48f8-8725-90c25a079e4c", + "serverExecutionDuration": 3.410067060031 + }, + "outputs": [], + "source": [ + "adapter_with_GPEI.model.surrogate.model.__class__" + ] }, - "originalKey": "b7f924fe-f3d9-4211-b402-421f4c90afe5", - "outputsInitialized": true, - "requestMsgId": "b7f924fe-f3d9-4211-b402-421f4c90afe5", - "serverExecutionDuration": 3.1334219966084 - }, - "outputs": [], - "source": [ - "adapter_with_GPEI.model.botorch_acqf_class" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "0462b383", - "metadata": { - "collapsed": false, - "executionStartTime": 1730916312847, - "executionStopTime": 1730916313093, - "id": "improved-replication", - "isAgentGenerated": false, - "jupyter": { - "outputs_hidden": false + { + "cell_type": "markdown", + "id": "20878dbc", + "metadata": { + "id": "connected-sheet", + "isAgentGenerated": false, + "language": "markdown", + "metadata": { + "originalKey": "8b6a9ddc-d2d2-4cd5-a6a8-820113f78262" + }, + "originalKey": "f5c0adbd-00a6-428d-810f-1e7ed0954b08", + "outputsInitialized": false, + "showInput": false + }, + "source": [ + "We can use the same `Models.BOTORCH_MODULAR` to set up a model for multi-objective optimization:" + ] }, - "language": "python", - "metadata": { - "originalKey": "f9a9cb14-20c3-4e1d-93a3-6a35c281ae01" + { + "cell_type": "code", + "execution_count": null, + "id": "6a440b4f", + "metadata": { + "collapsed": false, + "executionStartTime": 1730916314009, + "executionStopTime": 1730916314736, + "id": "documentary-jurisdiction", + "isAgentGenerated": false, + "jupyter": { + "outputs_hidden": false + }, + "language": "python", + "metadata": { + "originalKey": "8001de33-d9d9-4888-a5d1-7a59ebeccfd5" + }, + "originalKey": "9c64c497-f663-42a6-aa48-1f1f2ae2b80b", + "outputsInitialized": true, + "requestMsgId": "9c64c497-f663-42a6-aa48-1f1f2ae2b80b", + "serverExecutionDuration": 518.53136904538 + }, + "outputs": [], + "source": [ + "adapter_with_EHVI = Generators.BOTORCH_MODULAR(\n", + " experiment=get_branin_experiment_with_multi_objective(\n", + " has_objective_thresholds=True, with_batch=True\n", + " ),\n", + " data=get_branin_data_multi_objective(),\n", + ")\n", + "adapter_with_EHVI.gen(1)" + ] }, - "originalKey": "942f1817-8d40-48f8-8725-90c25a079e4c", - "outputsInitialized": true, - "requestMsgId": "942f1817-8d40-48f8-8725-90c25a079e4c", - "serverExecutionDuration": 3.410067060031 - }, - "outputs": [], - "source": [ - "adapter_with_GPEI.model.surrogate.model.__class__" - ] - }, - { - "cell_type": "markdown", - "id": "20878dbc", - "metadata": { - "id": "connected-sheet", - "isAgentGenerated": false, - "language": "markdown", - "metadata": { - "originalKey": "8b6a9ddc-d2d2-4cd5-a6a8-820113f78262" + { + "cell_type": "code", + "execution_count": null, + "id": "6e85102e", + "metadata": { + "collapsed": false, + "executionStartTime": 1730916314586, + "executionStopTime": 1730916314842, + "id": "changed-maintenance", + "isAgentGenerated": false, + "jupyter": { + "outputs_hidden": false + }, + "language": "python", + "metadata": { + "originalKey": "dcfdbecc-4a9a-49ac-ad55-0bc04b2ec566" + }, + "originalKey": "ab6e84ac-2a55-4f48-9ab7-06b8d9b58d1f", + "outputsInitialized": true, + "requestMsgId": "ab6e84ac-2a55-4f48-9ab7-06b8d9b58d1f", + "serverExecutionDuration": 3.3097150735557 + }, + "outputs": [], + "source": [ + "adapter_with_EHVI.model.botorch_acqf_class" + ] }, - "originalKey": "f5c0adbd-00a6-428d-810f-1e7ed0954b08", - "outputsInitialized": false, - "showInput": false - }, - "source": [ - "We can use the same `Models.BOTORCH_MODULAR` to set up a model for multi-objective optimization:" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "6a440b4f", - "metadata": { - "collapsed": false, - "executionStartTime": 1730916314009, - "executionStopTime": 1730916314736, - "id": "documentary-jurisdiction", - "isAgentGenerated": false, - "jupyter": { - "outputs_hidden": false + { + "cell_type": "code", + "execution_count": null, + "id": "d0994478", + "metadata": { + "collapsed": false, + "executionStartTime": 1730916315097, + "executionStopTime": 1730916315308, + "id": "operating-shelf", + "isAgentGenerated": false, + "jupyter": { + "outputs_hidden": false + }, + "language": "python", + "metadata": { + "originalKey": "16727a51-337d-4715-bf51-9cb6637a950f" + }, + "originalKey": "1e980e3c-09f6-44c1-a79f-f59867de0c3e", + "outputsInitialized": true, + "requestMsgId": "1e980e3c-09f6-44c1-a79f-f59867de0c3e", + "serverExecutionDuration": 3.4662369871512 + }, + "outputs": [], + "source": [ + "adapter_with_EHVI.model.surrogate.model.__class__" + ] }, - "language": "python", - "metadata": { - "originalKey": "8001de33-d9d9-4888-a5d1-7a59ebeccfd5" + { + "cell_type": "markdown", + "id": "89e7d57d", + "metadata": { + "id": "fatal-butterfly", + "isAgentGenerated": false, + "language": "markdown", + "metadata": { + "originalKey": "5c64eecc-5ce5-4907-bbcc-5b3cbf4358ae" + }, + "originalKey": "3ad7c4a7-fe19-44ad-938d-1be4f8b09bfb", + "outputsInitialized": false, + "showInput": false + }, + "source": [ + "Furthermore, the quick-start example at the top of this tutorial shows how to specify surrogate and acquisition subcomponents to `Generators.BOTORCH_MODULAR`. " + ] }, - "originalKey": "9c64c497-f663-42a6-aa48-1f1f2ae2b80b", - "outputsInitialized": true, - "requestMsgId": "9c64c497-f663-42a6-aa48-1f1f2ae2b80b", - "serverExecutionDuration": 518.53136904538 - }, - "outputs": [], - "source": [ - "adapter_with_EHVI = Generators.BOTORCH_MODULAR(\n", - " experiment=get_branin_experiment_with_multi_objective(\n", - " has_objective_thresholds=True, with_batch=True\n", - " ),\n", - " data=get_branin_data_multi_objective(),\n", - ")\n", - "adapter_with_EHVI.gen(1)" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "6e85102e", - "metadata": { - "collapsed": false, - "executionStartTime": 1730916314586, - "executionStopTime": 1730916314842, - "id": "changed-maintenance", - "isAgentGenerated": false, - "jupyter": { - "outputs_hidden": false + { + "cell_type": "markdown", + "id": "f9bc3db7", + "metadata": { + "id": "hearing-interface", + "isAgentGenerated": false, + "language": "markdown", + "metadata": { + "originalKey": "a0163432-f0ca-4582-ad84-16c77c99f20b" + }, + "originalKey": "44adf1ce-6d3e-455d-b53c-32d3c42a843f", + "outputsInitialized": false, + "showInput": false + }, + "source": [ + "## 5. Utilizing `BoTorchGenerator` in generation strategies\n", + "\n", + "Generation strategy is a key concept in Ax, enabling use of Service API (a.k.a. `AxClient`) and many other higher-level abstractions. A `GenerationStrategy` allows to chain multiple models in Ax and thereby automate candidate generation. Refer to the \"Generation Strategy\" tutorial for more detail in generation strategies.\n", + "\n", + "An example generation stategy with the modular `BoTorchGenerator` would look like this:" + ] }, - "language": "python", - "metadata": { - "originalKey": "dcfdbecc-4a9a-49ac-ad55-0bc04b2ec566" + { + "cell_type": "code", + "execution_count": null, + "id": "8b7f0ffb", + "metadata": { + "collapsed": false, + "executionStartTime": 1730916316730, + "executionStopTime": 1730916316968, + "id": "received-registration", + "isAgentGenerated": false, + "jupyter": { + "outputs_hidden": false + }, + "language": "python", + "metadata": { + "originalKey": "f7eabbcf-607c-4bed-9a0e-6ac6e8b04350" + }, + "originalKey": "4ee172c8-0648-418b-9968-647e8e916507", + "outputsInitialized": true, + "requestMsgId": "4ee172c8-0648-418b-9968-647e8e916507", + "serverExecutionDuration": 2.2927720565349 + }, + "outputs": [], + "source": [ + "from ax.generation_strategy.generation_strategy import GenerationStep, GenerationStrategy\n", + "from ax.modelbridge.modelbridge_utils import get_pending_observation_features\n", + "\n", + "gs = GenerationStrategy(\n", + " steps=[\n", + " GenerationStep( # Initialization step\n", + " # Which model to use for this step\n", + " model=Generators.SOBOL,\n", + " # How many generator runs (each of which is then made a trial)\n", + " # to produce with this step\n", + " num_trials=5,\n", + " # How many trials generated from this step must be `COMPLETED`\n", + " # before the next one\n", + " min_trials_observed=5,\n", + " ),\n", + " GenerationStep( # BayesOpt step\n", + " model=Generators.BOTORCH_MODULAR,\n", + " # No limit on how many generator runs will be produced\n", + " num_trials=-1,\n", + " model_kwargs={ # Kwargs to pass to `BoTorchModel.__init__`\n", + " \"surrogate_spec\": SurrogateSpec(\n", + " model_configs=[ModelConfig(botorch_model_class=SingleTaskGP)]\n", + " ),\n", + " \"botorch_acqf_class\": qLogNoisyExpectedImprovement,\n", + " },\n", + " ),\n", + " ]\n", + ")" + ] }, - "originalKey": "ab6e84ac-2a55-4f48-9ab7-06b8d9b58d1f", - "outputsInitialized": true, - "requestMsgId": "ab6e84ac-2a55-4f48-9ab7-06b8d9b58d1f", - "serverExecutionDuration": 3.3097150735557 - }, - "outputs": [], - "source": [ - "adapter_with_EHVI.model.botorch_acqf_class" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "d0994478", - "metadata": { - "collapsed": false, - "executionStartTime": 1730916315097, - "executionStopTime": 1730916315308, - "id": "operating-shelf", - "isAgentGenerated": false, - "jupyter": { - "outputs_hidden": false + { + "cell_type": "markdown", + "id": "157b623b", + "metadata": { + "id": "logical-windsor", + "isAgentGenerated": false, + "language": "markdown", + "metadata": { + "originalKey": "212c4543-220e-4605-8f72-5f86cf52f722" + }, + "originalKey": "ba3783ee-3d88-4e44-ad07-77de3c50f84d", + "outputsInitialized": false, + "showInput": false + }, + "source": [ + "Set up an experiment and generate 10 trials in it, adding synthetic data to experiment after each one:" + ] }, - "language": "python", - "metadata": { - "originalKey": "16727a51-337d-4715-bf51-9cb6637a950f" + { + "cell_type": "code", + "execution_count": null, + "id": "b75f3f73", + "metadata": { + "collapsed": false, + "executionStartTime": 1730916317751, + "executionStopTime": 1730916318153, + "id": "viral-cheese", + "isAgentGenerated": false, + "jupyter": { + "outputs_hidden": false + }, + "language": "python", + "metadata": { + "originalKey": "30cfcdd7-721d-4f89-b851-7a94140dfad6" + }, + "originalKey": "1b7d0cfc-f7cf-477d-b109-d34db9604938", + "outputsInitialized": true, + "requestMsgId": "1b7d0cfc-f7cf-477d-b109-d34db9604938", + "serverExecutionDuration": 3.9581339806318 + }, + "outputs": [], + "source": [ + "experiment = get_branin_experiment(minimize=True)\n", + "\n", + "assert len(experiment.trials) == 0\n", + "experiment.search_space" + ] }, - "originalKey": "1e980e3c-09f6-44c1-a79f-f59867de0c3e", - "outputsInitialized": true, - "requestMsgId": "1e980e3c-09f6-44c1-a79f-f59867de0c3e", - "serverExecutionDuration": 3.4662369871512 - }, - "outputs": [], - "source": [ - "adapter_with_EHVI.model.surrogate.model.__class__" - ] - }, - { - "cell_type": "markdown", - "id": "89e7d57d", - "metadata": { - "id": "fatal-butterfly", - "isAgentGenerated": false, - "language": "markdown", - "metadata": { - "originalKey": "5c64eecc-5ce5-4907-bbcc-5b3cbf4358ae" + { + "cell_type": "markdown", + "id": "ce37a384", + "metadata": { + "id": "incident-newspaper", + "isAgentGenerated": false, + "language": "markdown", + "metadata": { + "originalKey": "2807d7ce-8a6b-423c-b5f5-32edba09c78e" + }, + "originalKey": "df2e90f5-4132-4d87-989b-e6d47c748ddc", + "outputsInitialized": false, + "showInput": false + }, + "source": [ + "## 5a. Specifying `pending_observations`\n", + "Note that it's important to **specify pending observations** to the call to `gen` to avoid getting the same points re-suggested. Without `pending_observations` argument, Ax models are not aware of points that should be excluded from generation. Points are considered \"pending\" when they belong to `STAGED`, `RUNNING`, or `ABANDONED` trials (with the latter included so model does not re-suggest points that are considered \"bad\" and should not be re-suggested).\n", + "\n", + "If the call to `get_pending_observation_features` becomes slow in your setup (since it performs data-fetching etc.), you can opt for `get_pending_observation_features_based_on_trial_status` (also from `ax.modelbridge.modelbridge_utils`), but note the limitations of that utility (detailed in its docstring)." + ] }, - "originalKey": "3ad7c4a7-fe19-44ad-938d-1be4f8b09bfb", - "outputsInitialized": false, - "showInput": false - }, - "source": [ - "Furthermore, the quick-start example at the top of this tutorial shows how to specify surrogate and acquisition subcomponents to `Generators.BOTORCH_MODULAR`. " - ] - }, - { - "cell_type": "markdown", - "id": "f9bc3db7", - "metadata": { - "id": "hearing-interface", - "isAgentGenerated": false, - "language": "markdown", - "metadata": { - "originalKey": "a0163432-f0ca-4582-ad84-16c77c99f20b" + { + "cell_type": "code", + "execution_count": null, + "id": "4b5f671d", + "metadata": { + "collapsed": false, + "executionStartTime": 1730916318830, + "executionStopTime": 1730916321328, + "id": "casual-spread", + "isAgentGenerated": false, + "jupyter": { + "outputs_hidden": false + }, + "language": "python", + "metadata": { + "originalKey": "58aafd65-a366-4b66-a1b1-31b207037a2e" + }, + "originalKey": "fe7437c5-8834-46cc-94b2-91782d91ee96", + "outputsInitialized": true, + "requestMsgId": "fe7437c5-8834-46cc-94b2-91782d91ee96", + "serverExecutionDuration": 2274.8276960338 + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Completed trial #5, suggested by BoTorch.\n" + ] + }, + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Completed trial #6, suggested by BoTorch.\n" + ] + }, + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Completed trial #7, suggested by BoTorch.\n" + ] + }, + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Completed trial #8, suggested by BoTorch.\n" + ] + }, + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Completed trial #9, suggested by BoTorch.\n" + ] + } + ], + "source": [ + "for _ in range(10):\n", + " # Produce a new generator run and attach it to experiment as a trial\n", + " generator_run = gs.gen(\n", + " experiment=experiment,\n", + " n=1,\n", + " pending_observations=get_pending_observation_features(experiment=experiment),\n", + " )\n", + " trial = experiment.new_trial(generator_run)\n", + "\n", + " # Mark the trial as 'RUNNING' so we can mark it 'COMPLETED' later\n", + " trial.mark_running(no_runner_required=True)\n", + "\n", + " # Attach data for the new trial and mark it 'COMPLETED'\n", + " experiment.attach_data(get_branin_data(trials=[trial]))\n", + " trial.mark_completed()\n", + "\n", + " print(f\"Completed trial #{trial.index}, suggested by {generator_run._model_key}.\")" + ] }, - "originalKey": "44adf1ce-6d3e-455d-b53c-32d3c42a843f", - "outputsInitialized": false, - "showInput": false - }, - "source": [ - "## 5. Utilizing `BoTorchGenerator` in generation strategies\n", - "\n", - "Generation strategy is a key concept in Ax, enabling use of Service API (a.k.a. `AxClient`) and many other higher-level abstractions. A `GenerationStrategy` allows to chain multiple models in Ax and thereby automate candidate generation. Refer to the \"Generation Strategy\" tutorial for more detail in generation strategies.\n", - "\n", - "An example generation stategy with the modular `BoTorchGenerator` would look like this:" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "8b7f0ffb", - "metadata": { - "collapsed": false, - "executionStartTime": 1730916316730, - "executionStopTime": 1730916316968, - "id": "received-registration", - "isAgentGenerated": false, - "jupyter": { - "outputs_hidden": false + { + "cell_type": "markdown", + "id": "e4720316", + "metadata": { + "id": "circular-vermont", + "isAgentGenerated": false, + "language": "markdown", + "metadata": { + "originalKey": "9d3b86bf-b691-4315-8b8f-60504b37818c" + }, + "originalKey": "6a78ef13-fbaa-4cae-934b-d57f5807fe25", + "outputsInitialized": false, + "showInput": false + }, + "source": [ + "Now we examine the experiment and observe the trials that were added to it and produced by the generation strategy:" + ] }, - "language": "python", - "metadata": { - "originalKey": "f7eabbcf-607c-4bed-9a0e-6ac6e8b04350" + { + "cell_type": "code", + "execution_count": null, + "id": "a69b4418", + "metadata": { + "collapsed": false, + "executionStartTime": 1730916319576, + "executionStopTime": 1730916321368, + "id": "significant-particular", + "isAgentGenerated": false, + "jupyter": { + "outputs_hidden": false + }, + "language": "python", + "metadata": { + "originalKey": "ca12913d-e3fd-4617-a247-e3432665bac1" + }, + "originalKey": "b3160bc0-d5d1-45fa-bf62-4b9dd5778cac", + "outputsInitialized": true, + "requestMsgId": "b3160bc0-d5d1-45fa-bf62-4b9dd5778cac", + "serverExecutionDuration": 35.789265064523 + }, + "outputs": [], + "source": [ + "exp_to_df(experiment)" + ] }, - "originalKey": "4ee172c8-0648-418b-9968-647e8e916507", - "outputsInitialized": true, - "requestMsgId": "4ee172c8-0648-418b-9968-647e8e916507", - "serverExecutionDuration": 2.2927720565349 - }, - "outputs": [], - "source": [ - "from ax.modelbridge.generation_strategy import GenerationStep, GenerationStrategy\n", - "from ax.modelbridge.modelbridge_utils import get_pending_observation_features\n", - "\n", - "gs = GenerationStrategy(\n", - " steps=[\n", - " GenerationStep( # Initialization step\n", - " # Which model to use for this step\n", - " model=Generators.SOBOL,\n", - " # How many generator runs (each of which is then made a trial)\n", - " # to produce with this step\n", - " num_trials=5,\n", - " # How many trials generated from this step must be `COMPLETED`\n", - " # before the next one\n", - " min_trials_observed=5,\n", - " ),\n", - " GenerationStep( # BayesOpt step\n", - " model=Generators.BOTORCH_MODULAR,\n", - " # No limit on how many generator runs will be produced\n", - " num_trials=-1,\n", - " model_kwargs={ # Kwargs to pass to `BoTorchModel.__init__`\n", - " \"surrogate_spec\": SurrogateSpec(\n", - " model_configs=[ModelConfig(botorch_model_class=SingleTaskGP)]\n", - " ),\n", - " \"botorch_acqf_class\": qLogNoisyExpectedImprovement,\n", - " },\n", - " ),\n", - " ]\n", - ")" - ] - }, - { - "cell_type": "markdown", - "id": "157b623b", - "metadata": { - "id": "logical-windsor", - "isAgentGenerated": false, - "language": "markdown", - "metadata": { - "originalKey": "212c4543-220e-4605-8f72-5f86cf52f722" + { + "cell_type": "markdown", + "id": "5c778f3a", + "metadata": { + "id": "obvious-transparency", + "isAgentGenerated": false, + "language": "markdown", + "metadata": { + "originalKey": "c25da720-6d3d-4f16-b878-24f2d2755783" + }, + "originalKey": "633c66af-a89f-4f03-a88b-866767d0a52f", + "outputsInitialized": false, + "showInput": false + }, + "source": [ + "## 6. Customizing a `Surrogate` or `Acquisition`\n", + "\n", + "We expect the base `Surrogate` and `Acquisition` classes to work with most BoTorch components, but there could be a case where you would need to subclass one of aforementioned abstractions to handle a given BoTorch component. If you run into a case like this, feel free to open an issue on our [Github issues page](https://github.com/facebook/Ax/issues) –– it would be very useful for us to know \n", + "\n", + "One such example would be a need for a custom `MCAcquisitionObjective` or posterior transform. To subclass `Acquisition` accordingly, one would override the `get_botorch_objective_and_transform` method:" + ] }, - "originalKey": "ba3783ee-3d88-4e44-ad07-77de3c50f84d", - "outputsInitialized": false, - "showInput": false - }, - "source": [ - "Set up an experiment and generate 10 trials in it, adding synthetic data to experiment after each one:" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "b75f3f73", - "metadata": { - "collapsed": false, - "executionStartTime": 1730916317751, - "executionStopTime": 1730916318153, - "id": "viral-cheese", - "isAgentGenerated": false, - "jupyter": { - "outputs_hidden": false + { + "cell_type": "code", + "execution_count": null, + "id": "84e98211", + "metadata": { + "collapsed": false, + "executionStartTime": 1730916320585, + "executionStopTime": 1730916321384, + "id": "organizational-balance", + "isAgentGenerated": false, + "jupyter": { + "outputs_hidden": false + }, + "language": "python", + "metadata": { + "originalKey": "e7f8e413-f01e-4f9d-82c1-4912097637af" + }, + "originalKey": "2949718a-8a4e-41e5-91ac-5b020eface47", + "outputsInitialized": true, + "requestMsgId": "2949718a-8a4e-41e5-91ac-5b020eface47", + "serverExecutionDuration": 2.2059100447223 + }, + "outputs": [], + "source": [ + "from botorch.acquisition.objective import MCAcquisitionObjective, PosteriorTransform\n", + "from botorch.acquisition.risk_measures import RiskMeasureMCObjective\n", + "\n", + "\n", + "class CustomObjectiveAcquisition(Acquisition):\n", + " def get_botorch_objective_and_transform(\n", + " self,\n", + " botorch_acqf_class: Type[AcquisitionFunction],\n", + " model: Model,\n", + " objective_weights: Tensor,\n", + " objective_thresholds: Optional[Tensor] = None,\n", + " outcome_constraints: Optional[Tuple[Tensor, Tensor]] = None,\n", + " X_observed: Optional[Tensor] = None,\n", + " risk_measure: Optional[RiskMeasureMCObjective] = None,\n", + " ) -> Tuple[Optional[MCAcquisitionObjective], Optional[PosteriorTransform]]:\n", + " ... # Produce the desired `MCAcquisitionObjective` and `PosteriorTransform` instead of the default" + ] }, - "language": "python", - "metadata": { - "originalKey": "30cfcdd7-721d-4f89-b851-7a94140dfad6" + { + "cell_type": "markdown", + "id": "13843a20", + "metadata": { + "id": "theoretical-horizon", + "isAgentGenerated": false, + "language": "markdown", + "metadata": { + "originalKey": "7299f0fc-e19e-4383-99de-ef7a9a987fe9" + }, + "originalKey": "0ec8606d-9d5b-4bcb-ad7e-f54839ad6f9b", + "outputsInitialized": false, + "showInput": false + }, + "source": [ + "Then to use the new subclass in `BoTorchGenerator`, just specify `acquisition_class` argument along with `botorch_acqf_class` (to `BoTorchGenerator` directly or to `Generators.BOTORCH_MODULAR`, which just passes the relevant arguments to `BoTorchGenerator` under the hood, as discussed in section 4):" + ] }, - "originalKey": "1b7d0cfc-f7cf-477d-b109-d34db9604938", - "outputsInitialized": true, - "requestMsgId": "1b7d0cfc-f7cf-477d-b109-d34db9604938", - "serverExecutionDuration": 3.9581339806318 - }, - "outputs": [], - "source": [ - "experiment = get_branin_experiment(minimize=True)\n", - "\n", - "assert len(experiment.trials) == 0\n", - "experiment.search_space" - ] - }, - { - "cell_type": "markdown", - "id": "ce37a384", - "metadata": { - "id": "incident-newspaper", - "isAgentGenerated": false, - "language": "markdown", - "metadata": { - "originalKey": "2807d7ce-8a6b-423c-b5f5-32edba09c78e" + { + "cell_type": "code", + "execution_count": null, + "id": "2fffef64", + "metadata": { + "collapsed": false, + "executionStartTime": 1730916321675, + "executionStopTime": 1730916321901, + "id": "approximate-rolling", + "isAgentGenerated": false, + "jupyter": { + "outputs_hidden": false + }, + "language": "python", + "metadata": { + "originalKey": "07fe169a-78de-437e-9857-7c99cc48eedc" + }, + "originalKey": "e231ea1e-c70d-48dc-b6c6-1611c5ea1b26", + "outputsInitialized": true, + "requestMsgId": "e231ea1e-c70d-48dc-b6c6-1611c5ea1b26", + "serverExecutionDuration": 12.351316981949 + }, + "outputs": [], + "source": [ + "Generators.BOTORCH_MODULAR(\n", + " experiment=experiment,\n", + " data=data,\n", + " acquisition_class=CustomObjectiveAcquisition,\n", + " botorch_acqf_class=MyAcquisitionFunctionClass,\n", + ")" + ] }, - "originalKey": "df2e90f5-4132-4d87-989b-e6d47c748ddc", - "outputsInitialized": false, - "showInput": false - }, - "source": [ - "## 5a. Specifying `pending_observations`\n", - "Note that it's important to **specify pending observations** to the call to `gen` to avoid getting the same points re-suggested. Without `pending_observations` argument, Ax models are not aware of points that should be excluded from generation. Points are considered \"pending\" when they belong to `STAGED`, `RUNNING`, or `ABANDONED` trials (with the latter included so model does not re-suggest points that are considered \"bad\" and should not be re-suggested).\n", - "\n", - "If the call to `get_pending_observation_features` becomes slow in your setup (since it performs data-fetching etc.), you can opt for `get_pending_observation_features_based_on_trial_status` (also from `ax.modelbridge.modelbridge_utils`), but note the limitations of that utility (detailed in its docstring)." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "4b5f671d", - "metadata": { - "collapsed": false, - "executionStartTime": 1730916318830, - "executionStopTime": 1730916321328, - "id": "casual-spread", - "isAgentGenerated": false, - "jupyter": { - "outputs_hidden": false + { + "cell_type": "markdown", + "id": "16b06c8e", + "metadata": { + "id": "representative-implement", + "isAgentGenerated": false, + "language": "markdown", + "metadata": { + "originalKey": "608d5f0d-4528-4aa6-869d-db38fcbfb256" + }, + "originalKey": "cdcfb2bc-3016-4681-9fff-407f28321c3f", + "outputsInitialized": false, + "showInput": false + }, + "source": [ + "To use a custom `Surrogate` subclass, pass the `surrogate` argument of that type:\n", + "```\n", + "Generators.BOTORCH_MODULAR(\n", + " experiment=experiment, \n", + " data=data,\n", + " surrogate=CustomSurrogate(botorch_model_class=MyModelClass),\n", + ")\n", + "```" + ] }, - "language": "python", - "metadata": { - "originalKey": "58aafd65-a366-4b66-a1b1-31b207037a2e" + { + "cell_type": "markdown", + "id": "e47f94c4", + "metadata": { + "id": "framed-intermediate", + "isAgentGenerated": false, + "language": "markdown", + "metadata": { + "originalKey": "64f1289e-73c7-4cc5-96ee-5091286a8361" + }, + "originalKey": "ff03d674-f584-403f-ba65-f1bab921845b", + "outputsInitialized": false, + "showInput": false + }, + "source": [ + "------" + ] }, - "originalKey": "fe7437c5-8834-46cc-94b2-91782d91ee96", - "outputsInitialized": true, - "requestMsgId": "fe7437c5-8834-46cc-94b2-91782d91ee96", - "serverExecutionDuration": 2274.8276960338 - }, - "outputs": [ { - "name": "stdout", - "output_type": "stream", - "text": [ - "Completed trial #5, suggested by BoTorch.\n" - ] + "cell_type": "markdown", + "id": "44dc1fae", + "metadata": { + "id": "metropolitan-feedback", + "isAgentGenerated": false, + "language": "markdown", + "metadata": { + "originalKey": "d1e37569-dd0d-4561-b890-2f0097a345e0" + }, + "originalKey": "f71fcfa1-fc59-4bfb-84d6-b94ea5298bfa", + "outputsInitialized": false, + "showInput": false + }, + "source": [ + "## Appendix 1: Methods available on `BoTorchGenerator`\n", + "\n", + "Note that usually all these methods are used through `Adapter` –– a convertion and transformation layer that adapts Ax abstractions to inputs required by the given model.\n", + "\n", + "**Core methods on `BoTorchGenerator`:**\n", + "* `fit` selects a surrogate if needed and fits the surrogate model to data via `Surrogate.fit`,\n", + "* `predict` estimates metric values at a given point via `Surrogate.predict`,\n", + "* `gen` instantiates an acquisition function via `Acquisition.__init__` and optimizes it to generate candidates.\n", + "\n", + "**Other methods on `BoTorchGenerator`:**\n", + "* `update` updates surrogate model with training data and optionally reoptimizes model parameters via `Surrogate.update`,\n", + "* `cross_validate` re-fits the surrogate model to subset of training data and makes predictions for test data,\n", + "* `evaluate_acquisition_function` instantiates an acquisition function and evaluates it for a given point.\n", + "------\n" + ] }, { - "name": "stdout", - "output_type": "stream", - "text": [ - "Completed trial #6, suggested by BoTorch.\n" - ] + "cell_type": "markdown", + "id": "720415a6", + "metadata": { + "id": "possible-transsexual", + "isAgentGenerated": false, + "language": "markdown", + "metadata": { + "originalKey": "b02f928c-57d9-4b2a-b4fe-c6d28d368b12" + }, + "originalKey": "91cedde4-8911-441f-af05-eb124581cbbc", + "outputsInitialized": false, + "showInput": false + }, + "source": [ + "## Appendix 2: Default surrogate models and acquisition functions\n", + "\n", + "By default, the chosen surrogate model will be:\n", + "* if fidelity parameters are present in search space: `SingleTaskMultiFidelityGP`,\n", + "* if task parameters are present: a set of `MultiTaskGP` wrapped in a `ModelListGP` and each modeling one task,\n", + "* `SingleTaskGP` otherwise.\n", + "\n", + "The chosen acquisition function will be:\n", + "* for multi-objective settings: `qLogExpectedHypervolumeImprovement`,\n", + "* for single-objective settings: `qLogNoisyExpectedImprovement`.\n", + "----" + ] }, { - "name": "stdout", - "output_type": "stream", - "text": [ - "Completed trial #7, suggested by BoTorch.\n" - ] + "cell_type": "markdown", + "id": "45a8d6dc", + "metadata": { + "id": "continuous-strain", + "isAgentGenerated": false, + "language": "markdown", + "metadata": { + "originalKey": "76ae9852-9d21-43d6-bf75-bb087a474dd6" + }, + "originalKey": "c8b0f933-8df6-479b-aa61-db75ca877624", + "outputsInitialized": false, + "showInput": false + }, + "source": [ + "## Appendix 3: Handling storage errors that arise from objects that don't have serialization logic in A\n", + "\n", + "Attempting to store a generator run produced via `Generators.BOTORCH_MODULAR` instance that included options without serization logic with will produce an error like: `\"Object passed to 'object_to_json' (of type ) is not registered with a corresponding encoder in ENCODER_REGISTRY.\"`" + ] }, { - "name": "stdout", - "output_type": "stream", - "text": [ - "Completed trial #8, suggested by BoTorch.\n" - ] + "cell_type": "markdown", + "id": "7e0b9122", + "metadata": { + "id": "broadband-voice", + "isAgentGenerated": false, + "language": "markdown", + "metadata": { + "originalKey": "6487b68e-b808-4372-b6ba-ab02ce4826bc" + }, + "originalKey": "4d82f49a-3a8b-42f0-a4f5-5c079b793344", + "outputsInitialized": false, + "showInput": false + }, + "source": [ + "The two options for handling this error are:\n", + "1. disabling storage of `BoTorchGenerator`'s options by passing `no_model_options_storage=True` to `Generators.BOTORCH_MODULAR(...)` call –– this will prevent model options from being stored on the generator run, so a generator run can be saved but cannot be used to restore the model that produced it,\n", + "2. specifying serialization logic for a given object that needs to occur among the `Model` or `AcquisitionFunction` options. Tutorial for this is in the works, but in the meantime you can [post an issue on the Ax GitHub](https://github.com/facebook/Ax/issues) to get help with this." + ] }, { - "name": "stdout", - "output_type": "stream", - "text": [ - "Completed trial #9, suggested by BoTorch.\n" - ] + "cell_type": "code", + "execution_count": null, + "id": "a8ce55f4-74e6-4983-9013-1ec308a76b24", + "metadata": {}, + "outputs": [], + "source": [] + } + ], + "metadata": { + "fileHeader": "", + "fileUid": "0ff77011-535f-482a-8002-8dd1e5a1bdba", + "isAdHoc": false, + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.10.16" } - ], - "source": [ - "for _ in range(10):\n", - " # Produce a new generator run and attach it to experiment as a trial\n", - " generator_run = gs.gen(\n", - " experiment=experiment,\n", - " n=1,\n", - " pending_observations=get_pending_observation_features(experiment=experiment),\n", - " )\n", - " trial = experiment.new_trial(generator_run)\n", - "\n", - " # Mark the trial as 'RUNNING' so we can mark it 'COMPLETED' later\n", - " trial.mark_running(no_runner_required=True)\n", - "\n", - " # Attach data for the new trial and mark it 'COMPLETED'\n", - " experiment.attach_data(get_branin_data(trials=[trial]))\n", - " trial.mark_completed()\n", - "\n", - " print(f\"Completed trial #{trial.index}, suggested by {generator_run._model_key}.\")" - ] - }, - { - "cell_type": "markdown", - "id": "e4720316", - "metadata": { - "id": "circular-vermont", - "isAgentGenerated": false, - "language": "markdown", - "metadata": { - "originalKey": "9d3b86bf-b691-4315-8b8f-60504b37818c" - }, - "originalKey": "6a78ef13-fbaa-4cae-934b-d57f5807fe25", - "outputsInitialized": false, - "showInput": false - }, - "source": [ - "Now we examine the experiment and observe the trials that were added to it and produced by the generation strategy:" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "a69b4418", - "metadata": { - "collapsed": false, - "executionStartTime": 1730916319576, - "executionStopTime": 1730916321368, - "id": "significant-particular", - "isAgentGenerated": false, - "jupyter": { - "outputs_hidden": false - }, - "language": "python", - "metadata": { - "originalKey": "ca12913d-e3fd-4617-a247-e3432665bac1" - }, - "originalKey": "b3160bc0-d5d1-45fa-bf62-4b9dd5778cac", - "outputsInitialized": true, - "requestMsgId": "b3160bc0-d5d1-45fa-bf62-4b9dd5778cac", - "serverExecutionDuration": 35.789265064523 - }, - "outputs": [], - "source": [ - "exp_to_df(experiment)" - ] - }, - { - "cell_type": "markdown", - "id": "5c778f3a", - "metadata": { - "id": "obvious-transparency", - "isAgentGenerated": false, - "language": "markdown", - "metadata": { - "originalKey": "c25da720-6d3d-4f16-b878-24f2d2755783" - }, - "originalKey": "633c66af-a89f-4f03-a88b-866767d0a52f", - "outputsInitialized": false, - "showInput": false - }, - "source": [ - "## 6. Customizing a `Surrogate` or `Acquisition`\n", - "\n", - "We expect the base `Surrogate` and `Acquisition` classes to work with most BoTorch components, but there could be a case where you would need to subclass one of aforementioned abstractions to handle a given BoTorch component. If you run into a case like this, feel free to open an issue on our [Github issues page](https://github.com/facebook/Ax/issues) –– it would be very useful for us to know \n", - "\n", - "One such example would be a need for a custom `MCAcquisitionObjective` or posterior transform. To subclass `Acquisition` accordingly, one would override the `get_botorch_objective_and_transform` method:" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "84e98211", - "metadata": { - "collapsed": false, - "executionStartTime": 1730916320585, - "executionStopTime": 1730916321384, - "id": "organizational-balance", - "isAgentGenerated": false, - "jupyter": { - "outputs_hidden": false - }, - "language": "python", - "metadata": { - "originalKey": "e7f8e413-f01e-4f9d-82c1-4912097637af" - }, - "originalKey": "2949718a-8a4e-41e5-91ac-5b020eface47", - "outputsInitialized": true, - "requestMsgId": "2949718a-8a4e-41e5-91ac-5b020eface47", - "serverExecutionDuration": 2.2059100447223 - }, - "outputs": [], - "source": [ - "from botorch.acquisition.objective import MCAcquisitionObjective, PosteriorTransform\n", - "from botorch.acquisition.risk_measures import RiskMeasureMCObjective\n", - "\n", - "\n", - "class CustomObjectiveAcquisition(Acquisition):\n", - " def get_botorch_objective_and_transform(\n", - " self,\n", - " botorch_acqf_class: Type[AcquisitionFunction],\n", - " model: Model,\n", - " objective_weights: Tensor,\n", - " objective_thresholds: Optional[Tensor] = None,\n", - " outcome_constraints: Optional[Tuple[Tensor, Tensor]] = None,\n", - " X_observed: Optional[Tensor] = None,\n", - " risk_measure: Optional[RiskMeasureMCObjective] = None,\n", - " ) -> Tuple[Optional[MCAcquisitionObjective], Optional[PosteriorTransform]]:\n", - " ... # Produce the desired `MCAcquisitionObjective` and `PosteriorTransform` instead of the default" - ] - }, - { - "cell_type": "markdown", - "id": "13843a20", - "metadata": { - "id": "theoretical-horizon", - "isAgentGenerated": false, - "language": "markdown", - "metadata": { - "originalKey": "7299f0fc-e19e-4383-99de-ef7a9a987fe9" - }, - "originalKey": "0ec8606d-9d5b-4bcb-ad7e-f54839ad6f9b", - "outputsInitialized": false, - "showInput": false - }, - "source": [ - "Then to use the new subclass in `BoTorchGenerator`, just specify `acquisition_class` argument along with `botorch_acqf_class` (to `BoTorchGenerator` directly or to `Generators.BOTORCH_MODULAR`, which just passes the relevant arguments to `BoTorchGenerator` under the hood, as discussed in section 4):" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "2fffef64", - "metadata": { - "collapsed": false, - "executionStartTime": 1730916321675, - "executionStopTime": 1730916321901, - "id": "approximate-rolling", - "isAgentGenerated": false, - "jupyter": { - "outputs_hidden": false - }, - "language": "python", - "metadata": { - "originalKey": "07fe169a-78de-437e-9857-7c99cc48eedc" - }, - "originalKey": "e231ea1e-c70d-48dc-b6c6-1611c5ea1b26", - "outputsInitialized": true, - "requestMsgId": "e231ea1e-c70d-48dc-b6c6-1611c5ea1b26", - "serverExecutionDuration": 12.351316981949 - }, - "outputs": [], - "source": [ - "Generators.BOTORCH_MODULAR(\n", - " experiment=experiment,\n", - " data=data,\n", - " acquisition_class=CustomObjectiveAcquisition,\n", - " botorch_acqf_class=MyAcquisitionFunctionClass,\n", - ")" - ] - }, - { - "cell_type": "markdown", - "id": "16b06c8e", - "metadata": { - "id": "representative-implement", - "isAgentGenerated": false, - "language": "markdown", - "metadata": { - "originalKey": "608d5f0d-4528-4aa6-869d-db38fcbfb256" - }, - "originalKey": "cdcfb2bc-3016-4681-9fff-407f28321c3f", - "outputsInitialized": false, - "showInput": false - }, - "source": [ - "To use a custom `Surrogate` subclass, pass the `surrogate` argument of that type:\n", - "```\n", - "Generators.BOTORCH_MODULAR(\n", - " experiment=experiment, \n", - " data=data,\n", - " surrogate=CustomSurrogate(botorch_model_class=MyModelClass),\n", - ")\n", - "```" - ] - }, - { - "cell_type": "markdown", - "id": "e47f94c4", - "metadata": { - "id": "framed-intermediate", - "isAgentGenerated": false, - "language": "markdown", - "metadata": { - "originalKey": "64f1289e-73c7-4cc5-96ee-5091286a8361" - }, - "originalKey": "ff03d674-f584-403f-ba65-f1bab921845b", - "outputsInitialized": false, - "showInput": false - }, - "source": [ - "------" - ] - }, - { - "cell_type": "markdown", - "id": "44dc1fae", - "metadata": { - "id": "metropolitan-feedback", - "isAgentGenerated": false, - "language": "markdown", - "metadata": { - "originalKey": "d1e37569-dd0d-4561-b890-2f0097a345e0" - }, - "originalKey": "f71fcfa1-fc59-4bfb-84d6-b94ea5298bfa", - "outputsInitialized": false, - "showInput": false - }, - "source": [ - "## Appendix 1: Methods available on `BoTorchGenerator`\n", - "\n", - "Note that usually all these methods are used through `Adapter` –– a convertion and transformation layer that adapts Ax abstractions to inputs required by the given model.\n", - "\n", - "**Core methods on `BoTorchGenerator`:**\n", - "* `fit` selects a surrogate if needed and fits the surrogate model to data via `Surrogate.fit`,\n", - "* `predict` estimates metric values at a given point via `Surrogate.predict`,\n", - "* `gen` instantiates an acquisition function via `Acquisition.__init__` and optimizes it to generate candidates.\n", - "\n", - "**Other methods on `BoTorchGenerator`:**\n", - "* `update` updates surrogate model with training data and optionally reoptimizes model parameters via `Surrogate.update`,\n", - "* `cross_validate` re-fits the surrogate model to subset of training data and makes predictions for test data,\n", - "* `evaluate_acquisition_function` instantiates an acquisition function and evaluates it for a given point.\n", - "------\n" - ] - }, - { - "cell_type": "markdown", - "id": "720415a6", - "metadata": { - "id": "possible-transsexual", - "isAgentGenerated": false, - "language": "markdown", - "metadata": { - "originalKey": "b02f928c-57d9-4b2a-b4fe-c6d28d368b12" - }, - "originalKey": "91cedde4-8911-441f-af05-eb124581cbbc", - "outputsInitialized": false, - "showInput": false - }, - "source": [ - "## Appendix 2: Default surrogate models and acquisition functions\n", - "\n", - "By default, the chosen surrogate model will be:\n", - "* if fidelity parameters are present in search space: `SingleTaskMultiFidelityGP`,\n", - "* if task parameters are present: a set of `MultiTaskGP` wrapped in a `ModelListGP` and each modeling one task,\n", - "* `SingleTaskGP` otherwise.\n", - "\n", - "The chosen acquisition function will be:\n", - "* for multi-objective settings: `qLogExpectedHypervolumeImprovement`,\n", - "* for single-objective settings: `qLogNoisyExpectedImprovement`.\n", - "----" - ] - }, - { - "cell_type": "markdown", - "id": "45a8d6dc", - "metadata": { - "id": "continuous-strain", - "isAgentGenerated": false, - "language": "markdown", - "metadata": { - "originalKey": "76ae9852-9d21-43d6-bf75-bb087a474dd6" - }, - "originalKey": "c8b0f933-8df6-479b-aa61-db75ca877624", - "outputsInitialized": false, - "showInput": false - }, - "source": [ - "## Appendix 3: Handling storage errors that arise from objects that don't have serialization logic in A\n", - "\n", - "Attempting to store a generator run produced via `Generators.BOTORCH_MODULAR` instance that included options without serization logic with will produce an error like: `\"Object passed to 'object_to_json' (of type ) is not registered with a corresponding encoder in ENCODER_REGISTRY.\"`" - ] - }, - { - "cell_type": "markdown", - "id": "7e0b9122", - "metadata": { - "id": "broadband-voice", - "isAgentGenerated": false, - "language": "markdown", - "metadata": { - "originalKey": "6487b68e-b808-4372-b6ba-ab02ce4826bc" - }, - "originalKey": "4d82f49a-3a8b-42f0-a4f5-5c079b793344", - "outputsInitialized": false, - "showInput": false - }, - "source": [ - "The two options for handling this error are:\n", - "1. disabling storage of `BoTorchGenerator`'s options by passing `no_model_options_storage=True` to `Generators.BOTORCH_MODULAR(...)` call –– this will prevent model options from being stored on the generator run, so a generator run can be saved but cannot be used to restore the model that produced it,\n", - "2. specifying serialization logic for a given object that needs to occur among the `Model` or `AcquisitionFunction` options. Tutorial for this is in the works, but in the meantime you can [post an issue on the Ax GitHub](https://github.com/facebook/Ax/issues) to get help with this." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "a8ce55f4-74e6-4983-9013-1ec308a76b24", - "metadata": {}, - "outputs": [], - "source": [] - } - ], - "metadata": { - "kernelspec": { - "display_name": "Python 3 (ipykernel)", - "language": "python", - "name": "python3" - }, - "language_info": { - "codemirror_mode": { - "name": "ipython", - "version": 3 - }, - "file_extension": ".py", - "mimetype": "text/x-python", - "name": "python", - "nbconvert_exporter": "python", - "pygments_lexer": "ipython3", - "version": "3.10.16" } - }, - "nbformat": 4, - "nbformat_minor": 5 } diff --git a/tutorials/scheduler/scheduler.ipynb b/tutorials/scheduler/scheduler.ipynb index 650bd3ca127..377138ff109 100644 --- a/tutorials/scheduler/scheduler.ipynb +++ b/tutorials/scheduler/scheduler.ipynb @@ -1,933 +1,934 @@ { - "cells": [ - { - "cell_type": "markdown", - "metadata": { - "originalKey": "977ca50b-324e-4994-97cd-c6c17e723435" - }, - "source": [ - "# Configurable closed-loop optimization with Ax `Scheduler`\n", - "\n", - "*We recommend reading through the [\"Developer API\" tutorial](https://ax.dev/tutorials/gpei_hartmann_developer.html) before getting started with the `Scheduler`, as using it in this tutorial will require an Ax `Experiment` and an understanding of the experiment's subcomponents like the search space and the runner.*\n", - "\n", - "### Contents:\n", - "1. **Scheduler and external systems for trial evalution** –– overview of how scheduler works with an external system to run a closed-loop optimization.\n", - "2. **Set up a mock external system** –– creating a dummy external system client, which will be used to illustrate a scheduler setup in this tutorial.\n", - "3. **Set up an experiment according to the mock external system** –– set up a runner that deploys trials to the dummy external system from part 2 and a metric that fetches trial results from that system, then leverage those runner and metric and set up an experiment.\n", - "4. **Set up a scheduler**, given an experiment.\n", - " 1. Create a scheduler subclass to poll trial status.\n", - " 2. Set up a generation strategy using an auto-selection utility.\n", - "5. **Running the optimization** via `Scheduler.run_n_trials`.\n", - "6. **Leveraging SQL storage and experiment resumption** –– resuming an experiment in one line of code.\n", - "7. **Configuring the scheduler** –– overview of the many options scheduler provides to configure the closed-loop down to granular detail.\n", - "8. **Advanced functionality**:\n", - " 1. Reporting results to an external system during the optimization.\n", - " 2. Using `Scheduler.run_trials_and_yield_results` to run the optimization via a generator method." - ] - }, - { - "cell_type": "markdown", - "metadata": { - "originalKey": "99721805-f4f5-48e4-940c-bc2d0c73c61a" - }, - "source": [ - "## 1. `Scheduler` and external systems for trial evaluation\n", - "\n", - "`Scheduler` is a closed-loop manager class in Ax that continuously deploys trial runs to an arbitrary external system in an asynchronous fashion, polls their status from that system, and leverages known trial results to generate more trials.\n", - "\n", - "Key features of the `Scheduler`:\n", - "- Maintains user-set concurrency limits for trials run in parallel, keep track of tolerated level of failed trial runs, and 'oversee' the optimization in other ways,\n", - "- Leverages an Ax `Experiment` for optimization setup (an optimization config with metrics, a search space, a runner for trial evaluations),\n", - "- Uses an Ax `GenerationStrategy` for flexible specification of an optimization algorithm used to generate new trials to run,\n", - "- Supports SQL storage and allows for easy resumption of stored experiments." - ] - }, - { - "attachments": { - "image-2.png": { - "image/png": "iVBORw0KGgoAAAANSUhEUgAACFoAAAMgCAYAAAAZOpR9AAAgAElEQVR4AeydB5QcxZ3/STZgG4PD+WwDts/GZ+B8PPvPOYFtDOczBsMdNrbvDmyEApJQRihaQgkEQigAyhnlgAIoZ5SzULTiKiGUV3GVVhvq/37j63Z3T/dMz+zMVE3Pp9/bN7Mz1RU+85G2euu71VcpDghAAAIQgAAEIAABCEAAAhCAAAQgAAEIQAACEIAABCAAAQhAAAIQgAAEIACBUASuClWKQhCAAAQgAAEIQAACEIAABCAAAQhAAAIQgAAEIAABCEAAAhCAAAQgAAEIQAACiqAFEkAAAhCAAAQgAAEIQAACEIAABCAAAQhAAAIQgAAEIAABCEAAAhCAAAQgAIGQBAhahARFMQhAAAIQgAAEIAABCEAAAhCAAAQgAAEIQAACEIAABCAAAQhAAAIQgAAEIEDQAgcgAAEIQAACEIAABCAAAQhAAAIQgAAEIAABCEAAAhCAAAQgAAEIQAACEIBASAIELUKCohgEIAABCEAAAhCAAAQgAAEIQAACEIAABCAAAQhAAAIQgAAEIAABCEAAAhAgaIEDEIAABCAAAQhAAAIQgAAEIAABCEAAAhCAAAQgAAEIQAACEIAABCAAAQhAICQBghYhQVEMAhCAAAQgAAEIQAACEIAABCAAAQhAAAIQgAAEIAABCEAAAhCAAAQgAAEIELTAAQhAAAIQgAAEIAABCEAAAhCAAAQgAAEIQAACEIAABCAAAQhAAAIQgAAEIBCSAEGLkKAoBgEIQAACEIAABCAAAQhAAAIQgAAEIAABCEAAAhCAAAQgAAEIQAACEIAABAha4AAEIAABCEAAAhCAAAQgAAEIQAACEIAABCAAAQhAAAIQgAAEIAABCEAAAhAISYCgRUhQFIMABCAAAQhAAAIQgAAEIAABCEAAAhCAAAQgAAEIQAACEIAABCAAAQhAAAIELXAAAhCAAAQgAAEIQAACEIAABCAAAQhAAAIQgAAEIAABCEAAAhCAAAQgAAEIhCRA0CIkKIpBAAIQgAAEIAABCEAAAhCAAAQgAAEIQAACEIAABCAAAQhAAAIQgAAEIAABghY4AAEIQAACEIAABCAAAQhAAAIQgAAEIAABCEAAAhCAAAQgAAEIQAACEIAABEISIGgREhTFIAABCEAAAhCAAAQgAAEIQAACEIAABCAAAQhAAAIQgAAEIAABCEAAAhCAAEELHIAABCAAAQhAAAIQgAAEIAABCEAAAhCAAAQgAAEIQAACEIAABCAAAQhAAAIhCRC0CAmKYhCAAAQgAAEIQAACEIAABCAAAQhAAAIQgAAEIAABCEAAAhCAAAQgAAEIQICgBQ5AAAIQgAAEIAABCEAAAhCAAAQgAAEIQAACEIAABCAAAQhAAAIQgAAEIACBkAQIWoQERTEIQAACEIAABCAAAQhAAAIQgAAEIAABCEAAAhCAAAQgAAEIQAACEIAABCBA0AIHIAABCEAAAhCAAAQgAAEIQAACEIAABCAAAQhAAAIQgAAEIAABCEAAAhCAQEgCxgYt/vrXvyq+YIADOIADOIADOIADOIADmXEg5PUBxSAAAQhAAAIQgAAEckCAOW5m5rhwhCMO4AAO4AAO4AAORNeBHEzLq9QEQQsCHQRacAAHcAAHcAAHcAAHCsCBKl01cDIEIAABCEAAAhCAQEYJsCAQ3QUBPls+WxzAARzAARzAARzIjAMZnYBnoTKCFgXwS3X+MWfmHzMc4YgDOIADOIADOJDPDmThWoIqIQABCEAAAhCAAATSJJDP80r6znURDuAADuAADuAADuBALhxIc6qds9MIWhC04C9YcQAHcAAHcAAHcAAHCsCBnF1h0BAEIAABCEAAAhCAQFICufjFNG2wAIIDOIADOIADOIADOJDPDiSdVGsuQNCiAH6pns//gOg7PwBwAAdwAAdwAAdwIDMOaL7uoHkIQAACEEiRQHFxsTp79myKZ1EcAhDIFwLMcTMzx4UjHHEAB3AAB3AAB3Agug6YPrcnaEHQgr9gxQEcwAEcwAEcwAEcKAAHTL8woX8QgAAEskng6NGjauzYsfaXhBhMO0pKStS4cePUa6+9purWraueeeaZ2Nfzzz+vOnXqpGbOnKnKyspM6zb9gQAE0iTAgkB0FwT4bPlscQAHcAAHcAAHcCAzDqQ51c7ZaQQtCuCX6vxjzsw/ZjjCEQdwAAdwAAdwIJ8dyNkVBg1BAAIQMJCA/P9tBRfkcffu3XG9rKioUKWlpfZXZWVlXJlsvbB161bVqFEjVx+d/bWet2jRQm3fvj1b3aBeCEAghwTyeV5J37kuwgEcwAEcwAEcwAEcyIUDOZyep9UUQQuCFvwFKw7gAA7gAA7gAA7gQAE4kNbVAidBAAIQiAgB+QWQFVYIClqEKZMNHEuWLHH1zdlPv+e1a9dWJu7IkQ021AmBKBPIxS+maYMFEBzAARzAARzAARzAgXx2wPTrAYIWBfBL9Xz+B0Tf+QGAAziAAziAAziAA5lxwPQLE/oHAQhAIJsE5GeJM7Tgt6NFmDKZ7uP58+dVvXr1XH3r0aOH2rhxozp79qw6ffq0WrFihWrcuLGrTOfOnZXswMEBAQjkLwHmuJmZ48IRjjiAAziAAziAAzgQXQdMn+0TtCBowV+w4gAO4AAO4AAO4AAOFIADpl+Y0D8IQAAC2SRw6NAhNWjQIPvrzJkzcc3JL+eShTHiTqriCyNGjHC1OWHCBOV3yxIJXdSvX99Vdv/+/VVsndMhAAGdBFgQiO6CAJ8tny0O4AAO4AAO4AAOZMYBnfP1MG0TtCiAX6rzjzkz/5jhCEccwAEcwAEcwIF8diDMxQFlIAABCBQyAfk/PpdBCwlU1KxZ026zefPmCXepmD9/vl1W+rl06dJC/rgYOwTynkA+zyvpO9dFOIADOIADOIADOIADuXDA9Ek/QQuCFvwFKw7gAA7gAA7gAA7gQAE4YPqFCf2DAAQgoJuA/JIol0GLEydOuNpbsGBBQgSyK4ezf6NHj05YnjchAAGzCeTiF9O0wQIIDuAADuAADuAADuBAPjtg9oxeKYIWBfBL9Xz+B0Tf+QGAAziAAziAAziAA5lxwPQLE/oHgUIgUFpaqrZv365mzZql+vbtq1q2bKlat26tunfvruQWEhs2bAiN4fLly0oW5gcMGKBee+011aJFC9WsWTPVvn171a1bNzVjxgx1/PjxwPpOnjypZs6caX+dP38+Vnbnzp2x/vXv3z/Wt7Zt26qhQ4eqRYsWqY8++iiwPr83pP2JEyeqXr16qY4dO6qmTZvGxtypUyfVp08ftWLFCnXx4kW/U31fO3jwoFq8eLEaPnx4rD4Z76uvvhq7HcicOXPUpUuXfM+TF0tKSuyxyrhPnz4dKyu337A4DBs2zBVkkM/Eem/evHmx3SaEufXakiVLAttzvlFRURFjap23Zs2a2NubN292tbd7927naXHPi4uLXeXlM+KAAATylwBz3MzMceEIRxzAARzAARzAARyIrgOmz/YJWhC04C9YcQAHcAAHcAAHcAAHCsAB0y9M6B8Eok7gyJEjseCCc0cCv+cSbJAF+ETH5MmTVd26dV2L7n51yWvTpk3zrWrVqlWu8yXEIKGNoHqs1wcOHKiuXLniW6f14tmzZ9Wbb76pqlWrlrQ+GUdRUZF1qu+jtCdhD6sPQY9S15QpU3xvvyG/eHOeZ4Ua5s6d63rdWcb5XOqWwETjxo3t8jI+CawkO7xtv/vuu7FT1q5dqxo2bGh/WeGPoPq2bdtmty19kxALBwQgkL8EWBCI7oIAny2fLQ7gAA7gAA7gAA5kxgHTZ/sELQrgl+r8Y87MP2Y4whEHcAAHcAAHcCCfHTD9woT+QSDKBGQHg9q1a7sWyZ2L+N7n1atXjwXg/JjI4rq3fLLvZ8+eHVeVN2hRv3790PV26NAhMGAgO23IrhrJ+uR8X9hI0MPvkF0x2rVrl1J9shOF95D/v51tphO0kDol5OKsR3YOSXZ4QyJHjx5Ndorv+xJycba9evVq33K8CAEI5AeBfJ5X0neui3AAB3AAB3AAB3AAB3LhgOkze4IWBC34C1YcwAEcwAEcwAEcwIECcMD0CxP6B4GoEpBbUzgXx+W57GIgt32Q21FICGPq1KmunRKkTJ06dZR3QX79+vWuumRHhTZt2qh33nlHLVu2LHbrEamrefPmrnJSxnt4gxbOPnbu3FnJrgtyaw8JFrz++uuu+qSs7LxRWVnprTZuV4xatWrFbm0iAZF169YpCQdIEMIbPJGdKLyH7CDRqlUrV9s1atRQb7zxRmznCtkRQm7lIbdOcfZfngtb5yG/AHKWsYIWmzZtit3aRG5vIuN2lpExyuvyNX78+Fh1cvsO504dUibRUVZWpurVq2fXK22kc3j7Lw5J3RwQgED+EsjFL6ZpgwUQHMABHMABHMABHMCBfHbA9Nk+QYsC+KV6Pv8Dou/8AMABHMABHMABHMCBzDhg+oUJ/YNAVAl0797dXmSXRfyOHTuqkpKSuOGWlpbGQhPOhX4JOTiPwYMH23XJYn/QjgYXL1507QIhZeU15+EXtJByixYtchazn0voQkIOzv5JSMR5SPDi+eeft8s0adJESTDB79izZ4+qWbOmXVbCHN5DwiPO9iR8sn37dm+x2PeTJk1ylW3RooWrnPwscdZlBS2chcKUkfLezzRoNw4pu3HjRle7S5cudTYZ6vnevXvjbhWzfPnyUOdSCAIQMJcAc9zMzHHhCEccwAEcwAEcwAEciK4D5s7m/9YzghYELfgLVhzAARzAARzAARzAgQJwwPQLE/oHgSgSkMV85+K+7H4gt9YIOrZu3eoq/9JLL7mKNmvWzH6/W7durve838iODs62i4qKXEX8ghbJQgAbNmxw1dm6dWslu05Yx4EDB1zvL1682HrL99G5E0Xjxo1dZcrLy5VzvBIC2bdvn6uM8xsJqkgdzjEfOXLELiK/eHO+V5WghXdnkQkTJtjteJ8MGDDAbld28Uj0+XvPle+FqTO8ImPwuzWK37m8BgEImE2ABYHoLgjw2fLZ4gAO4AAO4AAO4EBmHDB7Rq8UQYsC+KU6/5gz848ZjnDEARzAARzAARzIZwdMvzChfxCIIoFBgwbZi+yyQB5mF4K+ffvGbqshi/Kyg8P58+djaCTQIDspvPzyy7GvZCGG6dOnu9pOFrSQUIMzNBH0eXTo0MFVrzOwILdJsfonj95bn3jrdNbVqFEj19tbtmxxtSNjT3YI3wYNGtj8nLtzyP/fmQpaCCdnqOOFF17wvY3KlStXXLdIGTp0aLIhuN6XoEj9+vVd/R44cKBvW64T+QYCEMgLAvk8r6TvXBfhAA7gAA7gAA7gAA7kwgHTJ/YELQha8BesOIADOIADOIADOIADBeCA6Rcm9A8CUSTwyiuv2IvksiuBLLxn+5CdHSRgIIEDZ7AgWdBi1qxZobrm3Qkj2S4YfpWeOnVKjRkzxtU/b9Bi/vz5rvdlN42qHPILICcPZ0DEqjdMGavsxIkTXfXt2LHDest+XLdunauM9zOwC/o8kTCH3GbG2We5dYzcnoUDAhCIBoFc/GKaNlgAwQEcwAEcwAEcwAEcyGcHTJ/5E7QogF+q5/M/IPrODwAcwAEcwAEcwAEcyIwDpl+Y0D8IRJGAhAeshfLOnTtnfIjFxcVKgg+TJk1SvXr1Ui1btlRyiw2rTeejd5HfG5jYvn17qP4dPnzYVf+7774beJ6EBWSXi4ULF6rRo0erN954w7UThLN/3qCFlHe+f/r06cB2wrwhP0uc9VU1aHHixAkX62HDhsV1o3fv3nabcpuVVA7ZscTZX2EXZseRVNqgLAQgoJcAc9zMzHHhCEccwAEcwAEcwAEciK4DemfsyVsnaEHQgr9gxQEcwAEcwAEcwAEcKAAHkl8aUAICEMgkgcuXL7sWyuWWIJk45FYi7733nmrSpImrfueivN/zZEGL48ePh+qe7MrhrF/CBN7j4MGDqn///q7bZjjP8XvuDVr07NnTbufZZ5+tcshAfvHmbLeqQQsZc7du3ew6ZceSsrIyG4V8/rVq1bLfD7tjiFXBW2+9ZZ9bo0YNJaEaDghAIFoEWBCI7oIAny2fLQ7gAA7gAA7gAA5kxgHTrwAIWhTAL9X5x5yZf8xwhCMO4AAO4AAO4EA+O2D6hQn9g0DUCMgODM6F/SFDhlR5iLI7RN26dV31OtuoXbu26tChg5JbTIwaNcpVLlnQIuxCvjdoIYEI5zFz5kxXu87+yXMJVHTp0kWNHz9evfrqq3ZZb9BCdgCxzn3uueecTaT1XP7/tuqTx0wELby3Blm/fr3dN+eOIdWrV1dnz5613wvzpGHDhnZ//cIsYeqgDAQgYDaBfJ5X0neui3AAB3AAB3AAB3AAB3LhgNkzeqUIWhC04C9YcQAHcAAHcAAHcAAHCsAB0y9M6B8EokagsrJS1axZ014sl90PqnJIcKNx48Z2fRIWaNq0qZJbd2zbti1uIV9+4eEMFiQLWuzcuTNU92TnC2e9cosP6/AGD6SchCnmzJmjDhw4oGSXB+cxfPhwuy5v0GLAgAH2e1LPxYsXnaem/NzLIxNBi/LycuUMRMjtW6zjzTfftPsvu1Okcly6dMk+V8Y+ZcqUVE6nLAQgkCcEcvGLadpgAQQHcAAHcAAHcAAHcCCfHTB9ak/QogB+qZ7P/4DoOz8AcAAHcAAHcAAHcCAzDph+YUL/IBBFAq1bt7YXzJs1axZqiFu3blX9+vWzv44dOxY774MPPrDrksX37t27JwwfbNmyxVU+WdBiwYIFofr34YcfuuqdN2+efd4bb7zhem/27Nn2e35Phg0bZpf3Bi3ef/99+z0Z7969e/2qcL0mAQUnu+XLl9vvy88Sqcf6ykTQQiqXoItVpwRrJBBy4cIFJbf7sF7fsGGD3Y8wT7xBi7lz54Y5jTIQgECeEWCOm5k5LhzhiAM4gAM4gAM4gAPRdcD0KT5BC4IW/AUrDuAADuAADuAADuBAAThg+oUJ/YNAFAnITgbWYrs8htk1om/fvvY5snBv7QIhtx5x1vXRRx8lROa9hUeyoEWbNm0S1me9KbcKcfZj8+bN1luqXr169nthgiWdOnWyy3uDFs5bb0h7svtFssMbAlmxYoV9ivzizdnvTAUtZIePatWq2XUvXrxYLV261P5exlVRUWH3I+yT7du3K9khRL6ssE3YcykHAQjkBwEWBKK7IMBny2eLAziAAziAAziAA5lxwPSZPUGLAvilOv+YM/OPGY5wxAEcwAEcwAEcyGcHTL8woX8QiCKBWbNm2QvussgvIYVEx6lTp1SdOnXsc2SHCOtwhhJkYT/R4r3siNC8eXO7HmnbGyzwBhmkjAQVEh1HjhxxhQokWGHd0uPs2bOu9pLdLkNCJ86AgtyCw3mcOHFCVa9e3a6zVq1a6ty5c84icc979Ohhl5e6S0pK7DLy/3c2ghbSQNeuXe26u3TpouQ2MVZb48ePt/vAEwhAAAJOAvk8r6TvXBfhAA7gAA7gAA7gAA7kwgHn/NnE5wQtCFrwF6w4gAM4gAM4gAM4gAMF4ICJFyP0CQJRJ1BaWqqaNGliL7rL4rvszOAXkpBwxGuvveYq67wth9wSw1q8l8egUIQEHuS2Is6y8lxuJeI8/IIWEmaQHRT8jsOHD6vGjRu76p0+fbpdVMYk51vtSnAiKBghoQ9vXc8995xdl/VkxIgRdn1Sr9yK5eTJk9bbrkdvqOXll192vS+/ALL6Jo/e4IkU3rFjh6vMmjVrXHUEfbN27VrXec52JJyS6iGfe6tWreyvt99+O9UqKA8BCOQBgVz8Ypo2WADBARzAARzAARzAARzIZwdMn9YTtCiAX6rn8z8g+s4PABzAARzAARzAARzIjAOmX5jQPwhElYDzNhLWAnznzp2V3NpDdnWQW0TMmTNHyS0mrPflsW3bturKlSs2ltmzZ7vel1DD5MmTldwSZP/+/UqCExMmTHDtiOGsb9CgQWrXrl12yMMvaCHlZScIuX3J/PnzY+WlnAQenLcFkXINGjSwb2tidfKVV15x9bFly5ZqyZIl6sCBA7GxLlq0KFa3s1/O58uWLVMHDx60qosFNWrXru2qUwIaskvEhg0b1J49e2Lj9gZUZCeMvXv32vXIE/lZ4mzLL2ght+hwlqlfv76SW7aMHTs2xtpVoeOb8vJyJcES57ny3Bv2cJyS8Ono0aNddYW5DUvCCnkTAhAwkgBz3MzMceEIRxzAARzAARzAARyIrgNGTuQdnSJoQdCCv2DFARzAARzAARzAARwoAAcc1wA8hQAEckhAdnoYMGCAa+HcuyDv/V7CBd6dEIqLi5Us/HvLBn3/4osv+pY9fvx4bPTeoIU3SBFUr7wu/ZCAiPdYsWKFb5tBdfmNRwImzkP66dwpI6gu5+sSSvEe8os3Zxm/oEVZWZmSnTWc5azndevW9Vbp+v7dd9+NO09CJukcBC3SocY5EMg/AiwIRHdBgM+WzxYHcAAHcAAHcAAHMuOA6bN8ghYF8Et1/jFn5h8zHOGIAziAAziAAziQzw6YfmFC/yAQdQISGJDFemvhPuhRdoWQHSr8Dgk3eHd48KunR48eSm4h0qZNm7j2goIWstuFd2cIv7o7deqkTp065de92Gt+gQNvPTVr1lRTpkxRhw4diu2g4XzfG7SQSiV00r59+7ixOM+T57LLxuLFi337Jv9/O8v7BS3kRNnJw1nOep4saOHdDUM+p8uXL/v2JdmLBC2SEeJ9CESDQD7PK+k710U4gAM4gAM4gAM4gAO5cMD0mT9BC5+ghekfGv2DAAQgAAEIQAACEMg/Arm4+EjURv4Ro8cQiB6BkydPxhbyhw0bpjp27BgLTcgtJ+RWIoMHD1arV69OOujz58+radOmqVdffVU1bdpUSWhBbtHRu3dvNXXqVOUMEMhtOOSWIc8//7xq3ry56t+/v5Lz5fDuaHH06NHY65s2bYr1pUWLFrH+ya4Tb7zxhpo4caJav369kl0fkh0SoJAxdujQIRZ+kNCBPB86dGhs/MLBOmTMXbp0ie0kIWXef/996y3Xo9yeQ/ostw3p1q2bkluISL0SzJCxC5OLFy+6znF+I2ENuQWK9SVBlKBDyk6fPl1J4EHKDx8+PBYMCSovr0v/nCEY+TzTPdauXWv3U9qXUAoHBCAQPQKJ5m28x8IFDuAADuAADuAADuAADvzV+IsAghYELYyXlA5CAAIQgAAEIACBKBDQfXEUBYaMAQIQyByBoKBF5loorJokHGHtfiGPskMIBwQgAIFEBHTPDWmfxRscwAEcwAEcwAEcwAHTHUg0nzbhPYIWBC1M8JA+QAACEIAABCAAgcgT0H3hEnnADBACEEiJAEGLlHAlLdy1a1c7aCE7jHBAAAIQSEZA99yQ9llYwQEcwAEcwAEcwAEcMN2BZHNq3e8TtCBoodtB2ocABCAAAQhAAAIFQUD3hUtBQGaQEIBAaAIELUKjSlpw+/btdshCdrOYO3du0nMoAAEIQED33JD2WVjBARzAARzAARzAARww3QHTrxoIWhC0MN1R+gcBCEAAAhCAAAQiQUD3hUskIDIICEAgYwQIWqSP8uOPP1aLFy9WBw4ciD02atTIDlrUq1dPXb58Of3KORMCECgYArrnhrTPwgoO4AAO4AAO4AAO4IDpDph+cUDQgqCF6Y7SPwhAAAIQgAAEIBAJArovXCIBkUFAAAIZI0DQIn2U69ats4MVsoOF82vWrFnpV8yZEIBAQRHQPTekfRZWcAAHcAAHcAAHcAAHTHfA9AsEghYELUx3lP5BAAIQgAAEIACBSBDQfeESCYgMAgIQyBgBghbpowwKWnTv3l1VVlamXzFnQgACBUVA99yQ9llYwQEcwAEcwAEcwAEcMN0B0y8QCFoQtDDdUfoHAQhAAAIQgAAEIkFA94VLJCAyCAhAIGMEdu/erXr16mV/nT59OmN1R72inTt3Kut2IdWrV1ctW7ZUM2bMUOXl5VEfOuODAAQySED33JD2WVjBARzAARzAARzAARww3YEMTr+zUhVBC4IWWRGLSiEAAQhAAAIQgAAE3AR0X7i4e8N3EIAABCBQVQIVFRVKvjggAAEIpENA99yQ9llYwQEcwAEcwAEcwAEcMN2BdObZuTyHoAVBi1z6RlsQgAAEIAABCECgYAnovnApWPAMHAIQgAAEIAABCBhIQPfckPZZWMEBHMABHMABHMABHDDdAQOn8a4uEbQgaOESgm8gAAEIQAACEIAABLJDQPeFS3ZGRa0QgAAEIAABCEDAn8DMmTPVunXr/N/kVaV7bkj7LKzgAA7gAA7gAA7gAA6Y7oDplw0ELQhamO4o/YMABCAAAQhAAAKRIKD7wiUSEPNoEBcvXlSHDx9W27ZtUytXrlQffPCBmjt3rpoxY4aaPn167Lm8tnz5crV161Z18OBBVVJSkkcjpKsQgAAEIACBxATat2+vrrrqKvX4448TuPBBpXtuSPssrOAADuAADuAADuAADpjugM802qiXCFoQtDBKSDoDAQhAAAIQgAAEokpA94VLVLmaMi4JSchnLGGKd955R7399ttpfQ0ePFjJXwBv2rRJnT592pTh0Q8IQAACEIBAygSsoIWELQhcxOPTPTekfRZWcAAHcAAHcAAHcAAHTHcgfhZt1isELQhamGUkvYEABCAAAQhAAAIRJaD7wiWiWLUO69KlS2rz5s1q0qRJaYUqwoQxxo4dq9avX89uF1o/aRqHAAQgAIF0CHiDFgQu3BR1zw1pn4UVHMABHMABHMABHMAB0x1wz6DN+46gBUEL86ykRxCAAAQgAAEIQCCCBHRfuEQQqbYhnTlzRi1atEj17ds3MGAh70lIYtasWbFbh8gOFXIbkd27d6uioiK1ffv22K4Vq1evVnPmzFETJkxQ/fv3D6yvV69eavbs2er48ePaxk3DEIAABOYQJnAAACAASURBVCAAgVQIBAUtCFz8jaLuuSHts7CCAziAAziAAziAAzhgugOpXH/oKEvQgqCFDu9oEwIQgAAEIAABCBQcAd0XLgUHPAsDltuDSNhBQg/e3SjktSlTpsTuQX/kyBFVUVGRcg8qKyvViRMnYgGM6dOnqz59+sS1I+2+9957qri4OOX6OQECEIAABCCQSwLJghaFHrjQPTekfRZWcAAHcAAHcAAHcAAHTHcgl9cv6bRF0IKgRTrecA4EIAABCEAAAhCAQIoEdF+4pNjdnBe3FltMfLzuuuvUww8/rLp16xYXfJBdK2S3igsXLmScWWlpaWwXjMmTJ8e127NnT/Xkk0+qG2+8MXbfexO50aer+GyuggH/DnAAB8I78Nhjj8UCixn/gWpohbrnhrTPwgoO4AAO4AAO4AAO4IDpDhg6lbe7RdCCoIUtA08gAAEIQAACEIAABLJHQPeFS/ZGlpmaTV2Iuu2221Tbtm3jgg6yq8RHH32UmcGHqOXYsWOx25B4d9Po3Lmzuuuuu1jQZ0EfB3AAB3AgEg5cffXVql+/fiF+MuZ/Ed1zQ9pnYQUHcAAHcAAHcAAHcMB0B0yf9RO0IGhhuqP0DwIQgAAEIAABCESCgO4LF9Mhmhi0ePDBB1WPHj1cIYsxY8aoQ4cOacN58uTJ2C1KnLcueeutt9QTTzyhrr322kgsspnoAn0K/xfpsIIVDuBAug7IjhZr167V9jM21w3rnhvSPgsrOIADOIADOIADOIADpjuQ6zl6qu0RtCBokaozlIcABCAAAQhAAAIQSIOA7guXNLpcsKeUlZWp6dOnuwIW8te1mzdvVpWVlUZwKSoqUkOGDHH1cfz48erixYtG9I9OQAACEIAABNq3bx8qAFhoAQvLDN1zQ9pnYQUHcAAHcAAHcAAHcMB0B6y5s6mPBC0IWpjqJv2CAAQgAAEIQAACkSKg+8IlUjCzOJhLly6pd999Ny7AcObMmSy2ml7VEqqYNm2aq6/Dhw9XJvY1vRFyFgQgAAEI5DOBZEGLQg1YWJ+p7rkh7bOwggM4gAM4gAM4gAM4YLoD1tzZ1EeCFgQtTHWTfkEAAhCAAAQgAIFIEdB94RIpmFkaTElJiRo5cqQruLBkyRJVXl6epRYzU+2GDRtUr1697H4PGjRInThxIjOVUwsEIAABCEAgTQJBQYtCD1hYOHXPDWmfhRUcwAEcwAEcwAEcwAHTHbDmzqY+ErQgaGGqm/QLAhCAAAQgAAEIRIqA7guXSMHMwmBkJ4tRo0bZYYW3335bbdy4MQstZafKPXv2qD59+tj9Hzx4MDtbZAc1tUIAAhCAQEgC3qCFBCzWrVsX8uzoF9M9N6R9FlZwAAdwAAdwAAdwAAdMd8D0qwKCFgQtTHeU/kEAAhCAAAQgAIFIENB94RIJiFkaRFlZmet2Ib1791a7d+/OUmvZq/bw4cNqwIABdtjinXfeURcuXMheg9QMAQhAAAIQSEDACloQsPCHpHtuSPssrOAADuAADuAADuAADpjugP9M2pxXCVoQtDDHRnoCAQhAAAIQgAAEIkxA94VLhNFWeWgzZsywwwmyk8XOnTurXKeuCiRs4dzZYty4ccbf+kQXK9qFAAQgAIHsEpg5cyY7WCRArHtuSPssrOAADuAADuAADuAADpjuQILptBFvEbQgaGGEiHQCAhCAAAQgAAEIRJ2A7guXqPNNd3xyexAJV1hf+XS7kKAx7927V/Xq1cse06JFi4KK8joEIAABCEAAApoI6J4b0j4LKziAAziAAziAAziAA6Y7oGmqHrpZghYELULLQkEIQAACEIAABCAAgfQJ6L5wSb/n0T3z2LFjSm4TYoUsFi9eHJnBbtq0yR6XjK+oqCgyY2MgEIAABCAAgSgQ0D03pH0WVnAAB3AAB3AAB3AAB0x3wPR5P0ELghamO0r/IAABCEAAAhCAQCQI6L5wiQTEDA6ivLxcjRw50g4jRPEWG85bogwYMEBdvHgxgwSpCgIQgAAEIACBqhDQPTekfRZWcAAHcAAHcAAHcAAHTHegKvPtXJxL0IKgRS48ow0IQAACEIAABCBQ8AR0X7gU/AfgAbB+/Xo7ZNGvXz915swZT4n8//by5ctq2LBh9jgXLFiQ/4NiBBCAAAQgAIGIENA9N6R9FlZwAAdwAAdwAAdwAAdMd8D0qT9BC4IWpjtK/yAAAQhAAAIQgEAkCOi+cIkExAwNoqSkREm4wrplyIYNGzJUs3nV7Nu3zx6njPfo0aPmdZIeQQACEIAABAqQgO65Ie2zsIIDOIADOIADOIADOGC6A6ZfJhC0IGhhuqP0DwIQgAAEIAABCESCgO4Ll0hAzNAgZGcHK2QxevRoVVFRkaGazaxm2rRp9ngnTpxoZifpFQQgAAEIQKDACOieG9I+Cys4gAM4gAM4gAM4gAOmO2D6JQJBC4IWpjtK/yAAAQhAAAIQgEAkCOi+cIkExAwM4vz586p379528ODgwYMZqNXsKuS2KM4xHzlyxOwO0zsIQAACEIBAARDQPTekfRZWcAAHcAAHcAAHcAAHTHfA9MsCghYELUx3lP5BAAIQgAAEIACBSBDQfeESCYgZGMSyZcvskMWECRMyUGN+VDFv3jx73LLDBQcETCRw+fJlZX2Vl5eb2EVj+3Rp+xZ1ccuH9lfZyRMp97X0o332+VJXxaWLKdfBCRCAQHgCuueGtM/CCg7gAA7gAA7gAA7ggOkOhJ9d6ylJ0IKghR7zaBUCEIAABCAAAQgUGAHdFy4Fhtt3uGVlZapfv3524GDv3r2+5aL44smTJ+1xy21TZJcLDgiYRODixYvqmWeesb/mzp1rUveM78ue/7xf7br/n+2vAzWfVJUphlUOv9TEPl/quly0w/hx00EI5DMB3XND2mdhBQdwAAdwAAdwAAdwwHQHTJ/vE7QgaGG6o/QPAhCAAAQgAAEIRIKA7guXSECs4iB27dplhw1GjBihKisrq1hj6qfPnj1bTZ06Nfb14Ycfpl5BFc6QdiVkIV9r1qypQk2cCoHMEwgTtLhy5YoaP368/bV79+7MdyRPa/QGLSQocWrMkJRGQ9AiJVwUhkCVCeieG9I+Cys4gAM4gAM4gAM4gAOmO1DlSXeWKyBoQdAiy4pRPQQgAAEIQAACEICAENB94cKnoJTcMsMKGqxevTrnSLZs2WL/tb785X7//v1z2oedO3fa4x85cmRO26YxCCQjECZoEaZMsnai+r5f0GL3g/+qSj8+EHrIBC1Co6IgBDJCQPfckPZZWMEBHMABHMABHMABHDDdgYxMvLNYCUELghZZ1IuqIQABCEAAAhCAAAQsArovXKx+FOpjaWmp6t27tx00yPWtM4qLi1Xr1q21Bi28t045ceJEoerAuA0k4A1RLFy4MK6X3jLcXuTviPyCFrKrxcEGfw69ew9Bi7/z5BkEckFA99yQ9llYwQEcwAEcwAEcwAEcMN2BXMzLq9IGQQuCFlXxh3MhAAEIQAACEIAABEIS0H3hErKbkS22b98+O2QxZsyYnI1TAh3z5s1Tzz//vCtkoWNHCxn0rFmzbA4bNmzIGQcagkAyAnIrHwkkWV9ymxDvQdDCS+Tv3wcFLSRscea9cX8vmOAZQYsEcHgLAlkgoHtuSPssrOAADuAADuAADuAADpjuQBam4RmtkqAFQYuMCkVlEIAABCAAAQhAAAL+BHRfuPj3qnBeXbZsmR0wWLJkSVYHLm116dIltoNFtWrV4gIWErLQFbTYvHmzzWH69OlZ5UDlEMg0AYIWwUQTBS2KfvX/VNnxo8En/987cUGL3duTnkMBCEAgfQK654a0z8IKDuAADuAADuAADuCA6Q6kP9vOzZkELQha5MY0WoEABCAAAQhAAAIFTkD3hUuB41fjx4+3AwZ79uzJKo6xY8cGhiuskIWuoMXJkydtDgMHDswqh3yvXFitX79erVixQu3atUudOnUq9C0YnGOXeoqKitSaNWvU0qVLY3Xu3LlTSWigKsfp06eV7EqyatUqdfRo8kX0oLbkljJy/rZt29Ty5ctjX5s2bVL79+9XFRUVQaclfP3SpUtqx44dsfFKuOfIkSNK2qnqQdAimKAraPHzu9XePzykZDcL6+tQizrBJ//fOwQtkiKiAAQySkD33JD2WVjBARzAARzAARzAARww3YGMTsCzUBlBC4IWWdCKKiEAAQhAAAIQgAAEvAR0X7h4+1No3/fr188OGFR1gTsZO5ODFtL3AQMG2CxKSkqSDaeg3pdARffu3VWDBg18wzJNmzZV8+fPV6WlpQm5yPsffPCB+stf/uJbjwRtatasqXr27Kn27t3rW9fZs2dV7dq11XPPPRf7Wr16tZLXevfurRo2bBhXr9yepmvXrmrjxo2+9XlflFt0SACpXr16cXVZgSBpZ/jw4erChQve0+O+F5eGDh2qWrZsqfx2cpHxjhgxInZrkLiTlYoxlTFY412wYEGsmASjrNdq1arl6muNGjXs96TM8ePHYwys8tZrfu05X5PblrRo0cKuq3Xr1s638+K5M2hR9PC96sK6FXbIwgpbnJs7LeFYCFokxMObEMg4Ad1zQ9pnYQUHcAAHcAAHcAAHcMB0BzI+Cc9whQQtCFpkWCmqgwAEIAABCEAAAhDwI6D7wsWvT4Xy2vnz5+1ggYQMsn0sXrw4tlgvC/bOL1lothawde1oIWN37u7x8ccfZxtH3tQ/e/ZsVb16dddn5Py8nM8lcCE7VfgdEuRp27ZtqHqkTglTyO4P3uPYsWOuOuRze+GFF1yvOftkPZeQw/vvv59w943du3fHgh7WOcke27VrpxKFciQsIkyS1SPvC2PZJcR7BO1WIX0NU6+UEWaTJ092lRcWyQ4J2DjbENb5dniDFtL/o13auMIWe37zI1V+2t9bKU/QIt8+dfqb7wR0zw1pn4UVHMABHMABHMABHMAB0x0wfc5P0IKghemO0j8IQAACEIAABCAQCQK6L1wiATHNQUiY4O2334596VxA9S5E9+/fP80RVe20OXPm2Dy2bt1atcoicrbcRsW50G49lx0R2rRpo2SnBes161Fe9+6OIrfH6NKlS1xZOUd2yWjfvr2qX79+3PuNGjWKI+kNWljtOh+bNWsWC2o4X7Oe9+3bN65OeeHw4cOBu1jIbhQSEvGGgqRO2Y3C75Dbq8jOEla71qMEPqQ+CYd4d7iQsMX27dtd1WUiaCHhF9mpw9leq1atXO34fTNy5EhX/+VWJ/l2+AUtykvOqT3/9VNX2OJIh6aBQyNoEYiGNyCQFQK654a0z8IKDuAADuAADuAADuCA6Q5kZSKewUoJWhC0yKBOVAUBCEAAAhCAAAQgEERA94VLUL8K4XXZLcAKWsyaNUvbkE0JWqxcudLmsWrVKm08TGlYFvytcID1OGTIEHXgwAFVUVFhd3Pt2rVxt+wYM2aM/b48kdt2WHXIo4QMli1bFttpwSoot6nYvHlzXHhDghXOIyhoIbf6kNuIWDtMSB+lr7169XK1Le1v2bLFWWXsuYzN2UfZdUX6LTu/WMfly5fVe++95yonwRLvIcES7y4bEmyQAI8zhCLBBbmtibPdxo0bu3bdCApayG1YJCwlX3IbEWcdEv6w3pPbhliHjMlZbv/+/dZbcY/Cz3krlpdffjmuTD684Be0kH6XLF3gClrIbUTOL//Ad0gELXyx8CIEskZA99yQ9llYwQEcwAEcwAEcwAEcMN2BrE3GM1QxQQuCFhlSiWogAAEIQAACEIAABBIR0H3hkqhvUX9PFrWtoMXChQu1DdeUoMWHH35o81iyZIk2HqY0/Morr7gW5eXWE0GHBFOcC/iyo4TzkB1TrPefffZZlWhnBLl9hlVWHiWQ4Tz8ghYSagiqUwIc48aNc9XZoUMHZ5Wx582bN7fLyPsSlgg6nOEN2SXi0qVLrqLz58+365IxdOzY0Q6AuAoqFQty1K1b11VebjliHUFBC+t9eQxTRsqJ40623kCMs075v9lZNp1/E0ePHlWys0dVv6Qv6R5BQQup73D7F1xhi71P/EyVny+Ja4qgRRwSXoBAVgnonhvSPgsrOIADOIADOIADOIADpjuQ1Ql5BionaEHQIgMaUQUEIAABCEAAAhCAQDICui9ckvUvyu/L4qcVtFi6dKm2oZoStJBdDiweCxYs0MbDhIbl36VzkT3ZbgYSZpBwgvOcQ4cO2UOR86335DYhiY6DBw/aZeWcefPmuYr7BS1k54lkh+w8YfVBHiVoZB1nz551vTdt2jTrLd9H764Wp0+ftsuVl5e7doKQIMaJEyfs9/2eyI4yzr45Qy1hQhRhyki7skuF7JhhtSW3ZnHuTuLs29ChQ+1ytWvXVrKbR6qHcLTaqurjmTNnUm0+Vj5R0KLs1ElV9OiPXGGLo11fimuHoEUcEl6AQFYJ6J4b0j4LKziAAziAAziAAziAA6Y7kNUJeQYqJ2hB0CIDGlEFBCAAAQhAAAIQgEAyArovXJL1L8rvr1mzxg4WyG0zdB2mBC3kVhlW0GLOnDm6cBjRrjdIsHz58qT9kt0LhJuEBuRLvrcO2W1CbpshXxKkSHRIyMC5KJ8saNGiRQvXrTaC6hbHnfVOmjTJVXTnzp12HyV4EXTILTtkhwpnXc6ghYzb+Z7criPZIbtnfPDBBzY7Z3AkTIgiTBmrDzJuZ//kM/EeEhaRW7FY5QYPHuwtEur7TAYtnIxDNf5/hRIFLaTIubnTXEELuYXIhQ9Xu5ogaOHCwTcQyDoB3XND2mdhBQdwAAdwAAdwAAdwwHQHsj4pr2IDBC0IWlRRIU6HAAQgAAEIQAACEAhDQPeFS5g+RrUMO1q4P1l2tPg7j4EDB9qL7LIjg4QLsnHIbgqyQ8WGDRvU+++/H7crhiz0JwtaTJw4MVTXrly5omQsVnigb9++oc6TsR84cEBJ2GTs2LGqQYMGdh1WXc4QgOyUYb0uj95bn4Rq1FEoTIgiTBmryuLiYheHQYMGWW/Zj5s2bXKNYdeuXfZ7qTwpKipSo0ePzsiXjDGdI1nQQuo81KKOK2yx77//Q1Vc/vvtYAhapEOecyCQPgHdc0PaZ2EFB3AAB3AAB3AAB3DAdAfSn23n5kyCFgQtcmMarUAAAhCAAAQgAIECJ6D7wqWQ8cuCsLWDw8KFC7WhMGVHiw8//NDmsWTJEm08TGjYeauPhg0bZqxLslPC2rVr1ciRI1W7du1UzZo1XQv6zoCC9TxZ0GLRokWh+9ekSRO7PWnf7zh37pyaP3++6tevn2rWrJkrlGD1yfvoDFpIf53vy04pVTnChCjClHH2oVu3bnYf5bYg3iDNgAED7PdbtmzpPDXvnocJWpQdP6qKfvX/XGGL471ft8dK0MJGwRMI5ISA7rkh7bOwggM4gAM4gAM4gAM4YLoDOZmYV6ERghYELaqgD6dCAAIQgAAEIAABCIQloPvCJWw/o1hux44ddrBAbvWg6zAlaCG3lrCCJ6tWrdKFw4h2GzdubC+0t23bNiN9Wrp0qfJ+1s5AgvX8xRdftNuW15IFLWQ3jLCHhAasdurXr+86TcIGo0aNUrVq1bLLWGWTPTqDFrLrhbP84cOHXe2k+k2YEEWYMs52ZTcbZx9Xr/77rTJk5486derY78+YMcN5at49DxO0kEGdeX+8K2ix62d3qkvbN8fGS9Ai7z52OpznBHTPDWmfhRUcwAEcwAEcwAEcwAHTHTB9yk/QgqCF6Y7SPwhAAAIQgAAEIBAJArovXCIBMc1BfPzxx3awYPz48WnWUvXTvIvv/fv3r3qladQwZ84cm8fWrVvTqCE6pzgDCbKrQ1UPCVk4F/at57KrhNy6YurUqbGdLo4cOaK8oYFkQYvFixeH7p7TtdatW9vnyS1M3nrrrbg+Suiia9eusR045s6dq8SLs2fPKtnxxBqDPDqDFpMnT3a9t2/fPruddJ54eUg/vEeYMs5zZGeRRo0a2f3s2bOn/bYzhPHss8+qM2fO2O/l45OwQYvKykp1sMGfXWGL/c88rirLriiCFvn4ydPnfCage25I+yys4AAO4AAO4AAO4AAOmO6A6fN9ghYELUx3lP5BAAIQgAAEIACBSBDQfeESCYhpDuL8+fN2sEBuFaDrcC5+y6K1rqCFhE2sHS0khFLIR48ePexF+Bo1aihZhE52lJWVqaNHj9pfFy5ciJ0iwYTq1avb9clnLLcOkdf9Dm9oIFnQQoINYQ4JUzj74QwXSFjDGZyQ22ksX75cye4OfkeioMWKFStcdcmtUsIcxcXFNruTJ0/ap3h5ZCJoIZVPnDjR7qdwKSkpibXZp08f+3UnI7tDKTyRQIfsFJKJrxSadRUNG7SQk0o/PqB2P3SPK2xRPLQ3QQsXUb6BQPYJ6J4b0j4LKziAAziAAziAAziAA6Y7kP1ZedVaIGhB0KJqBnE2BCAAAQhAAAIQgEAoArovXEJ1MsKF+vXrZ4cLZEFXx2FK0ELCJlbQwlp01sHDhDbHjBljL7ZLAGH37t1Ju+XcCUHOkcCBHHJrD2eIQW7Pkeg4duyYq3yyoIXsihHm2LRpk6ve0aNH26fJrhrOPsptdRIdcjsNZ3nnjhZ79+51vSehkmSHBBIk3GHV6Qw4ZCtoceLECVWtWjW7zQULFqjLly+7bp0in2lVjmnTptn1W2NL51H6KcGwdI5UghZS/6lxQ11Bi10P/Iva/+fHXK9d3r09na5wDgQgEJKA7rkh7bOwggM4gAM4gAM4gAM4YLoDIafW2ooRtCBooU0+GoYABCAAAQhAAAKFRED3hUshsfYbq3MXhz179vgVyfprJgQtZAcBK2QxcODArI/Z9AYWLlzoWiDv3bt30i4PGzbMPkcWxq2wyqRJk+zXZZF927ZtCeuaP3++q3yyoEWYOqVBCS84F/llVwrrkNuIWO/Vq1cv6Q4eXbp0scvLec6ghezkYdUljxKgSBZiEibOcyT0YB3ZClpI/W+88Ybd7ssvv6xWrVplf9+wYUMlAZCqHJkKWngZp9KnVIMWlRUV6sBzv3cFK3bd/8+u7wlapPIJUBYCqRPQPTekfRZWcAAHcAAHcAAHcAAHTHcg9Vl2bs8gaEHQIrfG0RoEIAABCEAAAhAoUAK6L1wKFLs97GXLltkBA+fCs10gB09MCFps3rzZ5jB9+vQcjNrsJmT3gOeff95edH/22WeV7AgRdMguDs7bcnTs2NEuKmEeZ4hAWAcdx48fV3Xq1HGVnz17tqu4d8cLqbtNmzausIPrBKViAQLn7g2NGzeO3c7CKte8eXO7TQlGyG1Ggo4PPvjALmuNS2774Tz69u3rKjNkyJDAOuX2JG3btnWVd9aXTtBi5syZzu4EPpfbmlhjkEdnP8aOHRt4Xtg35JYsEmLJxNe5c+fCNusql2rQQk6+vGeXkp0svAEL63uCFi7EfAOBjBPQPTekfRZWcAAHcAAHcAAHcAAHTHcg45PwDFdI0IKgRYaVojoIQAACEIAABCAAAT8Cui9c/PpUSK/t27fPDhjI7SJ0HCYELWbNmmVzkFtdcCglAQfnIryELSRkIMEA5yGL9RJccJaVBXbrcO6SIGVatWqlZAcR5yHBBtnFQXaTcNYjzydMmOAsqvyCFlKuSZMmaufOna5Ag9wKQ3bIcIYspKxzxwipXHbscLYru3N4xykL/fK6ty45T4ImzkMCIzVq1HDVKW14wwJHjhxRr7/+uqtc165dnVXFdsNw9m3u3Lmu9+Ub4Sefj1Wuc+fO6ujRo7FzhUFlZWXcOfKC7FghO1dY5zkfDx065HtOvr2YTtBCxlg8tDdBi3z7sOlvZAjonhvSPgsrOIADOIADOIADOIADpjtg+uSfoAVBC9MdpX8QgAAEIAABCEAgEgR0X7hEAmIVBlFaWhpbZLZum3HmzJkq1JbeqbqDFmVlZapfv3520OLEiRPpDSRiZwkX504P1iK8BAg6deqkJBDg/eykTK9evVwkhKczBCBl5PvXXnstxlx2UahVq5bvYr+UlZ0yJDhQVFQUqzcoaGH177nnnouVb9euXVy7UkZ2V5CxOQ8JL1jnW48S+ujRo4fq3r27atasmW/AwirboEED1a1bN1egYdy4cXF1SvkWLVrE6pVxO3cBkffq168ftzNHmB0tZCx+n4XVP2EWdLz77rtx/ZTPNypHukGLyrIrav8zj/uGLdjRIip2MA5TCeieG9I+Cys4gAM4gAM4gAM4gAOmO2DqXN7qF0ELghaWCzxCAAIQgAAEIAABCGSRgO4LlywOLW+qnjZtmh0yWL16dc77LTscWAvC8ii3WcjlIbsgWEGTkSNH5rJp49s6e/ZsLBTg/HwSPe/QoYO6cOFC3LjmzJnj+owT1TFo0KBYkMNbxnLTG7QYMWKEqlmzZqj6JQQiwQXvITs7dOnSJVQdEo6QHTG8/ZPvnbcckV0kZsyYERem8DtPXpNbtWzdutXbtVA7WshJcquPoLoTBS1k9w3veYsWLYrrR76+kG7QQsZ7aftmtetnd8aFLQha5KsN9DtfCOieG9I+Cys4gAM4gAM4gAM4gAOmO2D63J6gBUEL0x2lfxCAAAQgAAEIQCASBHRfuEQCYhUHsWvXLjtoIIvWQbcZqGIzgadLe7JAbX0FFszSG1OnTrXHv2bNmiy1kt/VSrAg0Y4JcvuJJUuWJHRn4cKF6sUXX4xb1JdFftnhQnagWL9+fQyU3G7Eu9tDUNBi5cqVSm7B8eabbwbuOiE7c8jtYRId58+fV6NGjQrcXaN27doxT6QtOfr37x83FmfQwmpr//79qmPHjnHjscINMnb5d1dSUmKd4nr07mght2/xO+QWIaNHj/a9/Yr3Vi3e819++WV7LLK7iF8YxXtOvny//+lH7KDE3t8/lHK3j/d+3T5/1/3/HHt+5Ug0bquSMgxOgECOCOieG9I+Cys4gAM4gAM4gAM4gAOmO5CjqXnaMcmfkwAAIABJREFUzRC0IGiRtjycCAEIQAACEIAABCAQnoDuC5fwPY1uSe+tM/bu3RvdwXpGJgvQ1m4W8qjj1imeLhn9rexWITuAzJ8/X8ntNjZu3KiOHj2qZEeIMIcEEXbv3q0kHCG7PSxevFjt27dPXblyJe50CT7I+xIsOHDggL1bhHdHC6nLOuQcCWtI32bPnq3k/xe/HTas8n6PUofsLCFtSx/Xrl0bG6NfAOnQoUOxAIcEdIqLi/2qs1+Tf2cHDx5Uy5cvj9UrYRIJYUhAItEh7UoIw/oKw1rqlPLnzp0LDHBYbUp9jRo1soMWAwcOtN6KxGPFhfOq/PTJ2FfFBf8wS6KBVpaX2+fH6jl7OlFx3oMABDJAQPfckPZZWMEBHMABHMABHMABHDDdgQxMu7NaBUELghZZFYzKIQABCEAAAhCAAAT+RkD3hQufw98ILFu2zA4cvPvuuwWDZd68efa45RYqHOYTSBS0ML/35vVQgiTW7hryKEEaDghAAAI6CeieG9I+Cys4gAM4gAM4gAM4gAOmO6Bzvh6mbYIWBC3CeEIZCEAAAhCAAAQgAIEqEtB94VLF7kfmdPkr/t69e9uhA/nL+6gfsnuFc8zWLSGiPu58Hx9Bi8x+gl26dLGDFi1btsxs5Zpqk50nLm7ZkPWvKx9/pGmENAuBaBPQPTekfRZWcAAHcAAHcAAHcAAHTHfA9CsCghYELUx3lP5BAAIQgAAEIACBSBDQfeESCYgZGsSCBQvsoMXo0aPtWzVkqHrjqpEdLKzbhkycONG4/tEhfwIELfy5hH3VeQsU+Tfv3M1CbtMShePsjMlq1/3/nPWvo51bRQEXY4CAcQR0zw1pn4UVHMABHMABHMABHMAB0x0wbhLv6RBBC4IWHiX4FgIQgAAEIAABCEAgGwR0X7hkY0z5WmdJSYnq16+fHT7YsGFDvg4lab/37dtnj1PCFuxmkRSZMQUIWqT/UZw8eVLVrVtX9ezZU/3lL39xhSwaNmyorly5kn7lBp156a+b1LEeHbP+dXbO+waNmq5AIDoEdM8NaZ+FFRzAARzAARzAARzAAdMdMH32T9CCoIXpjtI/CEAAAhCAAAQgEAkCui9cIgExg4NYt26dHUCQ0IXcXiNqx+XLl9U777xjj3P+/PlRG2Kkx0PQIv2PV4IWzh0snM+jHKxKnxhnQgACOgjonhvSPgsrOIADOIADOIADOIADpjugY56eSpsELQhapOILZSEAAQhAAAIQgAAE0iSg+8IlzW5H9rTy8nI1cuRIO4Qwbtw4Ja9F6ZgxY4Y9vgEDBqiLFy9GaXiRHwtBi/Q/4uLi4rigRa1atdS8efPSr5QzIQABCGSYgO65Ie2zsIIDOIADOIADOIADOGC6Axmegme8OoIWBC0yLhUVQgACEIAABCAAAQjEE9B94RLfI16RhezevXvbYYTFixdHBsqmTZvsccktQ3bv3h2ZsRXKQMrKytTBgwftrwsXLhTK0Ks8TmG3YsUKNWXKFDVp0iS1dOlSJbtccEAAAhAwiYDuuSHts7CCAziAAziAAziAAzhgugMmzd/9+kLQgqCFnxe8BoG8IHD69Gl1/vz5vOgrnYQABCAAAQjovnCJ2icgt/6YOXNmlYe1ceNGVyBBAgr5fuzbt0/16tXLHteiRYvyfUj0HwIQgAAEIBA5ArrnhrTPwgoO4AAO4AAO4AAO4IDpDph+EUDQgqCF6Y7SPwjECCxfvlw1a9ZM/e53v1Pf+9731M0336yuuuqq2Nc//uM/qvvuu0/9+c9/Vh06dFALFiwwmtrKlSvVnDlzXF8LFy40us+57JzcP97LR76Xv0zUfezYscO3b+fOndPdNdqHAATygIDuC5c8QBSqixKweOyxx2JzgPbt24c6J1kh5y02ZPeHnTt3JjvF2PcPHz6s+vbta4csxo4dG7lbohgLn45BAAIQgAAEUiCge25I+yys4AAO4AAO4AAO4AAOmO5ACtNrLUUJWhC00CIejUIgDIGKiorYdr8SorBCFWEf77//fjV37twwzeS0zKFDh3zH8vnPfz6n/TC5sRtvvNGXkexgovu48847ffu2YcMG3V2jfQhAIA8I6L5wyQNECbvoDFhY84FMBS2uXLmiJkyYYIcT5HYi+XirDQlZDBgwwB7HO++8w+5fCa3iTQhAAAIQgIA+ArrnhrTPwgoO4AAO4AAO4AAO4IDpDuibrYdrmaAFQYtwplAKAjkmIP+5f+c73/Fd1LYWV8I8SuBi1apVOe59cHMELYLZWO8QtLBI8AgBCESNgO4Ll3zl6RewsOYAmQpaCJtLly6pUaNG2SEF2dlCbiuSL8fevXtVnz597P4PGjRInTlzJl+6Tz8hAAEIQAACBUdA99yQ9llYwQEcwAEcwAEcwAEcMN0B0y8SCFoQtDDdUfpXgAQ++ugjdfvtt1c5ZGEtwshtRrZv324ESYIWyT8GghbJGVECAhDITwK6L1zyjVqigIX1Mz6TQQvhU1JSokaOHGmHFSRssXTpUiW7bJl8yM5KvXr1svstIYvjx4+b3GX6BgEIQAACECh4ArrnhrTPwgoO4AAO4AAO4AAO4IDpDph+0UDQgqCF6Y7SvwIjcPLkSXX33XdnLGRhLcTccccdSurWfRC0SP4JELRIzogSEIBAfhLQfeGSL9TCBCysn++ZDloII9nZwnkbEQlbjB8/3sjdIS5evKimTZtmByykr8OHDzeyr/niH/2EAAQgAAEI5IqA7rkh7bOwggM4gAM4gAM4gAM4YLoDuZqbp9sOQQuCFum6w3kQyAqBBx54IGHI4vrrr1dPPPGEateunXrrrbdUhw4dVI0aNdS//Mu/JDxPFmQefPBBVVZWlpV+h62UoEVyUgQtkjOiBAQgkJ8EdF+4mE4tlYCFFbTI1uMnPvEJVatWLVeAoV+/fmrLli2qsrLSCJR79uxRQ4YMcfXxxRdfVJ/5zGeSzomyxY16r4L9VTDg3wEO4EBmHDDih22WO6F7bkj7LKzgAA7gAA7gAA7gAA6Y7kCWp+RVrp6gBUGLKktEBRDIFIE1a9Yk/OX0Cy+8oE6fPh3Y3Ny5c9X999+fsI6+ffsGnp+LNwhaJKdM0CI5I0pAAAL5SUD3hYvJ1Pr376+uvvrqhD/DdSxcSUizR48erjDD2LFjlfw813XIDl1Tpkxx9UnCp7/97W/VtddeaxxDHZ8bbWZmkROOcMQBHNDpgK6fs7lsV/fckPZZWMEBHMABHMABHMABHDDdgVzOz9Npi6AFQYt0vOEcCGSFQIMGDQIXBzp16hSqTdlC+4c//GFgPT/5yU9C1ZOtQgQtkpMlaJGcESUgAIH8JKD7wsV0aibtaOFcWLr99ttV27ZtXcEGuUXHe++9pw4ePJgzrMePH1ezZ89WvXr1cvWlc+fOWbntmpMBz1lsxQEcwAEcyLUDOfsBq7Eh3XND2mdhBQdwAAdwAAdwAAdwwHQHNE7XQzVN0IKgRShRKASBXBD45S9/6RuQkO27S0pKQnfhyJEj6nOf+5xvXfLLoRMnToSuK9MFCVokJ0rQIjkjSkAAAvlJQPeFS75QSyVw0b59+5wMS249tnr1aiU7Y0nIwvklO1xs2rRJXbhwIeN9KS0tVdu3b1eTJ092tSntS+Bi0aJF6tKlSxlvlwohAAEIQAACEMg+Ad1zQ9pnYQUHcAAHcAAHcAAHcMB0B7I/K69aCwQtCFpUzSDOhkAGCXznO9/xDUfce++9Kbci22cH/cXN+vXrU6rvypUravny5WrChAmxRY2XX35ZDRw4UM2fP1/t3btXlZeXh64vlaDFjh071KRJk1TPnj3Va6+9psaNG6ek7+fOnQvdXrKCcq952X68T58+SsYlC0hTp05VW7duTXZqSu9LuGXevHmqe/fu6vXXX1fvvPNO7HvZgcR7FErQoqioKMZ6wIAB6pVXXoktoMlCmnzGFRUVXiwZ+V7cWbx4sXrzzTdjbYpb0g8OCEAgNwR0X7jkZpSZayVM4CJXQQtrVPL/qN+uElbwQX6myv/jEvpM5//yyspKVVxcHAtuTJ8+Pfbz2RnqsJ7LbhpSjgMCEIAABCAAgfwloHtuSPssrOAADuAADuAADuAADpjugOmzfYIWBC1Md5T+FRAB2ZrbLxzxjW98I2UKsoDsV5e8Nm3atFD1bdiwQT311FPqlltuCaxL6pMdN/77v/87tiiSrOIwQQsJVPz4xz9O2OZDDz0Uqj2//ki4QRamvv3tbyds484771SvvvqqOnPmjF81SV+TEEqNGjXUrbfeGtiOhCoef/xxtXLlSru+VIIW8jnfc889cV8SXghzbN68Oe5cqe+Pf/yj7+nCxM8rcSXMIaEcCTl8//vf963Hqvu2225TrVu3VuJLmKNNmzZx4/jBD35gnyoLg82bN1ef/OQn49qV0AsHBCCQGwK6L1xyM8rMt5IocJHroIU1OvnZ+MEHHwQGISQQIeFF+ZkuwQz5OSe7Xmzbtk3t3r07FnKTnSrk55DslDF37txYoFN+fllhCu+j7GAhdcktRDggAAEIQAACEMh/ArrnhrTPwgoO4AAO4AAO4AAO4IDpDpg+6ydoQdDCdEfpXwERuP/+++MWga2F51GjRqVEQu6ZLgscfl9h/oK/d+/e6vrrrw/sj9Uv76OEBmSXiKAjUdBCFm1kgd9bZ9D311xzjapdu7aS7czDHrJLxne/+93QbUjbd911l9qzZ0/YJmLlunbtGgugBPXd+/rVV18dC2VICCSVoIWEB7x1yfedOnUK1V9Z+PI7/3vf+57v+VUJWshfNz/44IO+7fn1QV77yle+otasWePbF+eL//Ef/xFX7w033BArIot4Uk9QGwQtnCR5DoHsEtB94ZLd0WW/dr/Aha6ghTVa+bkl/89OnDgxMCDhDUyk+v2YMWOUjD2V26hZ/eMRAhCAAAQgAAFzCeieG9I+Cys4gAM4gAM4gAM4gAOmO2DubP5vPSNoQdDCdEfpXwEReOaZZwIXgz/96U+rDh06ZPS2GX5oT58+rX73u98F9iNosdr5+he/+MXYX6v61R8UtLjpppvUL37xi7TaldtOhDlkoeYzn/lMWm184QtfiN1yIkw7derUSasNYfjEE0/47rog78ln4z3yJWghf/X85S9/OS0uEjyRv4hOdAQFLSRY86UvfSlhuwQtEpHlPQhkloDuC5fMjkZfbc7Ahe6ghZOCBCHk1luyO8WwYcPSDl4MHjxYzZw5U23cuFGdOnXK2QTPIQABCEAAAhCIEAHdc0PaZ2EFB3AAB3AAB3AAB3DAdAdMn/4TtCBoYbqj9K+ACMiihDOw4Pf8H/7hH1T37t2V7FiR6UN2lPinf/qnpH3w65f3tW9961vq2LFjcV0MClp4z0/le7kdRKJdNKQTHTt2rPK4pJ2hQ4fGjcn5gvyVbip9T6VsvgYtRowYoa699toqc5GgUdARFLSQ24ckY0zQIogqr0Mg8wR0X7hkfkR6a5TAhQQSTD0uXLgQuwWUfO6yg5KE7iSEMWPGDDV9+nQ1Z84ctXDhQrV8+fLYz3GZ27BrhamfJv2CAAQgAAEIZJ6A7rkh7bOwggM4gAM4gAM4gAM4YLoDmZ+FZ7ZGghYELTJrFLVBoAoE5BYY3/zmN5MuDFsLx3JLi4YNG6qpU6dmZKeLVq1aJWz77rvvVs8995zq3Lmzatq0qfrZz36WsPxPf/rTOBphgxZf/epX1ZNPPqnatWunmjRpon784x8nbOu3v/1tXFvWC7KrwSc+8YnA84Xjn/70J9W2bdvYrUtuv/32wLLCftGiRVbVrkdpR8IY1ufj9/ipT31K/fu//7tq2bKlql69urrnnntChxDyMWghf4ksu4H4sZDXvvGNb6g//OEPMfayo8u3v/3twLJSfsiQIS7m1jd+QYugNr2vE7SwKPIIgewT0H3hkv0R0gIEIAABCEAAAhCAQFgCuueGtM/CCg7gAA7gAA7gAA7ggOkOhJ1b6ypH0IKghS73aBcCvgTGjh2bcKHZu0hsfX/dddep++67T7300kuxIEBpaalv/UEvfvzxx0pu0WDV53y85ZZbVJ8+fVRFRUXc6YsXL04YDtm3b5/rnDBBi3r16qnLly+7zpNvBg0aFBhKuOOOO+LKWy88+uijvuO6+eabley24D1knJ06dQpsSwInV65c8Z6mqlWr5tuOsJQdHWQrdL/zVqxYoSRY4mTu9zwfgxaNGjXyHZcEUl5//XVfpyRMEeSihDaKi4vj2IcNWvzrv/5rLJw0fPhwNXnyZNWjR4/Y1vRxFfICBCCQFQK6L1yyMigqhQAEIAABCEAAAhBIi4DuuSHts7CCAziAAziAAziAAzhgugNpTbRzeBJBC4IWOdSNpiAQjoAsAktwwm+xPexrn/70p9V//ud/KglChDlq1qzp257sBCE/aBId27ZtUxJa8OubBDScR7KgRZcuXZzF457LLhB+7UiQwS+cMWvWLN/yEh7xhkC8jU2bNs33XGlfbvPiPGRcQbtmSKhg0qRJzuJxz48cOaLuvffewPakzXwLWogXfh7La7KFfKJj48aN6oYbbvDl0aZNm7hTkwUtrrnmmtjtY/zCQnGV8QIEIJA1ArovXLI2MCqGAAQgAAEIQAACEEiZgO65Ie2zsIIDOIADOIADOIADOGC6AylPsnN8AkELghY5Vo7mIBCOgAQEvvzlL/suNPsFDRK99sADD6hly5YFNlxUVBS4e0Pr1q0Dz3O+IYvffn34zW9+4ywWu1e7Xzl57c4771Ry+5REh/zQCzp/y5YtcafK7hN+5YNuQeGt4KmnnvI9/xe/+IWr6NChQ33LSdtvvfWWq2zQN6tXrw6sQ+rJt6CFBH382Id1Sm4b43f+1772NVVZWenCmCxo8f7777vK8w0EIKCHgO4LFz2jplUIQAACEIAABCAAAT8CuueGtM/CCg7gAA7gAA7gAA7ggOkO+M2jTXqNoAVBC5N8pC8QcBGQ20xMmDBByaK+34JzKq/Jbgvvvfeeq37rmzFjxvjW//Wvf11duHDBKpbwce3atb513Hrrra7zEu1o4XcbD9fJSqny8nIlO0T4jX3RokWu4rt27fIt993vftdVLtE3ckuVq6++Oq4eeU3es44//elPcWWkjzfddJM6d+6cVSzp4yOPPOJbj9SVT0GLixcvquuvvz5uLLKTyKVLl5JykAJSh9wqxO+zXrJkiauOREELCXxwQAACZhDQfeFiBgV6AQEIQAACEIAABCAgBHTPDWmfhRUcwAEcwAEcwAEcwAHTHTD9yoGgBUEL0x2lfxCIEdixY4fq1q2b+vWvf60+9alP+S4++y1IO1+TsIXfX/Z36NDBt75mzZqlRF9CGd4v7+08EgUt5AdamOM73/mOb3+9QYv+/fv7lqtXr16YZuwyd911l289U6dOtcsE9al+/fp2mTBP5s+f79tWvgUtgsbxq1/9KgwGu8zjjz/uy6NHjx52GXkSFLSQW8qE9cpVId9AAAJZIaD7wiUrg6JSCEAAAhCAAAQgAIG0COieG9I+Cys4gAM4gAM4gAM4gAOmO5DWRDuHJxG0IGiRQ91oCgKZIVBaWqoWL16sJCDx85//XF133XW+i9HOkIX1/Itf/KI6f/68qyNPP/207/nTpk1zlcvEN0FBCwmByA4eYY4f/ehHvv31Bi0kUGGN2/kot56oU6dO6K8gvl26dLG7+/nPf963LbkFTCrH4cOHfeuR/ufTjhYShHAyt57ffPPNobnLZxTEtVatWi6sQUGLn/zkJ65yfAMBCOgloPvCRe/oaR0CEIAABCAAAQhAwElA99yQ9llYwQEcwAEcwAEcwAEcMN0B5/zZxOcELQhamOglfYJASgRkAX7s2LHqqaeeClyYtha65bFr166u+n/wgx/4LorLD5hMH0FBC1lQD3uEDVr84Q9/8B2Xk0VVnlu7VVRUVKhrrrnGt62tW7eGHVasXGVlpe8tN6Sf+RS0aN26tS+PqvB2nvvwww+7uAYFLapVq+YqxzcQgIBeArovXPSOntYhAAEIQAACEIAABJwEdM8NaZ+FFRzAARzAARzAARzAAdMdcM6fTXxO0IKghYle0icIpE2grKxMyU4L119/feBC9+233+6q/5ZbbvEtK7srZPrIZdDioYce8h2Xc8G+Ks9feOGFGJ4zZ84EtiPvpXp861vf8q0vn4IWtWvX9h1DVXg7z5VbijiPoKDFK6+84izGcwhAQDMB3RcumodP8xCAAAQgAAEIQAACDgK654a0z8IKDuAADuAADuAADuCA6Q44ps9GPiVoQdDCSDHpVGERkHBE79691dtvvx33tWXLlrRgbNy4Ud1www2Bi93OAMCNN97oW+7AgQNptZ3opFwGLR577DHfcTkX7KvyvFWrVrGhlpeXK7n1iV9dJSUliXD4vnfrrbf61pVPQYsmTZr4jsGPUTqv/f73v3exCwpajBs3zlWObyAAAb0EdF+46B09rUMAAhCAAAQgAAEIOAnonhvSPgsrOIADOIADOIADOIADpjvgnD+b+JygBUELE72kTwVGYOfOnYGL0i+++GLaNBo3bhxY7+rVq+1677nnHt9yy5Yts8tk6kkugxay44TfIv7dd9+thE1Vv5wM77jjDt+2Nm/enBK60tLSwNuQZCNosXz5ct9+f+973/Pt95133ulbfsOGDa7yffr08S0nIZKqcpfzZ8yY4WovKGgxdepUVzm+gQAE9BLQfeGid/S0DgEIQAACEIAABCDgJKB7bkj7LKzgAA7gAA7gAA7gAA6Y7oBz/mzic4IWBC1M9JI+FRiB8+fP+y5KS0jgF7/4Rdo0hg8fHlivc6H6j3/8o2+5MWPGhG5bAgJTpkyJ+5KdNZxHLoMW/fv39x1Xx44dnV3KyPOHH37Yt633338/pfp37NjhW4+4kErQ4qWXXgrV7sSJE33bq2rQYv78+b71/vnPfw7Vr1QLEbRIlRjlIaCHgO4LFz2jplUIQAACEIAABCAAAT8CuueGtM/CCg7gAA7gAA7gAA7ggOkO+M2jTXqNoAVBC5N8pC8FTOCWW27xXZj+7Gc/qyorK9MiI7cj8dvRQV5bt26dXacsyvuVe/rpp+0yyZ7MmzfPt46vf/3rrlNzGbRYuHChb5+eeuopV58y8U39+vV926pZs2ZK1Qd9FkFBi7/85S9VardHjx6+51c1aPHRRx/51vvDH/4wJR5hCxO0CEuKchDQS0D3hYve0dM6BCAAAQhAAAIQgICTgO65Ie2zsIIDOIADOIADOIADOGC6A875s4nPCVoQtDDRS/pUgASCFoplgb1Dhw5pEfmf//kf38VuqfPo0aN2naNHj/Yt98lPflIdO3bMLpfoSdOmTX3rqFWrluu0XAYtPv74Y98+fepTn3KN39VBn2/q1q2rfvzjH7u+fvOb3yjZicQ6ggIL119/vTpy5IhVLOHjpUuX1Be/+EXfPgcFLfr16+db/le/+lXCtqw3gxypatBCwkHCWfrt/Lr66qvV+vXrreaTPr7yyisu7vI5yC4vBw8edJ0b9O+HW4e4MPENBLQT0H3hoh0AHYAABCAAAQhAAAIQsAnonhvSPgsrOIADOIADOIADOIADpjtgT54NfULQgqCFoWrSrUIjMGTIENeCtHdxWm7xkMohC8yyqO2sx3r+5S9/2bVLxs6dOwPLyo4JyQ4JEgQFBLy3zshl0EL6fdttt/kyaNiwYbJhxd5fu3at7/nf+MY3VEVFhV2H3CIliPeLL75ol0v0pGvXrr5tWZ+b361DZs2a5XvOF77wBVVSUpKoOVVUVKSuvfZa3/OrGrSQhh944AHfuh955JGE/bLePHz4sLrhhhvi6pAAh5cFQQuLGo8QMJuA7gsXs+nQOwhAAAIQgAAEIFBYBHTPDWmfhRUcwAEcwAEcwAEcwAHTHTD9CoGgBUEL0x2lfwVCQBaOP/3pT8ctKluL7LK4LLeVOHHiREIiZWVlauDAgSroViRSX6tWreLqePbZZ33blvDAm2++GVfeeqG8vFw9/PDDvufeeOON6uLFi1bR2GOugxYjRozw7dsnPvGJGCdX5zzfSIDkzjvv9D2/S5cuntJKPfnkk75lhXmyXUmEcVBQw3LAGy6QDuzYsSOwzc6dO8f10XpBduN49NFHA8/NRNBi+fLlgfW3a9fOFVSx+mU9Sv+CghreXVLkHIIWFjkeIWA2Ad0XLmbToXcQgAAEIAABCECgsAjonhvSPgsrOIADOIADOIADOIADpjtg+hUCQQuCFqY7Sv8KiEDPnj0DF6atxXYJXDz//PNq8ODBat68eUp+CKxcuVLJ7T86duyo7rjjjoR1fOYzn1F79+6Noyq7B8h7Vjvex+bNm6utW7e6dsKQW0Dce++9gec89dRTce3kOmght7D4wQ9+ENjHGjVqqN27d7vGJeGR8ePHq29/+9u+58ntQPwCL/JZXHPNNb7nCE9pS5hJ/XLIjhjy/QsvvBB4jvNz8AtayO1GrrvuOt/z5dYvcusNCd9Yh7Qtvtx1112+51jtZSJoIW0G3ZpE2vn1r3+ttmzZYvOw+jhnzpyEn9mHH35oFbUfCVrYKHgCAaMJ6L5wMRoOnYMABCAAAQhAAAIFRkD33JD2WVjBARzAARzAARzAARww3QHTLxEIWhC0MN1R+ldABGQR/Ec/+lHCBXBrITydRwkILFiwIJDoq6++mrRtuUXIfffdp7761a8mLPu1r31NnTx5Mq6tXActpAOJdlawOMoOID/96U9j/INug2KVbdGiRdy4rBeefvrphFykjptuukn927/9m7r55puTlrXalEe/oIW0W6dOnYT1SDvi1fe//33fW3E427CeZypoceDAgaRtSnhI+nf//fcn9ep3v/udhdr1SNDChYNvIGAsAd0XLsaCoWMQgAAEIAABCECgAAnonhvSPgsrOIADOIADOIADOIADpjtlP+HyAAAgAElEQVRg+mUCQQuCFqY7Sv8KjEBxcXFsQdxa8M7U47XXXqumTJmSkObly5fVD3/4w4SL9mH6I7flWLVqlW9bOoIW0pH69etXeVwydtmVQnbJCDr279+fdFeRMAz9ygQFLWQ3Egkr+J2T7muZCloIp+7duye9LUqYfv7yl79U4qjfQdDCjwqvQcA8ArovXMwjQo8gAAEIQAACEIBA4RLQPTekfRZWcAAHcAAHcAAHcAAHTHfA9KsFghYELUx3lP4VIIFTp04pue1GottQhFmYtspIyGLYsGGhSF65ckW1bNky7bYlZNG/f//AtnQFLaRDI0eOVJ/97GfTDiTIbTDkdh/JjjNnzqj/+q//SqsduRXLo48+6ntuUNBC+tO+fXvfcywH/B7Fi969e/uel8mghfRPbnNz6623+rbl1zfva7LbyIULFwLRE7QIRMMbEDCKgO4LF6Ng0BkIQAACEIAABCBQ4AR0zw1pn4UVHMABHMABHMABHMAB0x0w/ZKBoAVBC9MdpX8FTGDnzp2qWrVq6rrrrktrgfpzn/uckttcyO0bUj0WLlyobrvttpTaffzxx5X0OdGhM2gh/ZIdJ372s5+lNK677rpLjRo1SsmtXcIesuvFa6+9piTM4A0NBH3/xBNPqKNHj6onn3zS95xEQQvp19ChQ0PfjkRCD0uWLInx8OtPpoMW0j+5lczvf/9737H59UFeEwfffvttdenSpYToCVokxMOb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sWXLlqr5JmW0UL203Modd9zhK79bF/texotJkyaZvr6+quWrxqvW43kzJuStPrW2J+en0yfCFa550UDWH0woHwQgAAEIQAACECgSgbyMMakHz0toAA2gATSABtAAGkADaWkg688HGC0wWjR9Yjetm410k+vIg0aLDRs2xNbJ8OHDPWPBjTfe6F3nfn/rrbd631drt507d3rpyZgwYcIE79pajRZbt271ro3KN0mjhfIYGBgw06dPj2W4uOqqq8yiRYuqljGq7PV8nzdjQt7qU0+bck1yfSEsYZk3DWT9wYTyQQACEIAABCAAgSIRyNtYk/rw/IQG0AAaQANoAA2gATSQtAay/nyA0QKjRVMndZO+wUgvnU47aLTQEhdxWbtGhZEjR3rX3XXXXZ5hYtiwYd731dJdu3atd52MFvPnz/eubQejhVu/np4es3DhQvPkk08a13hiI1tor6VXVq9e7dXRvT6N93kzJuStPmm0OWmm02/CFa7toIGsP5hQPghAAAIQgAAEIFAkAu0wfqSMPOegATSABtAAGkADaAANtFIDWX8+wGiB0aJpE7qtvBHJu7Y/BEGjxZQpU2LppL+/32eKeOKJJ7zr9N41FMgkEadd5s6d67vOja7RbkaLYH337Nljxo0bZxTJwmVzzz33xGITTK+ez3kzJuStPvW0KdfU1t/BC15F0kDWH0woHwQgAAEIQAACECgSgSKNQ6krz11oAA2gATSABtAAGkAD9Wgg688HGC0wWjRtQreeG4hrWtPxBo0WWupjaGioqlYWL17sMwxMmzbNu2bGjBm+Y0uXLvWOVWrnMWPG+K7bv3+/d11WjRYynGgJEPvat2+fV+awuuq4GwnkyiuvLC05EnZu0t/lzZiQt/ok3d6k15o+Fe5wz4oGsv5gQvkgAAEIQAACEIBAkQhkZYxIOXheQQNoAA2gATSABtAAGsiqBrL+fIDRAqNFxQngrN5YlCvdTj9otFC0hTjLWdx9990+U8S6des8fSkShRu14aabbjIyJFRqS13vXnPjjTeaY8eOeddk1WgxODjoi1IxduxYr8xR9X388cd9de3r66t6TVRatXyfN2NC3upTS1tybrr9InzhmwcNZP3BhPJBAAIQgAAEIACBIhHIw/iSOvCchAbQABpAA2gADaABNJCmBrL+fIDRAqNFUyZz07zJSDv5TjzMaCGT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xh0KF2owuIH48Jt2KR5c8D9FLmixdPmSBtyw7x+3aEISbnm2/cs/bl5c8/D/a+nNvMVPJfNYXuKJj/xHS16+PPvy08WYWacWO1zx5Wg5W43bsPjtzXs0+tRWQMYODPkYJw855JDiwAMPbBqDMQz/8pe/bOzn2JFHHhksDeMnhuvf//73xV577dWSf8899yxOOumkgslPjPyxgCGaOuwzf/6fgBiMtaeddlqxww47NMvFMFol+KDFwmtOawEmFk44Kau4hdf+W2s+r5xegRYvv/xycfnllxcjRowodt9992a/OR877rhjQ6Obbropy+hMx+66665i1KhRxW9+85sWHXfeeefGOb3wwgsbEEtKBFzm2rnBbS4BYOPcc88t9t9//5Y2HnTQQcUFF1xQvPDC6wAQBmzO40477dSSlj4dddRRjTbG6j/11FObdTOOCNdff31xwgknFL/4xS9ayqMt9BU3vqlQBbQAaJg4cWKwPsblKaec0gCA/PpYLsM0O+CAA1ra6V5XpIldG2g4ZsyYxnn66U9/2lIGY+OSSy4p7Frx68/5/oc//KHZRv/aPfjgg5vHOJ8WgESsX5wDC7fddlujnQaUHH744Y1DgAuWnviee+6xLG0xMBXj0R/3Vuauu+5anHXWWQ3QpS3zn3fkgBbAIFdffXXb2LV6qP+iiy5qACOxerR/8CiQem7r5TGBFgItBFpUu+5dI7hAi3LtQsY2gRZp3dwxJtAirRVHbYwJtCjXylIItDAl8mOBFvlakdKuS4EWAi2qjRyllgJSQApIASkgBaSAFJACNSnQywn1UFk1NVvF9kiB5SuXF2NmnRYFElyoge1Tbz24JW0IdACyOPjGHVvS+eX43//9f0c2e1QFtMDrhhvwxvHj/944u27S3vtc2sDslm/bGITNwJiKf/azn1mWZoxXgsMOOywrP4ZbDKmhwBvlbt14DcBw6xuXSdMtaLFk9rRizohvNaGJp373lWLl8vSb8itXrCjmHLdJS56lj85sfn/ioPWKXoAWeALYb7/9WrRwdXG3991336ieaIy3CIz0bp7YNueWtYZjAYjG8mJ0x1hOHtsXioEJAAWAZX7+858n05IfI0wo7LPPPs28gB1nn31283uoXtvHpFXM60MuaLFgwYLiuOOOK60P4OLmm29uaT6wh7WlLF6yZElLXr5g1PXhh1A56AOo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" + "cells": [ + { + "cell_type": "markdown", + "metadata": { + "originalKey": "977ca50b-324e-4994-97cd-c6c17e723435" + }, + "source": [ + "# Configurable closed-loop optimization with Ax `Scheduler`\n", + "\n", + "*We recommend reading through the [\"Developer API\" tutorial](https://ax.dev/tutorials/gpei_hartmann_developer.html) before getting started with the `Scheduler`, as using it in this tutorial will require an Ax `Experiment` and an understanding of the experiment's subcomponents like the search space and the runner.*\n", + "\n", + "### Contents:\n", + "1. **Scheduler and external systems for trial evalution** –– overview of how scheduler works with an external system to run a closed-loop optimization.\n", + "2. **Set up a mock external system** –– creating a dummy external system client, which will be used to illustrate a scheduler setup in this tutorial.\n", + "3. **Set up an experiment according to the mock external system** –– set up a runner that deploys trials to the dummy external system from part 2 and a metric that fetches trial results from that system, then leverage those runner and metric and set up an experiment.\n", + "4. **Set up a scheduler**, given an experiment.\n", + " 1. Create a scheduler subclass to poll trial status.\n", + " 2. Set up a generation strategy using an auto-selection utility.\n", + "5. **Running the optimization** via `Scheduler.run_n_trials`.\n", + "6. **Leveraging SQL storage and experiment resumption** –– resuming an experiment in one line of code.\n", + "7. **Configuring the scheduler** –– overview of the many options scheduler provides to configure the closed-loop down to granular detail.\n", + "8. **Advanced functionality**:\n", + " 1. Reporting results to an external system during the optimization.\n", + " 2. Using `Scheduler.run_trials_and_yield_results` to run the optimization via a generator method." + ] + }, + { + "cell_type": "markdown", + "metadata": { + "originalKey": "99721805-f4f5-48e4-940c-bc2d0c73c61a" + }, + "source": [ + "## 1. `Scheduler` and external systems for trial evaluation\n", + "\n", + "`Scheduler` is a closed-loop manager class in Ax that continuously deploys trial runs to an arbitrary external system in an asynchronous fashion, polls their status from that system, and leverages known trial results to generate more trials.\n", + "\n", + "Key features of the `Scheduler`:\n", + "- Maintains user-set concurrency limits for trials run in parallel, keep track of tolerated level of failed trial runs, and 'oversee' the optimization in other ways,\n", + "- Leverages an Ax `Experiment` for optimization setup (an optimization config with metrics, a search space, a runner for trial evaluations),\n", + "- Uses an Ax `GenerationStrategy` for flexible specification of an optimization algorithm used to generate new trials to run,\n", + "- Supports SQL storage and allows for easy resumption of stored experiments." + ] + }, + { + "attachments": { + "image-2.png": { + "image/png": "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rrvuOt/z5dYvcusNCd9Yh7Qtvtx1112+51jtZSJoIW0G3ZpE2vn1r3+ttmzZYvOw+jhnzpyEn9mHH35oFbUfCVrYKHgCAaMJ6L5wMRoOnYMABCAAAQhAAAIFRkD33JD2WVjBARzAARzAARzAARww3QHTLxEIWhC0MN1R+ldABGQR/Ec/+lHCBXBrITydRwkILFiwIJDoq6++mrRtuUXIfffdp7761a8mLPu1r31NnTx5Mq6tXActpAOJdlawOMoOID/96U9j/INug2KVbdGiRdy4rBeefvrphFykjptuukn927/9m7r55puTlrXalEe/oIW0W6dOnYT1SDvi1fe//33fW3E427CeZypoceDAgaRtSnhI+nf//fcn9ep3v/udhdr1SNDChYNvIGAsAd0XLsaCoWMQgAAEIAABCECgAAnonhvSPgsrOIADOIADOIADOIADpjtlP+HyAAAgAElEQVRg+mUCQQuCFqY7Sv8KjEBxcXFsQdxa8M7U47XXXqumTJmSkObly5fVD3/4w4SL9mH6I7flWLVqlW9bOoIW0pH69etXeVwydtmVQnbJCDr279+fdFeRMAz9ygQFLWQ3Egkr+J2T7muZCloIp+7duye9LUqYfv7yl79U4qjfQdDCjwqvQcA8ArovXMwjQo8gAAEIQAACEIBA4RLQPTekfRZWcAAHcAAHcAAHcAAHTHfA9KsFghYELUx3lP4VIIFTp04pue1GottQhFmYtspIyGLYsGGhSF65ckW1bNky7bYlZNG/f//AtnQFLaRDI0eOVJ/97GfTDiTIbTDkdh/JjjNnzqj/+q//SqsduRXLo48+6ntuUNBC+tO+fXvfcywH/B7Fi969e/uel8mghfRPbnNz6623+rbl1zfva7LbyIULFwLRE7QIRMMbEDCKgO4LF6Ng0BkIQAACEIAABCBQ4AR0zw1pn4UVHMABHMABHMABHMAB0x0w/ZKBoAVBC9MdpX8FTGDnzp2qWrVq6rrrrktrgfpzn/uckttcyO0bUj0WLlyobrvttpTaffzxx5X0OdGhM2gh/ZIdJ372s5+lNK677rpLjRo1SsmtXcIesuvFa6+9piTM4A0NBH3/xBNPqKNHj6onn3zS95xEQQvp19ChQ0PfjkRCD0uWLInx8OtPpoMW0j+5lczvf/9737H59UFeEwfffvttdenSpYToCVokxMOb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sWXLlqr5JmW0UL203Modd9zhK79bF/texotJkyaZvr6+quWrxqvW43kzJuStPrW2J+en0yfCFa550UDWH0woHwQgAAEIQAACECgSgbyMMakHz0toAA2gATSABtAAGkADaWkg688HGC0wWjR9Yjetm410k+vIg0aLDRs2xNbJ8OHDPWPBjTfe6F3nfn/rrbd631drt507d3rpyZgwYcIE79pajRZbt271ro3KN0mjhfIYGBgw06dPj2W4uOqqq8yiRYuqljGq7PV8nzdjQt7qU0+bck1yfSEsYZk3DWT9wYTyQQACEIAABCAAgSIRyNtYk/rw/IQG0AAaQANoAA2gATSQtAay/nyA0QKjRVMndZO+wUgvnU47aLTQEhdxWbtGhZEjR3rX3XXXXZ5hYtiwYd731dJdu3atd52MFvPnz/eubQejhVu/np4es3DhQvPkk08a13hiI1tor6VXVq9e7dXRvT6N93kzJuStPmm0OWmm02/CFa7toIGsP5hQPghAAAIQgAAEIFAkAu0wfqSMPOegATSABtAAGkADaAANtFIDWX8+wGiB0aJpE7qtvBHJu7Y/BEGjxZQpU2LppL+/32eKeOKJJ7zr9N41FMgkEadd5s6d67vOja7RbkaLYH337Nljxo0bZxTJwmVzzz33xGITTK+ez3kzJuStPvW0KdfU1t/BC15F0kDWH0woHwQgAAEIQAACECgSgSKNQ6krz11oAA2gATSABtAAGkAD9Wgg688HGC0wWjRtQreeG4hrWtPxBo0WWupjaGioqlYWL17sMwxMmzbNu2bGjBm+Y0uXLvWOVWrnMWPG+K7bv3+/d11WjRYynGgJEPvat2+fV+awuuq4GwnkyiuvLC05EnZu0t/lzZiQt/ok3d6k15o+Fe5wz4oGsv5gQvkgAAEIQAACEIBAkQhkZYxIOXheQQNoAA2gATSABtAAGsiqBrL+fIDRAqNFxQngrN5YlCvdTj9otFC0hTjLWdx9990+U8S6des8fSkShRu14aabbjIyJFRqS13vXnPjjTeaY8eOeddk1WgxODjoi1IxduxYr8xR9X388cd9de3r66t6TVRatXyfN2NC3upTS1tybrr9InzhmwcNZP3BhPJBAAIQgAAEIACBIhHIw/iSOvCchAbQABpAA2gADaABNJCmBrL+fIDRAqNFUyZz07zJSDv5TjzMaCGT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xh0KF2owuIH48Jt2KR5c8D9FLmixdPmSBtyw7x+3aEISbnm2/cs/bl5c8/D/a+nNvMVPJfNYXuKJj/xHS16+PPvy08WYWacWO1zx5Wg5W43bsPjtzXs0+tRWQMYODPkYJw855JDiwAMPbBqDMQz/8pe/bOzn2JFHHhksDeMnhuvf//73xV577dWSf8899yxOOumkgslPjPyxgCGaOuwzf/6fgBiMtaeddlqxww47NMvFMFol+KDFwmtOawEmFk44Kau4hdf+W2s+r5xegRYvv/xycfnllxcjRowodt9992a/OR877rhjQ6Obbropy+hMx+66665i1KhRxW9+85sWHXfeeefGOb3wwgsbEEtKBFzm2rnBbS4BYOPcc88t9t9//5Y2HnTQQcUFF1xQvPDC6wAQBmzO40477dSSlj4dddRRjTbG6j/11FObdTOOCNdff31xwgknFL/4xS9ayqMt9BU3vqlQBbQAaJg4cWKwPsblKaec0gCA/PpYLsM0O+CAA1ra6V5XpIldG2g4ZsyYxnn66U9/2lIGY+OSSy4p7Frx68/5/oc//KHZRv/aPfjgg5vHOJ8WgESsX5wDC7fddlujnQaUHH744Y1DgAuWnviee+6xLG0xMBXj0R/3Vuauu+5anHXWWQ3QpS3zn3fkgBbAIFdffXXb2LV6qP+iiy5qACOxerR/8CiQem7r5TGBFgItBFpUu+5dI7hAi3LtQsY2gRZp3dwxJtAirRVHbYwJtCjXylIItDAl8mOBFvlakdKuS4EWAi2qjRyllgJSQApIASkgBaSAFJACNSnQywn1UFk1NVvF9kiB5SuXF2NmnRYFElyoge1Tbz24JW0IdACyOPjGHVvS+eX43//9f0c2e1QFtMDrhhvwxvHj/944u27S3vtc2sDslm/bGITNwJiKf/azn1mWZoxXgsMOOywrP4ZbDKmhwBvlbt14DcBw6xuXSdMtaLFk9rRizohvNaGJp373lWLl8vSb8itXrCjmHLdJS56lj85sfn/ioPWKXoAWeALYb7/9WrRwdXG3991336ieaIy3CIz0bp7YNueWtYZjAYjG8mJ0x1hOHtsXioEJAAWAZX7+858n05IfI0wo7LPPPs28gB1nn31283uoXtvHpFXM60MuaLFgwYLiuOOOK60P4OLmm29uaT6wh7WlLF6yZElLXr5g1PXhh1A56AOo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" + } + }, + "cell_type": "markdown", + "metadata": { + "originalKey": "f85ac1dc-8678-4b68-a31b-33623c95fd89" + }, + "source": [ + "This scheme summarizes how the scheduler interacts with any external system used to run trial evaluations:\n", + "\n", + "![image-2.png](attachment:image-2.png)" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "originalKey": "72643e42-f7e8-4aec-a371-efa5d1991899" + }, + "source": [ + "## 2. Set up a mock external execution system " + ] + }, + { + "cell_type": "markdown", + "metadata": { + "originalKey": "d8e139e3-c453-43f3-8211-0a85453bab54" + }, + "source": [ + "An example of an 'external system' running trial evaluations could be a remote server executing scheduled jobs, a subprocess conducting ML training runs, an engine running physics simulations, etc. For the sake of example here, let us assume a dummy external system with the following client:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "import sys\n", + "in_colab = 'google.colab' in sys.modules\n", + "if in_colab:\n", + " %pip install ax-platform" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "code_folding": [], + "executionStartTime": 1646325042150, + "executionStopTime": 1646325042183, + "hidden_ranges": [], + "originalKey": "1dd579d5-2afa-4cad-b6c0-a54343863579", + "requestMsgId": "1dd579d5-2afa-4cad-b6c0-a54343863579" + }, + "outputs": [], + "source": [ + "from random import randint\n", + "from time import time\n", + "from typing import Any, Dict, NamedTuple, Union\n", + "\n", + "from ax.core.base_trial import TrialStatus\n", + "from ax.utils.measurement.synthetic_functions import branin\n", + "\n", + "\n", + "class MockJob(NamedTuple):\n", + " \"\"\"Dummy class to represent a job scheduled on `MockJobQueue`.\"\"\"\n", + "\n", + " id: int\n", + " parameters: Dict[str, Union[str, float, int, bool]]\n", + "\n", + "\n", + "class MockJobQueueClient:\n", + " \"\"\"Dummy class to represent a job queue where the Ax `Scheduler` will\n", + " deploy trial evaluation runs during optimization.\n", + " \"\"\"\n", + "\n", + " jobs: Dict[str, MockJob] = {}\n", + "\n", + " def schedule_job_with_parameters(\n", + " self, parameters: Dict[str, Union[str, float, int, bool]]\n", + " ) -> int:\n", + " \"\"\"Schedules an evaluation job with given parameters and returns job ID.\"\"\"\n", + " # Code to actually schedule the job and produce an ID would go here;\n", + " # using timestamp in microseconds as dummy ID for this example.\n", + " job_id = int(time() * 1e6)\n", + " self.jobs[job_id] = MockJob(job_id, parameters)\n", + " return job_id\n", + "\n", + " def get_job_status(self, job_id: int) -> TrialStatus:\n", + " \"\"\" \"Get status of the job by a given ID. For simplicity of the example,\n", + " return an Ax `TrialStatus`.\n", + " \"\"\"\n", + " job = self.jobs[job_id]\n", + " # Instead of randomizing trial status, code to check actual job status\n", + " # would go here.\n", + " if randint(0, 3) > 0:\n", + " return TrialStatus.COMPLETED\n", + " return TrialStatus.RUNNING\n", + "\n", + " def get_outcome_value_for_completed_job(self, job_id: int) -> Dict[str, float]:\n", + " \"\"\"Get evaluation results for a given completed job.\"\"\"\n", + " job = self.jobs[job_id]\n", + " # In a real external system, this would retrieve real relevant outcomes and\n", + " # not a synthetic function value.\n", + " return {\"branin\": branin(job.parameters.get(\"x1\"), job.parameters.get(\"x2\"))}\n", + "\n", + "\n", + "MOCK_JOB_QUEUE_CLIENT = MockJobQueueClient()\n", + "\n", + "\n", + "def get_mock_job_queue_client() -> MockJobQueueClient:\n", + " \"\"\"Obtain the singleton job queue instance.\"\"\"\n", + " return MOCK_JOB_QUEUE_CLIENT" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "originalKey": "d3127829-507d-46ff-bd4f-81ea1bd21066", + "showInput": false + }, + "source": [ + "## 3. Set up an experiment according to the mock external system\n", + "\n", + "As mentioned above, using a `Scheduler` requires a fully set up experiment with metrics and a runner. Refer to the \"Building Blocks of Ax\" tutorial to learn more about those components, as here we assume familiarity with them. \n", + "\n", + "The following runner and metric set up intractions between the `Scheduler` and the mock external system we assume:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "code_folding": [], + "executionStartTime": 1646325042214, + "executionStopTime": 1646325042307, + "hidden_ranges": [], + "originalKey": "62b96030-89c2-45a6-9250-0f1b529bbd38", + "requestMsgId": "62b96030-89c2-45a6-9250-0f1b529bbd38" + }, + "outputs": [], + "source": [ + "from collections import defaultdict\n", + "from typing import Iterable, Set\n", + "\n", + "from ax.core.base_trial import BaseTrial\n", + "from ax.core.runner import Runner\n", + "from ax.core.trial import Trial\n", + "\n", + "\n", + "class MockJobRunner(Runner): # Deploys trials to external system.\n", + " def run(self, trial: BaseTrial) -> Dict[str, Any]:\n", + " \"\"\"Deploys a trial based on custom runner subclass implementation.\n", + "\n", + " Args:\n", + " trial: The trial to deploy.\n", + "\n", + " Returns:\n", + " Dict of run metadata from the deployment process.\n", + " \"\"\"\n", + " if not isinstance(trial, Trial):\n", + " raise ValueError(\"This runner only handles `Trial`.\")\n", + "\n", + " mock_job_queue = get_mock_job_queue_client()\n", + " job_id = mock_job_queue.schedule_job_with_parameters(\n", + " parameters=trial.arm.parameters\n", + " )\n", + " # This run metadata will be attached to trial as `trial.run_metadata`\n", + " # by the base `Scheduler`.\n", + " return {\"job_id\": job_id}\n", + "\n", + " def poll_trial_status(\n", + " self, trials: Iterable[BaseTrial]\n", + " ) -> Dict[TrialStatus, Set[int]]:\n", + " \"\"\"Checks the status of any non-terminal trials and returns their\n", + " indices as a mapping from TrialStatus to a list of indices. Required\n", + " for runners used with Ax ``Scheduler``.\n", + "\n", + " NOTE: Does not need to handle waiting between polling calls while trials\n", + " are running; this function should just perform a single poll.\n", + "\n", + " Args:\n", + " trials: Trials to poll.\n", + "\n", + " Returns:\n", + " A dictionary mapping TrialStatus to a list of trial indices that have\n", + " the respective status at the time of the polling. This does not need to\n", + " include trials that at the time of polling already have a terminal\n", + " (ABANDONED, FAILED, COMPLETED) status (but it may).\n", + " \"\"\"\n", + " status_dict = defaultdict(set)\n", + " for trial in trials:\n", + " mock_job_queue = get_mock_job_queue_client()\n", + " status = mock_job_queue.get_job_status(\n", + " job_id=trial.run_metadata.get(\"job_id\")\n", + " )\n", + " status_dict[status].add(trial.index)\n", + "\n", + " return status_dict" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "executionStartTime": 1646325042364, + "executionStopTime": 1646325042596, + "originalKey": "66cfd1c1-541a-4206-964c-25dbfafecd2a", + "requestMsgId": "66cfd1c1-541a-4206-964c-25dbfafecd2a" + }, + "outputs": [], + "source": [ + "import pandas as pd\n", + "\n", + "from ax.core.metric import Metric, MetricFetchResult, MetricFetchE\n", + "from ax.core.base_trial import BaseTrial\n", + "from ax.core.data import Data\n", + "from ax.utils.common.result import Ok, Err\n", + "\n", + "\n", + "class BraninForMockJobMetric(Metric): # Pulls data for trial from external system.\n", + " def fetch_trial_data(self, trial: BaseTrial) -> MetricFetchResult:\n", + " \"\"\"Obtains data via fetching it from ` for a given trial.\"\"\"\n", + " if not isinstance(trial, Trial):\n", + " raise ValueError(\"This metric only handles `Trial`.\")\n", + "\n", + " try:\n", + " mock_job_queue = get_mock_job_queue_client()\n", + "\n", + " # Here we leverage the \"job_id\" metadata created by `MockJobRunner.run`.\n", + " branin_data = mock_job_queue.get_outcome_value_for_completed_job(\n", + " job_id=trial.run_metadata.get(\"job_id\")\n", + " )\n", + " df_dict = {\n", + " \"trial_index\": trial.index,\n", + " \"metric_name\": \"branin\",\n", + " \"arm_name\": trial.arm.name,\n", + " \"mean\": branin_data.get(\"branin\"),\n", + " # Can be set to 0.0 if function is known to be noiseless\n", + " # or to an actual value when SEM is known. Setting SEM to\n", + " # `None` results in Ax assuming unknown noise and inferring\n", + " # noise level from data.\n", + " \"sem\": None,\n", + " }\n", + " return Ok(value=Data(df=pd.DataFrame.from_records([df_dict])))\n", + " except Exception as e:\n", + " return Err(\n", + " MetricFetchE(message=f\"Failed to fetch {self.name}\", exception=e)\n", + " )" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "originalKey": "98c546ac-4e5d-4cee-9ea0-68b4d061c65f", + "showInput": false + }, + "source": [ + "Now we can set up the experiment using the runner and metric we defined. This experiment will have a single-objective optimization config, minimizing the Branin function, and the search space that corresponds to that function." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "executionStartTime": 1646325042616, + "executionStopTime": 1646325042623, + "originalKey": "d2d49a52-1b22-469b-8e09-0e68f59000d5", + "requestMsgId": "d2d49a52-1b22-469b-8e09-0e68f59000d5" + }, + "outputs": [], + "source": [ + "from ax import *\n", + "\n", + "\n", + "def make_branin_experiment_with_runner_and_metric() -> Experiment:\n", + " parameters = [\n", + " RangeParameter(\n", + " name=\"x1\",\n", + " parameter_type=ParameterType.FLOAT,\n", + " lower=-5,\n", + " upper=10,\n", + " ),\n", + " RangeParameter(\n", + " name=\"x2\",\n", + " parameter_type=ParameterType.FLOAT,\n", + " lower=0,\n", + " upper=15,\n", + " ),\n", + " ]\n", + "\n", + " objective = Objective(metric=BraninForMockJobMetric(name=\"branin\"), minimize=True)\n", + "\n", + " return Experiment(\n", + " name=\"branin_test_experiment\",\n", + " search_space=SearchSpace(parameters=parameters),\n", + " optimization_config=OptimizationConfig(objective=objective),\n", + " runner=MockJobRunner(),\n", + " is_test=True, # Marking this experiment as a test experiment.\n", + " )\n", + "\n", + "\n", + "experiment = make_branin_experiment_with_runner_and_metric()" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "originalKey": "d28afea7-6c3f-4813-af4e-253692718015", + "showInput": false + }, + "source": [ + "## 4. Setting up a `Scheduler`" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "originalKey": "db14819c-a219-483d-ba06-60d30294ad94", + "showInput": false + }, + "source": [ + "### 4A. Auto-selecting a generation strategy\n", + "\n", + "A `Scheduler` requires an Ax `GenerationStrategy` specifying the algorithm to use for the optimization. Here we use the `choose_generation_strategy` utility that auto-picks a generation strategy based on the search space properties. To construct a custom generation strategy instead, refer to the [\"Generation Strategy\" tutorial](https://ax.dev/tutorials/generation_strategy.html).\n", + "\n", + "Importantly, a generation strategy in Ax limits allowed parallelism levels for each generation step it contains. If you would like the `Scheduler` to ensure parallelism limitations, set `max_examples` on each generation step in your generation strategy." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "executionStartTime": 1646325042632, + "executionStopTime": 1646325042699, + "originalKey": "d699d3e9-85d3-40f3-822f-ece6a6cc58e3", + "requestMsgId": "d699d3e9-85d3-40f3-822f-ece6a6cc58e3", + "scrolled": true + }, + "outputs": [], + "source": [ + "from ax.generation_strategy.dispatch_utils import choose_generation_strategy\n", + "\n", + "generation_strategy = choose_generation_strategy(\n", + " search_space=experiment.search_space,\n", + " max_parallelism_cap=3,\n", + ")" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "originalKey": "452f36d1-c7d8-477a-87d9-1b9767ace072", + "showInput": false + }, + "source": [ + "Now we have all the components needed to start the scheduler:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "code_folding": [], + "executionStartTime": 1646325042718, + "executionStopTime": 1646325042829, + "hidden_ranges": [], + "originalKey": "139e2f4d-ee86-425b-bece-697ed21c2316", + "requestMsgId": "139e2f4d-ee86-425b-bece-697ed21c2316" + }, + "outputs": [], + "source": [ + "from ax.service.scheduler import Scheduler, SchedulerOptions\n", + "\n", + "\n", + "scheduler = Scheduler(\n", + " experiment=experiment,\n", + " generation_strategy=generation_strategy,\n", + " options=SchedulerOptions(),\n", + ")" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### 4B. Optional: Defining a plotting function" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "import numpy as np\n", + "from ax.plot.trace import optimization_trace_single_method\n", + "from ax.utils.notebook.plotting import render, init_notebook_plotting\n", + "import plotly.io as pio\n", + "\n", + "init_notebook_plotting()\n", + "if in_colab:\n", + " pio.renderers.default = \"colab\"\n", + "\n", + "\n", + "def get_plot():\n", + " best_objectives = np.array(\n", + " [[trial.objective_mean for trial in scheduler.experiment.trials.values()]]\n", + " )\n", + " best_objective_plot = optimization_trace_single_method(\n", + " y=np.minimum.accumulate(best_objectives, axis=1),\n", + " title=\"Model performance vs. # of iterations\",\n", + " ylabel=\"Y\",\n", + " )\n", + " return best_objective_plot" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "originalKey": "f8a2cc5b-f289-497b-80b5-6807d85137b5", + "showInput": false + }, + "source": [ + "## 5. Running the optimization\n", + "\n", + "Once the `Scheduler` instance is set up, user can execute `run_n_trials` as many times as needed, and each execution will add up to the specified `max_trials` trials to the experiment. The number of trials actually run might be less than `max_trials` if the optimization was concluded (e.g. there are no more points in the search space)." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "scheduler.run_n_trials(max_trials=3)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "best_objective_plot = get_plot()\n", + "render(best_objective_plot)" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "originalKey": "e3740875-5b3c-456d-a674-c2c78dab0e0d", + "showInput": false + }, + "source": [ + "We can examine `experiment` to see that it now has three trials:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "executionStartTime": 1646325045492, + "executionStopTime": 1646325045752, + "originalKey": "0ff23f6f-3011-4962-a691-9187f3e8b222", + "requestMsgId": "0ff23f6f-3011-4962-a691-9187f3e8b222" + }, + "outputs": [], + "source": [ + "from ax.service.utils.report_utils import exp_to_df\n", + "\n", + "exp_to_df(experiment)" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "originalKey": "c2888bcc-0c82-4f24-bcb6-105c7e9c4e77", + "showInput": false + }, + "source": [ + "Now we can run `run_n_trials` again to add three more trials to the experiment (this time, without plotting)." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "executionStartTime": 1646325045788, + "executionStopTime": 1646325048325, + "originalKey": "e76eb807-0a6c-45bc-a00f-e753ae8ef6db", + "requestMsgId": "e76eb807-0a6c-45bc-a00f-e753ae8ef6db", + "scrolled": true + }, + "outputs": [], + "source": [ + "scheduler.run_n_trials(max_trials=3)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "best_objective_plot = get_plot()\n", + "render(best_objective_plot)" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "originalKey": "bee52b5d-a5fe-4554-b294-da9b83e8ff02", + "showInput": false + }, + "source": [ + "Examiniming the experiment, we now see 6 trials, one of which is produced by Bayesian optimization (GPEI):" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "executionStartTime": 1646325048364, + "executionStopTime": 1646325048529, + "originalKey": "39204bbb-757b-4dfb-a685-5d540e621ec9", + "requestMsgId": "39204bbb-757b-4dfb-a685-5d540e621ec9" + }, + "outputs": [], + "source": [ + "exp_to_df(experiment)" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "originalKey": "bf89e55c-08cf-480c-914a-2f0c682f74fd", + "showInput": false + }, + "source": [ + "For each call to `run_n_trials`, one can specify a timeout; if `run_n_trials` has been running for too long without finishing its `max_trials`, the operation will exit gracefully:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "executionStartTime": 1646325048565, + "executionStopTime": 1646325049269, + "originalKey": "5b07d1f4-af03-4652-8ed2-bb772b077305", + "requestMsgId": "5b07d1f4-af03-4652-8ed2-bb772b077305" + }, + "outputs": [], + "source": [ + "scheduler.run_n_trials(max_trials=3, timeout_hours=0.00001)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "best_objective_plot = get_plot()\n", + "render(best_objective_plot)" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "originalKey": "6363db46-3b18-4a8b-8c0f-3e290806592b", + "showInput": false + }, + "source": [ + "## 6. Leveraging SQL storage and experiment resumption\n", + "\n", + "When a scheduler is SQL-enabled, it will automatically save all updates it makes to the experiment in the course of the optimization. The experiment can then be resumed in the event of a crash or after a pause. The scheduler should be stateless and therefore, the scheduler itself is not saved in the database.\n", + "\n", + "To store state of optimization to an SQL backend, first follow [setup instructions](https://ax.dev/docs/storage.html#sql) on Ax website. Having set up the SQL backend, pass `DBSettings` to the `Scheduler` on instantiation (note that SQLAlchemy dependency will have to be installed – for installation, refer to [optional dependencies](https://ax.dev/docs/installation.html#optional-dependencies) on Ax website):" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "code_folding": [], + "executionStartTime": 1646325049292, + "executionStopTime": 1646325049522, + "hidden_ranges": [], + "originalKey": "c89a6d00-b660-4370-93a6-b46edfc58e07", + "requestMsgId": "c89a6d00-b660-4370-93a6-b46edfc58e07" + }, + "outputs": [], + "source": [ + "from ax.storage.registry_bundle import RegistryBundle\n", + "from ax.storage.sqa_store.db import (\n", + " create_all_tables,\n", + " get_engine,\n", + " init_engine_and_session_factory,\n", + ")\n", + "from ax.storage.sqa_store.decoder import Decoder\n", + "from ax.storage.sqa_store.encoder import Encoder\n", + "from ax.storage.sqa_store.sqa_config import SQAConfig\n", + "from ax.storage.sqa_store.structs import DBSettings\n", + "\n", + "bundle = RegistryBundle(\n", + " metric_clss={BraninForMockJobMetric: None}, runner_clss={MockJobRunner: None}\n", + ")\n", + "\n", + "# URL is of the form \"dialect+driver://username:password@host:port/database\".\n", + "# Instead of URL, can provide a `creator function`; can specify custom encoders/decoders if necessary.\n", + "db_settings = DBSettings(\n", + " url=\"sqlite:///foo.db\",\n", + " encoder=bundle.encoder,\n", + " decoder=bundle.decoder,\n", + ")\n", + "\n", + "# The following lines are only necessary because it is the first time we are using this database\n", + "# in practice, you will not need to run these lines every time you initialize your scheduler\n", + "init_engine_and_session_factory(url=db_settings.url)\n", + "engine = get_engine()\n", + "create_all_tables(engine)\n", + "\n", + "stored_experiment = make_branin_experiment_with_runner_and_metric()\n", + "generation_strategy = choose_generation_strategy(search_space=experiment.search_space)\n", + "\n", + "scheduler_with_storage = Scheduler(\n", + " experiment=stored_experiment,\n", + " generation_strategy=generation_strategy,\n", + " options=SchedulerOptions(),\n", + " db_settings=db_settings,\n", + ")" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "originalKey": "6939cf6e-5f6b-4a61-a807-f2fea1c7f5ea", + "showInput": false + }, + "source": [ + "To resume a stored experiment:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "code_folding": [], + "executionStartTime": 1646325049666, + "executionStopTime": 1646325049932, + "hidden_ranges": [], + "originalKey": "351e7fca-4332-41ec-ad7d-6a143e0000ef", + "requestMsgId": "351e7fca-4332-41ec-ad7d-6a143e0000ef" + }, + "outputs": [], + "source": [ + "reloaded_experiment_scheduler = Scheduler.from_stored_experiment(\n", + " experiment_name=\"branin_test_experiment\",\n", + " options=SchedulerOptions(),\n", + " # `DBSettings` are also required here so scheduler has access to the\n", + " # database, from which it needs to load the experiment.\n", + " db_settings=db_settings,\n", + ")" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "originalKey": "e4064b5c-3dc0-4be5-bd34-63804ab19047", + "showInput": false + }, + "source": [ + "With the newly reloaded experiment, the `Scheduler` can continue the optimization:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "executionStartTime": 1646325049943, + "executionStopTime": 1646325050416, + "originalKey": "6dddf6e6-1fd3-4e23-a88b-7b964db9b20d", + "requestMsgId": "6dddf6e6-1fd3-4e23-a88b-7b964db9b20d" + }, + "outputs": [], + "source": [ + "reloaded_experiment_scheduler.run_n_trials(max_trials=3)" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "originalKey": "e3f24c9e-3da1-4ee0-ab1c-741f624a6014", + "showInput": false + }, + "source": [ + "## 7. Configuring the scheduler with `SchedulerOptions`, like early stopping\n", + "\n", + "`Scheduler` exposes many options to configure the exact settings of the closed-loop optimization to perform. A few notable ones are:\n", + "- `trial_type` –– currently only `Trial` and not `BatchTrial` is supported, but support for `BatchTrial`-s will follow,\n", + "- `tolerated_trial_failure_rate` and `min_failed_trials_for_failure_rate_check` –– together these two settings control how the scheduler monitors the failure rate among trial runs it deploys. Once `min_failed_trials_for_failure_rate_check` is deployed, the scheduler will start checking whether the ratio of failed to total trials is greater than `tolerated_trial_failure_rate`, and if it is, scheduler will exit the optimization with a `FailureRateExceededError`,\n", + "- `ttl_seconds_for_trials` –– sometimes a failure in a trial run means that it will be difficult to query its status (e.g. due to a crash). If this setting is specified, the Ax `Experiment` will automatically mark trials that have been running for too long (more than their 'time-to-live' (TTL) seconds) as failed,\n", + "- `run_trials_in_batches` –– if `True`, the scheduler will attempt to run trials not by calling `Scheduler.run_trial` in a loop, but by calling `Scheduler.run_trials` on all ready-to-deploy trials at once. This could allow for saving compute in cases where the deployment operation has large overhead and deploying many trials at once saves compute. Note that using this option successfully will require your scheduler subclass to implement `MySchedulerSubclass.run_trials` and `MySchedulerSubclass.poll_available_capacity`.\n", + "- `early_stopping_strategy` -- determines whether a trial should be stopped given the current state of the experiment, so that less promising trials can be terminated quickly. For more on this, see the Trial-Level Early Stopping tutorial: https://ax.dev/tutorials/early_stopping/early_stopping.html\n", + "- `global_stopping_strategy` -- determines whether the full optimization should be stopped or not, so that the run terminates when little progress is being made. A `global_stopping_strategy` instance can be passed to `SchedulerOptions` just as it is passed to `AxClient`, as illustrated in the tutorial on Global Stopping Strategy with AxClient: https://ax.dev/tutorials/gss.html\n", + "\n", + "The rest of the options are described in the docstring below:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "executionStartTime": 1646325050451, + "executionStopTime": 1646325050569, + "originalKey": "b9645271-88cd-43f1-9e07-83afe722696d", + "requestMsgId": "b9645271-88cd-43f1-9e07-83afe722696d" + }, + "outputs": [], + "source": [ + "print(SchedulerOptions.__doc__)" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "originalKey": "eef1a121-1eee-4302-b586-85958f177b04", + "showInput": false + }, + "source": [ + "## 8. Advanced functionality\n", + "\n", + "### 8a. Reporting results to an external system\n", + "\n", + "The `Scheduler` can report the optimization result to an external system each time there are new completed trials if the user-implemented subclass implements `MySchedulerSubclass.report_results` to do so. For example, the folliwing method:\n", + "\n", + "```\n", + "class MySchedulerSubclass(Scheduler):\n", + " ...\n", + " \n", + " def report_results(self, force_refit: bool = False):\n", + " write_to_external_database(len(self.experiment.trials))\n", + " return (True, {}) # Returns optimization success status and optional dict of outputs.\n", + "```\n", + "could be used to record number of trials in experiment so far in an external database.\n", + "\n", + "Since `report_results` is an instance method, it has access to `self.experiment` and `self.generation_strategy`, which contain all the information about the state of the optimization thus far." + ] + }, + { + "cell_type": "markdown", + "metadata": { + "originalKey": "12b60db0-52d8-4337-ad1c-77fdc3c2452b", + "showInput": false + }, + "source": [ + "### 8b. Using `run_trials_and_yield_results` generator method\n", + "\n", + "In some systems it's beneficial to have greater control over `Scheduler.run_n_trials` instead of just starting it and needing to wait for it to run all the way to completion before having access to its output. For this purpose, the `Scheduler` implements a generator method `run_trials_and_yield_results`, which yields the output of `Scheduler.report_results` each time there are new completed trials and can be used like so:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "code_folding": [], + "executionStartTime": 1646325050601, + "executionStopTime": 1646325050672, + "hidden_ranges": [], + "originalKey": "77bf9ea5-5ec2-4d65-a723-3c0dfeea144b", + "requestMsgId": "77bf9ea5-5ec2-4d65-a723-3c0dfeea144b" + }, + "outputs": [], + "source": [ + "class ResultReportingScheduler(Scheduler):\n", + " def report_results(self, force_refit: bool = False):\n", + " return True, {\n", + " \"trials so far\": len(self.experiment.trials),\n", + " \"currently producing trials from generation step\": self.generation_strategy._curr.model_name,\n", + " \"running trials\": [t.index for t in self.running_trials],\n", + " }" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "executionStartTime": 1646325050680, + "executionStopTime": 1646325057409, + "originalKey": "c037044e-79d8-4c36-92e9-d9f360a9f5fe", + "requestMsgId": "c037044e-79d8-4c36-92e9-d9f360a9f5fe" + }, + "outputs": [], + "source": [ + "experiment = make_branin_experiment_with_runner_and_metric()\n", + "scheduler = ResultReportingScheduler(\n", + " experiment=experiment,\n", + " generation_strategy=choose_generation_strategy(\n", + " search_space=experiment.search_space,\n", + " max_parallelism_cap=3,\n", + " ),\n", + " options=SchedulerOptions(),\n", + ")\n", + "\n", + "for reported_result in scheduler.run_trials_and_yield_results(max_trials=6):\n", + " print(\"Reported result: \", reported_result)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# Clean up to enable running the tutorial repeatedly with\n", + "# the same results. You wouldn't do this if you wanted to\n", + "# keep adding data to the same experiment.\n", + "from ax.storage.sqa_store.delete import delete_experiment\n", + "\n", + "delete_experiment(\"branin_test_experiment\")" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [] } - }, - "cell_type": "markdown", - "metadata": { - "originalKey": "f85ac1dc-8678-4b68-a31b-33623c95fd89" - }, - "source": [ - "This scheme summarizes how the scheduler interacts with any external system used to run trial evaluations:\n", - "\n", - "![image-2.png](attachment:image-2.png)" - ] - }, - { - "cell_type": "markdown", - "metadata": { - "originalKey": "72643e42-f7e8-4aec-a371-efa5d1991899" - }, - "source": [ - "## 2. Set up a mock external execution system " - ] - }, - { - "cell_type": "markdown", - "metadata": { - "originalKey": "d8e139e3-c453-43f3-8211-0a85453bab54" - }, - "source": [ - "An example of an 'external system' running trial evaluations could be a remote server executing scheduled jobs, a subprocess conducting ML training runs, an engine running physics simulations, etc. For the sake of example here, let us assume a dummy external system with the following client:" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "import sys\n", - "in_colab = 'google.colab' in sys.modules\n", - "if in_colab:\n", - " %pip install ax-platform" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "code_folding": [], - "executionStartTime": 1646325042150, - "executionStopTime": 1646325042183, - "hidden_ranges": [], - "originalKey": "1dd579d5-2afa-4cad-b6c0-a54343863579", - "requestMsgId": "1dd579d5-2afa-4cad-b6c0-a54343863579" - }, - "outputs": [], - "source": [ - "from random import randint\n", - "from time import time\n", - "from typing import Any, Dict, NamedTuple, Union\n", - "\n", - "from ax.core.base_trial import TrialStatus\n", - "from ax.utils.measurement.synthetic_functions import branin\n", - "\n", - "\n", - "class MockJob(NamedTuple):\n", - " \"\"\"Dummy class to represent a job scheduled on `MockJobQueue`.\"\"\"\n", - "\n", - " id: int\n", - " parameters: Dict[str, Union[str, float, int, bool]]\n", - "\n", - "\n", - "class MockJobQueueClient:\n", - " \"\"\"Dummy class to represent a job queue where the Ax `Scheduler` will\n", - " deploy trial evaluation runs during optimization.\n", - " \"\"\"\n", - "\n", - " jobs: Dict[str, MockJob] = {}\n", - "\n", - " def schedule_job_with_parameters(\n", - " self, parameters: Dict[str, Union[str, float, int, bool]]\n", - " ) -> int:\n", - " \"\"\"Schedules an evaluation job with given parameters and returns job ID.\"\"\"\n", - " # Code to actually schedule the job and produce an ID would go here;\n", - " # using timestamp in microseconds as dummy ID for this example.\n", - " job_id = int(time() * 1e6)\n", - " self.jobs[job_id] = MockJob(job_id, parameters)\n", - " return job_id\n", - "\n", - " def get_job_status(self, job_id: int) -> TrialStatus:\n", - " \"\"\" \"Get status of the job by a given ID. For simplicity of the example,\n", - " return an Ax `TrialStatus`.\n", - " \"\"\"\n", - " job = self.jobs[job_id]\n", - " # Instead of randomizing trial status, code to check actual job status\n", - " # would go here.\n", - " if randint(0, 3) > 0:\n", - " return TrialStatus.COMPLETED\n", - " return TrialStatus.RUNNING\n", - "\n", - " def get_outcome_value_for_completed_job(self, job_id: int) -> Dict[str, float]:\n", - " \"\"\"Get evaluation results for a given completed job.\"\"\"\n", - " job = self.jobs[job_id]\n", - " # In a real external system, this would retrieve real relevant outcomes and\n", - " # not a synthetic function value.\n", - " return {\"branin\": branin(job.parameters.get(\"x1\"), job.parameters.get(\"x2\"))}\n", - "\n", - "\n", - "MOCK_JOB_QUEUE_CLIENT = MockJobQueueClient()\n", - "\n", - "\n", - "def get_mock_job_queue_client() -> MockJobQueueClient:\n", - " \"\"\"Obtain the singleton job queue instance.\"\"\"\n", - " return MOCK_JOB_QUEUE_CLIENT" - ] - }, - { - "cell_type": "markdown", - "metadata": { - "originalKey": "d3127829-507d-46ff-bd4f-81ea1bd21066", - "showInput": false - }, - "source": [ - "## 3. Set up an experiment according to the mock external system\n", - "\n", - "As mentioned above, using a `Scheduler` requires a fully set up experiment with metrics and a runner. Refer to the \"Building Blocks of Ax\" tutorial to learn more about those components, as here we assume familiarity with them. \n", - "\n", - "The following runner and metric set up intractions between the `Scheduler` and the mock external system we assume:" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "code_folding": [], - "executionStartTime": 1646325042214, - "executionStopTime": 1646325042307, - "hidden_ranges": [], - "originalKey": "62b96030-89c2-45a6-9250-0f1b529bbd38", - "requestMsgId": "62b96030-89c2-45a6-9250-0f1b529bbd38" - }, - "outputs": [], - "source": [ - "from collections import defaultdict\n", - "from typing import Iterable, Set\n", - "\n", - "from ax.core.base_trial import BaseTrial\n", - "from ax.core.runner import Runner\n", - "from ax.core.trial import Trial\n", - "\n", - "\n", - "class MockJobRunner(Runner): # Deploys trials to external system.\n", - " def run(self, trial: BaseTrial) -> Dict[str, Any]:\n", - " \"\"\"Deploys a trial based on custom runner subclass implementation.\n", - "\n", - " Args:\n", - " trial: The trial to deploy.\n", - "\n", - " Returns:\n", - " Dict of run metadata from the deployment process.\n", - " \"\"\"\n", - " if not isinstance(trial, Trial):\n", - " raise ValueError(\"This runner only handles `Trial`.\")\n", - "\n", - " mock_job_queue = get_mock_job_queue_client()\n", - " job_id = mock_job_queue.schedule_job_with_parameters(\n", - " parameters=trial.arm.parameters\n", - " )\n", - " # This run metadata will be attached to trial as `trial.run_metadata`\n", - " # by the base `Scheduler`.\n", - " return {\"job_id\": job_id}\n", - "\n", - " def poll_trial_status(\n", - " self, trials: Iterable[BaseTrial]\n", - " ) -> Dict[TrialStatus, Set[int]]:\n", - " \"\"\"Checks the status of any non-terminal trials and returns their\n", - " indices as a mapping from TrialStatus to a list of indices. Required\n", - " for runners used with Ax ``Scheduler``.\n", - "\n", - " NOTE: Does not need to handle waiting between polling calls while trials\n", - " are running; this function should just perform a single poll.\n", - "\n", - " Args:\n", - " trials: Trials to poll.\n", - "\n", - " Returns:\n", - " A dictionary mapping TrialStatus to a list of trial indices that have\n", - " the respective status at the time of the polling. This does not need to\n", - " include trials that at the time of polling already have a terminal\n", - " (ABANDONED, FAILED, COMPLETED) status (but it may).\n", - " \"\"\"\n", - " status_dict = defaultdict(set)\n", - " for trial in trials:\n", - " mock_job_queue = get_mock_job_queue_client()\n", - " status = mock_job_queue.get_job_status(\n", - " job_id=trial.run_metadata.get(\"job_id\")\n", - " )\n", - " status_dict[status].add(trial.index)\n", - "\n", - " return status_dict" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "executionStartTime": 1646325042364, - "executionStopTime": 1646325042596, - "originalKey": "66cfd1c1-541a-4206-964c-25dbfafecd2a", - "requestMsgId": "66cfd1c1-541a-4206-964c-25dbfafecd2a" - }, - "outputs": [], - "source": [ - "import pandas as pd\n", - "\n", - "from ax.core.metric import Metric, MetricFetchResult, MetricFetchE\n", - "from ax.core.base_trial import BaseTrial\n", - "from ax.core.data import Data\n", - "from ax.utils.common.result import Ok, Err\n", - "\n", - "\n", - "class BraninForMockJobMetric(Metric): # Pulls data for trial from external system.\n", - " def fetch_trial_data(self, trial: BaseTrial) -> MetricFetchResult:\n", - " \"\"\"Obtains data via fetching it from ` for a given trial.\"\"\"\n", - " if not isinstance(trial, Trial):\n", - " raise ValueError(\"This metric only handles `Trial`.\")\n", - "\n", - " try:\n", - " mock_job_queue = get_mock_job_queue_client()\n", - "\n", - " # Here we leverage the \"job_id\" metadata created by `MockJobRunner.run`.\n", - " branin_data = mock_job_queue.get_outcome_value_for_completed_job(\n", - " job_id=trial.run_metadata.get(\"job_id\")\n", - " )\n", - " df_dict = {\n", - " \"trial_index\": trial.index,\n", - " \"metric_name\": \"branin\",\n", - " \"arm_name\": trial.arm.name,\n", - " \"mean\": branin_data.get(\"branin\"),\n", - " # Can be set to 0.0 if function is known to be noiseless\n", - " # or to an actual value when SEM is known. Setting SEM to\n", - " # `None` results in Ax assuming unknown noise and inferring\n", - " # noise level from data.\n", - " \"sem\": None,\n", - " }\n", - " return Ok(value=Data(df=pd.DataFrame.from_records([df_dict])))\n", - " except Exception as e:\n", - " return Err(\n", - " MetricFetchE(message=f\"Failed to fetch {self.name}\", exception=e)\n", - " )" - ] - }, - { - "cell_type": "markdown", - "metadata": { - "originalKey": "98c546ac-4e5d-4cee-9ea0-68b4d061c65f", - "showInput": false - }, - "source": [ - "Now we can set up the experiment using the runner and metric we defined. This experiment will have a single-objective optimization config, minimizing the Branin function, and the search space that corresponds to that function." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "executionStartTime": 1646325042616, - "executionStopTime": 1646325042623, - "originalKey": "d2d49a52-1b22-469b-8e09-0e68f59000d5", - "requestMsgId": "d2d49a52-1b22-469b-8e09-0e68f59000d5" - }, - "outputs": [], - "source": [ - "from ax import *\n", - "\n", - "\n", - "def make_branin_experiment_with_runner_and_metric() -> Experiment:\n", - " parameters = [\n", - " RangeParameter(\n", - " name=\"x1\",\n", - " parameter_type=ParameterType.FLOAT,\n", - " lower=-5,\n", - " upper=10,\n", - " ),\n", - " RangeParameter(\n", - " name=\"x2\",\n", - " parameter_type=ParameterType.FLOAT,\n", - " lower=0,\n", - " upper=15,\n", - " ),\n", - " ]\n", - "\n", - " objective = Objective(metric=BraninForMockJobMetric(name=\"branin\"), minimize=True)\n", - "\n", - " return Experiment(\n", - " name=\"branin_test_experiment\",\n", - " search_space=SearchSpace(parameters=parameters),\n", - " optimization_config=OptimizationConfig(objective=objective),\n", - " runner=MockJobRunner(),\n", - " is_test=True, # Marking this experiment as a test experiment.\n", - " )\n", - "\n", - "\n", - "experiment = make_branin_experiment_with_runner_and_metric()" - ] - }, - { - "cell_type": "markdown", - "metadata": { - "originalKey": "d28afea7-6c3f-4813-af4e-253692718015", - "showInput": false - }, - "source": [ - "## 4. Setting up a `Scheduler`" - ] - }, - { - "cell_type": "markdown", - "metadata": { - "originalKey": "db14819c-a219-483d-ba06-60d30294ad94", - "showInput": false - }, - "source": [ - "### 4A. Auto-selecting a generation strategy\n", - "\n", - "A `Scheduler` requires an Ax `GenerationStrategy` specifying the algorithm to use for the optimization. Here we use the `choose_generation_strategy` utility that auto-picks a generation strategy based on the search space properties. To construct a custom generation strategy instead, refer to the [\"Generation Strategy\" tutorial](https://ax.dev/tutorials/generation_strategy.html).\n", - "\n", - "Importantly, a generation strategy in Ax limits allowed parallelism levels for each generation step it contains. If you would like the `Scheduler` to ensure parallelism limitations, set `max_examples` on each generation step in your generation strategy." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "executionStartTime": 1646325042632, - "executionStopTime": 1646325042699, - "originalKey": "d699d3e9-85d3-40f3-822f-ece6a6cc58e3", - "requestMsgId": "d699d3e9-85d3-40f3-822f-ece6a6cc58e3", - "scrolled": true - }, - "outputs": [], - "source": [ - "from ax.modelbridge.dispatch_utils import choose_generation_strategy\n", - "\n", - "generation_strategy = choose_generation_strategy(\n", - " search_space=experiment.search_space,\n", - " max_parallelism_cap=3,\n", - ")" - ] - }, - { - "cell_type": "markdown", - "metadata": { - "originalKey": "452f36d1-c7d8-477a-87d9-1b9767ace072", - "showInput": false - }, - "source": [ - "Now we have all the components needed to start the scheduler:" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "code_folding": [], - "executionStartTime": 1646325042718, - "executionStopTime": 1646325042829, - "hidden_ranges": [], - "originalKey": "139e2f4d-ee86-425b-bece-697ed21c2316", - "requestMsgId": "139e2f4d-ee86-425b-bece-697ed21c2316" - }, - "outputs": [], - "source": [ - "from ax.service.scheduler import Scheduler, SchedulerOptions\n", - "\n", - "\n", - "scheduler = Scheduler(\n", - " experiment=experiment,\n", - " generation_strategy=generation_strategy,\n", - " options=SchedulerOptions(),\n", - ")" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "### 4B. Optional: Defining a plotting function" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "import numpy as np\n", - "from ax.plot.trace import optimization_trace_single_method\n", - "from ax.utils.notebook.plotting import render, init_notebook_plotting\n", - "import plotly.io as pio\n", - "\n", - "init_notebook_plotting()\n", - "if in_colab:\n", - " pio.renderers.default = \"colab\"\n", - "\n", - "\n", - "def get_plot():\n", - " best_objectives = np.array(\n", - " [[trial.objective_mean for trial in scheduler.experiment.trials.values()]]\n", - " )\n", - " best_objective_plot = optimization_trace_single_method(\n", - " y=np.minimum.accumulate(best_objectives, axis=1),\n", - " title=\"Model performance vs. # of iterations\",\n", - " ylabel=\"Y\",\n", - " )\n", - " return best_objective_plot" - ] - }, - { - "cell_type": "markdown", - "metadata": { - "originalKey": "f8a2cc5b-f289-497b-80b5-6807d85137b5", - "showInput": false - }, - "source": [ - "## 5. Running the optimization\n", - "\n", - "Once the `Scheduler` instance is set up, user can execute `run_n_trials` as many times as needed, and each execution will add up to the specified `max_trials` trials to the experiment. The number of trials actually run might be less than `max_trials` if the optimization was concluded (e.g. there are no more points in the search space)." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "scheduler.run_n_trials(max_trials=3)" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "best_objective_plot = get_plot()\n", - "render(best_objective_plot)" - ] - }, - { - "cell_type": "markdown", - "metadata": { - "originalKey": "e3740875-5b3c-456d-a674-c2c78dab0e0d", - "showInput": false - }, - "source": [ - "We can examine `experiment` to see that it now has three trials:" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "executionStartTime": 1646325045492, - "executionStopTime": 1646325045752, - "originalKey": "0ff23f6f-3011-4962-a691-9187f3e8b222", - "requestMsgId": "0ff23f6f-3011-4962-a691-9187f3e8b222" - }, - "outputs": [], - "source": [ - "from ax.service.utils.report_utils import exp_to_df\n", - "\n", - "exp_to_df(experiment)" - ] - }, - { - "cell_type": "markdown", - "metadata": { - "originalKey": "c2888bcc-0c82-4f24-bcb6-105c7e9c4e77", - "showInput": false - }, - "source": [ - "Now we can run `run_n_trials` again to add three more trials to the experiment (this time, without plotting)." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "executionStartTime": 1646325045788, - "executionStopTime": 1646325048325, - "originalKey": "e76eb807-0a6c-45bc-a00f-e753ae8ef6db", - "requestMsgId": "e76eb807-0a6c-45bc-a00f-e753ae8ef6db", - "scrolled": true - }, - "outputs": [], - "source": [ - "scheduler.run_n_trials(max_trials=3)" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "best_objective_plot = get_plot()\n", - "render(best_objective_plot)" - ] - }, - { - "cell_type": "markdown", - "metadata": { - "originalKey": "bee52b5d-a5fe-4554-b294-da9b83e8ff02", - "showInput": false - }, - "source": [ - "Examiniming the experiment, we now see 6 trials, one of which is produced by Bayesian optimization (GPEI):" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "executionStartTime": 1646325048364, - "executionStopTime": 1646325048529, - "originalKey": "39204bbb-757b-4dfb-a685-5d540e621ec9", - "requestMsgId": "39204bbb-757b-4dfb-a685-5d540e621ec9" - }, - "outputs": [], - "source": [ - "exp_to_df(experiment)" - ] - }, - { - "cell_type": "markdown", - "metadata": { - "originalKey": "bf89e55c-08cf-480c-914a-2f0c682f74fd", - "showInput": false - }, - "source": [ - "For each call to `run_n_trials`, one can specify a timeout; if `run_n_trials` has been running for too long without finishing its `max_trials`, the operation will exit gracefully:" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "executionStartTime": 1646325048565, - "executionStopTime": 1646325049269, - "originalKey": "5b07d1f4-af03-4652-8ed2-bb772b077305", - "requestMsgId": "5b07d1f4-af03-4652-8ed2-bb772b077305" - }, - "outputs": [], - "source": [ - "scheduler.run_n_trials(max_trials=3, timeout_hours=0.00001)" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "best_objective_plot = get_plot()\n", - "render(best_objective_plot)" - ] - }, - { - "cell_type": "markdown", - "metadata": { - "originalKey": "6363db46-3b18-4a8b-8c0f-3e290806592b", - "showInput": false - }, - "source": [ - "## 6. Leveraging SQL storage and experiment resumption\n", - "\n", - "When a scheduler is SQL-enabled, it will automatically save all updates it makes to the experiment in the course of the optimization. The experiment can then be resumed in the event of a crash or after a pause. The scheduler should be stateless and therefore, the scheduler itself is not saved in the database.\n", - "\n", - "To store state of optimization to an SQL backend, first follow [setup instructions](https://ax.dev/docs/storage.html#sql) on Ax website. Having set up the SQL backend, pass `DBSettings` to the `Scheduler` on instantiation (note that SQLAlchemy dependency will have to be installed – for installation, refer to [optional dependencies](https://ax.dev/docs/installation.html#optional-dependencies) on Ax website):" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "code_folding": [], - "executionStartTime": 1646325049292, - "executionStopTime": 1646325049522, - "hidden_ranges": [], - "originalKey": "c89a6d00-b660-4370-93a6-b46edfc58e07", - "requestMsgId": "c89a6d00-b660-4370-93a6-b46edfc58e07" - }, - "outputs": [], - "source": [ - "from ax.storage.registry_bundle import RegistryBundle\n", - "from ax.storage.sqa_store.db import (\n", - " create_all_tables,\n", - " get_engine,\n", - " init_engine_and_session_factory,\n", - ")\n", - "from ax.storage.sqa_store.decoder import Decoder\n", - "from ax.storage.sqa_store.encoder import Encoder\n", - "from ax.storage.sqa_store.sqa_config import SQAConfig\n", - "from ax.storage.sqa_store.structs import DBSettings\n", - "\n", - "bundle = RegistryBundle(\n", - " metric_clss={BraninForMockJobMetric: None}, runner_clss={MockJobRunner: None}\n", - ")\n", - "\n", - "# URL is of the form \"dialect+driver://username:password@host:port/database\".\n", - "# Instead of URL, can provide a `creator function`; can specify custom encoders/decoders if necessary.\n", - "db_settings = DBSettings(\n", - " url=\"sqlite:///foo.db\",\n", - " encoder=bundle.encoder,\n", - " decoder=bundle.decoder,\n", - ")\n", - "\n", - "# The following lines are only necessary because it is the first time we are using this database\n", - "# in practice, you will not need to run these lines every time you initialize your scheduler\n", - "init_engine_and_session_factory(url=db_settings.url)\n", - "engine = get_engine()\n", - "create_all_tables(engine)\n", - "\n", - "stored_experiment = make_branin_experiment_with_runner_and_metric()\n", - "generation_strategy = choose_generation_strategy(search_space=experiment.search_space)\n", - "\n", - "scheduler_with_storage = Scheduler(\n", - " experiment=stored_experiment,\n", - " generation_strategy=generation_strategy,\n", - " options=SchedulerOptions(),\n", - " db_settings=db_settings,\n", - ")" - ] - }, - { - "cell_type": "markdown", - "metadata": { - "originalKey": "6939cf6e-5f6b-4a61-a807-f2fea1c7f5ea", - "showInput": false - }, - "source": [ - "To resume a stored experiment:" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "code_folding": [], - "executionStartTime": 1646325049666, - "executionStopTime": 1646325049932, - "hidden_ranges": [], - "originalKey": "351e7fca-4332-41ec-ad7d-6a143e0000ef", - "requestMsgId": "351e7fca-4332-41ec-ad7d-6a143e0000ef" - }, - "outputs": [], - "source": [ - "reloaded_experiment_scheduler = Scheduler.from_stored_experiment(\n", - " experiment_name=\"branin_test_experiment\",\n", - " options=SchedulerOptions(),\n", - " # `DBSettings` are also required here so scheduler has access to the\n", - " # database, from which it needs to load the experiment.\n", - " db_settings=db_settings,\n", - ")" - ] - }, - { - "cell_type": "markdown", - "metadata": { - "originalKey": "e4064b5c-3dc0-4be5-bd34-63804ab19047", - "showInput": false - }, - "source": [ - "With the newly reloaded experiment, the `Scheduler` can continue the optimization:" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "executionStartTime": 1646325049943, - "executionStopTime": 1646325050416, - "originalKey": "6dddf6e6-1fd3-4e23-a88b-7b964db9b20d", - "requestMsgId": "6dddf6e6-1fd3-4e23-a88b-7b964db9b20d" - }, - "outputs": [], - "source": [ - "reloaded_experiment_scheduler.run_n_trials(max_trials=3)" - ] - }, - { - "cell_type": "markdown", - "metadata": { - "originalKey": "e3f24c9e-3da1-4ee0-ab1c-741f624a6014", - "showInput": false - }, - "source": [ - "## 7. Configuring the scheduler with `SchedulerOptions`, like early stopping\n", - "\n", - "`Scheduler` exposes many options to configure the exact settings of the closed-loop optimization to perform. A few notable ones are:\n", - "- `trial_type` –– currently only `Trial` and not `BatchTrial` is supported, but support for `BatchTrial`-s will follow,\n", - "- `tolerated_trial_failure_rate` and `min_failed_trials_for_failure_rate_check` –– together these two settings control how the scheduler monitors the failure rate among trial runs it deploys. Once `min_failed_trials_for_failure_rate_check` is deployed, the scheduler will start checking whether the ratio of failed to total trials is greater than `tolerated_trial_failure_rate`, and if it is, scheduler will exit the optimization with a `FailureRateExceededError`,\n", - "- `ttl_seconds_for_trials` –– sometimes a failure in a trial run means that it will be difficult to query its status (e.g. due to a crash). If this setting is specified, the Ax `Experiment` will automatically mark trials that have been running for too long (more than their 'time-to-live' (TTL) seconds) as failed,\n", - "- `run_trials_in_batches` –– if `True`, the scheduler will attempt to run trials not by calling `Scheduler.run_trial` in a loop, but by calling `Scheduler.run_trials` on all ready-to-deploy trials at once. This could allow for saving compute in cases where the deployment operation has large overhead and deploying many trials at once saves compute. Note that using this option successfully will require your scheduler subclass to implement `MySchedulerSubclass.run_trials` and `MySchedulerSubclass.poll_available_capacity`.\n", - "- `early_stopping_strategy` -- determines whether a trial should be stopped given the current state of the experiment, so that less promising trials can be terminated quickly. For more on this, see the Trial-Level Early Stopping tutorial: https://ax.dev/tutorials/early_stopping/early_stopping.html\n", - "- `global_stopping_strategy` -- determines whether the full optimization should be stopped or not, so that the run terminates when little progress is being made. A `global_stopping_strategy` instance can be passed to `SchedulerOptions` just as it is passed to `AxClient`, as illustrated in the tutorial on Global Stopping Strategy with AxClient: https://ax.dev/tutorials/gss.html\n", - "\n", - "The rest of the options are described in the docstring below:" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "executionStartTime": 1646325050451, - "executionStopTime": 1646325050569, - "originalKey": "b9645271-88cd-43f1-9e07-83afe722696d", - "requestMsgId": "b9645271-88cd-43f1-9e07-83afe722696d" - }, - "outputs": [], - "source": [ - "print(SchedulerOptions.__doc__)" - ] - }, - { - "cell_type": "markdown", - "metadata": { - "originalKey": "eef1a121-1eee-4302-b586-85958f177b04", - "showInput": false - }, - "source": [ - "## 8. Advanced functionality\n", - "\n", - "### 8a. Reporting results to an external system\n", - "\n", - "The `Scheduler` can report the optimization result to an external system each time there are new completed trials if the user-implemented subclass implements `MySchedulerSubclass.report_results` to do so. For example, the folliwing method:\n", - "\n", - "```\n", - "class MySchedulerSubclass(Scheduler):\n", - " ...\n", - " \n", - " def report_results(self, force_refit: bool = False):\n", - " write_to_external_database(len(self.experiment.trials))\n", - " return (True, {}) # Returns optimization success status and optional dict of outputs.\n", - "```\n", - "could be used to record number of trials in experiment so far in an external database.\n", - "\n", - "Since `report_results` is an instance method, it has access to `self.experiment` and `self.generation_strategy`, which contain all the information about the state of the optimization thus far." - ] - }, - { - "cell_type": "markdown", - "metadata": { - "originalKey": "12b60db0-52d8-4337-ad1c-77fdc3c2452b", - "showInput": false - }, - "source": [ - "### 8b. Using `run_trials_and_yield_results` generator method\n", - "\n", - "In some systems it's beneficial to have greater control over `Scheduler.run_n_trials` instead of just starting it and needing to wait for it to run all the way to completion before having access to its output. For this purpose, the `Scheduler` implements a generator method `run_trials_and_yield_results`, which yields the output of `Scheduler.report_results` each time there are new completed trials and can be used like so:" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "code_folding": [], - "executionStartTime": 1646325050601, - "executionStopTime": 1646325050672, - "hidden_ranges": [], - "originalKey": "77bf9ea5-5ec2-4d65-a723-3c0dfeea144b", - "requestMsgId": "77bf9ea5-5ec2-4d65-a723-3c0dfeea144b" - }, - "outputs": [], - "source": [ - "class ResultReportingScheduler(Scheduler):\n", - " def report_results(self, force_refit: bool = False):\n", - " return True, {\n", - " \"trials so far\": len(self.experiment.trials),\n", - " \"currently producing trials from generation step\": self.generation_strategy._curr.model_name,\n", - " \"running trials\": [t.index for t in self.running_trials],\n", - " }" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "executionStartTime": 1646325050680, - "executionStopTime": 1646325057409, - "originalKey": "c037044e-79d8-4c36-92e9-d9f360a9f5fe", - "requestMsgId": "c037044e-79d8-4c36-92e9-d9f360a9f5fe" - }, - "outputs": [], - "source": [ - "experiment = make_branin_experiment_with_runner_and_metric()\n", - "scheduler = ResultReportingScheduler(\n", - " experiment=experiment,\n", - " generation_strategy=choose_generation_strategy(\n", - " search_space=experiment.search_space,\n", - " max_parallelism_cap=3,\n", - " ),\n", - " options=SchedulerOptions(),\n", - ")\n", - "\n", - "for reported_result in scheduler.run_trials_and_yield_results(max_trials=6):\n", - " print(\"Reported result: \", reported_result)" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "# Clean up to enable running the tutorial repeatedly with\n", - "# the same results. You wouldn't do this if you wanted to\n", - "# keep adding data to the same experiment.\n", - "from ax.storage.sqa_store.delete import delete_experiment\n", - "\n", - "delete_experiment(\"branin_test_experiment\")" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [] - } - ], - "metadata": { - "custom": { - "cells": [], - "metadata": { + ], + "metadata": { + "custom": { + "cells": [], + "metadata": { + "fileHeader": "", + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.9.15" + } + }, + "nbformat": 4, + "nbformat_minor": 2 + }, "fileHeader": "", + "fileUid": "8d7b08b8-0f6e-49e0-90f6-1f90cd56c1d0", + "indentAmount": 2, + "isAdHoc": false, "kernelspec": { - "display_name": "Python 3 (ipykernel)", - "language": "python", - "name": "python3" + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" }, "language_info": { - "codemirror_mode": { - "name": "ipython", - "version": 3 - }, - "file_extension": ".py", - "mimetype": "text/x-python", - "name": "python", - "nbconvert_exporter": "python", - "pygments_lexer": "ipython3", - "version": "3.9.15" + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.11.5" } - }, - "nbformat": 4, - "nbformat_minor": 2 - }, - "indentAmount": 2, - "kernelspec": { - "display_name": "Python 3 (ipykernel)", - "language": "python", - "name": "python3" - }, - "language_info": { - "codemirror_mode": { - "name": "ipython", - "version": 3 - }, - "file_extension": ".py", - "mimetype": "text/x-python", - "name": "python", - "nbconvert_exporter": "python", - "pygments_lexer": "ipython3", - "version": "3.11.5" } - }, - "nbformat": 4, - "nbformat_minor": 2 } diff --git a/tutorials/sebo/sebo.ipynb b/tutorials/sebo/sebo.ipynb index f3e2f100663..ac944c28c0b 100644 --- a/tutorials/sebo/sebo.ipynb +++ b/tutorials/sebo/sebo.ipynb @@ -1,661 +1,661 @@ { - "cells": [ - { - "cell_type": "markdown", - "metadata": { - "collapsed": true, - "customInput": null, - "jupyter": { - "outputs_hidden": true + "cells": [ + { + "cell_type": "markdown", + "metadata": { + "collapsed": true, + "customInput": null, + "jupyter": { + "outputs_hidden": true + }, + "originalKey": "d3a0136e-94fa-477c-a839-20e5b7f1cdd2", + "showInput": false + }, + "source": [ + "# Sparsity Exploration Bayesian Optimization (SEBO) Ax API \n", + "\n", + "This tutorial introduces the Sparsity Exploration Bayesian Optimization (SEBO) method and demonstrates how to utilize it using the Ax API. SEBO is designed to enhance Bayesian Optimization (BO) by taking the interpretability and simplicity of configurations into consideration. In essence, SEBO incorporates sparsity, modeled as the $L_0$ norm, as an additional objective in BO. By employing multi-objective optimization techniques such as Expected Hyper-Volume Improvement, SEBO enables the joint optimization of objectives while simultaneously incorporating feature-level sparsity. This allows users to efficiently explore different trade-offs between objectives and sparsity.\n", + "\n", + "\n", + "For a more detailed understanding of the SEBO algorithm, please refer to the following publication:\n", + "\n", + "[1] [S. Liu, Q. Feng, D. Eriksson, B. Letham and E. Bakshy. Sparse Bayesian Optimization. International Conference on Artificial Intelligence and Statistics, 2023.](https://proceedings.mlr.press/v206/liu23b/liu23b.pdf)\n", + "\n", + "By following this tutorial, you will learn how to leverage the SEBO method through the Ax API, empowering you to effectively balance objectives and sparsity in your optimization tasks. Let's get started!" + ] }, - "originalKey": "d3a0136e-94fa-477c-a839-20e5b7f1cdd2", - "showInput": false - }, - "source": [ - "# Sparsity Exploration Bayesian Optimization (SEBO) Ax API \n", - "\n", - "This tutorial introduces the Sparsity Exploration Bayesian Optimization (SEBO) method and demonstrates how to utilize it using the Ax API. SEBO is designed to enhance Bayesian Optimization (BO) by taking the interpretability and simplicity of configurations into consideration. In essence, SEBO incorporates sparsity, modeled as the $L_0$ norm, as an additional objective in BO. By employing multi-objective optimization techniques such as Expected Hyper-Volume Improvement, SEBO enables the joint optimization of objectives while simultaneously incorporating feature-level sparsity. This allows users to efficiently explore different trade-offs between objectives and sparsity.\n", - "\n", - "\n", - "For a more detailed understanding of the SEBO algorithm, please refer to the following publication:\n", - "\n", - "[1] [S. Liu, Q. Feng, D. Eriksson, B. Letham and E. Bakshy. Sparse Bayesian Optimization. International Conference on Artificial Intelligence and Statistics, 2023.](https://proceedings.mlr.press/v206/liu23b/liu23b.pdf)\n", - "\n", - "By following this tutorial, you will learn how to leverage the SEBO method through the Ax API, empowering you to effectively balance objectives and sparsity in your optimization tasks. Let's get started!" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "import sys\n", - "import plotly.io as pio\n", - "if 'google.colab' in sys.modules:\n", - " pio.renderers.default = \"colab\"\n", - " %pip install ax-platform" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "collapsed": false, - "customOutput": null, - "executionStartTime": 1689117385062, - "executionStopTime": 1689117389874, - "jupyter": { - "outputs_hidden": false + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "import sys\n", + "import plotly.io as pio\n", + "if 'google.colab' in sys.modules:\n", + " pio.renderers.default = \"colab\"\n", + " %pip install ax-platform" + ] }, - "originalKey": "cea96143-019a-41c1-a388-545f48992db9", - "requestMsgId": "c2c22a5d-aee0-4a1e-98d9-b360aa1851ff", - "showInput": true - }, - "outputs": [], - "source": [ - "import math\n", - "import os\n", - "import warnings\n", - "\n", - "import matplotlib\n", - "import matplotlib.pyplot as plt\n", - "\n", - "import numpy as np\n", - "import torch\n", - "from ax import Data, Experiment, ParameterType, RangeParameter, SearchSpace\n", - "from ax.core.objective import Objective\n", - "from ax.core.optimization_config import OptimizationConfig\n", - "from ax.metrics.noisy_function import NoisyFunctionMetric\n", - "from ax.modelbridge.generation_strategy import GenerationStep, GenerationStrategy\n", - "from ax.modelbridge.registry import Generators\n", - "from ax.models.torch.botorch_modular.sebo import SEBOAcquisition\n", - "from ax.models.torch.botorch_modular.surrogate import Surrogate\n", - "from ax.runners.synthetic import SyntheticRunner\n", - "from ax.service.ax_client import AxClient, ObjectiveProperties\n", - "from botorch.acquisition.multi_objective import qNoisyExpectedHypervolumeImprovement\n", - "from botorch.models import SaasFullyBayesianSingleTaskGP, SingleTaskGP\n", - "from pyre_extensions import assert_is_instance" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "%matplotlib inline\n", - "matplotlib.rcParams.update({\"font.size\": 16})\n", - "\n", - "warnings.filterwarnings('ignore')\n", - "SMOKE_TEST = os.environ.get(\"SMOKE_TEST\")\n", - "\n", - "torch.manual_seed(12345) # To always get the same Sobol points\n", - "tkwargs = {\n", - " \"dtype\": torch.double,\n", - " \"device\": torch.device(\"cuda\" if torch.cuda.is_available() else \"cpu\"),\n", - "}" - ] - }, - { - "cell_type": "markdown", - "metadata": { - "customInput": null, - "originalKey": "7f07af01-ad58-4cfb-beca-f624310d278d", - "showInput": false - }, - "source": [ - "# Demo of using Developer API" - ] - }, - { - "cell_type": "markdown", - "metadata": { - "customInput": null, - "originalKey": "c8a27a2f-1120-4894-9302-48bfde402268", - "showInput": false - }, - "source": [ - "## Problem Setup \n", - "\n", - "In this simple experiment we use the Branin function embedded in a 10-dimensional space. Additional resources:\n", - "- To set up a custom metric for your problem, refer to the dedicated section of the Developer API tutorial: https://ax.dev/tutorials/gpei_hartmann_developer.html#8.-Defining-custom-metrics.\n", - "- To avoid needing to setup up custom metrics by Ax Service API: https://ax.dev/tutorials/gpei_hartmann_service.html." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "collapsed": false, - "customInput": null, - "executionStartTime": 1689117390036, - "executionStopTime": 1689117390038, - "jupyter": { - "outputs_hidden": false + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false, + "customOutput": null, + "executionStartTime": 1689117385062, + "executionStopTime": 1689117389874, + "jupyter": { + "outputs_hidden": false + }, + "originalKey": "cea96143-019a-41c1-a388-545f48992db9", + "requestMsgId": "c2c22a5d-aee0-4a1e-98d9-b360aa1851ff", + "showInput": true + }, + "outputs": [], + "source": [ + "import math\n", + "import os\n", + "import warnings\n", + "\n", + "import matplotlib\n", + "import matplotlib.pyplot as plt\n", + "\n", + "import numpy as np\n", + "import torch\n", + "from ax import Data, Experiment, ParameterType, RangeParameter, SearchSpace\n", + "from ax.core.objective import Objective\n", + "from ax.core.optimization_config import OptimizationConfig\n", + "from ax.metrics.noisy_function import NoisyFunctionMetric\n", + "from ax.generation_strategy.generation_strategy import GenerationStep, GenerationStrategy\n", + "from ax.modelbridge.registry import Generators\n", + "from ax.models.torch.botorch_modular.sebo import SEBOAcquisition\n", + "from ax.models.torch.botorch_modular.surrogate import Surrogate\n", + "from ax.runners.synthetic import SyntheticRunner\n", + "from ax.service.ax_client import AxClient, ObjectiveProperties\n", + "from botorch.acquisition.multi_objective import qNoisyExpectedHypervolumeImprovement\n", + "from botorch.models import SaasFullyBayesianSingleTaskGP, SingleTaskGP\n", + "from pyre_extensions import assert_is_instance" + ] }, - "originalKey": "e91fc838-9f47-44f1-99ac-4477df208566", - "requestMsgId": "1591e6b0-fa9b-4b9f-be72-683dccbe923a", - "showInput": true - }, - "outputs": [], - "source": [ - "aug_dim = 8 \n", - "\n", - "# evaluation function \n", - "def branin_augment(x_vec, augment_dim):\n", - " assert len(x_vec) == augment_dim\n", - " x1, x2 = (\n", - " 15 * x_vec[0] - 5,\n", - " 15 * x_vec[1],\n", - " ) # Only dimensions 0 and augment_dim-1 affect the value of the function\n", - " t1 = x2 - 5.1 / (4 * math.pi**2) * x1**2 + 5 / math.pi * x1 - 6\n", - " t2 = 10 * (1 - 1 / (8 * math.pi)) * np.cos(x1)\n", - " return t1**2 + t2 + 10" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "collapsed": false, - "customInput": null, - "customOutput": null, - "executionStartTime": 1689117390518, - "executionStopTime": 1689117390540, - "jupyter": { - "outputs_hidden": false + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "%matplotlib inline\n", + "matplotlib.rcParams.update({\"font.size\": 16})\n", + "\n", + "warnings.filterwarnings('ignore')\n", + "SMOKE_TEST = os.environ.get(\"SMOKE_TEST\")\n", + "\n", + "torch.manual_seed(12345) # To always get the same Sobol points\n", + "tkwargs = {\n", + " \"dtype\": torch.double,\n", + " \"device\": torch.device(\"cuda\" if torch.cuda.is_available() else \"cpu\"),\n", + "}" + ] }, - "originalKey": "850830c6-509f-4087-bce8-da0be4fd48ef", - "requestMsgId": "56726053-205d-4d7e-b1b5-1a76324188ee", - "showInput": true - }, - "outputs": [], - "source": [ - "class AugBraninMetric(NoisyFunctionMetric):\n", - " def f(self, x: np.ndarray) -> float:\n", - " return assert_is_instance(branin_augment(x_vec=x, augment_dim=aug_dim), float)\n", - "\n", - "\n", - "# Create search space in Ax \n", - "search_space = SearchSpace(\n", - " parameters=[\n", - " RangeParameter(\n", - " name=f\"x{i}\",\n", - " parameter_type=ParameterType.FLOAT, \n", - " lower=0.0, upper=1.0\n", - " )\n", - " for i in range(aug_dim)\n", - " ]\n", - ")" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "collapsed": false, - "customInput": null, - "executionStartTime": 1689117391899, - "executionStopTime": 1689117391915, - "jupyter": { - "outputs_hidden": false + { + "cell_type": "markdown", + "metadata": { + "customInput": null, + "originalKey": "7f07af01-ad58-4cfb-beca-f624310d278d", + "showInput": false + }, + "source": [ + "# Demo of using Developer API" + ] }, - "originalKey": "d039b709-67c6-475a-96ce-290f869e0f88", - "requestMsgId": "3e23ed64-7d10-430b-b790-91a0c7cf72fe", - "showInput": true - }, - "outputs": [], - "source": [ - "# Create optimization goals \n", - "optimization_config = OptimizationConfig(\n", - " objective=Objective(\n", - " metric=AugBraninMetric(\n", - " name=\"objective\",\n", - " param_names=[f\"x{i}\" for i in range(aug_dim)],\n", - " noise_sd=None, # Set noise_sd=None if you want to learn the noise, otherwise it defaults to 1e-6\n", - " ),\n", - " minimize=True,\n", - " )\n", - ")\n", - "\n", - "# Experiment\n", - "experiment = Experiment(\n", - " name=\"sebo_experiment\",\n", - " search_space=search_space,\n", - " optimization_config=optimization_config,\n", - " runner=SyntheticRunner(),\n", - ")\n", - "\n", - "# target sparse point to regularize towards to. Here we set target sparse value being zero for all the parameters. \n", - "target_point = torch.tensor([0 for _ in range(aug_dim)], **tkwargs)" - ] - }, - { - "cell_type": "markdown", - "metadata": { - "customInput": null, - "originalKey": "e57edb00-eafc-4d07-bdb9-e8cf073b4caa", - "showInput": false - }, - "source": [ - "## Run optimization loop" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "collapsed": false, - "customInput": null, - "customOutput": null, - "executionStartTime": 1689117395051, - "executionStopTime": 1689117395069, - "jupyter": { - "outputs_hidden": false + { + "cell_type": "markdown", + "metadata": { + "customInput": null, + "originalKey": "c8a27a2f-1120-4894-9302-48bfde402268", + "showInput": false + }, + "source": [ + "## Problem Setup \n", + "\n", + "In this simple experiment we use the Branin function embedded in a 10-dimensional space. Additional resources:\n", + "- To set up a custom metric for your problem, refer to the dedicated section of the Developer API tutorial: https://ax.dev/tutorials/gpei_hartmann_developer.html#8.-Defining-custom-metrics.\n", + "- To avoid needing to setup up custom metrics by Ax Service API: https://ax.dev/tutorials/gpei_hartmann_service.html." + ] }, - "originalKey": "c4848148-bff5-44a7-9ad5-41e78ccb413c", - "requestMsgId": "8aa87d22-bf89-471f-be9f-7c31f7b8bd62", - "showInput": true - }, - "outputs": [], - "source": [ - "N_INIT = 10\n", - "\n", - "if SMOKE_TEST:\n", - " N_BATCHES = 1\n", - " BATCH_SIZE = 1\n", - " SURROGATE_CLASS = None # Auto-pick SingleTaskGP\n", - "else:\n", - " N_BATCHES = 4\n", - " BATCH_SIZE = 5\n", - " SURROGATE_CLASS = SaasFullyBayesianSingleTaskGP\n", - "\n", - "print(f\"Doing {N_INIT + N_BATCHES * BATCH_SIZE} evaluations\")" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "collapsed": false, - "customInput": null, - "customOutput": null, - "executionStartTime": 1689117396326, - "executionStopTime": 1689117396376, - "jupyter": { - "outputs_hidden": false + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false, + "customInput": null, + "executionStartTime": 1689117390036, + "executionStopTime": 1689117390038, + "jupyter": { + "outputs_hidden": false + }, + "originalKey": "e91fc838-9f47-44f1-99ac-4477df208566", + "requestMsgId": "1591e6b0-fa9b-4b9f-be72-683dccbe923a", + "showInput": true + }, + "outputs": [], + "source": [ + "aug_dim = 8\n", + "\n", + "# evaluation function\n", + "def branin_augment(x_vec, augment_dim):\n", + " assert len(x_vec) == augment_dim\n", + " x1, x2 = (\n", + " 15 * x_vec[0] - 5,\n", + " 15 * x_vec[1],\n", + " ) # Only dimensions 0 and augment_dim-1 affect the value of the function\n", + " t1 = x2 - 5.1 / (4 * math.pi**2) * x1**2 + 5 / math.pi * x1 - 6\n", + " t2 = 10 * (1 - 1 / (8 * math.pi)) * np.cos(x1)\n", + " return t1**2 + t2 + 10" + ] }, - "originalKey": "b260d85f-2797-44e3-840a-86587534b589", - "requestMsgId": "2cc516e3-b16e-40ca-805f-dcd792c92fa6", - "showInput": true - }, - "outputs": [], - "source": [ - "# Initial Sobol points\n", - "sobol = Generators.SOBOL(search_space=experiment.search_space)\n", - "for _ in range(N_INIT):\n", - " experiment.new_trial(sobol.gen(1)).run()" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "collapsed": false, - "customInput": null, - "customOutput": null, - "executionStartTime": 1689117396900, - "executionStopTime": 1689124188959, - "jupyter": { - "outputs_hidden": false + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false, + "customInput": null, + "customOutput": null, + "executionStartTime": 1689117390518, + "executionStopTime": 1689117390540, + "jupyter": { + "outputs_hidden": false + }, + "originalKey": "850830c6-509f-4087-bce8-da0be4fd48ef", + "requestMsgId": "56726053-205d-4d7e-b1b5-1a76324188ee", + "showInput": true + }, + "outputs": [], + "source": [ + "class AugBraninMetric(NoisyFunctionMetric):\n", + " def f(self, x: np.ndarray) -> float:\n", + " return assert_is_instance(branin_augment(x_vec=x, augment_dim=aug_dim), float)\n", + "\n", + "\n", + "# Create search space in Ax\n", + "search_space = SearchSpace(\n", + " parameters=[\n", + " RangeParameter(\n", + " name=f\"x{i}\",\n", + " parameter_type=ParameterType.FLOAT,\n", + " lower=0.0, upper=1.0\n", + " )\n", + " for i in range(aug_dim)\n", + " ]\n", + ")" + ] }, - "originalKey": "7c198035-add2-4717-be27-4fb67c4d1782", - "requestMsgId": "d844fa20-0adf-4ba3-ace5-7253ba678db2", - "showInput": true - }, - "outputs": [], - "source": [ - "data = experiment.fetch_data()\n", - "\n", - "for i in range(N_BATCHES):\n", - "\n", - " model = Generators.BOTORCH_MODULAR(\n", - " experiment=experiment, \n", - " data=data,\n", - " surrogate=Surrogate(botorch_model_class=SURROGATE_CLASS), # can use SAASGP (i.e. SaasFullyBayesianSingleTaskGP) for high-dim cases\n", - " search_space=experiment.search_space,\n", - " botorch_acqf_class=qNoisyExpectedHypervolumeImprovement,\n", - " acquisition_class=SEBOAcquisition,\n", - " acquisition_options={\n", - " \"penalty\": \"L0_norm\", # it can be L0_norm or L1_norm. \n", - " \"target_point\": target_point, \n", - " \"sparsity_threshold\": aug_dim,\n", - " },\n", - " torch_device=tkwargs['device'],\n", - " )\n", - "\n", - " generator_run = model.gen(BATCH_SIZE)\n", - " trial = experiment.new_batch_trial(generator_run=generator_run)\n", - " trial.run()\n", - "\n", - " new_data = trial.fetch_data(metrics=list(experiment.metrics.values()))\n", - " data = Data.from_multiple_data([data, new_data])\n", - " print(f\"Iteration: {i}, Best so far: {data.df['mean'].min():.3f}\")" - ] - }, - { - "cell_type": "markdown", - "metadata": { - "customInput": null, - "originalKey": "7998635d-6750-4825-b93d-c7b61f74c3c5", - "showInput": false - }, - "source": [ - "## Plot sparisty vs objective \n", - "\n", - "Visualize the objective and sparsity trade-offs using SEBO. Each point represent designs along the Pareto frontier found by SEBO. The x-axis corresponds to the number of active parameters used, i.e.\n", - "non-sparse parameters, and the y-axis corresponds the best identified objective values. Based on this, decision-makers balance both simplicity/interpretability of generated policies and optimization performance when deciding which configuration to use." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "collapsed": false, - "customInput": null, - "customOutput": null, - "executionStartTime": 1689124189044, - "executionStopTime": 1689124189182, - "jupyter": { - "outputs_hidden": false + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false, + "customInput": null, + "executionStartTime": 1689117391899, + "executionStopTime": 1689117391915, + "jupyter": { + "outputs_hidden": false + }, + "originalKey": "d039b709-67c6-475a-96ce-290f869e0f88", + "requestMsgId": "3e23ed64-7d10-430b-b790-91a0c7cf72fe", + "showInput": true + }, + "outputs": [], + "source": [ + "# Create optimization goals\n", + "optimization_config = OptimizationConfig(\n", + " objective=Objective(\n", + " metric=AugBraninMetric(\n", + " name=\"objective\",\n", + " param_names=[f\"x{i}\" for i in range(aug_dim)],\n", + " noise_sd=None, # Set noise_sd=None if you want to learn the noise, otherwise it defaults to 1e-6\n", + " ),\n", + " minimize=True,\n", + " )\n", + ")\n", + "\n", + "# Experiment\n", + "experiment = Experiment(\n", + " name=\"sebo_experiment\",\n", + " search_space=search_space,\n", + " optimization_config=optimization_config,\n", + " runner=SyntheticRunner(),\n", + ")\n", + "\n", + "# target sparse point to regularize towards to. Here we set target sparse value being zero for all the parameters.\n", + "target_point = torch.tensor([0 for _ in range(aug_dim)], **tkwargs)" + ] }, - "originalKey": "416ccd12-51a1-4bfe-9e10-436cd88ec6be", - "requestMsgId": "5143ae57-1d0d-4f9d-bc9d-9d151f3e9af0", - "showInput": true - }, - "outputs": [], - "source": [ - "def nnz_exact(x, sparse_point):\n", - " return len(x) - (np.array(x) == np.array(sparse_point)).sum()\n", - "\n", - " \n", - "df = data.df\n", - "df['L0_norm'] = df['arm_name'].apply(lambda d: nnz_exact(list(experiment.arms_by_name[d].parameters.values()), [0 for _ in range(aug_dim)]) )" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "collapsed": false, - "customInput": null, - "customOutput": null, - "executionStartTime": 1689124189219, - "executionStopTime": 1689124189321, - "jupyter": { - "outputs_hidden": false + { + "cell_type": "markdown", + "metadata": { + "customInput": null, + "originalKey": "e57edb00-eafc-4d07-bdb9-e8cf073b4caa", + "showInput": false + }, + "source": [ + "## Run optimization loop" + ] }, - "originalKey": "97b96822-7d7f-4a5d-8458-01ff890d2fde", - "requestMsgId": "34abdf8d-6f0c-48a1-8700-8e2c3075a085", - "showInput": true - }, - "outputs": [], - "source": [ - "result_by_sparsity = {l: df[df.L0_norm <= l]['mean'].min() for l in range(1, aug_dim+1)}\n", - "result_by_sparsity" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "collapsed": false, - "customInput": null, - "customOutput": null, - "executionStartTime": 1689134836494, - "executionStopTime": 1689134837813, - "jupyter": { - "outputs_hidden": false + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false, + "customInput": null, + "customOutput": null, + "executionStartTime": 1689117395051, + "executionStopTime": 1689117395069, + "jupyter": { + "outputs_hidden": false + }, + "originalKey": "c4848148-bff5-44a7-9ad5-41e78ccb413c", + "requestMsgId": "8aa87d22-bf89-471f-be9f-7c31f7b8bd62", + "showInput": true + }, + "outputs": [], + "source": [ + "N_INIT = 10\n", + "\n", + "if SMOKE_TEST:\n", + " N_BATCHES = 1\n", + " BATCH_SIZE = 1\n", + " SURROGATE_CLASS = None # Auto-pick SingleTaskGP\n", + "else:\n", + " N_BATCHES = 4\n", + " BATCH_SIZE = 5\n", + " SURROGATE_CLASS = SaasFullyBayesianSingleTaskGP\n", + "\n", + "print(f\"Doing {N_INIT + N_BATCHES * BATCH_SIZE} evaluations\")" + ] }, - "originalKey": "7193e2b0-e192-439a-b0d0-08a2029f64ca", - "requestMsgId": "f095d820-55e0-4201-8e3a-77f17b2155f1", - "showInput": true - }, - "outputs": [], - "source": [ - "fig, ax = plt.subplots(figsize=(8, 6))\n", - "ax.plot(list(result_by_sparsity.keys()), list(result_by_sparsity.values()), '.b-', label=\"sebo\", markersize=10)\n", - "ax.grid(True)\n", - "ax.set_title(f\"Branin, D={aug_dim}\", fontsize=20)\n", - "ax.set_xlabel(\"Number of active parameters\", fontsize=20)\n", - "ax.set_ylabel(\"Best value found\", fontsize=20)\n", - "# ax.legend(fontsize=18)\n", - "plt.show()" - ] - }, - { - "cell_type": "markdown", - "metadata": { - "customInput": null, - "originalKey": "1ba68dc9-d60b-4b39-8e58-ea9bdc06b44c", - "showInput": false - }, - "source": [ - "# Demo of Using GenerationStrategy and Service API \n", - "\n", - "Please check [Service API tutorial](https://ax.dev/tutorials/gpei_hartmann_service.html) for more detailed information. " - ] - }, - { - "cell_type": "markdown", - "metadata": { - "customInput": null, - "originalKey": "45e5586c-55eb-4908-aa73-bca4ee883b56", - "showInput": false - }, - "source": [ - "## Create `GenerationStrategy`" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "collapsed": false, - "customInput": null, - "executionStartTime": 1689124192972, - "executionStopTime": 1689124192975, - "jupyter": { - "outputs_hidden": false + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false, + "customInput": null, + "customOutput": null, + "executionStartTime": 1689117396326, + "executionStopTime": 1689117396376, + "jupyter": { + "outputs_hidden": false + }, + "originalKey": "b260d85f-2797-44e3-840a-86587534b589", + "requestMsgId": "2cc516e3-b16e-40ca-805f-dcd792c92fa6", + "showInput": true + }, + "outputs": [], + "source": [ + "# Initial Sobol points\n", + "sobol = Generators.SOBOL(search_space=experiment.search_space)\n", + "for _ in range(N_INIT):\n", + " experiment.new_trial(sobol.gen(1)).run()" + ] }, - "originalKey": "7c0bfe37-8f1f-4999-8833-42ffb2569c04", - "requestMsgId": "bbd9058a-709e-4262-abe1-720d37e8786f", - "showInput": true - }, - "outputs": [], - "source": [ - "gs = GenerationStrategy(\n", - " name=\"SEBO_L0\",\n", - " steps=[\n", - " GenerationStep( # Initialization step\n", - " model=Generators.SOBOL, \n", - " num_trials=N_INIT,\n", - " ),\n", - " GenerationStep( # BayesOpt step\n", - " model=Generators.BOTORCH_MODULAR,\n", - " # No limit on how many generator runs will be produced\n", - " num_trials=-1,\n", - " model_kwargs={ # Kwargs to pass to `BoTorchModel.__init__`\n", - " \"surrogate\": Surrogate(botorch_model_class=SURROGATE_CLASS),\n", - " \"acquisition_class\": SEBOAcquisition,\n", - " \"botorch_acqf_class\": qNoisyExpectedHypervolumeImprovement,\n", - " \"acquisition_options\": {\n", - " \"penalty\": \"L0_norm\", # it can be L0_norm or L1_norm.\n", - " \"target_point\": target_point, \n", - " \"sparsity_threshold\": aug_dim,\n", - " },\n", - " },\n", - " )\n", - " ]\n", - ")" - ] - }, - { - "cell_type": "markdown", - "metadata": { - "customInput": null, - "originalKey": "e4911bc6-32cb-42a5-908f-57f3f04e58e5", - "showInput": false - }, - "source": [ - "## Initialize client and set up experiment" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "collapsed": false, - "customInput": null, - "executionStartTime": 1689124192979, - "executionStopTime": 1689124192984, - "jupyter": { - "outputs_hidden": false + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false, + "customInput": null, + "customOutput": null, + "executionStartTime": 1689117396900, + "executionStopTime": 1689124188959, + "jupyter": { + "outputs_hidden": false + }, + "originalKey": "7c198035-add2-4717-be27-4fb67c4d1782", + "requestMsgId": "d844fa20-0adf-4ba3-ace5-7253ba678db2", + "showInput": true + }, + "outputs": [], + "source": [ + "data = experiment.fetch_data()\n", + "\n", + "for i in range(N_BATCHES):\n", + "\n", + " model = Generators.BOTORCH_MODULAR(\n", + " experiment=experiment,\n", + " data=data,\n", + " surrogate=Surrogate(botorch_model_class=SURROGATE_CLASS), # can use SAASGP (i.e. SaasFullyBayesianSingleTaskGP) for high-dim cases\n", + " search_space=experiment.search_space,\n", + " botorch_acqf_class=qNoisyExpectedHypervolumeImprovement,\n", + " acquisition_class=SEBOAcquisition,\n", + " acquisition_options={\n", + " \"penalty\": \"L0_norm\", # it can be L0_norm or L1_norm.\n", + " \"target_point\": target_point,\n", + " \"sparsity_threshold\": aug_dim,\n", + " },\n", + " torch_device=tkwargs['device'],\n", + " )\n", + "\n", + " generator_run = model.gen(BATCH_SIZE)\n", + " trial = experiment.new_batch_trial(generator_run=generator_run)\n", + " trial.run()\n", + "\n", + " new_data = trial.fetch_data(metrics=list(experiment.metrics.values()))\n", + " data = Data.from_multiple_data([data, new_data])\n", + " print(f\"Iteration: {i}, Best so far: {data.df['mean'].min():.3f}\")" + ] }, - "originalKey": "47938102-0613-4b37-acb2-9f1f5f3fe6b1", - "requestMsgId": "38b4b17c-6aae-43b8-aa58-2df045f522fe", - "showInput": true - }, - "outputs": [], - "source": [ - "ax_client = AxClient(generation_strategy=gs)\n", - "\n", - "experiment_parameters = [\n", - " {\n", - " \"name\": f\"x{i}\",\n", - " \"type\": \"range\",\n", - " \"bounds\": [0, 1],\n", - " \"value_type\": \"float\",\n", - " \"log_scale\": False,\n", - " }\n", - " for i in range(aug_dim)\n", - "]\n", - "\n", - "objective_metrics = {\n", - " \"objective\": ObjectiveProperties(minimize=False, threshold=-10),\n", - "}\n", - "\n", - "ax_client.create_experiment(\n", - " name=\"branin_augment_sebo_experiment\",\n", - " parameters=experiment_parameters,\n", - " objectives=objective_metrics,\n", - ")" - ] - }, - { - "cell_type": "markdown", - "metadata": { - "customInput": null, - "originalKey": "6a7942e4-9727-43d9-8d8d-c327d38c2373", - "showInput": false - }, - "source": [ - "## Define evaluation function " - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "collapsed": false, - "customInput": null, - "executionStartTime": 1689124192990, - "executionStopTime": 1689124192992, - "jupyter": { - "outputs_hidden": false + { + "cell_type": "markdown", + "metadata": { + "customInput": null, + "originalKey": "7998635d-6750-4825-b93d-c7b61f74c3c5", + "showInput": false + }, + "source": [ + "## Plot sparisty vs objective \n", + "\n", + "Visualize the objective and sparsity trade-offs using SEBO. Each point represent designs along the Pareto frontier found by SEBO. The x-axis corresponds to the number of active parameters used, i.e.\n", + "non-sparse parameters, and the y-axis corresponds the best identified objective values. Based on this, decision-makers balance both simplicity/interpretability of generated policies and optimization performance when deciding which configuration to use." + ] }, - "originalKey": "4e2994ff-36ac-4d48-a789-3d0398e1e856", - "requestMsgId": "8f74a775-a8ce-462d-993c-5c9291c748b9", - "showInput": true - }, - "outputs": [], - "source": [ - "def evaluation(parameters):\n", - " # put parameters into 1-D array\n", - " x = [parameters.get(param[\"name\"]) for param in experiment_parameters]\n", - " res = branin_augment(x_vec=x, augment_dim=aug_dim)\n", - " eval_res = {\n", - " # flip the sign to maximize\n", - " \"objective\": (res * -1, 0.0),\n", - " }\n", - " return eval_res" - ] - }, - { - "cell_type": "markdown", - "metadata": { - "customInput": null, - "originalKey": "4597531b-7ac8-4dd0-94c4-836672e0f4c4", - "showInput": false - }, - "source": [ - "## Run optimization loop\n", - "\n", - "Running only 1 BO trial for demonstration. " - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "collapsed": false, - "customInput": null, - "executionStartTime": 1689124193044, - "executionStopTime": 1689130398208, - "jupyter": { - "outputs_hidden": false + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false, + "customInput": null, + "customOutput": null, + "executionStartTime": 1689124189044, + "executionStopTime": 1689124189182, + "jupyter": { + "outputs_hidden": false + }, + "originalKey": "416ccd12-51a1-4bfe-9e10-436cd88ec6be", + "requestMsgId": "5143ae57-1d0d-4f9d-bc9d-9d151f3e9af0", + "showInput": true + }, + "outputs": [], + "source": [ + "def nnz_exact(x, sparse_point):\n", + " return len(x) - (np.array(x) == np.array(sparse_point)).sum()\n", + "\n", + "\n", + "df = data.df\n", + "df['L0_norm'] = df['arm_name'].apply(lambda d: nnz_exact(list(experiment.arms_by_name[d].parameters.values()), [0 for _ in range(aug_dim)]) )" + ] }, - "originalKey": "bc7accb2-48a2-4c88-a932-7c79ec81075a", - "requestMsgId": "f054e5b1-12eb-459b-a508-6944baf82dfb", - "showInput": true - }, - "outputs": [], - "source": [ - "for _ in range(N_INIT + 1): \n", - " parameters, trial_index = ax_client.get_next_trial()\n", - " res = evaluation(parameters)\n", - " ax_client.complete_trial(trial_index=trial_index, raw_data=res)" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [] - } - ], - "metadata": { - "fileHeader": "", - "kernelspec": { - "display_name": "Python 3 (ipykernel)", - "language": "python", - "name": "python3" - }, - "language_info": { - "codemirror_mode": { - "name": "ipython", - "version": 3 - }, - "file_extension": ".py", - "mimetype": "text/x-python", - "name": "python", - "nbconvert_exporter": "python", - "pygments_lexer": "ipython3", - "version": "3.10.16" + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false, + "customInput": null, + "customOutput": null, + "executionStartTime": 1689124189219, + "executionStopTime": 1689124189321, + "jupyter": { + "outputs_hidden": false + }, + "originalKey": "97b96822-7d7f-4a5d-8458-01ff890d2fde", + "requestMsgId": "34abdf8d-6f0c-48a1-8700-8e2c3075a085", + "showInput": true + }, + "outputs": [], + "source": [ + "result_by_sparsity = {l: df[df.L0_norm <= l]['mean'].min() for l in range(1, aug_dim+1)}\n", + "result_by_sparsity" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false, + "customInput": null, + "customOutput": null, + "executionStartTime": 1689134836494, + "executionStopTime": 1689134837813, + "jupyter": { + "outputs_hidden": false + }, + "originalKey": "7193e2b0-e192-439a-b0d0-08a2029f64ca", + "requestMsgId": "f095d820-55e0-4201-8e3a-77f17b2155f1", + "showInput": true + }, + "outputs": [], + "source": [ + "fig, ax = plt.subplots(figsize=(8, 6))\n", + "ax.plot(list(result_by_sparsity.keys()), list(result_by_sparsity.values()), '.b-', label=\"sebo\", markersize=10)\n", + "ax.grid(True)\n", + "ax.set_title(f\"Branin, D={aug_dim}\", fontsize=20)\n", + "ax.set_xlabel(\"Number of active parameters\", fontsize=20)\n", + "ax.set_ylabel(\"Best value found\", fontsize=20)\n", + "# ax.legend(fontsize=18)\n", + "plt.show()" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "customInput": null, + "originalKey": "1ba68dc9-d60b-4b39-8e58-ea9bdc06b44c", + "showInput": false + }, + "source": [ + "# Demo of Using GenerationStrategy and Service API \n", + "\n", + "Please check [Service API tutorial](https://ax.dev/tutorials/gpei_hartmann_service.html) for more detailed information. " + ] + }, + { + "cell_type": "markdown", + "metadata": { + "customInput": null, + "originalKey": "45e5586c-55eb-4908-aa73-bca4ee883b56", + "showInput": false + }, + "source": [ + "## Create `GenerationStrategy`" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false, + "customInput": null, + "executionStartTime": 1689124192972, + "executionStopTime": 1689124192975, + "jupyter": { + "outputs_hidden": false + }, + "originalKey": "7c0bfe37-8f1f-4999-8833-42ffb2569c04", + "requestMsgId": "bbd9058a-709e-4262-abe1-720d37e8786f", + "showInput": true + }, + "outputs": [], + "source": [ + "gs = GenerationStrategy(\n", + " name=\"SEBO_L0\",\n", + " steps=[\n", + " GenerationStep( # Initialization step\n", + " model=Generators.SOBOL,\n", + " num_trials=N_INIT,\n", + " ),\n", + " GenerationStep( # BayesOpt step\n", + " model=Generators.BOTORCH_MODULAR,\n", + " # No limit on how many generator runs will be produced\n", + " num_trials=-1,\n", + " model_kwargs={ # Kwargs to pass to `BoTorchModel.__init__`\n", + " \"surrogate\": Surrogate(botorch_model_class=SURROGATE_CLASS),\n", + " \"acquisition_class\": SEBOAcquisition,\n", + " \"botorch_acqf_class\": qNoisyExpectedHypervolumeImprovement,\n", + " \"acquisition_options\": {\n", + " \"penalty\": \"L0_norm\", # it can be L0_norm or L1_norm.\n", + " \"target_point\": target_point,\n", + " \"sparsity_threshold\": aug_dim,\n", + " },\n", + " },\n", + " )\n", + " ]\n", + ")" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "customInput": null, + "originalKey": "e4911bc6-32cb-42a5-908f-57f3f04e58e5", + "showInput": false + }, + "source": [ + "## Initialize client and set up experiment" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false, + "customInput": null, + "executionStartTime": 1689124192979, + "executionStopTime": 1689124192984, + "jupyter": { + "outputs_hidden": false + }, + "originalKey": "47938102-0613-4b37-acb2-9f1f5f3fe6b1", + "requestMsgId": "38b4b17c-6aae-43b8-aa58-2df045f522fe", + "showInput": true + }, + "outputs": [], + "source": [ + "ax_client = AxClient(generation_strategy=gs)\n", + "\n", + "experiment_parameters = [\n", + " {\n", + " \"name\": f\"x{i}\",\n", + " \"type\": \"range\",\n", + " \"bounds\": [0, 1],\n", + " \"value_type\": \"float\",\n", + " \"log_scale\": False,\n", + " }\n", + " for i in range(aug_dim)\n", + "]\n", + "\n", + "objective_metrics = {\n", + " \"objective\": ObjectiveProperties(minimize=False, threshold=-10),\n", + "}\n", + "\n", + "ax_client.create_experiment(\n", + " name=\"branin_augment_sebo_experiment\",\n", + " parameters=experiment_parameters,\n", + " objectives=objective_metrics,\n", + ")" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "customInput": null, + "originalKey": "6a7942e4-9727-43d9-8d8d-c327d38c2373", + "showInput": false + }, + "source": [ + "## Define evaluation function " + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false, + "customInput": null, + "executionStartTime": 1689124192990, + "executionStopTime": 1689124192992, + "jupyter": { + "outputs_hidden": false + }, + "originalKey": "4e2994ff-36ac-4d48-a789-3d0398e1e856", + "requestMsgId": "8f74a775-a8ce-462d-993c-5c9291c748b9", + "showInput": true + }, + "outputs": [], + "source": [ + "def evaluation(parameters):\n", + " # put parameters into 1-D array\n", + " x = [parameters.get(param[\"name\"]) for param in experiment_parameters]\n", + " res = branin_augment(x_vec=x, augment_dim=aug_dim)\n", + " eval_res = {\n", + " # flip the sign to maximize\n", + " \"objective\": (res * -1, 0.0),\n", + " }\n", + " return eval_res" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "customInput": null, + "originalKey": "4597531b-7ac8-4dd0-94c4-836672e0f4c4", + "showInput": false + }, + "source": [ + "## Run optimization loop\n", + "\n", + "Running only 1 BO trial for demonstration. " + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false, + "customInput": null, + "executionStartTime": 1689124193044, + "executionStopTime": 1689130398208, + "jupyter": { + "outputs_hidden": false + }, + "originalKey": "bc7accb2-48a2-4c88-a932-7c79ec81075a", + "requestMsgId": "f054e5b1-12eb-459b-a508-6944baf82dfb", + "showInput": true + }, + "outputs": [], + "source": [ + "for _ in range(N_INIT + 1):\n", + " parameters, trial_index = ax_client.get_next_trial()\n", + " res = evaluation(parameters)\n", + " ax_client.complete_trial(trial_index=trial_index, raw_data=res)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [] + } + ], + "metadata": { + "fileHeader": "", + "fileUid": "33f37456-c9e2-4251-a6a1-1dcefc6e6d74", + "isAdHoc": false, + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.10.16" + } } - }, - "nbformat": 4, - "nbformat_minor": 4 }