1. Decision Variable¶

Decision variables are the parameters or choices that can be adjusted to achieve the best outcome for a given black-box function. In black-box optimization, these decision variables are manipulated to explore potential solutions without requiring an understanding of the function’s internal structure. The optimization algorithm iteratively adjusts these variables, observing the objective function’s values.

Creating decision variables¶

With Amplify-BBOpt, you can define the decision variables using the variable classes below. These classes are for decision variables that represent binary, integer, and real values.

from amplify_bbopt import (
    BinaryVariable,
    DiscreteVariable,
    IntegerVariable,
    RealVariable,
    RealVariableLogUniform,
)

# A binary variable
binary_var = BinaryVariable()

# An integer variable ranging [0, 10]
integer_var = IntegerVariable(bounds=(0, 10))

# A real variable ranging [0.0, 1.0] with 11 discrete points
real_var = RealVariable(bounds=(0.0, 1.0), nbins=11)

# A real variable ranging [0.01, 1.0] with 3 discrete points
# uniformly distributed in the log domain
real_log_var = RealVariableLogUniform(bounds=(0.01, 1.0), nbins=3)

# An arbitrary discrete variable that takes values 1, 2, 4, 8 or 16
discrete_var = DiscreteVariable(discretized_list=[1, 2, 4, 8, 16])

There are also variable list classes that define a list of individual variables of the same type.

Variable class	Variable list class
`BinaryVariable`	`BinaryVariableList`
`IntegerVariable`	`IntegerVariableList`
`RealVariable`	`RealVariableList`
`RealVariableLogUniform`	`RealVariableListLogUniform`
`DiscreteVariable`	`DiscreteVariableList`

Each variable list can represent a list of values of the corresponding variable type. Here is an example of generating 100 variables at once for the aforementioned variable types.

from amplify_bbopt import (
    BinaryVariableList,
    DiscreteVariableList,
    IntegerVariableList,
    RealVariableList,
    RealVariableListLogUniform,
)

# A binary variable list with size 100
binary_var_list = BinaryVariableList(100)

# An integer variable list with size 100, with each element ranging [0, 10]
integer_var_list = IntegerVariableList(bounds=(0, 10), length=100)

# A real variable list with size 100, with each element ranging [0.0, 1.0]
# with 11 discrete points
real_var_list = RealVariableList(bounds=(0.0, 1.0), nbins=11, length=100)

# A real variable list with size 100, with each element ranging [0.01, 1.0]
# with 3 discrete points uniformly distributed in the log domain
real_log_var_list = RealVariableListLogUniform(
    bounds=(0.01, 1.0), nbins=3, length=100
)

# An arbitrary discrete variable list with size 100,
# with each element takes values 1, 2, 4, 8 or 16
discrete_var_list = DiscreteVariableList(
    discretized_list=[1, 2, 4, 8, 16], length=100
)

Variable information¶

Each of these variables has useful attributes, as follows:

Attribute	Data type	Details
`type`	`type`	Variable type
`nbins`	`int`	Number of discretization points
`len`	`int`	Length of the variable (only meaningful for variable list classes)
`method`	`str`	Variable conversion (encoding) method
`bounds`	`tuple`	The lower and upper bounds the variable can take

We have not yet described the variable conversion here. Below are some examples of using these attributes.

integer_var = IntegerVariable(bounds=(0, 10))
print(f"{integer_var.type=}")
print(f"{integer_var.nbins=}")
print(f"{integer_var.len=}")
print(f"{integer_var.bounds=}")

integer_var.type=<class 'int'>
integer_var.nbins=11
integer_var.len=1
integer_var.bounds=(0, 10)

real_var_list = RealVariableList(bounds=(0.0, 1.0), nbins=11, length=100)
print(f"{real_var_list.type=}")
print(f"{real_var_list.nbins=}")
print(f"{real_var_list.len=}")
print(f"{real_var_list.bounds=}")

real_var_list.type=<class 'float'>
real_var_list.nbins=11
real_var_list.len=100
real_var_list.bounds=(0.0, 1.0)

You can view the attributes mentioned above, type, nbins, len and method, the discretization indice (i = 0, ... nbins - 1), and corresponding values that the variable can take with the given discretization method.

# A binary variable
binary_var = BinaryVariable()
print(binary_var)

      type  nbins  len method  nvars            i=0
None  bool      1    1   None      1  (False, True)

# A real variable ranging [0.0, 1.0] with 11 discrete points
real_var = RealVariable(bounds=(0.0, 1.0), nbins=11)
print(real_var)

       type  nbins  len       method  nvars  i=0  i=1  i=2  i=3  i=4  i=5  i=6  i=7  i=8  i=9  i=10
None  float     11    1  domain_wall     10  0.0  0.1  0.2  0.3  0.4  0.5  0.6  0.7  0.8  0.9   1.0

# A real variable list with size 100, with each element ranging [0.0, 1.0]
# with 11 discrete points
real_var_list = RealVariableList(bounds=(0.0, 1.0), nbins=11, length=100)
print(real_var_list)

       type  nbins  len       method  nvars  i=0  i=1  i=2  i=3  i=4  i=5  i=6  i=7  i=8  i=9  i=10
None  float     11  100  domain_wall     10  0.0  0.1  0.2  0.3  0.4  0.5  0.6  0.7  0.8  0.9   1.0

Variable conversion¶

Depending on the optimization class, the variables defined in conjunction with the black-box function may need to be converted (encoded) to more primitive variables, such as binary variables. Amplify-BBOpt handles (or lets the Amplify SDK handle) such variable conversion. For details, see “Variable Conversion”.