mindfoundry.optaas.client package

Subpackages

Submodules

mindfoundry.optaas.client.api_key module

class mindfoundry.optaas.client.api_key.ApiKey(json: Dict, session: OPTaaSSession)[source]

Bases: object

A key that can be used to interact with OPTaaS.

json

The full JSON representation of this key in OPTaaS.

Type

Dict

id

The actual API key.

Type

str

role

The role assigned to this key.

Type

UserRole

expired

Whether this key has expired, i.e. can no longer be used.

Type

bool

set_expired(expired: bool) → None[source]

Expires or un-expires an API Key by making a PUT request to OPTaaS. Only available to Admin users.

set_role(role: UserRole) → None[source]

Modifies the role associated with an API Key by making a PUT request to OPTaaS. Only available to Admin users.

class mindfoundry.optaas.client.api_key.UserRole(value)[source]

Bases: Enum

An enumeration.

ADMIN = 'admin'
READ_ONLY = 'read_only'
STANDARD = 'standard'

mindfoundry.optaas.client.client module

class mindfoundry.optaas.client.client.OPTaaSClient(server_url: str, api_key: str, disable_version_check: bool = False, max_retries: int = 3, keep_alive: bool = True)[source]

Bases: object

Sets up a connection to OPTaaS and allows you to create a Task, retrieve existing Tasks etc.

Parameters

  • server_url (str) – URL of your OPTaaS server

  • api_key (str) – Your personal API key

  • disable_version_check (bool, default False) – Set to True if you don’t want to be notified when a new version of the client is available

  • max_retries (int, default 3) – How many times to retry a request if a connection error occurs.

  • keep_alive (bool, default True) – Very rarely required. Set to False only if you experience connection dropping issues.

create_likelihood_task(title: str, parameters: List[Parameter], targets: List[Parameter], observed_data: List[Objective], likelihood: Expr, constraints: Optional[List[Constraint]] = None, random_seed: Optional[int] = None, initial_configurations: Optional[int] = None, user_defined_data: Optional[Any] = None) → Task[source]

Creates a new Task by making a POST request to OPTaaS

Parameters

  • title (str) – Name/description of your Task.

  • parameters (List[Parameter]) – Parameters that you would like to optimize.

  • constraints (List[Constraint]) – Constraints on what values can be assigned to Parameters.

  • targets (List[Parameter]) – Parameters to be optimized by maximising the likelihood. Note 1: Currently only one single is supported.

  • observed_data (List[Objective], optional) – Specification of the observed data at the configurations. Note: Conditional parameters (i.e. ChoiceParameters and anything with optional=True) are not supported in multi-objective tasks.

  • likelihood (Expr) – The likelihood function expressed as sympy Expr to be optimized wrt to the targets’ variables. The likelihood is in function of the parameters, observed_data and targets.

  • initial_configurations (int, optional, default 10, minimum 1) – Number of Configurations that OPTaaS will generate upfront. If you are planning to have multiple clients working concurrently, set this to be equal to the number of clients.

  • user_defined_data (Any, optional) – Any other data you would like to store in the task JSON

  • random_seed (int, optional) – Seed for the random generator used by OPTaaS when generating Configurations. If not specified, a new seed will be used for each Task. Use this only if you need reproducible results, i.e. if you create 2 Tasks with identical attributes including an identical random_seed, and you use the same scoring function, then OPTaaS is guaranteed to generate the same Configurations in the same order for both Tasks.

Returns

A new Task

Raises

.OPTaaSError –

create_sklearn_task(title: str, pipeline: OptimizablePipeline, additional_parameters: List[Parameter] = None, additional_constraints: List[Constraint] = None, additional_prior_means: List[PriorMeanExpression] = None, random_seed: int = None, initial_configurations: int = None, objectives: List[Objective] = None, goal: Goal = None, min_known_score: float = None, max_known_score: float = None, user_defined_data: Any = None, **kwargs) → SklearnTask[source]

Creates a new SklearnTask by making a POST request to OPTaaS

All the arguments from OPTaaSClient.create_task() can be used here except instead of parameters and constraints there is additional_parameters and additional_constraints.

Parameters

  • pipeline (OptimizablePipeline) – The pipeline you wish to optimize.

  • additional_parameters (List[Parameter], optional) – Additional parameters that you would like to optimize.

  • additional_constraints (List[Constraint], optional) – Additional constraints on your Parameters.

  • additional_prior_means (List[Constraint], optional) – Additional prior_means on your Parameters.

  • kwargs – Additional arguments required to optimize certain estimators, e.g. PCA requires feature_count.

Returns

A new SklearnTask

Raises

  • .MissingArgumentError –

  • .OPTaaSError –

create_task(title: str, parameters: List[Parameter], constraints: Optional[List[Constraint]] = None, prior_means: Optional[List[PriorMeanExpression]] = None, random_seed: Optional[int] = None, initial_configurations: Optional[int] = None, objectives: Optional[List[Objective]] = None, goal: Optional[Goal] = None, min_known_score: Optional[float] = None, max_known_score: Optional[float] = None, user_defined_data: Optional[Any] = None) → Task[source]

Creates a new Task by making a POST request to OPTaaS

Parameters

  • title (str) – Name/description of your Task.

  • parameters (List[Parameter]) – Parameters that you would like to optimize.

  • constraints (List[Constraint]) – Constraints on what values can be assigned to Parameters.

  • prior_means (List[PriorMeansExpression]) – Prior means to be used by the optimizer. This is a list of expressions provided by the user which together define a guess for the function we are trying to optimize. Expressions are provided in the same “When-Then” format that is used to describe input parameter constraints. The ordering of this list is important: the first expression whose “When” evaluates to True will be used to calculate the prior mean value. If none evaluate to True, a default value of 0 will be used, which is equivalent to there being no prior mean known. Prior means do not come with uncertainty information, and they are directly subtracted from the data before a surrogate model is fitted.

  • initial_configurations (int, optional, default 10, minimum 1) – Number of Configurations that OPTaaS will generate upfront. If you are planning to have multiple clients working concurrently, set this to be equal to the number of clients.

  • objectives (List[Objective], optional) – Specification of each objective for a multi-objective optimization. Note: Conditional parameters (i.e. ChoiceParameters and anything with optional=True) are not supported in multi-objective tasks.

  • goal (Goal, optional, default Goal.max) – Whether OPTaaS should aim for the lowest (min) or highest (max) score. Do not use in multi-objective optimizations (specify goal for each objective instead).

  • min_known_score (float, optional) – Minimum known score value. Do not use in multi-objective optimizations (specify min_known_score for each objective instead).

  • max_known_score (float, optional) – Maximum known score value. Do not use in multi-objective optimizations (specify max_known_score for each objective instead).

  • user_defined_data (Any, optional) – Any other data you would like to store in the task JSON

  • random_seed (int, optional) – Seed for the random generator used by OPTaaS when generating Configurations. If not specified, a new seed will be used for each Task. Use this only if you need reproducible results, i.e. if you create 2 Tasks with identical attributes including an identical random_seed, and you use the same scoring function, then OPTaaS is guaranteed to generate the same Configurations in the same order for both Tasks.

Returns

A new Task

Raises

.OPTaaSError –

generate_api_key(role: Optional[UserRole] = None) → ApiKey[source]

Generates a new API key by making a POST request to OPTaaS. Only available to Admin users.

get_all_tasks() → List[Task][source]

Retrieves a list of all stored Tasks by making a GET request to OPTaaS.

Returns

List of Tasks

Raises

.OPTaaSError –

get_api_keys() → List[ApiKey][source]

Retrieves the list of all API keys by making a GET request to OPTaaS. Only available to Admin users.

get_sklearn_task(task_id: str, pipeline: OptimizablePipeline) → SklearnTask[source]

Retrieves a stored SklearnTask by making a GET request to OPTaaS.

This allows you to create a SklearnTask and then use it again in a separate/later session, assuming of course that you call this method with the same estimators you used to create the original task.

Parameters
Returns

A SklearnTask

Raises

.OPTaaSError –

get_task(task_id: str) → Task[source]

Retrieves a stored Task by making a GET request to OPTaaS.

Parameters

task_id (str) – unique id for the Task

Returns

A Task

Raises

.OPTaaSError –

mindfoundry.optaas.client.configuration module

class mindfoundry.optaas.client.configuration.Configuration(json: Dict)[source]

Bases: object

A set of values assigned to each Parameter, as generated by OPTaaS or defined by the user.

json

The full Configuration object as stored in OPTaaS in JSON format.

Type

Dict

id

Unique id for the Configuration.

Type

str

values

Values assigned to each Parameter. Dict keys will be the Parameter names, and values will correspond to the Parameter type. GroupParameters will appear as nested Dicts.

Type

Dict

type

One of

  • default: all parameters are set to their default values

  • exploration: values are chosen so as to explore a new region of the parameter space

  • exploitation: values are chosen so as to improve upon a previously provided result

  • user-defined: values are provided by the user

Type

str

mindfoundry.optaas.client.constraint module

mindfoundry.optaas.client.expressions module

class mindfoundry.optaas.client.expressions.BinaryPredicate(left_operand, operator: str, right_operand)[source]

Bases: Predicate

A Predicate with 2 operands

class mindfoundry.optaas.client.expressions.Constraint(then: Expression, when: Optional[Expression] = None)[source]

Bases: WhenThenExpression

This is an alias for the WhenThenExpression class which defines a when expression, then expression clause:

The “when” part is optional (if omitted, the then part applies).

class mindfoundry.optaas.client.expressions.Expression[source]

Bases: ABC

Allows us to build expressions for Constraints using common operators. The following operators are supported:

  • addition: x + y

  • subtraction: x - y

  • multiplication: x * y

  • division: x / y

  • floor division: x // y

  • remainder: x % y

  • exponentiation: x ** y

  • equality: x == y

  • inequality: x != y

  • greater than: x > y

  • greater than or equal: x >= y

  • less than: x < y

  • less than or equal: x <= y

  • and: x & y

  • or: x | y

Example

((param1 + param2 <= param3) & param4.is_present()) | param5 == ‘abc’

Note the use of brackets with the & and | operators - this is because they don’t have the same precedence as and and or so you need to be explicit in order to generate the correct expression.

See this page for more examples.

Refer to the OPTaaS swagger page for more details on constraint syntax.

abstract to_optaas_expression() → str[source]
class mindfoundry.optaas.client.expressions.Predicate(optaas_expression: str)[source]

Bases: Expression

An Expression that evaluates to a boolean value that can be used in a Constraint

to_optaas_expression() → str[source]

A string representation of this expression in a format which can be parsed by OPTaaS

class mindfoundry.optaas.client.expressions.PriorMeanExpression(then: Expression, when: Optional[Expression] = None)[source]

Bases: WhenThenExpression

This is an alias for the WhenThenExpression class which defines a when expression, then expression clause:

The “when” part is optional (if omitted, the then part applies).

class mindfoundry.optaas.client.expressions.UnaryPredicate(operand, operator: str)[source]

Bases: Predicate

A Predicate with a single operand

class mindfoundry.optaas.client.expressions.WhenThenExpression(then: Expression, when: Optional[Expression] = None)[source]

Bases: ABC

Defines a when expression, then expression clause:

The “when” part is optional (if omitted, the then part applies).

NOTE: At the MFOpt level, WhenThenExpressions get transformed to either constraints or prior mean functions, which means the “then” expressions have to conform to some formats: they have to be boolean for constraints, and not boolean for prior means.

to_optaas_expression() → str[source]

mindfoundry.optaas.client.goal module

class mindfoundry.optaas.client.goal.Goal(value)[source]

Bases: Enum

Specifies whether OPTaaS will aim for the lowest (min) or highest (max) score

max = 1
min = 0

mindfoundry.optaas.client.objective module

class mindfoundry.optaas.client.objective.Objective(id: str, goal: Optional[Goal] = None, min_known_score: Optional[float] = None, max_known_score: Optional[float] = None)[source]

Bases: object

An objective for optimizing as part of a multi-objective Task.

When evaluating a Configuration and producing a Result, you can include a score for each Objective.

Parameters

  • id (str) – A unique id for the objective.

  • goal (Goal, optional, default Goal.max) – Whether OPTaaS should aim for the lowest (min) or highest (max) score.

  • min_known_score (float, optional) – Minimum known score value for this objective.

  • max_known_score (float, optional) – Maximum known score value for this objective.

to_json() → Dict[str, Any][source]

mindfoundry.optaas.client.parameter module

class mindfoundry.optaas.client.parameter.BoolParameter(name: str, id: Optional[str] = None, optional: Optional[bool] = None, include_in_default: Optional[bool] = None, default: Optional[bool] = None)[source]

Bases: Parameter

A Parameter which will be assigned either True or False.

Parameters

default (bool, optional) – False if not specified.

is_compatible_value(value: Any) → bool[source]

Value must be a bool.

class mindfoundry.optaas.client.parameter.CategoricalParameter(name: str, values: List[Union[str, int, float, bool]], id: Optional[str] = None, optional: Optional[bool] = None, include_in_default: Optional[bool] = None, default=None)[source]

Bases: Parameter

A Parameter which can be assigned any value from a specified list of allowed values.

Parameters

  • values (List[Union[str, int, float, bool]]) – Allowed values (can be string, numeric, boolean or any mixture of those).

  • default (Union[str, int, float, bool], optional) – If defined, must be equal to a value from values. If not defined, the default will be the first value from values.

is_compatible_value(value: Any) → bool[source]

Value must be identical to one of the specified values.

class mindfoundry.optaas.client.parameter.ChoiceParameter(name: str, choices: List[Parameter], id: Optional[str] = None, optional: Optional[bool] = None, include_in_default: Optional[bool] = None, default: Optional[Parameter] = None)[source]

Bases: Parameter

A set of Parameters, only one of which will be chosen to appear in each Configuration.

choices

Parameters to choose from. Cannot be empty.

Type

List[Parameter]

default

Default choice, must be present in the choices list. If not specified, the default will be the first item in choices.

Type

Parameter, optional

Raises

.ValueError –

is_compatible_value(value: Any) → bool[source]

Always False because ChoiceParameter never stores a single value.

to_json() → dict[source]

JSON representation of this Parameter (used when making a request to OPTaaS to create the Task)

class mindfoundry.optaas.client.parameter.ConstantParameter(name: str, value: Union[str, int, float, bool], id: Optional[str] = None, optional: Optional[bool] = None, include_in_default: Optional[bool] = None)[source]

Bases: Parameter

A Parameter which will always be assigned a specified value.

Parameters

value (Union[str, int, float, bool]) – value (can be string, numeric or boolean).

is_compatible_value(value: Any) → bool[source]

Value must be identical to the specified value.

class mindfoundry.optaas.client.parameter.DiscreteParameter(name: str, values: List[Union[int, float]], id: Optional[str] = None, optional: Optional[bool] = None, include_in_default: Optional[bool] = None, default=None)[source]

Bases: Parameter

Similar to a CategoricalParameter, but can only take numeric values, and can therefore be used with numeric operators in a Constraint.

Parameters

  • values (List[Union[int, float]]) – Allowed values (must be numeric). The ordering of this list is NOT significant.

  • default (Union[int, float], optional) – If defined, must be equal to a value from values. If not defined, the default will be the median value from values, after sorting them numerically.

is_compatible_value(value: Any) → bool[source]

Value must be identical to one of the specified values.

class mindfoundry.optaas.client.parameter.Distribution(value)[source]

Bases: Enum

Specifies the distribution of values for a NumericParameter.

This will influence the values assigned by OPTaaS in each Configuration.

LOGUNIFORM = 'LogUniform'
TRUNCATED_NORMAL = 'Truncated_Normal'
UNIFORM = 'Uniform'
class mindfoundry.optaas.client.parameter.FloatParameter(name: str, minimum: float, maximum: float, id: Optional[str] = None, optional: Optional[bool] = None, include_in_default: Optional[bool] = None, default: Optional[float] = None, distribution: Optional[Distribution] = None, cyclical: Optional[bool] = None)[source]

Bases: NumericParameter

A Parameter which can be assigned any float value between the minimum and maximum (inclusive).

Parameters

  • minimum (float) – Smallest allowed value.

  • maximum (float) – Largest allowed value.

  • default (float, optional) – If defined, must be a value between minimum and maximum. If not defined, it will be set to the midpoint between minimum and maximum.

  • distribution (Distribution, optional, default Distribution.UNIFORM) – See Distribution

  • cyclical (bool, optional, default False) – If True, OPTaaS will select values from a period starting at the minimum (inclusive) and ending at the maximum (exclusive). Values near the minimum and maximum will be considered to be close, as if they were on a circle. Note: if cyclical is true, distribution will be ignored. Also, if any of your parameters are cyclical, all your parameters must be Floats, Constants or Groups (other types are not currently supported), and none of them can be optional.

is_compatible_value(value: Any) → bool[source]

Value must be a float or int (not bool) and within the range [minimum - maximum] (inclusive).

class mindfoundry.optaas.client.parameter.GroupParameter(name: str, items: List[Parameter], id: Optional[str] = None, optional: Optional[bool] = None, include_in_default: Optional[bool] = None)[source]

Bases: Parameter

A set of Parameters, all of which will be included in each Configuration unless marked as Parameter.optional.

There is no default value for groups.

items

Parameters that comprise this Group. Can be empty.

Type

List[Parameter]

is_compatible_value(value: Any) → bool[source]

Always False because GroupParameter never stores a single value.

to_json() → dict[source]

JSON representation of this Parameter (used when making a request to OPTaaS to create the Task)

class mindfoundry.optaas.client.parameter.IntParameter(name: str, minimum: int, maximum: int, id: Optional[str] = None, optional: Optional[bool] = None, include_in_default: Optional[bool] = None, default: Optional[int] = None, distribution: Optional[Distribution] = None)[source]

Bases: NumericParameter

A Parameter which can be assigned any integer value between the minimum and maximum (inclusive).

Parameters

  • minimum (int) – Smallest allowed value.

  • maximum (int) – Largest allowed value.

  • default (int, optional) – If defined, must be a value between minimum and maximum. If not defined, it will be set to the midpoint between minimum and maximum.

  • distribution (Distribution, optional, default Distribution.UNIFORM) – See Distribution

is_compatible_value(value: Any) → bool[source]

Value must be an int (not bool) and within the range [minimum - maximum] (inclusive).

class mindfoundry.optaas.client.parameter.NumericParameter(name: str, type_: str, minimum: Union[int, float], maximum: Union[int, float], id: Optional[str] = None, optional: Optional[bool] = None, include_in_default: Optional[bool] = None, default: Optional[Union[int, float]] = None, distribution: Optional[Distribution] = None)[source]

Bases: Parameter, ABC

Superclass for FloatParameter and IntParameter

abstract is_compatible_value(value: Any) → bool[source]

Returns True iff the given value is compatible with this Parameter.

class mindfoundry.optaas.client.parameter.Parameter(name: str, type_: str, id_: Optional[str], optional: Optional[bool] = False, include_in_default: Optional[bool] = True, default=None)[source]

Bases: Expression, ABC

Superclass for all parameters.

name

Human-readable name for the parameter.

Type

str

type

Parameter type (e.g. “integer” or “choice”)

Type

str

id

Unique id for this Parameter. If not specified, the object id will be used.

Type

str, optional

optional

Whether the parameter can be omitted in a Configuration.

Type

bool, optional, default False

include_in_default

Whether an optional parameter will be included in the default Configuration.

Type

bool, optional, default True

default

Value to use when generating the default Configuration.

Type

Any, optional

is_absent() → Expression[source]

Returns a Expression that evaluates to False if this parameter is present in a Configuration

abstract is_compatible_value(value: Any) → bool[source]

Returns True iff the given value is compatible with this Parameter.

is_present() → Expression[source]

Returns a Expression that evaluates to True if this parameter is present in a Configuration

to_json() → Dict[source]

JSON representation of this Parameter (used when making a request to OPTaaS to create the Task)

to_optaas_expression() → str[source]
class mindfoundry.optaas.client.parameter.SubsetParameter(name: str, values: List[Union[str, int, float, bool]], id: Optional[str] = None, optional: Optional[bool] = None, include_in_default: Optional[bool] = None, default: Optional[List[Union[str, int, float, bool]]] = None)[source]

Bases: Parameter

A parameter that may contain any subset of a valid set of values.

Parameters

  • values (List[Union[str, int, float, bool]]) – Allowed values (can be string, numeric, boolean or any mixture of those).

  • default (List[Union[str, int, float, bool]]) – The default for this kind of parameter must be a subset of allowed values. Optional. Assumed to be the empty set if not otherwise specified.

is_compatible_value(value: List[Any]) → bool[source]

Value must be a subset of allowed values, i.e. all of its element must be included in the set of allowed values. An empty subset is also a valid value by extension. No duplicate items are allowed.

mindfoundry.optaas.client.prediction module

class mindfoundry.optaas.client.prediction.Prediction(json: Dict[str, Any])[source]

Bases: object

The result obtained by taking a Configuration and running it through the surrogate model.

Must contain a mean value. You cannot specify variance without mean.

json

The full Prediction object as stored in OPTaaS in JSON format.

Type

Dict

configuration

key-value pairs corresponding to the parameters and their respective values

Type

Dict[str, Any]

mean

Mean from surrogate model prediction

Type

float

variance

Variance of the surrogate model prediction. Must be >= 0.

Type

float

mindfoundry.optaas.client.result module

class mindfoundry.optaas.client.result.Result(configuration: Configuration, score: Optional[Union[float, Dict]] = None, error: Optional[str] = None, variance: Optional[Union[float, Dict]] = None, user_defined_data: Optional[Any] = None)[source]

Bases: object

The result obtained by taking a Configuration and running it through your scoring function.

Must contain either a score value or an error. You cannot specify variance without score.

Parameters

  • configuration (Configuration) – The Configuration used to obtain this Result.

  • score (ScoreValueOrDict) – The score obtained. For multi-objective tasks, a dictionary of scores for each objective (using the objective IDs as keys).

  • variance (VarianceValueOrDict >=0, optional, defaults to 0) – Variance associated with the score. For multi-objective tasks, a dictionary of variances for each objective (using the objective IDs as keys).

  • error (Any) – Any data related to an error encountered while calculating the score.

  • user_defined_data (Any, optional) – Any other data you wish to store as part of this Result.

Raises

.ValueError –

to_json() → Dict[str, Any][source]
to_json_without_configuration() → Dict[str, Any][source]
class mindfoundry.optaas.client.result.StoredResult(json: Dict)[source]

Bases: object

A Result that has been stored in OPTaaS.

json

The full Result object as stored in OPTaaS in JSON format.

Type

Dict

id

Unique id for the Result.

Type

int

configuration

The Configuration used to obtain the Result

Type

Configuration

pipeline

The Pipeline corresponding to the Configuration (only available for SklearnTasks).

Type

Optional[Pipeline]

score

Score obtained by using the Configuration, or a Dict of scores for each objective.

Type

ScoreValueOrDict

variance

Variance associated with the score, or a Dict of variance for each objective.

Type

VarianceValueOrDict

error

Any data related to an error encountered when trying to use the Configuration.

Type

Any

user_defined_data

Any other data provided when storing the Result.

Type

Any

as_pandas_row() → Dict[source]

Returns this Result as a Dict that can be used to create a Pandas DataFrame.

mindfoundry.optaas.client.session module

exception mindfoundry.optaas.client.session.OPTaaSError(response: Response)[source]

Bases: RuntimeError

Wrapper class for an error Response received from OPTaaS.

class mindfoundry.optaas.client.session.OPTaaSResponse(response: Response, disable_version_check: bool = False)[source]

Bases: object

Wrapper class for a successful Response received from OPTaaS.

class mindfoundry.optaas.client.session.OPTaaSSession(server_url: str, api_key: str, disable_version_check: bool, max_retries: int, keep_alive: bool)[source]

Bases: object

Wrapper class for a Session that makes requests to OPTaaS.

Parameters

  • server_url (str) – URL of your OPTaaS server

  • api_key (str) – Your personal API key

  • disable_version_check (bool, default False) – Set to True if you don’t want to be notified when a new version of the client is available

  • max_retries (int, default 3) – How many times to retry a request if a connection error occurs.

  • keep_alive (bool, default True) – Whether to set the Connection HTTP Header to “keep-alive”.

delete(endpoint: str, timeout: float = 60) → OPTaaSResponse[source]

Make a DELETE request to OPTaaS

Parameters

  • endpoint (str) – Endpoint for the request (will be appended to the server_url).

  • timeout (float, optional) – Request timeout in seconds

Returns

The OPTaaSResponse to the request.

Raises

.OPTaaSError –

get(endpoint: str, query_params: Optional[Dict] = None, timeout: float = 60) → OPTaaSResponse[source]

Make a GET request to OPTaaS

Parameters

  • endpoint (str) – Endpoint for the request (will be appended to the server_url).

  • query_params (Dict, optional) – Query parameters in Dict format (will be appended to the url).

  • timeout (float, optional) – Request timeout in seconds

Returns

The OPTaaSResponse to the request.

Raises

.OPTaaSError –

post(endpoint: str, body: dict, timeout: float = 60) → OPTaaSResponse[source]

Make a POST request to OPTaaS with a JSON body.

Parameters

  • endpoint (str) – Endpoint for the request (will be appended to the server_url).

  • body (dict) – Request body in JSON format.

  • timeout (float, optional) – Request timeout in seconds

Returns

The OPTaaSResponse to the request.

Raises

.OPTaaSError –

put(endpoint: str, body: dict, timeout: float = 60) → OPTaaSResponse[source]

Make a PUT request to OPTaaS with a JSON body.

Parameters

  • endpoint (str) – Endpoint for the request (will be appended to the server_url).

  • body (dict) – Request body in JSON format.

  • timeout (float, optional) – Request timeout in seconds

Returns

The OPTaaSResponse to the request.

Raises

.OPTaaSError –

mindfoundry.optaas.client.task module

class mindfoundry.optaas.client.task.Task(json: dict, session: OPTaaSSession)[source]

Bases: object

Allows you to access Task attributes and perform all Task-related functions.

json

The full JSON representation of this Task in OPTaaS.

Type

Dict

id

Unique id for the Task.

Type

str

title

Name/description as provided when the Task was created.

Type

str

parameters

JSON representation of the Parameters defined for this Task.

Type

List[Dict]

constraints

List of OPTaaS string representations of the Constraints defined for this Task.

Type

List[str]

prior_means

List of OPTaaS string representations of the Prior Means defined for this Task.

Type

List[str]

status

Current status of the Task, e.g. ‘running’ or ‘done’

Type

str

number_of_iterations

Number of Results provided for this Task so far.

Type

int

user_defined_data

Any other data as provided when the Task was created.

Type

Any

add_user_defined_configuration(values: Optional[Dict] = None, score: Optional[Union[float, Dict[str, float]]] = None, variance: Optional[Union[float, Dict[str, float]]] = None, user_defined_data: Optional[Any] = None, configurations: Optional[List[UserDefinedConfiguration]] = None) → Union[Configuration, List[Configuration]][source]

Make a POST request to OPTaaS to store a list of user-provided Configuration using the values provided.

Also optionally store a list of Result for this Configuration using the provided score.

This is useful for giving OPTaaS a “warm start” by providing some examples of good/bad Configurations.

Optionally, it is possible to pass the input as single unwrapped values.

Parameters

  • values (Dict, optional) – Values assigned to each Parameter. See Configuration.values.

  • score (ScoreValueOrDict, optional) – Score obtained when using this Configuration. For multi-objective tasks, a dictionary of scores for each objective, using Objective.id values as keys, e.g. {“id1”: 1.23, “id2”: 4.56}.

  • variance (VarianceValueOrDict >=0, optional, defaults to 0) – Variance associated with the score. For multi-objective tasks, a dictionary of variances for each objective, using Objective.id values as keys, e.g. {“id1”: 1.23, “id2”: 4.56}.

  • user_defined_data (Any, optional, ignored if score is not provided) – Any other data to store in the Result.

  • configurations (List[UserDefinedConfiguration], optional) – list of UserDefinedConfiguration.

  • provided. (Either values or configurations should be) –

Returns

The newly created list of Configuration. In case a single unwrapped value was provided, it returns the unwrapped configuration.

Raises

.OPTaaSError –

complete()[source]

Make a PUT request to OPTaaS to complete the task (no further configurations or results can be created)

delete()[source]

Delete this Task (cannot be undone).

generate_configurations(quantity: int = 1) → List[Configuration][source]

Make a POST request to OPTaaS to generate a set of new Configurations for this Task.

Parameters

quantity (int, optional, default 1) – The number of configurations to generate (minimum 1).

Returns

A list of the newly created Configurations.

Raises

.OPTaaSError –

get_best_result_and_configuration() → StoredResult[source]

Make a GET request to OPTaaS to retrieve the Result with the best score, including the Configuration used to obtain it.

Not currently supported for multi-objective Tasks.

Returns

The best StoredResult with included Configuration.

Raises

  • .OPTaaSError –

  • .ValueError –

get_configuration(configuration_id: str) → Configuration[source]

Make a GET request to OPTaaS to retrieve a specific Configuration by id.

Parameters

configuration_id (str) – Unique id for the Configuration.

Returns

The retrieved Configuration.

Raises

.OPTaaSError –

get_configurations(limit: Optional[int] = None) → List[Configuration][source]

Make a GET request to OPTaaS to retrieve a list of Configurations for this Task.

Parameters

limit (int, optional, minimum 1) – Upper bound on the number of Configurations that will be returned.

Returns

The list of Configurations.

Raises

.OPTaaSError –

get_pareto_set() → List[StoredResult][source]

Make a GET request to OPTaaS to retrieve the set of Pareto front Results for a multi-objective Task.

These are the Results where, for each objective, the score cannot be improved without reducing the score for another objective.

Not supported for single-objective Tasks.

Note: if a Result doesn’t contain a score value for all Objectives, it will be excluded from the Pareto set.

Returns

The list of Pareto front Results.

Raises

.OPTaaSError –

get_result(result_id: int) → StoredResult[source]

Make a GET request to OPTaaS to retrieve a specific StoredResult by id.

Parameters

result_id (str) – Unique id for the Result.

Returns

The retrieved StoredResult.

Raises

.OPTaaSError –

get_results(limit: int = None, best_first: bool = False, as_dataframe: bool = False, include_configurations=None) → Union[List[StoredResult], DataFrame][source]

Make a GET request to OPTaaS to retrieve a list of Results for this Task.

Parameters

  • limit (int, optional, minimum 1) – Upper bound on the number of Results that will be returned.

  • best_first (bool, optional, default False) – If True, Results will appear in score order, with the best score first (not currently supported for multi-objective tasks). If False, Results will appear in the order they were created.

  • as_dataframe (bool, optional, default False) – Return the data as a Pandas DataFrame. It will include a column for each parameter, plus the score, variance and error from each Result.

  • include_configurations – Deprecated.

Returns

The list of Results or a DataFrame.

Raises

.OPTaaSError –

get_sqrt_crlb()[source]

Make a GET request to OPTaaS to retrieve the square roots of the Cramer-Rao lower bounds of the estimates. https://en.wikipedia.org/wiki/Cram%C3%A9r%E2%80%93Rao_bound The value can be used as a proxy of the quality of the estimate.

Not supported for tasks without targets.

Returs:

The square root of the CRLB for the targets of this task as dictionary from target id to sqrt_crlb.

get_surrogate_predictions(configurations: List[Dict]) → List[Prediction][source]

Make a POST request to OPTaaS to retrieve the surrogate prediction for some configurations

Parameters

configurations (List[Dict]) – key value pairs corresponding to parameter names and their values.

:param See Configuration.values.:

Returns

List[Prediction]: a list of objects, each containing the mean and variance of the surrogate at each corresponding configuration point. For multi-objective Tasks, the mean and variance are dictionaries containing mean (and variance respectively) for each objective.

Raises

.OPTaaSError –

get_targets_estimates()[source]

Make a GET request to OPTaaS to retrieve the current estimates for the targets of this task.

Not supported for tasks without targets.

Returs:

The current estimates for the targets of this task as dictionary from target id to estimate.

record_result(configuration: Configuration, score: Optional[Union[float, Dict[str, float]]] = None, error: Optional[str] = None, variance: Optional[Union[float, Dict[str, float]]] = None, user_defined_data: Optional[Any] = None, return_next_config: bool = True) → Optional[Configuration][source]

Make a POST request to OPTaaS to record a Result for the given Configuration.

Must specify either score or error.

After the Result is recorded, OPTaaS will automatically generate the next Configuration for you to try.

Parameters

  • configuration (Configuration) – The Configuration used to obtain this Result.

  • score (ScoreValueOrDict) – The score obtained. For multi-objective tasks, a dictionary of scores for each objective, using Objective.id values as keys, e.g. {“id1”: 1.23, “id2”: 4.56}.

  • error (Any) – Any data related to an error encountered while calculating the score.

  • variance (VarianceValueOrDict >=0, optional, defaults to 0) – Variance associated with the score. For multi-objective tasks, a dictionary of variances for each objective, using Objective.id values as keys, e.g. {“id1”: 1.23, “id2”: 4.56}.

  • user_defined_data (Any, optional) – Any other data you wish to store as part of this Result.

  • return_next_config (bool, optional, default True) – Whether to return the next Configuration to try.

Returns

If return_next_config`==True, the next :class:.Configuration` generated by OPTaaS, otherwise None.

Raises

  • .OPTaaSError –

  • .ValueError –

record_results(results: List[Result], return_next_config: bool = True) → List[Configuration][source]

Make a POST request to OPTaaS to store a batch of Results and get the next batch of Configurations.

Parameters

  • results (List[Result]) – List of Results to record. Must be non-empty.

  • return_next_config (bool, optional, default True) – Whether to return the next Configurations to try.

Returns

If return_next_config`==True, a list of the same length as `results, containing the next Configurations for you to try, otherwise an empty list.

Raises

  • .OPTaaSError –

  • .ValueError –

refresh()[source]

Make a GET request to OPTaaS to retrieve the latest Task data and update this object accordingly.

resume()[source]

Make a PUT request to OPTaaS to resume a completed task

run(scoring_function: Callable[[...], Union[float, Dict[str, float], Tuple[float, float], Tuple[Dict[str, float], Dict[str, float]]]], max_iterations: int, score_threshold: Optional[Union[float, Dict[str, float]]] = None, logging_level: Literal['DEBUG', 'INFO', 'WARNING', 'ERROR'] = 'INFO') → Union[StoredResult, List[StoredResult]][source]

Run this task, using the provided scoring function to calculate the score for each configuration.

Parameters

  • scoring_function (Callable[..., ScoringFunctionOutput]) – Function that takes configuration values as arguments, e.g. if you have parameters x and y, your function would be def get_score(x, y). The function can return just a score, or a tuple of (score, variance). For multi-objective tasks the score and variance must be dictionaries, with Objective.id values as keys, e.g. {“id1”: 1.23, “id2”: 4.56}.

  • max_iterations (int) – Max number of iterations to run, i.e. number of results to record before stopping.

  • score_threshold (ScoreValueOrDict, optional, defaults to min/max known score if defined) – Stop running the task when the score is equal to or better than this value. For multi-objective tasks, use a dictionary with Objective.id values as keys, e.g. {“id1”: 1.23, “id2”: 4.56}.

  • logging_level (Literal["DEBUG", "INFO", "WARNING", "ERROR"], optional, defaults to "INFO") – Set the logging level.

Returns

The best recorded Result with the Configuration that was used to achieve it. For multi-objective tasks, the set of Pareto front Results will be returned instead.

Raises

.OPTaaSError –

mindfoundry.optaas.client.user_defined_configuration module

class mindfoundry.optaas.client.user_defined_configuration.UserDefinedConfiguration(values: Dict, score: Optional[Union[float, Dict[str, float]]] = None, variance: Optional[Union[float, Dict[str, float]]] = None, user_defined_data: Optional[Any] = None)[source]

Bases: object

A user defined configuration containing the parameters values and optionally score, variance and user_defined_data.

get_body() → Dict[source]
score: Optional[Union[float, Dict[str, float]]] = None
user_defined_data: Any = None
values: Dict
variance: Optional[Union[float, Dict[str, float]]] = None

mindfoundry.optaas.client.utils module

class mindfoundry.optaas.client.utils.MfOptOptimizer(value)[source]

Bases: Enum

An enumeration.

BAYESIAN = 'mf_bayesian'
LIKELIHOOD = 'likelihood'
mindfoundry.optaas.client.utils.get_choice_name(dictionary: Dict) → str
mindfoundry.optaas.client.utils.get_choice_value(dictionary: Dict) → Any
mindfoundry.optaas.client.utils.get_first_key(dictionary: Dict) → str[source]
mindfoundry.optaas.client.utils.get_first_value(dictionary: Dict) → Any[source]
mindfoundry.optaas.client.utils.move_dict_value_up_one_level(dictionary: Dict, key: str) → None[source]

Changes dict {‘key’: {‘sub_key’: ‘sub_value’}} to {‘key’: ‘sub_value’}

mindfoundry.optaas.client.version_check module

mindfoundry.optaas.client.version_check.compare_versions(response: Response) → None[source]

mindfoundry.optaas.client.viz module

class mindfoundry.optaas.client.viz.SurrogateViz(client: OPTaaSClient, task: Task)[source]

Bases: object

plot_surrogate_mean_and_std(x_var: str, y_var: str, z_range: Tuple[float, float], fig_width: int = 600, fig_height: int = 600) → DynamicMap[source]
plot_surrogate_with_uncertainties(x_var: str, y_var: str, z_range: Tuple[float, float], fig_width: int = 600, fig_height: int = 600) → DynamicMap[source]

Module contents