Vocs

xopt.vocs.VOCS

Bases: XoptBaseModel

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

Attributes

xopt.vocs.VOCS.all_names property

all_names

Returns all vocs names (variables, constants, objectives, constraints)

xopt.vocs.VOCS.bounds property

bounds

Returns a bounds array (mins, maxs) of shape (2, n_variables) Arrays of lower and upper bounds can be extracted by: mins, maxs = vocs.bounds

xopt.vocs.VOCS.constant_names property

constant_names

Returns a sorted list of constraint names

xopt.vocs.VOCS.constraint_names property

constraint_names

Returns a sorted list of constraint names

xopt.vocs.VOCS.n_constants property

n_constants

Returns the number of constants

xopt.vocs.VOCS.n_constraints property

n_constraints

Returns the number of constraints

xopt.vocs.VOCS.n_inputs property

n_inputs

Returns the number of inputs (variables and constants)

xopt.vocs.VOCS.n_objectives property

n_objectives

Returns the number of objectives

xopt.vocs.VOCS.n_observables property

n_observables

Returns the number of constraints

xopt.vocs.VOCS.n_outputs property

n_outputs

Returns the number of outputs len(objectives + constraints + observables)

xopt.vocs.VOCS.n_variables property

n_variables

Returns the number of variables

xopt.vocs.VOCS.objective_names property

objective_names

Returns a sorted list of objective names

xopt.vocs.VOCS.output_names property

output_names

Returns a list of expected output keys: (objectives + constraints + observables) Each sub-list is sorted.

xopt.vocs.VOCS.variable_names property

variable_names

Returns a sorted list of variable names

Functions

xopt.vocs.VOCS.constraint_data

constraint_data(data, prefix='constraint_')

Returns a dataframe containing constraint data transformed according to vocs.constraints such that values that satisfy each constraint are negative.

Returns:

Type	Description
result: DataFrame	Processed Dataframe

Source code in xopt/vocs.py

def constraint_data(
    self,
    data: Union[pd.DataFrame, List[Dict], List[Dict]],
    prefix: str = "constraint_",
) -> pd.DataFrame:
    """
    Returns a dataframe containing constraint data transformed according to
    `vocs.constraints` such that values that satisfy each constraint are negative.

    Parameters
    ----------
        data: DataFrame
            Data to be processed.
        prefix: str, optional
            Prefix added to column names.

    Returns
    -------
        result: DataFrame
            Processed Dataframe
    """
    return form_constraint_data(self.constraints, data, prefix)

xopt.vocs.VOCS.convert_dataframe_to_inputs

convert_dataframe_to_inputs(data, include_constants=True)

Extracts only inputs from a dataframe. This will add constants if include_constants is true.

Source code in xopt/vocs.py

def convert_dataframe_to_inputs(
    self, data: pd.DataFrame, include_constants=True
) -> pd.DataFrame:
    """
    Extracts only inputs from a dataframe.
    This will add constants if `include_constants` is true.
    """
    # make sure that the df keys only contain vocs variables
    if not set(self.variable_names) == set(data.keys()):
        raise ValueError(
            "input dataframe column set must equal set of vocs variables"
        )

    # only keep the variables
    inner_copy = data.copy()

    # append constants if requested
    if include_constants:
        constants = self.constants
        if constants is not None:
            for name, val in constants.items():
                inner_copy[name] = val

    return inner_copy

xopt.vocs.VOCS.convert_numpy_to_inputs

convert_numpy_to_inputs(inputs, include_constants=True)

convert 2D numpy array to list of dicts (inputs) for evaluation Assumes that the columns of the array match correspond to `sorted(self.vocs.variables.keys())

Source code in xopt/vocs.py

def convert_numpy_to_inputs(
    self, inputs: np.ndarray, include_constants=True
) -> pd.DataFrame:
    """
    convert 2D numpy array to list of dicts (inputs) for evaluation
    Assumes that the columns of the array match correspond to
    `sorted(self.vocs.variables.keys())

    """
    df = pd.DataFrame(inputs, columns=self.variable_names)
    return self.convert_dataframe_to_inputs(df, include_constants)

xopt.vocs.VOCS.correct_list_types

correct_list_types(v)

make sure that constraint list types are correct

Source code in xopt/vocs.py

@field_validator("constraints")
def correct_list_types(cls, v):
    """make sure that constraint list types are correct"""
    for _, item in v.items():
        if not isinstance(item[0], str):
            raise ValueError(
                "constraint specification list must have the first "
                "element as a string`"
            )

        if not isinstance(item[1], float):
            raise ValueError(
                "constraint specification list must have the second "
                "element as a float"
            )

    return v

xopt.vocs.VOCS.cumulative_optimum

cumulative_optimum(data)

Returns the cumulative optimum for the given DataFrame.

Parameters:

Name	Type	Description	Default
data	DataFrame	Data for which the cumulative optimum shall be calculated.	required

Returns:

Type	Description
DataFrame	Cumulative optimum for the given DataFrame.

Source code in xopt/vocs.py

def cumulative_optimum(self, data: pd.DataFrame) -> pd.DataFrame:
    """
    Returns the cumulative optimum for the given DataFrame.

    Parameters
    ----------
    data: DataFrame
        Data for which the cumulative optimum shall be calculated.

    Returns
    -------
    DataFrame
        Cumulative optimum for the given DataFrame.

    """
    if not self.objectives:
        raise RuntimeError("No objectives defined.")
    if data.empty:
        return pd.DataFrame()
    obj_name = self.objective_names[0]
    obj = self.objectives[obj_name]
    get_opt = np.nanmax if obj == "MAXIMIZE" else np.nanmin
    feasible = self.feasibility_data(data)["feasible"]
    feasible_obj_values = [
        data[obj_name].values[i] if feasible[i] else np.nan
        for i in range(len(data))
    ]
    cumulative_optimum = np.array(
        [get_opt(feasible_obj_values[: i + 1]) for i in range(len(data))]
    )
    return pd.DataFrame({f"best_{obj_name}": cumulative_optimum}, index=data.index)

xopt.vocs.VOCS.denormalize_inputs

denormalize_inputs(input_points)

Denormalize input data (transform data from the range [0,1]) based on the variable ranges defined in the VOCS.

Parameters:

Name	Type	Description	Default
input_points	DataFrame	A DataFrame containing normalized input data in the range [0,1].	required

Returns:

Name	Type	Description
result	DataFrame	A DataFrame with denormalized input data corresponding to the specified variable ranges. Contains columns equal to the intersection between input_points and vocs.variable_names.

Notes

If the input DataFrame is empty or no variable information is available in the VOCS, an empty DataFrame is returned.

Source code in xopt/vocs.py

def denormalize_inputs(self, input_points: pd.DataFrame) -> pd.DataFrame:
    """
    Denormalize input data (transform data from the range [0,1]) based on the
    variable ranges defined in the VOCS.

    Parameters
    ----------
    input_points : pd.DataFrame
        A DataFrame containing normalized input data in the range [0,1].

    Returns
    -------
    result : pd.DataFrame
        A DataFrame with denormalized input data corresponding to the
        specified variable ranges. Contains columns equal to the intersection
        between `input_points` and `vocs.variable_names`.

    Notes
    -----

    If the input DataFrame is empty or no variable information is available in
    the VOCS, an empty DataFrame is returned.

    """
    denormed_data = {}
    for name in self.variable_names:
        if name in input_points.columns:
            width = self.variables[name][1] - self.variables[name][0]
            denormed_data[name] = (
                input_points[name] * width + self.variables[name][0]
            )

    if len(denormed_data):
        return pd.DataFrame(denormed_data)
    else:
        return pd.DataFrame([])

xopt.vocs.VOCS.extract_data

extract_data(data, return_raw=False, return_valid=False)

split dataframe into seperate dataframes for variables, objectives and constraints based on vocs - objective data is transformed based on vocs.objectives properties

Returns:

Type	Description
variable_data : DataFrame	Dataframe containing variable data objective_data : DataFrame Dataframe containing objective data constraint_data : DataFrame Dataframe containing constraint data

Source code in xopt/vocs.py

def extract_data(self, data: pd.DataFrame, return_raw=False, return_valid=False):
    """
    split dataframe into seperate dataframes for variables, objectives and
    constraints based on vocs - objective data is transformed based on
    `vocs.objectives` properties

    Parameters
    ----------
        data: DataFrame
            Dataframe to be split
        return_raw : bool, optional
            If True, return untransformed objective data
        return_valid : bool, optional
            If True, only return data that satisfies all of the contraint
            conditions.

    Returns
    -------
        variable_data : DataFrame
            Dataframe containing variable data
        objective_data : DataFrame
            Dataframe containing objective data
        constraint_data : DataFrame
            Dataframe containing constraint data
    """
    variable_data = self.variable_data(data, "")
    objective_data = self.objective_data(data, "", return_raw)
    constraint_data = self.constraint_data(data, "")
    observable_data = self.observable_data(data, "")

    if return_valid:
        feasible_status = self.feasibility_data(data)["feasible"]
        return (
            variable_data[feasible_status],
            objective_data[feasible_status],
            constraint_data[feasible_status],
            observable_data[feasible_status],
        )

    return variable_data, objective_data, constraint_data, observable_data

xopt.vocs.VOCS.feasibility_data

feasibility_data(data, prefix='feasible_')

Returns a dataframe containing booleans denoting if a constraint is satisfied or not. Returned dataframe also contains a column feasible which denotes if all constraints are satisfied.

Returns:

Type	Description
result: DataFrame	Processed Dataframe

Source code in xopt/vocs.py

def feasibility_data(
    self,
    data: Union[pd.DataFrame, List[Dict], List[Dict]],
    prefix: str = "feasible_",
) -> pd.DataFrame:
    """
    Returns a dataframe containing booleans denoting if a constraint is satisfied or
    not. Returned dataframe also contains a column `feasible` which denotes if
    all constraints are satisfied.

    Parameters
    ----------
        data: DataFrame
            Data to be processed.
        prefix: str, optional
            Prefix added to column names.

    Returns
    -------
        result: DataFrame
            Processed Dataframe
    """
    return form_feasibility_data(self.constraints, data, prefix)

xopt.vocs.VOCS.normalize_inputs

normalize_inputs(input_points)

Normalize input data (transform data into the range [0,1]) based on the variable ranges defined in the VOCS.

Parameters:

Name	Type	Description	Default
input_points	DataFrame	A DataFrame containing input data to be normalized.	required

Returns:

Name	Type	Description
result	DataFrame	A DataFrame with input data in the range [0,1] corresponding to the specified variable ranges. Contains columns equal to the intersection between input_points and vocs.variable_names.

Notes

If the input DataFrame is empty or no variable information is available in the VOCS, an empty DataFrame is returned.

Source code in xopt/vocs.py

def normalize_inputs(self, input_points: pd.DataFrame) -> pd.DataFrame:
    """
    Normalize input data (transform data into the range [0,1]) based on the
    variable ranges defined in the VOCS.

    Parameters
    ----------
    input_points : pd.DataFrame
        A DataFrame containing input data to be normalized.

    Returns
    -------
    result : pd.DataFrame
        A DataFrame with input data in the range [0,1] corresponding to the
        specified variable ranges. Contains columns equal to the intersection
        between `input_points` and `vocs.variable_names`.

    Notes
    -----

    If the input DataFrame is empty or no variable information is available in
    the VOCS, an empty DataFrame is returned.

    """
    normed_data = {}
    for name in self.variable_names:
        if name in input_points.columns:
            width = self.variables[name][1] - self.variables[name][0]
            normed_data[name] = (
                input_points[name] - self.variables[name][0]
            ) / width

    if len(normed_data):
        return pd.DataFrame(normed_data)
    else:
        return pd.DataFrame([])

xopt.vocs.VOCS.objective_data

objective_data(data, prefix='objective_', return_raw=False)

Returns a dataframe containing objective data transformed according to vocs.objectives such that we always assume minimization.

Returns:

Type	Description
result: DataFrame	Processed Dataframe

Source code in xopt/vocs.py

def objective_data(
    self,
    data: Union[pd.DataFrame, List[Dict], List[Dict]],
    prefix: str = "objective_",
    return_raw=False,
) -> pd.DataFrame:
    """
    Returns a dataframe containing objective data transformed according to
    `vocs.objectives` such that we always assume minimization.

    Parameters
    ----------
        data: DataFrame
            Data to be processed.
        prefix: str, optional
            Prefix added to column names.

    Returns
    -------
        result: DataFrame
            Processed Dataframe
    """
    return form_objective_data(self.objectives, data, prefix, return_raw)

xopt.vocs.VOCS.observable_data

observable_data(data, prefix='observable_')

Returns a dataframe containing observable data

Returns:

Type	Description
result: DataFrame	Processed Dataframe

Source code in xopt/vocs.py

def observable_data(
    self,
    data: Union[pd.DataFrame, List[Dict], List[Dict]],
    prefix: str = "observable_",
) -> pd.DataFrame:
    """
    Returns a dataframe containing observable data

    Parameters
    ----------
        data: DataFrame
            Data to be processed.
        prefix: str, optional
            Prefix added to column names.

    Returns
    -------
        result: DataFrame
            Processed Dataframe
    """
    return form_observable_data(self.observable_names, data, prefix)

xopt.vocs.VOCS.random_inputs

random_inputs(n=None, custom_bounds=None, include_constants=True, seed=None)

Uniform sampling of the variables.

Returns a dict of inputs.

If include_constants, the vocs.constants are added to the dict.

Optional: n (integer) to make arrays of inputs, of size n. seed (integer) to initialize the random number generator

Source code in xopt/vocs.py

def random_inputs(
    self,
    n: int = None,
    custom_bounds: dict = None,
    include_constants: bool = True,
    seed: int = None,
) -> list[dict]:
    """
    Uniform sampling of the variables.

    Returns a dict of inputs.

    If include_constants, the vocs.constants are added to the dict.

    Optional:
        n (integer) to make arrays of inputs, of size n.
        seed (integer) to initialize the random number generator

    """
    inputs = {}
    if seed is None:
        rng_sample_function = np.random.random
    else:
        rng = np.random.default_rng(seed=seed)
        rng_sample_function = rng.random

    # get bounds
    # if custom_bounds is specified then they will be clipped inside
    # vocs variable bounds -- raise a warning in this case
    if custom_bounds is None:
        bounds = self.variables
    else:
        variable_bounds = pd.DataFrame(self.variables)

        # check type
        if not isinstance(custom_bounds, dict):
            raise TypeError("`custom_bounds` must be a dict")

        # check custom bounds validity
        try:
            validate_variable_bounds(custom_bounds)
        except ValueError:
            raise ValueError("specified `custom_bounds` not valid")

        old_custom_bounds = deepcopy(custom_bounds)

        custom_bounds = pd.DataFrame(custom_bounds)
        custom_bounds = custom_bounds.clip(
            variable_bounds.iloc[0], variable_bounds.iloc[1], axis=1
        )
        bounds = custom_bounds.to_dict()

        # check to make sure clipped values are not equal -- if not custom_bounds
        # are not inside vocs bounds
        for name, value in bounds.items():
            if value[0] == value[1]:
                raise ValueError(
                    f"specified `custom_bounds` for {name} is "
                    f"outside vocs domain"
                )

        # if clipping was used then raise a warning
        if bounds != old_custom_bounds:
            warnings.warn(
                "custom bounds were clipped by vocs bounds", RuntimeWarning
            )

        for k in bounds.keys():
            bounds[k] = [bounds[k][i] for i in range(2)]

    for key, val in bounds.items():  # No need to sort here
        a, b = val
        x = rng_sample_function(n)
        inputs[key] = x * a + (1 - x) * b

    # Constants
    if include_constants and self.constants is not None:
        inputs.update(self.constants)

    if n is None:
        return [inputs]
    else:
        return pd.DataFrame(inputs).to_dict("records")

xopt.vocs.VOCS.select_best

select_best(data, n=1)

get the best value and point for a given data set based on vocs - does not work for multi-objective problems - data that violates any constraints is ignored

Returns:

Type	Description
index: index of best point	value: value of best point params: input parameters that give the best point

Source code in xopt/vocs.py

def select_best(self, data: pd.DataFrame, n: int = 1):
    """
    get the best value and point for a given data set based on vocs
    - does not work for multi-objective problems
    - data that violates any constraints is ignored

    Parameters
    ----------
        data: DataFrame
            Dataframe to select best point from
        n: int, optional
            Number of best points to return

    Returns
    -------
        index: index of best point
        value: value of best point
        params: input parameters that give the best point
    """
    if self.n_objectives != 1:
        raise NotImplementedError(
            "cannot select best point when n_objectives is not 1"
        )

    if data.empty:
        raise RuntimeError("cannot select best point if dataframe is empty")

    feasible_data = self.feasibility_data(data)
    if feasible_data.empty:
        raise RuntimeError(
            "cannot select best point if no points satisfy the given constraints"
        )

    ascending_flag = {"MINIMIZE": True, "MAXIMIZE": False}
    obj = self.objectives[self.objective_names[0]]
    obj_name = self.objective_names[0]
    res = data[feasible_data["feasible"]].sort_values(
        obj_name, ascending=ascending_flag[obj]
    )[obj_name][:n]

    params = data.iloc[res.index.to_numpy()][self.variable_names].to_dict(
        orient="records"
    )[0]

    return res.index.to_numpy(), res.to_numpy(), params

xopt.vocs.VOCS.validate_input_data

validate_input_data(input_points)

Validates input data. Raises an error if the input data does not satisfy requirements given by vocs.

Returns:

Type	Description
None

Raises:

Type	Description
ValueError: if input data does not satisfy requirements.

Source code in xopt/vocs.py

def validate_input_data(self, input_points: pd.DataFrame) -> None:
    """
    Validates input data. Raises an error if the input data does not satisfy
    requirements given by vocs.

    Parameters
    ----------
        input_points : DataFrame
            Input data to be validated.

    Returns
    -------
        None

    Raises
    ------
        ValueError: if input data does not satisfy requirements.
    """
    validate_input_data(self, input_points)

xopt.vocs.VOCS.variable_data

variable_data(data, prefix='variable_')

Returns a dataframe containing variables according to vocs.variables in sorted order

Returns:

Type	Description
result: DataFrame	Processed Dataframe

Source code in xopt/vocs.py

def variable_data(
    self,
    data: Union[pd.DataFrame, List[Dict], List[Dict]],
    prefix: str = "variable_",
) -> pd.DataFrame:
    """
    Returns a dataframe containing variables according to `vocs.variables` in sorted
    order

    Parameters
    ----------
        data: DataFrame
            Data to be processed.
        prefix: str, optional
            Prefix added to column names.

    Returns
    -------
        result: DataFrame
            Processed Dataframe
    """
    return form_variable_data(self.variables, data, prefix=prefix)