Vocs

xopt.vocs.VOCS

Bases: XoptBaseModel

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

Attributes:

variables : Dict[str, conlist(float, min_length=2, max_length=2)] Input variable names with a list of minimum and maximum values. constraints : Dict[str, conlist(Union[float, ConstraintEnum], min_length=2, max_length=2)] Constraint names with a list of constraint type and value. objectives : Dict[str, ObjectiveEnum] Objective names with type of objective. constants : Dict[str, Any] Constant names and values passed to evaluate function. observables : List[str] Observation names tracked alongside objectives and constraints.

Methods:

from_yaml(cls, yaml_text: str) -> 'VOCS' Create a VOCS object from a YAML string. as_yaml(self) -> str Convert the VOCS object to a YAML string. random_inputs(self, n: int = None, custom_bounds: dict = None, include_constants: bool = True, seed: int = None) -> list[dict] Uniform sampling of the variables. convert_dataframe_to_inputs(self, data: pd.DataFrame, include_constants: bool = True) -> pd.DataFrame Extracts only inputs from a dataframe. convert_numpy_to_inputs(self, inputs: np.ndarray, include_constants: bool = True) -> pd.DataFrame Convert 2D numpy array to list of dicts (inputs) for evaluation. 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. objective_data(self, data: Union[pd.DataFrame, List[Dict], List[Dict]], prefix: str = "objective_", return_raw: bool = False) -> pd.DataFrame Returns a dataframe containing objective data transformed according to vocs.objectives. 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. observable_data(self, data: Union[pd.DataFrame, List[Dict], List[Dict]], prefix: str = "observable_") -> pd.DataFrame Returns a dataframe containing observable data. 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. 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. 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. 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. extract_data(self, data: pd.DataFrame, return_raw: bool = False, return_valid: bool = False) -> tuple Split dataframe into separate dataframes for variables, objectives and constraints based on vocs. select_best(self, data: pd.DataFrame, n: int = 1) -> tuple Get the best value and point for a given data set based on vocs. cumulative_optimum(self, data: pd.DataFrame) -> pd.DataFrame Returns the cumulative optimum for the given DataFrame.

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

Returns:

Type	Description
ndarray	The bounds array.

xopt.vocs.VOCS.constant_names property

constant_names

Returns a sorted list of constant 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 observables

xopt.vocs.VOCS.n_outputs property

n_outputs

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

Returns:

Type	Description
int	The number of outputs.

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.observable_names property

observable_names

Returns a sorted list of observable names

xopt.vocs.VOCS.output_names property

output_names

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

Returns:

Type	Description
List[str]	The list of expected output keys.

xopt.vocs.VOCS.variable_names property

variable_names

Returns a sorted list of variable names

Functions

xopt.vocs.VOCS.as_yaml

as_yaml()

Convert the VOCS object to a YAML string.

Returns:

Type	Description
str	The YAML string representation of the VOCS object.

Source code in xopt/vocs.py

def as_yaml(self) -> str:
    """
    Convert the VOCS object to a YAML string.

    Returns
    -------
    str
        The YAML string representation of the VOCS object.
    """
    return yaml.dump(self.model_dump(), default_flow_style=None, sort_keys=False)

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.

Parameters:

Name	Type	Description	Default
data	Union[DataFrame, List[Dict]]	The data to be processed.	required
prefix	str	Prefix added to column names. Defaults to "constraint_".	'constraint_'

Returns:

Type	Description
DataFrame	The processed dataframe.

Source code in xopt/vocs.py

def constraint_data(
    self,
    data: pd.DataFrame | 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 : Union[pd.DataFrame, List[Dict]]
        The data to be processed.
    prefix : str, optional
        Prefix added to column names. Defaults to "constraint_".

    Returns
    -------
    pd.DataFrame
        The 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.

Parameters:

Name	Type	Description	Default
data	DataFrame	The dataframe to extract inputs from.	required
include_constants	bool	Whether to include constants in the inputs. Defaults to True.	True

Returns:

Type	Description
DataFrame	A dataframe containing the extracted inputs.

Source code in xopt/vocs.py

def convert_dataframe_to_inputs(
    self, data: pd.DataFrame, include_constants: bool = True
) -> pd.DataFrame:
    """
    Extracts only inputs from a dataframe.
    This will add constants if `include_constants` is true.

    Parameters
    ----------
    data : pd.DataFrame
        The dataframe to extract inputs from.
    include_constants : bool, optional
        Whether to include constants in the inputs. Defaults to True.

    Returns
    -------
    pd.DataFrame
        A dataframe containing the extracted inputs.
    """
    # 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())

Parameters:

Name	Type	Description	Default
inputs	ndarray	The 2D numpy array to convert.	required
include_constants	bool	Whether to include constants in the inputs. Defaults to True.	True

Returns:

Type	Description
DataFrame	A dataframe containing the converted inputs.

Source code in xopt/vocs.py

def convert_numpy_to_inputs(
    self, inputs: np.ndarray, include_constants: bool = 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())`

    Parameters
    ----------
    inputs : np.ndarray
        The 2D numpy array to convert.
    include_constants : bool, optional
        Whether to include constants in the inputs. Defaults to True.

    Returns
    -------
    pd.DataFrame
        A dataframe containing the converted inputs.
    """
    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:

Type	Description
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
    -------
    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 observable_data : DataFrame Dataframe containing observable 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
        observable_data : DataFrame
            Dataframe containing observable 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.loc[feasible_status, :],
            objective_data.loc[feasible_status, :],
            constraint_data.loc[feasible_status, :],
            observable_data.loc[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.

Parameters:

Name	Type	Description	Default
data	Union[DataFrame, List[Dict]]	The data to be processed.	required
prefix	str	Prefix added to column names. Defaults to "feasible_".	'feasible_'

Returns:

Type	Description
DataFrame	The processed dataframe.

Source code in xopt/vocs.py

def feasibility_data(
    self,
    data: pd.DataFrame | 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 : Union[pd.DataFrame, List[Dict]]
        The data to be processed.
    prefix : str, optional
        Prefix added to column names. Defaults to "feasible_".

    Returns
    -------
    pd.DataFrame
        The processed dataframe.
    """
    return form_feasibility_data(self.constraints, data, prefix)

xopt.vocs.VOCS.from_yaml classmethod

from_yaml(yaml_text)

Create a VOCS object from a YAML string.

Parameters:

Name	Type	Description	Default
yaml_text	str	The YAML string to create the VOCS object from.	required

Returns:

Type	Description
VOCS	The created VOCS object.

Source code in xopt/vocs.py

@classmethod
def from_yaml(cls, yaml_text: str) -> "VOCS":
    """
    Create a VOCS object from a YAML string.

    Parameters
    ----------
    yaml_text : str
        The YAML string to create the VOCS object from.

    Returns
    -------
    VOCS
        The created VOCS object.
    """
    loaded = yaml.safe_load(yaml_text)
    return cls(**loaded)

xopt.vocs.VOCS.grid_inputs

grid_inputs(n, custom_bounds=None, include_constants=True)

Generate a meshgrid of inputs.

Parameters:

Name	Type	Description	Default
n	Union[int, Dict[str, int]]	Number of points to generate along each axis. If an integer is provided, the same number of points is used for all variables. If a dictionary is provided, it should have variable names as keys and the number of points as values.	required
custom_bounds	dict	Custom bounds for the variables. If None, the default bounds from self.variables are used. The dictionary should have variable names as keys and a list of two values [min, max] as values.	None
include_constants	bool	If True, include constant values from self.constants in the output DataFrame.	True

Returns:

Type	Description
DataFrame	A DataFrame containing the generated meshgrid of inputs. Each column corresponds to a variable, and each row represents a point in the grid.

Raises:

Type	Description
TypeError	If custom_bounds is not a dictionary.
ValueError	If custom_bounds are not valid or are outside the domain of self.variables.

Warns:

Type	Description
RuntimeWarning	If custom_bounds are clipped by the bounds of self.variables.

Notes

The function generates a meshgrid of inputs based on the specified bounds. If custom_bounds are provided, they are validated and clipped to ensure they lie within the domain of self.variables. The resulting meshgrid is flattened and returned as a DataFrame. If include_constants is True, constant values from self.constants are added to the DataFrame.

Source code in xopt/vocs.py

def grid_inputs(
    self,
    n: int | dict[str, int],
    custom_bounds: dict = None,
    include_constants: bool = True,
) -> pd.DataFrame:
    """
    Generate a meshgrid of inputs.

    Parameters
    ----------
    n : Union[int, Dict[str, int]]
        Number of points to generate along each axis. If an integer is provided, the same number of points
        is used for all variables. If a dictionary is provided, it should have variable names as keys and
        the number of points as values.
    custom_bounds : dict, optional
        Custom bounds for the variables. If None, the default bounds from `self.variables` are used.
        The dictionary should have variable names as keys and a list of two values [min, max] as values.
    include_constants : bool, optional
        If True, include constant values from `self.constants` in the output DataFrame.

    Returns
    -------
    pd.DataFrame
        A DataFrame containing the generated meshgrid of inputs. Each column corresponds to a variable,
        and each row represents a point in the grid.

    Raises
    ------
    TypeError
        If `custom_bounds` is not a dictionary.
    ValueError
        If `custom_bounds` are not valid or are outside the domain of `self.variables`.

    Warns
    -----
    RuntimeWarning
        If `custom_bounds` are clipped by the bounds of `self.variables`.

    Notes
    -----
    The function generates a meshgrid of inputs based on the specified bounds. If `custom_bounds` are provided,
    they are validated and clipped to ensure they lie within the domain of `self.variables`. The resulting meshgrid
    is flattened and returned as a DataFrame. If `include_constants` is True, constant values from `self.constants`
    are added to the DataFrame.
    """
    bounds = clip_variable_bounds(self, custom_bounds)

    grid_axes = []
    for key, val in bounds.items():
        if isinstance(n, int):
            num_points = n
        elif isinstance(n, dict) and key in n:
            num_points = n[key]
        else:
            raise ValueError(
                f"Number of points for variable '{key}' not specified."
            )
        grid_axes.append(np.linspace(val[0], val[1], num_points))

    mesh = np.meshgrid(*grid_axes)
    inputs = {key: mesh[i].flatten() for i, key in enumerate(bounds.keys())}

    if include_constants and self.constants is not None:
        for key, value in self.constants.items():
            inputs[key] = np.full_like(next(iter(inputs.values())), value)

    return pd.DataFrame(inputs)

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:

Type	Description
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
    -------
    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.

Parameters:

Name	Type	Description	Default
data	Union[DataFrame, List[Dict]]	The data to be processed.	required
prefix	str	Prefix added to column names. Defaults to "objective_".	'objective_'
return_raw	bool	Whether to return raw objective data. Defaults to False.	False

Returns:

Type	Description
DataFrame	The processed dataframe.

Source code in xopt/vocs.py

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

    Parameters
    ----------
    data : Union[pd.DataFrame, List[Dict]]
        The data to be processed.
    prefix : str, optional
        Prefix added to column names. Defaults to "objective_".
    return_raw : bool, optional
        Whether to return raw objective data. Defaults to False.

    Returns
    -------
    pd.DataFrame
        The 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.

Parameters:

Name	Type	Description	Default
data	Union[DataFrame, List[Dict]]	The data to be processed.	required
prefix	str	Prefix added to column names. Defaults to "observable_".	'observable_'

Returns:

Type	Description
DataFrame	The processed dataframe.

Source code in xopt/vocs.py

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

    Parameters
    ----------
    data : Union[pd.DataFrame, List[Dict]]
        The data to be processed.
    prefix : str, optional
        Prefix added to column names. Defaults to "observable_".

    Returns
    -------
    pd.DataFrame
        The 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.

Parameters:

Name	Type	Description	Default
n	int	Number of samples to generate. Defaults to None.	None
custom_bounds	dict	Custom bounds for the variables. Defaults to None.	None
include_constants	bool	Whether to include constants in the inputs. Defaults to True.	True
seed	int	Seed for the random number generator. Defaults to None.	None

Returns:

Type	Description
list[dict]	A list of dictionaries containing the sampled inputs.

Source code in xopt/vocs.py

def random_inputs(
    self,
    n: int = None,
    custom_bounds: dict[str, list[float]] = 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.

    Parameters
    ----------
    n : int, optional
        Number of samples to generate. Defaults to None.
    custom_bounds : dict, optional
        Custom bounds for the variables. Defaults to None.
    include_constants : bool, optional
        Whether to include constants in the inputs. Defaults to True.
    seed : int, optional
        Seed for the random number generator. Defaults to None.

    Returns
    -------
    list[dict]
        A list of dictionaries containing the sampled inputs.
    """
    inputs = {}
    if seed is None:
        rng_sample_function = np.random.random
    else:
        rng = np.random.default_rng(seed=seed)
        rng_sample_function = rng.random

    bounds = clip_variable_bounds(self, custom_bounds)

    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 or (~feasible_data["feasible"]).all():
        raise FeasibilityError(
            "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.loc[feasible_data["feasible"], :]
        .sort_values(obj_name, ascending=ascending_flag[obj])
        .loc[:, obj_name]
        .iloc[:n]
    )

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

    return (
        res.index.to_numpy(copy=True, dtype=int),
        res.to_numpy(copy=True, dtype=float),
        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.

Parameters:

Name	Type	Description	Default
data	Union[DataFrame, List[Dict]]	The data to be processed.	required
prefix	str	Prefix added to column names. Defaults to "variable_".	'variable_'

Returns:

Type	Description
DataFrame	The processed dataframe.

Source code in xopt/vocs.py

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

    Parameters
    ----------
    data : Union[pd.DataFrame, List[Dict]]
        The data to be processed.
    prefix : str, optional
        Prefix added to column names. Defaults to "variable_".

    Returns
    -------
    pd.DataFrame
        The processed dataframe.
    """
    return form_variable_data(self.variables, data, prefix=prefix)