VOCS API

class gest_api.vocs.VOCS(*, variables, objectives={}, constraints={}, constants={}, observables={})

Variables, Objectives, Constraints, and other Settings (VOCS) data structure to describe optimization problems.

VOCS objects specify the following fields:

Inputs:

  • variables: defines the names and types of input parameters that will be passed to an objective function in order to solve the optimization problem.

  • constants (optional): defines the names and values of constant values that will be passed alongside variables to the objective function.

Outputs:

  • objectives: defines the names and types of function outputs that will be optimized or explored.

  • constraints (optional): defines the names and types of function outputs that will be used as constraints that need to be satisfied for a valid solution to the optimization problem.

  • observables (optional): defines the names of any other function outputs that should be passed to the generator (alongside the objectives and constraints).

Example:

from gest_api.vocs import VOCS

vocs = VOCS(
    variables={"x1": [0, 1], "x2": [0, 5]},
    objectives={"f1": "MAXIMIZE"},
    constants={"alpha": 0.55},
    constraints={"c1": ["LESS_THAN", 0]},
    observables={"o1"}
)
Parameters:

  • variables (VariableDict)

  • objectives (ObjectiveDict)

  • constraints (ConstraintDict)

  • constants (ConstantDict)

  • observables (ObservableDict)

Names and settings for input parameters for passing to an objective function to solve the optimization problem.

A dictionary with keys being variable names (as strings) and values as either:

  • A two-element list, representing bounds.

  • A set of discrete values, with curly-braces.

1from gest_api.vocs import VOCS
2
3vocs = VOCS(variables={"x": [0.0, 1.0]})
4...
5vocs = VOCS(variables={"x": {0, 1, 2, "/usr", "/home", "/bin"}})

Names of objective function outputs, and guidance for the direction of optimization.

A dictionary with keys being objective names (as strings) and values as either:

  • "MINIMIZE"

  • "MAXIMIZE"

  • "EXPLORE"

1from gest_api.vocs import VOCS
2
3vocs = VOCS(objectives={"f": "MINIMIZE"})
4...
5vocs = VOCS(objectives={"f": "MAXIMIZE"})
6...
7vocs = VOCS(objectives={"f": "EXPLORE"})

Names of function outputs that and their category of constraint that must be satisfied for a valid solution to the optimization problem.

A dictionary with keys being constraint names (as strings) and values as a length-2 list with the first element being "LESS_THAN", "GREATER_THAN", or "BOUNDS".

The second element depends on the type of constraint:

  • If "BOUNDS", a two-element list of floats, representing boundaries.

  • If "LESS_THAN", or "GREATER_THAN", a single float value.

1from gest_api.vocs import VOCS
2
3vocs = VOCS(constraints={"c": ["LESS_THAN", 1.0]})
4...
5vocs = VOCS(constraints={"c": ["GREATER_THAN", 0.0]})
6...
7vocs = VOCS(constraints={"c": ["BOUNDS", [0.0, 1.0]]})

Names and values of constants for passing alongside variables to the objective function.

A dictionary with keys being constant names (as strings) and values as any type.

1from gest_api.vocs import VOCS
2
3vocs = VOCS(constants={"alpha": 1.0, "beta": 2.0})

Names of other objective function outputs that will be passed to the optimizer (alongside the objectives and constraints).

A set of strings or a dictionary with keys being names and values being type:

1from gest_api.vocs import VOCS
2
3vocs = VOCS(observables={"temp", "temp2"})
4...
5vocs = VOCS(observables={"temp": "float", "temp2": "int"})

Each section below links to the detailed structure for the parameters.

Parameter Reference