Domains

Domains represent the variables and constraints of an optimisation space. Each reaction optimisation problem will have an associated domain.

class summit.domain.CategoricalVariable(name, description, **kwargs)[source]

Representation of a categorical variable

Categorical variables are discrete choices that do not have an ordering. Common examples are selections of catalysts, bases, or ligands.

Each possible discrete choice is referred to as a level. These are added as a list using the list keyword argument.

When available, descriptors can be added to a categorical variable. These might be values such as the melting point, logP, etc. of each level of the categorical variable. These descriptors can significantly improve the speed of optimization and also make many more strategies compatible with categorical variables (i.e., all that work with continuos variables).

Parameters
  • name (str) – The name of the variable

  • description (str) – A short description of the variable

  • levels (list of any serializable object, optional) – The potential values of the Categorical variable. When descriptors are passed, this can be left empty, and the levels will be inferred from the index of the descriptors DataSet.

  • descriptors (DataSet, optional) – A DataSet where the keys correspond to the levels and the data columns are descriptors.

name
description
levels
ds
Type

descriptors DataSet

Raises
  • ValueError – When the levels are not unique

  • TypeError – When levels is not a list

Examples

The simplest way to use a CategoricalVariable is without descriptors:

>>> base = CategoricalVariable('base', 'Organic Base', levels=['DBU', 'BMTG', 'TEA'])

When descriptors are available, they can be used directly without specfying the levels:

>>> solvent_df = DataSet([[5, 81],[-93, 111]], index=['benzene', 'toluene'], columns=['melting_point', 'boiling_point'])
>>> solvent = CategoricalVariable('solvent', 'solvent descriptors', descriptors=solvent_df)

It is also possible to specify a subset of the descriptors as possible choices by passing both descriptors and levels. The levels must match the index of the descriptors DataSet.

>>> solvent_df = DataSet([[5, 81],[-93, 111]], index=['benzene', 'toluene'], columns=['melting_point', 'boiling_point'])
>>> solvent = CategoricalVariable('solvent', 'solvent descriptors', levels=['benzene', 'toluene'],descriptors=solvent_df)
add_level(level)[source]

Add a level to the discrete variable

Parameters

level – Value to add to the levels of the discrete variable

Raises

ValueError – If the level is already in the list of levels

property levels

Potential values of the discrete variable

Type

numpy.ndarray

property num_descriptors

Returns the number of descriptors

remove_level(level)[source]

Add a level to the discrete variable

Parameters

level – Level to remove from the discrete variable

Raises

ValueError – If the level does not exist for the discrete variable

to_dict()[source]

Return json encoding of the variable

class summit.domain.Constraint(lhs, constraint_type='<=')[source]

A constraint for an optimization domain

Parameters
  • lhs (str) – The left hand side of a constraint equation

  • constraint_type (str) – The type of constraint. Must be <, <=, ==, > or >=. Default: “<=”

Raises

ValueError

Examples

These should be constraints in the form “lhs constraint_type constraint 0” So for example, x+y=3 should be rewritten as x+y-3=0 and therefore:

>>> domain = Domain()
>>> domain += Constraint(lhs="x+y-3", constraint_type="==")

Or x+y<0 would be:

>>> domain = Domain()
>>> domain += Constraint(lhs="x+y", constraint_type="<")
class summit.domain.ContinuousVariable(name: str, description: str, bounds: list, **kwargs)[source]

Representation of a continuous variable

Parameters
  • name (str) – The name of the variable

  • description (str) – A short description of the variable

  • bounds (list of float or int) – The lower and upper bounds (respectively) of the variable

  • is_objective (bool, optional) – If True, this variable is an output. Defaults to False (i.e., an input variable)

  • maximize (bool, optional) – If True, the output will be maximized; if False, it will be minimized. Defaults to True.

name
description
bounds
lower_bound
upper_bound

Examples

>>> var = ContinuousVariable('temperature', 'reaction temperature', [1, 100])
property bounds

Lower and upper bound of the variable

Type

numpy.ndarray

property lower_bound

lower bound of the variable

Type

float or int

property upper_bound

upper bound of the variable

Type

float or int

class summit.domain.Domain(variables=[], constraints=[])[source]

Representation of the optimization domain

Parameters
  • variables (Variable or list of Variable like objects, optional) – list of variable objects (i.e., ContinuousVariable, CategoricalVariable)

  • constraints (Constraint or list of Constraint objects, optional) – list of constraints on the problem

variables
Raises
  • TypeError – If variables or constraints are not lists or a single instance of the object

  • ValueError – If variable names are not unique

Examples

>>> domain = Domain()
>>> domain += ContinuousVariable('temperature', 'reaction temperature', [1, 100])
num_continuous_dimensions(include_descriptors=False, include_outputs=False)int[source]

The number of continuous dimensions

Parameters
  • include_descriptors (bool, optional) – If True, the number of descriptors columns are considered. Defaults to False.

  • include_outputs (bool, optional) – If True include output variables in the count. Defaults to False.

Returns

num_variables – Number of variables in the domain

Return type

int

num_variables(include_outputs=False)int[source]

Number of variables in the domain

Parameters

include_outputs (bool, optional) – If True include output variables in the count. Defaults to False.

Returns

num_variables – Number of variables in the domain

Return type

int

to_dict()[source]

Return a dictionary representation of the domain

to_json()[source]

Return the a json representation of the domain

property variables

List of variables in the domain

Type

[List[Type[Variable]]]

exception summit.domain.DomainError[source]
class summit.domain.Variable(name: str, description: str, variable_type: str, **kwargs)[source]

A base class for variables

Parameters
  • name (str) – The name of the variable

  • description (str) – A short description of the variable

  • is_objective (bool, optional) – If True, this variable is an output. Defaults to False (i.e., an input variable)

  • maximize (bool, optional) – If True, the output will be maximized; if False, it will be minimized. Defaults to True.

  • units (str, optional) – Units of the variable. Defaults to None.

name
description
property description

description of the variable

Type

str

property name

name of the variable

Type

str