ax.storage¶

ax.storage.json_store.decoder module¶

ax.storage.json_store.decoder.data_from_json(data_by_trial_json)[source]¶

Load Ax Data from JSON.

ax.storage.json_store.decoder.experiment_from_json(object_json)[source]¶

Load Ax Experiment from JSON.

Return type

Experiment

ax.storage.json_store.decoder.generation_strategy_from_json(generation_strategy_json)[source]¶

Load generation strategy from JSON.

Return type

GenerationStrategy

ax.storage.json_store.decoder.generator_run_from_json(object_json)[source]¶

Load Ax GeneratorRun from JSON.

Return type

GeneratorRun

ax.storage.json_store.decoder.object_from_json(object_json)[source]¶

Recursively load objects from a JSON-serializable dictionary.

Return type

Any

ax.storage.json_store.decoder.parameter_constraints_from_json(parameter_constraint_json, parameters)[source]¶

Load ParameterConstraints from JSON.

Order and SumConstraint are tied to a search space, and require that SearchSpace’s parameters to be passed in for decoding.

Parameters

• parameter_constraint_json (List[Dict[str, Any]]) – JSON representation of parameter constraints.

• parameters (List[Parameter]) – Parameter definitions for decoding via parameter names.

Returns

Python classes for parameter constraints.

Return type

parameter_constraints

ax.storage.json_store.decoder.search_space_from_json(search_space_json)[source]¶

Load a SearchSpace from JSON.

This function is necessary due to the coupled loading of SearchSpace and parameter constraints.

Return type

SearchSpace

ax.storage.json_store.decoder.simple_experiment_from_json(object_json)[source]¶

Load AE SimpleExperiment from JSON.

Return type

SimpleExperiment

ax.storage.json_store.decoder.transform_type_from_json(object_json)[source]¶

Load the transform type from JSON.

Return type

Type[Transform]

ax.storage.json_store.decoder.trials_from_json(experiment, trials_json)[source]¶

Load Ax Trials from JSON.

Return type

Dict[int, BaseTrial]

ax.storage.json_store.decoders module¶

ax.storage.json_store.decoders.batch_trial_from_json(experiment, index, trial_type, status, time_created, time_completed, time_staged, time_run_started, abandoned_reason, run_metadata, generator_run_structs, runner, abandoned_arms_metadata, num_arms_created, status_quo, status_quo_weight)[source]¶

Load Ax BatchTrial from JSON.

Other classes don’t need explicit deserializers, because we can just use their constructors (see decoder.py). However, the constructor for Batch does not allow us to exactly recreate an existing object.

Return type

BatchTrial

ax.storage.json_store.decoders.trial_from_json(experiment, index, trial_type, status, time_created, time_completed, time_staged, time_run_started, abandoned_reason, run_metadata, generator_run, runner, num_arms_created)[source]¶

Load Ax trial from JSON.

Other classes don’t need explicit deserializers, because we can just use their constructors (see decoder.py). However, the constructor for Trial does not allow us to exactly recreate an existing object.

Return type

Trial

ax.storage.json_store.encoder module¶

ax.storage.json_store.encoder.object_to_json(object)[source]¶

Convert an Ax object to a JSON-serializable dictionary.

The root node passed to this function should always be an instance of a core Ax class or a JSON-compatible python builtin. The sub-fields of the input will then be recursively passed to this function.

e.g. if we pass an instance of Experiment, we will first fall through to the line object_dict = ENCODER_REGISTRY[_type](object), which will convert the Experiment to a (shallow) dictionary, where search subfield remains “unconverted”, i.e.: {“name”: <name: string>, “search_space”: <search space: SearchSpace>}. We then pass each item of the dictionary back into this function to recursively convert the entire object.

Return type

Any

ax.storage.json_store.encoders module¶

ax.storage.json_store.encoders.arm_to_dict(arm)[source]¶

Convert Ax arm to a dictionary.

Return type

Dict[str, Any]

ax.storage.json_store.encoders.batch_to_dict(batch)[source]¶

Convert Ax batch to a dictionary.

Return type

Dict[str, Any]

ax.storage.json_store.encoders.choice_parameter_to_dict(parameter)[source]¶

Convert Ax choice parameter to a dictionary.

Return type

Dict[str, Any]

ax.storage.json_store.encoders.data_to_dict(data)[source]¶

Convert Ax data to a dictionary.

Return type

Dict[str, Any]

ax.storage.json_store.encoders.experiment_to_dict(experiment)[source]¶

Convert Ax experiment to a dictionary.

Return type

Dict[str, Any]

ax.storage.json_store.encoders.fixed_parameter_to_dict(parameter)[source]¶

Convert Ax fixed parameter to a dictionary.

Return type

Dict[str, Any]

ax.storage.json_store.encoders.generation_strategy_to_dict(generation_strategy)[source]¶

Return type

Dict[str, Any]

ax.storage.json_store.encoders.generator_run_to_dict(generator_run)[source]¶

Convert Ax generator run to a dictionary.

Return type

Dict[str, Any]

ax.storage.json_store.encoders.metric_to_dict(metric)[source]¶

Convert Ax metric to a dictionary.

Return type

Dict[str, Any]

ax.storage.json_store.encoders.objective_to_dict(objective)[source]¶

Convert Ax objective to a dictionary.

Return type

Dict[str, Any]

ax.storage.json_store.encoders.optimization_config_to_dict(optimization_config)[source]¶

Convert Ax optimization config to a dictionary.

Return type

Dict[str, Any]

ax.storage.json_store.encoders.order_parameter_constraint_to_dict(parameter_constraint)[source]¶

Convert Ax order parameter constraint to a dictionary.

Return type

Dict[str, Any]

ax.storage.json_store.encoders.outcome_constraint_to_dict(outcome_constraint)[source]¶

Convert Ax outcome constraint to a dictionary.

Return type

Dict[str, Any]

ax.storage.json_store.encoders.parameter_constraint_to_dict(parameter_constraint)[source]¶

Convert Ax sum parameter constraint to a dictionary.

Return type

Dict[str, Any]

ax.storage.json_store.encoders.range_parameter_to_dict(parameter)[source]¶

Convert Ax range parameter to a dictionary.

Return type

Dict[str, Any]

ax.storage.json_store.encoders.runner_to_dict(runner)[source]¶

Convert Ax synthetic runner to a dictionary.

Return type

Dict[str, Any]

ax.storage.json_store.encoders.search_space_to_dict(search_space)[source]¶

Convert Ax search space to a dictionary.

Return type

Dict[str, Any]

ax.storage.json_store.encoders.simple_experiment_to_dict(experiment)[source]¶

Convert AE simple experiment to a dictionary.

Return type

Dict[str, Any]

ax.storage.json_store.encoders.sum_parameter_constraint_to_dict(parameter_constraint)[source]¶

Convert Ax sum parameter constraint to a dictionary.

Return type

Dict[str, Any]

ax.storage.json_store.encoders.transform_type_to_dict(transform_type)[source]¶

Convert a transform class to a dictionary.

Return type

Dict[str, Any]

ax.storage.json_store.encoders.trial_to_dict(trial)[source]¶

Convert Ax trial to a dictionary.

Return type

Dict[str, Any]

ax.storage.json_store.load module¶

ax.storage.json_store.load.load_experiment(filepath)[source]¶

Load experiment from file.

1. Read file.

2. Convert dictionary to Ax experiment instance.

Return type

Experiment

ax.storage.json_store.registry module¶

ax.storage.json_store.registry.DECODER_REGISTRY = {'AbandonedArm': <class 'ax.core.batch_trial.AbandonedArm'>, 'Arm': <class 'ax.core.arm.Arm'>, 'BatchTrial': <class 'ax.core.batch_trial.BatchTrial'>, 'BraninMetric': <class 'ax.metrics.branin.BraninMetric'>, 'ChoiceParameter': <class 'ax.core.parameter.ChoiceParameter'>, 'ComparisonOp': <enum 'ComparisonOp'>, 'Data': <class 'ax.core.data.Data'>, 'DomainType': <enum 'DomainType'>, 'Experiment': <class 'ax.core.experiment.Experiment'>, 'FactorialMetric': <class 'ax.metrics.factorial.FactorialMetric'>, 'FixedParameter': <class 'ax.core.parameter.FixedParameter'>, 'GenerationStep': <class 'ax.modelbridge.generation_strategy.GenerationStep'>, 'GenerationStrategy': <class 'ax.modelbridge.generation_strategy.GenerationStrategy'>, 'GeneratorRun': <class 'ax.core.generator_run.GeneratorRun'>, 'GeneratorRunStruct': <class 'ax.core.batch_trial.GeneratorRunStruct'>, 'Hartmann6Metric': <class 'ax.metrics.hartmann6.Hartmann6Metric'>, 'L2NormMetric': <class 'ax.metrics.l2norm.L2NormMetric'>, 'Metric': <class 'ax.core.metric.Metric'>, 'Models': <enum 'Models'>, 'NegativeBraninMetric': <class 'ax.metrics.branin.NegativeBraninMetric'>, 'NoisyFunctionMetric': <class 'ax.metrics.noisy_function.NoisyFunctionMetric'>, 'Objective': <class 'ax.core.objective.Objective'>, 'OptimizationConfig': <class 'ax.core.optimization_config.OptimizationConfig'>, 'OrderConstraint': <class 'ax.core.parameter_constraint.OrderConstraint'>, 'OutcomeConstraint': <class 'ax.core.outcome_constraint.OutcomeConstraint'>, 'ParameterConstraint': <class 'ax.core.parameter_constraint.ParameterConstraint'>, 'ParameterConstraintType': <enum 'ParameterConstraintType'>, 'ParameterType': <enum 'ParameterType'>, 'RangeParameter': <class 'ax.core.parameter.RangeParameter'>, 'SearchSpace': <class 'ax.core.search_space.SearchSpace'>, 'SimpleExperiment': <class 'ax.core.simple_experiment.SimpleExperiment'>, 'SumConstraint': <class 'ax.core.parameter_constraint.SumConstraint'>, 'SyntheticRunner': <class 'ax.runners.synthetic.SyntheticRunner'>, 'Trial': <class 'ax.core.trial.Trial'>, 'TrialStatus': <enum 'TrialStatus'>, 'Type[Transform]': typing.Type[ax.modelbridge.transforms.base.Transform]}¶

ax.storage.json_store.registry.ENCODER_REGISTRY = {<class 'ax.core.arm.Arm'>: <function arm_to_dict>, <class 'ax.core.batch_trial.BatchTrial'>: <function batch_to_dict>, <class 'ax.metrics.branin.BraninMetric'>: <function metric_to_dict>, <class 'ax.core.parameter.ChoiceParameter'>: <function choice_parameter_to_dict>, <class 'ax.core.data.Data'>: <function data_to_dict>, <class 'ax.core.experiment.Experiment'>: <function experiment_to_dict>, <class 'ax.metrics.factorial.FactorialMetric'>: <function metric_to_dict>, <class 'ax.core.parameter.FixedParameter'>: <function fixed_parameter_to_dict>, <class 'ax.modelbridge.generation_strategy.GenerationStrategy'>: <function generation_strategy_to_dict>, <class 'ax.core.generator_run.GeneratorRun'>: <function generator_run_to_dict>, <class 'ax.metrics.hartmann6.Hartmann6Metric'>: <function metric_to_dict>, <class 'ax.metrics.l2norm.L2NormMetric'>: <function metric_to_dict>, <class 'ax.core.metric.Metric'>: <function metric_to_dict>, <class 'ax.metrics.branin.NegativeBraninMetric'>: <function metric_to_dict>, <class 'ax.metrics.noisy_function.NoisyFunctionMetric'>: <function metric_to_dict>, <class 'ax.core.objective.Objective'>: <function objective_to_dict>, <class 'ax.core.optimization_config.OptimizationConfig'>: <function optimization_config_to_dict>, <class 'ax.core.parameter_constraint.OrderConstraint'>: <function order_parameter_constraint_to_dict>, <class 'ax.core.outcome_constraint.OutcomeConstraint'>: <function outcome_constraint_to_dict>, <class 'ax.core.parameter_constraint.ParameterConstraint'>: <function parameter_constraint_to_dict>, <class 'ax.core.parameter.RangeParameter'>: <function range_parameter_to_dict>, <class 'ax.core.search_space.SearchSpace'>: <function search_space_to_dict>, <class 'ax.core.simple_experiment.SimpleExperiment'>: <function simple_experiment_to_dict>, <class 'ax.core.parameter_constraint.SumConstraint'>: <function sum_parameter_constraint_to_dict>, <class 'ax.runners.synthetic.SyntheticRunner'>: <function runner_to_dict>, <class 'ax.core.trial.Trial'>: <function trial_to_dict>, typing.Type[ax.modelbridge.transforms.base.Transform]: <function transform_type_to_dict>}¶

ax.storage.json_store.save module¶

ax.storage.json_store.save.save_experiment(experiment, filepath)[source]¶

Save experiment to file.

1. Convert Ax experiment to JSON-serializable dictionary.

2. Write to file.

Return type

None

ax.storage.sqa_store.base_decoder module¶

class ax.storage.sqa_store.decoder.Decoder(config)[source]¶

Bases: object

Class that contains methods for loading an Ax experiment from SQLAlchemy.

Instantiate with an instance of Config to customize the functionality. For even more flexibility, create a subclass.

config¶

Metadata needed to save and load an experiment to SQLAlchemy.

abandoned_arm_from_sqa(abandoned_arm_sqa)[source]¶

Convert SQLAlchemy AbandonedArm to Ax AbandonedArm.

Return type

AbandonedArm

arm_from_sqa(arm_sqa)[source]¶

Convert SQLAlchemy Arm to Ax Arm.

Return type

Arm

data_from_sqa(data_sqa)[source]¶

Convert SQLAlchemy Data to AE Data.

Return type

Data

experiment_from_sqa(experiment_sqa)[source]¶

Convert SQLAlchemy Experiment to Ax Experiment.

Return type

Experiment

generation_strategy_from_sqa(gs_sqa)[source]¶

Convert SQALchemy generation strategy to Ax GenerationStrategy.

Return type

GenerationStrategy

generator_run_from_sqa(generator_run_sqa)[source]¶

Convert SQLAlchemy GeneratorRun to Ax GeneratorRun.

Return type

GeneratorRun

get_enum_name(value, enum)[source]¶

Given an enum value (int) and an enum (of ints), return the corresponding enum name. If the value is not present in the enum, throw an error.

Return type

Optional[str]

get_init_args_from_properties(object_sqa, class_)[source]¶

Given a SQAAlchemy instance with a properties blob, extract the arguments required for its class’s initializer.

Return type

Dict[str, Any]

metric_from_sqa(metric_sqa)[source]¶

Convert SQLAlchemy Metric to Ax Metric, Objective, or OutcomeConstraint.

Return type

Union[Metric, Objective, OutcomeConstraint]

opt_config_and_tracking_metrics_from_sqa(metrics_sqa)[source]¶

Convert a list of SQLAlchemy Metrics to a a tuple of Ax OptimizationConfig and tracking metrics.

Return type

Tuple[Optional[OptimizationConfig], List[Metric]]

parameter_constraint_from_sqa(parameter_constraint_sqa, parameters)[source]¶

Convert SQLAlchemy ParameterConstraint to Ax ParameterConstraint.

Return type

ParameterConstraint

parameter_from_sqa(parameter_sqa)[source]¶

Convert SQLAlchemy Parameter to Ax Parameter.

Return type

Parameter

runner_from_sqa(runner_sqa)[source]¶

Convert SQLAlchemy Runner to Ax Runner.

Return type

Runner

search_space_from_sqa(parameters_sqa, parameter_constraints_sqa)[source]¶

Convert a list of SQLAlchemy Parameters and ParameterConstraints to an Ax SearchSpace.

Return type

Optional[SearchSpace]

trial_from_sqa(trial_sqa, experiment)[source]¶

Convert SQLAlchemy Trial to Ax Trial.

Return type

BaseTrial

ax.storage.sqa_store.base_encoder module¶

class ax.storage.sqa_store.encoder.Encoder(config)[source]¶

Bases: object

Class that contains methods for storing an Ax experiment to SQLAlchemy.

Instantiate with an instance of Config to customize the functionality. For even more flexibility, create a subclass.

config¶

Metadata needed to save and load an experiment to SQLAlchemy.

abandoned_arm_to_sqa(abandoned_arm)[source]¶

Convert Ax AbandonedArm to SQLAlchemy.

Return type

SQAAbandonedArm

arm_to_sqa(arm, weight=1.0)[source]¶

Convert Ax Arm to SQLAlchemy.

Return type

SQAArm

data_to_sqa(data, trial_index, timestamp)[source]¶

Convert AE data to SQLAlchemy.

Return type

SQAData

experiment_to_sqa(experiment)[source]¶

Convert Ax Experiment to SQLAlchemy.

In addition to creating and storing a new Experiment object, we need to create and store copies of the Trials, Metrics, Parameters, ParameterConstraints, and Runner owned by this Experiment.

Return type

SQAExperiment

generation_strategy_to_sqa(generation_strategy, experiment_id)[source]¶

Convert an Ax GenerationStrategy to SQLAlchemy, preserving its state, so that the restored generation strategy can be resumed from the point at which it was interrupted and stored.

Return type

SQAGenerationStrategy

generator_run_to_sqa(generator_run, weight=None)[source]¶

Convert Ax GeneratorRun to SQLAlchemy.

In addition to creating and storing a new GeneratorRun object, we need to create and store copies of the Arms, Metrics, Parameters, and ParameterConstraints owned by this GeneratorRun.

Return type

SQAGeneratorRun

get_enum_value(value, enum)[source]¶

Given an enum name (string) and an enum (of ints), return the corresponding enum value. If the name is not present in the enum, throw an error.

Return type

Optional[int]

get_metric_type_and_properties(metric)[source]¶

Given an Ax Metric, convert its type into a member of MetricType enum, and construct a dictionary to be stored in the database properties json blob.

Return type

Tuple[int, Dict[str, Any]]

metric_to_sqa(metric)[source]¶

Convert Ax Metric to SQLAlchemy.

Return type

SQAMetric

objective_to_sqa(objective)[source]¶

Convert Ax Objective to SQLAlchemy.

Return type

SQAMetric

optimization_config_to_sqa(optimization_config)[source]¶

Convert Ax OptimizationConfig to a list of SQLAlchemy Metrics.

Return type

List[SQAMetric]

outcome_constraint_to_sqa(outcome_constraint)[source]¶

Convert Ax OutcomeConstraint to SQLAlchemy.

Return type

SQAMetric

parameter_constraint_to_sqa(parameter_constraint)[source]¶

Convert Ax ParameterConstraint to SQLAlchemy.

Return type

SQAParameterConstraint

parameter_to_sqa(parameter)[source]¶

Convert Ax Parameter to SQLAlchemy.

Return type

SQAParameter

runner_to_sqa(runner, trial_type=None)[source]¶

Convert Ax Runner to SQLAlchemy.

Return type

SQARunner

search_space_to_sqa(search_space)[source]¶

Convert Ax SearchSpace to a list of SQLAlchemy Parameters and ParameterConstraints.

Return type

Tuple[List[SQAParameter], List[SQAParameterConstraint]]

trial_to_sqa(trial)[source]¶

Convert Ax Trial to SQLAlchemy.

In addition to creating and storing a new Trial object, we need to create and store the GeneratorRuns and Runner that it owns.

Return type

SQATrial

ax.storage.sqa_store.db module¶

ax.storage.sqa_store.db.Ax_PROD_TIER = 'xdb.adaptive_experiment'¶

ax.storage.sqa_store.db.EXPIRE_ON_COMMIT = False¶

ax.storage.sqa_store.db.HASH_FIELD_LENGTH = 32¶

ax.storage.sqa_store.db.JSON_FIELD_LENGTH = 4096¶

ax.storage.sqa_store.db.LONGTEXT_BYTES = 4294967295¶

ax.storage.sqa_store.db.LONG_STRING_FIELD_LENGTH = 255¶

ax.storage.sqa_store.db.MEDIUMTEXT_BYTES = 16777215¶

ax.storage.sqa_store.db.NAME_OR_TYPE_FIELD_LENGTH = 100¶

ax.storage.sqa_store.db.SESSION_FACTORY = None¶

class ax.storage.sqa_store.db.SQABase[source]¶

Bases: object

Metaclass for SQLAlchemy classes corresponding to core Ax classes.

property attributes¶

Return a list of the column attributes and relationship fields on this SQABase instance. Used for iterating over the fields to determine equality, perform updates, etc.

equals(other)¶

fields_equal(other, field)[source]¶

Check if field on self is equal to field on other.

Return type

bool

static list_equals(l1, l2)[source]¶

Compare equality of two lists.

Assumptions:

– The lists do not contain duplicates

Checking equality is then the same as checking that the lists are the same length, and that one is a subset of the other.

Return type

bool

static list_update(l1, l2)[source]¶

Given an existing list (l1) and an new version (l2):

– update the existing items in l1 that have matching items in l2 – delete existing items in l1 that don’t have matching items in l2 – add items in l2 that don’t exist in l1

e.g. list_update([1,2,3], [1,5]) => [1,5]

list_update([Arm(name=”0_0”)], [Arm(name=”0_0”), Arm(name=”0_1”)]) =>

[Arm(name=”0_0”), Arm(name=”0_1”)] where Arm(name=”0_0”) has been updated, not replaced, so that we don’t delete/recreate the DB row

Return type

List[~T]

static list_update_without_unique_id(l1, l2)[source]¶

Merge a new list (l2) into an existing list (l1) This method works for lists whose items do not have a unique_id field. If the lists are equal, return the old one. Else, return the new one.

Return type

List[~T]

update(other)[source]¶

Merge other into self.

Return type

None

update_field(other, field)[source]¶

Update field on self to be equal to field on other.

Return type

None

ax.storage.sqa_store.db.T = ~T¶

ax.storage.sqa_store.db.create_all_tables(engine)[source]¶

Create all tables that inherit from Base.

Parameters

engine (Engine) – a SQLAlchemy engine with a connection to a MySQL or SQLite DB.

Note

In order for all tables to be correctly created, all modules that define a mapped class that inherits from Base must be imported.

Return type

None

ax.storage.sqa_store.db.create_mysql_engine_from_creator(creator, echo=False, pool_recycle=10, **kwargs)[source]¶

Create a SQLAlchemy engine with the MySQL dialect given a creator function.

Parameters

• creator (Callable) – a callable which returns a DBAPI connection.

• echo (bool) – if True, set engine to be verbose.

• pool_recycle (int) – number of seconds after which to recycle connections. -1 means no timeout. Default is 10 seconds.

• **kwargs – keyword args passed to create_engine

Returns

SQLAlchemy engine with connection to MySQL DB.

Return type

Engine

ax.storage.sqa_store.db.create_mysql_engine_from_url(url, echo=False, pool_recycle=10, **kwargs)[source]¶

Create a SQLAlchemy engine with the MySQL dialect given a database url.

Parameters

• url (str) – a database url that can include username, password, hostname, database name as well as optional keyword arguments for additional configuration. e.g. dialect+driver://username:password@host:port/database.

• echo (bool) – if True, set engine to be verbose.

• pool_recycle (int) – number of seconds after which to recycle connections. -1 means no timeout. Default is 10 seconds.

• **kwargs – keyword args passed to create_engine

Returns

SQLAlchemy engine with connection to MySQL DB.

Return type

Engine

ax.storage.sqa_store.db.create_test_engine(path=None, echo=True)[source]¶

Creates a SQLAlchemy engine object for use in unit tests.

Parameters

• path (Optional[str]) – if None, use in-memory SQLite; else attempt to create a SQLite DB in the path provided.

• echo (bool) – if True, set engine to be verbose.

Returns

an instance of SQLAlchemy engine.

Return type

Engine

ax.storage.sqa_store.db.get_engine()[source]¶

Fetch a SQLAlchemy engine, if already initialized.

If not initialized, need to either call init_engine_and_session_factory or get_session explicitly.

Returns

an instance of a SQLAlchemy engine with a connection to a DB.

Return type

Engine

ax.storage.sqa_store.db.get_session()[source]¶

Fetch a SQLAlchemy session with a connection to a DB.

Unless init_engine_and_session_factory is called first with custom args, this will automatically initialize a connection to xdb.adaptive_experiment.

Returns

an instance of a SQLAlchemy session.

Return type

Session

ax.storage.sqa_store.db.init_engine_and_session_factory(url=None, creator=None, echo=False, force_init=False, **kwargs)[source]¶

Initialize the global engine and SESSION_FACTORY for SQLAlchemy.

The initialization needs to only happen once. Note that it is possible to re-initialize the engine by setting the force_init flag to True, but this should only be used if you are absolutely certain that you know what you are doing.

Parameters

• url (Optional[str]) – a database url that can include username, password, hostname, database name as well as optional keyword arguments for additional configuration. e.g. dialect+driver://username:password@host:port/database. Either this argument or creator argument must be specified.

• creator (Optional[Callable]) – a callable which returns a DBAPI connection. Either this argument or url argument must be specified.

• echo (bool) – if True, logging for engine is enabled.

• force_init (bool) – if True, allows re-initializing engine and session factory.

• **kwargs – keyword arguments passed to create_mysql_engine_from_creator

Return type

None

ax.storage.sqa_store.db.init_test_engine_and_session_factory(tier_or_path=None, echo=False, force_init=False, **kwargs)[source]¶

Initialize the global engine and SESSION_FACTORY for SQLAlchemy, using an in-memory SQLite database.

The initialization needs to only happen once. Note that it is possible to re-initialize the engine by setting the force_init flag to True, but this should only be used if you are absolutely certain that you know what you are doing.

Parameters

• tier_or_path (Optional[str]) – the name of the DB tier.

• echo (bool) – if True, logging for engine is enabled.

• force_init (bool) – if True, allows re-initializing engine and session factory.

• **kwargs – keyword arguments passed to create_mysql_engine_from_creator

Return type

None

ax.storage.sqa_store.db.session_scope()[source]¶

Provide a transactional scope around a series of operations.

Return type

Generator[Session, None, None]

ax.storage.sqa_store.json module¶

ax.storage.sqa_store.json.JSONEncodedDict = JSONEncodedObject(length=4096)¶

ax.storage.sqa_store.json.JSONEncodedList = JSONEncodedObject(length=4096)¶

class ax.storage.sqa_store.json.JSONEncodedMediumText(object_pairs_hook=None, *args, **kwargs)[source]¶

Bases: ax.storage.sqa_store.json.JSONEncodedObject

Class for JSON-encoding objects in SQLAlchemy, backed by MEDIUMTEXT (MySQL).

See description in JSONEncodedObject.

impl = Text(length=16777215)¶

class ax.storage.sqa_store.json.JSONEncodedObject(object_pairs_hook=None, *args, **kwargs)[source]¶

Bases: sqlalchemy.sql.type_api.TypeDecorator

Class for JSON-encoding objects in SQLAlchemy.

Represents an object that is automatically marshalled and unmarshalled to/from the corresponding JSON string. By itself, this data structure does not track any changes.

impl = VARCHAR(length=4096)¶

process_bind_param(value, dialect)[source]¶

Receive a bound parameter value to be converted.

Subclasses override this method to return the value that should be passed along to the underlying TypeEngine object, and from there to the DBAPI execute() method.

The operation could be anything desired to perform custom behavior, such as transforming or serializing data. This could also be used as a hook for validating logic.

This operation should be designed with the reverse operation in mind, which would be the process_result_value method of this class.

Parameters

• value (Any) – Data to operate upon, of any type expected by this method in the subclass. Can be None.

• dialect (Any) – the Dialect in use.

Return type

Optional[str]

process_result_value(value, dialect)[source]¶

Receive a result-row column value to be converted.

Subclasses should implement this method to operate on data fetched from the database.

Subclasses override this method to return the value that should be passed back to the application, given a value that is already processed by the underlying TypeEngine object, originally from the DBAPI cursor method fetchone() or similar.

The operation could be anything desired to perform custom behavior, such as transforming or serializing data. This could also be used as a hook for validating logic.

Parameters

• value (Any) – Data to operate upon, of any type expected by this method in the subclass. Can be None.

• dialect (Any) – the Dialect in use.

This operation should be designed to be reversible by the “process_bind_param” method of this class.

Return type

Any

class ax.storage.sqa_store.json.JSONEncodedText(object_pairs_hook=None, *args, **kwargs)[source]¶

Bases: ax.storage.sqa_store.json.JSONEncodedObject

Class for JSON-encoding objects in SQLAlchemy, backed by TEXT (MySQL).

See description in JSONEncodedObject.

impl¶

alias of sqlalchemy.sql.sqltypes.Text

ax.storage.sqa_store.json.JSONEncodedTextDict = JSONEncodedText()¶

ax.storage.sqa_store.load module¶

ax.storage.sqa_store.load.load_experiment(experiment_name, config=None)[source]¶

Load experiment by name (uses default SQAConfig).

Return type

Experiment

ax.storage.sqa_store.load.load_generation_strategy_by_experiment_name(experiment_name, config=None)[source]¶

Finds a generation strategy attached to an experiment specified by a name and restores it from its corresponding SQA object.

Return type

GenerationStrategy

ax.storage.sqa_store.load.load_generation_strategy_by_id(gs_id, config=None)[source]¶

Finds a generation strategy stored by a given ID and restores it.

Return type

GenerationStrategy

ax.storage.sqa_store.save module¶

ax.storage.sqa_store.save.save_experiment(experiment, config=None)[source]¶

Save experiment (using default SQAConfig).

Return type

None

ax.storage.sqa_store.save.save_generation_strategy(generation_strategy, config=None)[source]¶

Save generation strategy (using default SQAConfig if no config is specified). If the generation strategy has an experiment set, the experiment will be saved first.

Return type

int

Returns

The ID of the saved generation strategy.

ax.storage.sqa_store.sqa_classes module¶

ax.storage.sqa_store.sqa_classes.ONLY_ONE_FIELDS = ['experiment_id', 'generator_run_id']¶

class ax.storage.sqa_store.sqa_classes.SQAAbandonedArm(*args, **kwargs)[source]¶

Bases: sqlalchemy.ext.declarative.declarative_base

abandoned_reason = Column(None, String(length=255), table=None)¶

id = Column(None, Integer(), table=None, primary_key=True, nullable=False)¶

immutable_fields = ['name', 'time_abandoned']¶

name = Column(None, String(length=100), table=None, nullable=False)¶

time_abandoned = Column(None, IntTimestamp(), table=None, nullable=False, default=ColumnDefault(<function datetime.now>))¶

trial_id = Column(None, Integer(), ForeignKey('trial_v2.id'), table=None)¶

unique_id = 'name'¶

class ax.storage.sqa_store.sqa_classes.SQAArm(*args, **kwargs)[source]¶

Bases: sqlalchemy.ext.declarative.declarative_base

generator_run_id = Column(None, Integer(), ForeignKey('generator_run_v2.id'), table=None)¶

id = Column(None, Integer(), table=None, primary_key=True, nullable=False)¶

immutable_fields = ['parameters']¶

name = Column(None, String(length=100), table=None)¶

parameters = Column(None, JSONEncodedText(), table=None, nullable=False)¶

unique_id = 'name'¶

weight = Column(None, Float(), table=None, nullable=False, default=ColumnDefault(1.0))¶

class ax.storage.sqa_store.sqa_classes.SQAData(*args, **kwargs)[source]¶

Bases: sqlalchemy.ext.declarative.declarative_base

data_json = Column(None, Text(length=4294967295), table=None, nullable=False)¶

description = Column(None, String(length=255), table=None)¶

experiment_id = Column(None, Integer(), ForeignKey('experiment_v2.id'), table=None)¶

generation_strategy_id = Column(None, Integer(), ForeignKey('generation_strategy.id'), table=None)¶

id = Column(None, Integer(), table=None, primary_key=True, nullable=False)¶

time_created = Column(None, BigInteger(), table=None, nullable=False)¶

trial_index = Column(None, Integer(), table=None)¶

unique_id = 'time_created'¶

class ax.storage.sqa_store.sqa_classes.SQAExperiment(*args, **kwargs)[source]¶

Bases: sqlalchemy.ext.declarative.declarative_base

data = <RelationshipProperty at 0x1a2eff7c48; no key>¶

default_trial_type = Column(None, String(length=100), table=None)¶

description = Column(None, String(length=255), table=None)¶

experiment_type = Column(None, Integer(), table=None)¶

generation_strategy = <RelationshipProperty at 0x1a2eff7f48; no key>¶

id = Column(None, Integer(), table=None, primary_key=True, nullable=False)¶

ignore_during_update_fields = ['time_created']¶

immutable_fields = ['name']¶

is_test = Column(None, Boolean(), table=None, nullable=False, default=ColumnDefault(False))¶

metrics = <RelationshipProperty at 0x1a2eff7cc8; no key>¶

name = Column(None, String(length=100), table=None, nullable=False)¶

parameter_constraints = <RelationshipProperty at 0x1a2eff7dc8; no key>¶

parameters = <RelationshipProperty at 0x1a2eff7d48; no key>¶

properties = Column(None, JSONEncodedText(), table=None, default=ColumnDefault({}))¶

runners = <RelationshipProperty at 0x1a2eff7e48; no key>¶

status_quo_name = Column(None, String(length=100), table=None)¶

status_quo_parameters = Column(None, JSONEncodedText(), table=None)¶

time_created = Column(None, IntTimestamp(), table=None, nullable=False)¶

trials = <RelationshipProperty at 0x1a2eff7ec8; no key>¶

class ax.storage.sqa_store.sqa_classes.SQAGenerationStrategy(*args, **kwargs)[source]¶

Bases: sqlalchemy.ext.declarative.declarative_base

curr_index = Column(None, Integer(), table=None, nullable=False)¶

data = <RelationshipProperty at 0x1a2eff7148; no key>¶

experiment_id = Column(None, Integer(), ForeignKey('experiment_v2.id'), table=None)¶

generated = Column(None, JSONEncodedObject(length=4096), table=None, nullable=False)¶

generator_runs = <RelationshipProperty at 0x1a2eff70c8; no key>¶

id = Column(None, Integer(), table=None, primary_key=True, nullable=False)¶

name = Column(None, String(length=100), table=None, nullable=False)¶

observed = Column(None, JSONEncodedObject(length=4096), table=None, nullable=False)¶

steps = Column(None, JSONEncodedObject(length=4096), table=None, nullable=False)¶

class ax.storage.sqa_store.sqa_classes.SQAGeneratorRun(*args, **kwargs)[source]¶

Bases: sqlalchemy.ext.declarative.declarative_base

arms = <RelationshipProperty at 0x1a2ef638c8; no key>¶

best_arm_name = Column(None, String(length=100), table=None)¶

best_arm_parameters = Column(None, JSONEncodedText(), table=None)¶

best_arm_predictions = Column(None, JSONEncodedObject(length=4096), table=None)¶

bridge_kwargs = Column(None, JSONEncodedText(), table=None)¶

fit_time = Column(None, Float(), table=None)¶

gen_time = Column(None, Float(), table=None)¶

generation_strategy_id = Column(None, Integer(), ForeignKey('generation_strategy.id'), table=None)¶

generator_run_type = Column(None, Integer(), table=None)¶

id = Column(None, Integer(), table=None, primary_key=True, nullable=False)¶

ignore_during_update_fields = ['time_created']¶

index = Column(None, Integer(), table=None)¶

metrics = <RelationshipProperty at 0x1a2ef63948; no key>¶

model_key = Column(None, String(length=100), table=None)¶

model_kwargs = Column(None, JSONEncodedText(), table=None)¶

model_predictions = Column(None, JSONEncodedObject(length=4096), table=None)¶

parameter_constraints = <RelationshipProperty at 0x1a2ef63a48; no key>¶

parameters = <RelationshipProperty at 0x1a2ef639c8; no key>¶

time_created = Column(None, IntTimestamp(), table=None, nullable=False, default=ColumnDefault(<function datetime.now>))¶

trial_id = Column(None, Integer(), ForeignKey('trial_v2.id'), table=None)¶

unique_id = 'index'¶

weight = Column(None, Float(), table=None)¶

class ax.storage.sqa_store.sqa_classes.SQAMetric(*args, **kwargs)[source]¶

Bases: sqlalchemy.ext.declarative.declarative_base

bound = Column(None, Float(), table=None)¶

canonical_name = Column(None, String(length=100), table=None)¶

experiment_id = Column(None, Integer(), ForeignKey('experiment_v2.id'), table=None)¶

generator_run_id = Column(None, Integer(), ForeignKey('generator_run_v2.id'), table=None)¶

id = Column(None, Integer(), table=None, primary_key=True, nullable=False)¶

immutable_fields = ['name', 'metric_type']¶

intent = Column(None, StringEnum(length=100), table=None, nullable=False)¶

lower_is_better = Column(None, Boolean(), table=None)¶

metric_type = Column(None, Integer(), table=None, nullable=False)¶

minimize = Column(None, Boolean(), table=None)¶

name = Column(None, String(length=255), table=None, nullable=False)¶

op = Column(None, IntEnum(), table=None)¶

properties = Column(None, JSONEncodedText(), table=None, default=ColumnDefault({}))¶

relative = Column(None, Boolean(), table=None)¶

trial_type = Column(None, String(length=100), table=None)¶

unique_id = 'name'¶

class ax.storage.sqa_store.sqa_classes.SQAParameter(*args, **kwargs)[source]¶

Bases: sqlalchemy.ext.declarative.declarative_base

choice_values = Column(None, JSONEncodedObject(length=4096), table=None)¶

digits = Column(None, Integer(), table=None)¶

domain_type = Column(None, IntEnum(), table=None, nullable=False)¶

experiment_id = Column(None, Integer(), ForeignKey('experiment_v2.id'), table=None)¶

fixed_value = Column(None, JSONEncodedObject(length=4096), table=None)¶

generator_run_id = Column(None, Integer(), ForeignKey('generator_run_v2.id'), table=None)¶

id = Column(None, Integer(), table=None, primary_key=True, nullable=False)¶

immutable_fields = ['name', 'parameter_type']¶

is_fidelity = Column(None, Boolean(), table=None)¶

is_ordered = Column(None, Boolean(), table=None)¶

is_task = Column(None, Boolean(), table=None)¶

log_scale = Column(None, Boolean(), table=None)¶

lower = Column(None, Float(), table=None)¶

name = Column(None, String(length=100), table=None, nullable=False)¶

parameter_type = Column(None, IntEnum(), table=None, nullable=False)¶

target_value = Column(None, JSONEncodedObject(length=4096), table=None)¶

unique_id = 'name'¶

upper = Column(None, Float(), table=None)¶

class ax.storage.sqa_store.sqa_classes.SQAParameterConstraint(*args, **kwargs)[source]¶

Bases: sqlalchemy.ext.declarative.declarative_base

bound = Column(None, Float(), table=None, nullable=False)¶

constraint_dict = Column(None, JSONEncodedObject(length=4096), table=None, nullable=False)¶

experiment_id = Column(None, Integer(), ForeignKey('experiment_v2.id'), table=None)¶

generator_run_id = Column(None, Integer(), ForeignKey('generator_run_v2.id'), table=None)¶

id = Column(None, Integer(), table=None, primary_key=True, nullable=False)¶

immutable_fields = ['type', 'constraint_dict', 'bound']¶

type = Column(None, IntEnum(), table=None, nullable=False)¶

class ax.storage.sqa_store.sqa_classes.SQARunner(*args, **kwargs)[source]¶

Bases: sqlalchemy.ext.declarative.declarative_base

experiment_id = Column(None, Integer(), ForeignKey('experiment_v2.id'), table=None)¶

id = Column(None, Integer(), table=None, primary_key=True, nullable=False)¶

properties = Column(None, JSONEncodedText(), table=None, default=ColumnDefault({}))¶

runner_type = Column(None, Integer(), table=None, nullable=False)¶

trial_id = Column(None, Integer(), ForeignKey('trial_v2.id'), table=None)¶

trial_type = Column(None, String(length=100), table=None)¶

class ax.storage.sqa_store.sqa_classes.SQATrial(*args, **kwargs)[source]¶

Bases: sqlalchemy.ext.declarative.declarative_base

abandoned_arms = <RelationshipProperty at 0x1a2eff7848; no key>¶

abandoned_reason = Column(None, String(length=100), table=None)¶

deployed_name = Column(None, String(length=100), table=None)¶

experiment_id = Column(None, Integer(), ForeignKey('experiment_v2.id'), table=None)¶

generator_runs = <RelationshipProperty at 0x1a2eff78c8; no key>¶

id = Column(None, Integer(), table=None, primary_key=True, nullable=False)¶

ignore_during_update_fields = ['time_created']¶

immutable_fields = ['is_batch']¶

index = Column(None, Integer(), table=None, nullable=False)¶

is_batch = Column('is_batched', Boolean(), table=None, nullable=False, default=ColumnDefault(True))¶

num_arms_created = Column(None, Integer(), table=None, nullable=False, default=ColumnDefault(0))¶

run_metadata = Column(None, JSONEncodedText(), table=None)¶

runner = <RelationshipProperty at 0x1a2eff7948; no key>¶

status = Column(None, IntEnum(), table=None, nullable=False, default=ColumnDefault(<TrialStatus.CANDIDATE: 0>))¶

status_quo_name = Column(None, String(length=100), table=None)¶

time_completed = Column(None, IntTimestamp(), table=None)¶

time_created = Column(None, IntTimestamp(), table=None, nullable=False)¶

time_run_started = Column(None, IntTimestamp(), table=None)¶

time_staged = Column(None, IntTimestamp(), table=None)¶

trial_type = Column(None, String(length=100), table=None)¶

unique_id = 'index'¶

ax.storage.sqa_store.sqa_enum module¶

class ax.storage.sqa_store.sqa_enum.BaseNullableEnum(enum, *arg, **kw)[source]¶

Bases: sqlalchemy.sql.type_api.TypeDecorator

process_bind_param(value, dialect)[source]¶

Receive a bound parameter value to be converted.

Subclasses override this method to return the value that should be passed along to the underlying TypeEngine object, and from there to the DBAPI execute() method.

The operation could be anything desired to perform custom behavior, such as transforming or serializing data. This could also be used as a hook for validating logic.

This operation should be designed with the reverse operation in mind, which would be the process_result_value method of this class.

Parameters

• value (Any) – Data to operate upon, of any type expected by this method in the subclass. Can be None.

• dialect (Any) – the Dialect in use.

Return type

Any

process_result_value(value, dialect)[source]¶

Receive a result-row column value to be converted.

Subclasses should implement this method to operate on data fetched from the database.

Subclasses override this method to return the value that should be passed back to the application, given a value that is already processed by the underlying TypeEngine object, originally from the DBAPI cursor method fetchone() or similar.

The operation could be anything desired to perform custom behavior, such as transforming or serializing data. This could also be used as a hook for validating logic.

Parameters

• value (Any) – Data to operate upon, of any type expected by this method in the subclass. Can be None.

• dialect (Any) – the Dialect in use.

This operation should be designed to be reversible by the “process_bind_param” method of this class.

Return type

Any

class ax.storage.sqa_store.sqa_enum.IntEnum(enum, *arg, **kw)[source]¶

Bases: ax.storage.sqa_store.sqa_enum.BaseNullableEnum

impl¶

alias of sqlalchemy.sql.sqltypes.SmallInteger

class ax.storage.sqa_store.sqa_enum.StringEnum(enum, *arg, **kw)[source]¶

Bases: ax.storage.sqa_store.sqa_enum.BaseNullableEnum

impl = VARCHAR(length=100)¶

ax.storage.sqa_store.timestamp module¶

class ax.storage.sqa_store.timestamp.IntTimestamp(*args, **kwargs)[source]¶

Bases: sqlalchemy.sql.type_api.TypeDecorator

impl¶

alias of sqlalchemy.sql.sqltypes.Integer

process_bind_param(value, dialect)[source]¶

Receive a bound parameter value to be converted.

Subclasses override this method to return the value that should be passed along to the underlying TypeEngine object, and from there to the DBAPI execute() method.

The operation could be anything desired to perform custom behavior, such as transforming or serializing data. This could also be used as a hook for validating logic.

This operation should be designed with the reverse operation in mind, which would be the process_result_value method of this class.

Parameters

• value (Optional[datetime]) – Data to operate upon, of any type expected by this method in the subclass. Can be None.

• dialect (Dialect) – the Dialect in use.

Return type

Optional[int]

process_result_value(value, dialect)[source]¶

Receive a result-row column value to be converted.

Subclasses should implement this method to operate on data fetched from the database.

Subclasses override this method to return the value that should be passed back to the application, given a value that is already processed by the underlying TypeEngine object, originally from the DBAPI cursor method fetchone() or similar.

The operation could be anything desired to perform custom behavior, such as transforming or serializing data. This could also be used as a hook for validating logic.

Parameters

• value (Optional[int]) – Data to operate upon, of any type expected by this method in the subclass. Can be None.

• dialect (Dialect) – the Dialect in use.

This operation should be designed to be reversible by the “process_bind_param” method of this class.

Return type

Optional[datetime]

ax.storage.sqa_store.utils module¶

ax.storage.sqa_store.utils.is_foreign_key_field(field)[source]¶

Return true if field name is a foreign key field, i.e. ends in _id.

Return type

bool

ax.storage.sqa_store.validation module¶

ax.storage.sqa_store.validation.consistency_exactly_one(instance, exactly_one_fields)[source]¶

Ensure that exactly one of exactly_one_fields has a value set.

Return type

Any

ax.storage.sqa_store.validation.validate_metric(mapper, connection, target)[source]¶

Return type

None

ax.storage.sqa_store.validation.validate_parameter(mapper, connection, target)[source]¶

Return type

None

ax.storage.sqa_store.validation.validate_parameter_constraint(mapper, connection, target)[source]¶

Return type

None

ax.storage.sqa_store.validation.validate_runner(mapper, connection, target)[source]¶

Return type

None