Campaign#

Bases: object

Base class for tracking optimization progress and other metrics over multiple iterations.

Parameters:

X_space (ParamSpace) – The parameter space for the campaign.
target (Target | list[Target]) – The target(s) for optimization.
task (TaskType | str | None, optional) – The task type: ‘optimization’ or ‘characterization’. If None, the campaign will issue a warning and default to TaskType.OPTIMIZATION. Pass task='characterization' explicitly for characterization campaigns. Defaults to None.
constraints (Output_Constraint | list[Output_Constraint] | None, optional) – Output constraints for the campaign. Defaults to None.
optimizer (Optimizer | None, optional) –
The optimizer to use. If None, a BayesianOptimizer will be created automatically with default settings. To control fix_random_state, create your own optimizer instance and pass it here:
```
# For stochastic variation
opt = BayesianOptimizer(X_space, seed=123, fix_random_state=False)
campaign = Campaign(X_space, target, optimizer=opt)
```
Defaults to None.
designer (ExpDesigner | None, optional) – The experimental designer for generating initial designs. If None, an ExpDesigner will be created automatically. Defaults to None.
objective (Objective | None, optional) – The objective function for optimization. If None, will be created automatically based on targets. Defaults to None.
seed (int | None, optional) – Random seed for reproducibility. If None and no rng is provided, a time-based seed will be generated. This seed is used to initialize the RNG for the campaign, optimizer, and designer. Defaults to None.
rng (RNGManager | None, optional) – An existing RNGManager instance to share across components. If provided, the campaign will use this shared RNG instead of creating its own. If both rng and seed are provided, seed is ignored. Defaults to None.

X_space#

The parameter space for the campaign.

Type:: ParamSpace

data#

The data collected during the campaign.

Type:: pd.DataFrame

optimizer#

The optimizer used for optimization.

Type:: Optimizer

designer#

The experimental designer used for experiment design.

Type:: ExpDesigner

iter#

The current iteration number.

Type:: int

seed#

The seed for random number generation.

Type:: int

rng#

The random number generator manager for the campaign.

Type:: RNGManager

Properties:: m_exp (int): The number of observations in campaign.data y (pd.Series): The response data in campaign.data y_names (list): The names of the response data columns f (pd.Series): The transformed response data o (pd.Series): The objective function evaluated on f o_names (list): The names of the objective function columns X (pd.DataFrame): The input features of campaign.data response_max (float | pd.Series): The maximum for each response target (Target | list[Target]): The target(s) for optimization. objective (Objective, optional): The objective of the optimization campaign

Note

By default, campaigns use deterministic behavior (fix_random_state=True in the optimizer). To enable stochastic variation, create a custom optimizer with fix_random_state=False and pass it to the campaign.

__init__(X_space: ParamSpace, target: Target | list[Target], task: TaskType | str | None = None, constraints: Output_Constraint | list[Output_Constraint] | None = None, optimizer: Optimizer | None = None, designer: ExpDesigner | None = None, objective: Objective | None = None, seed: int | None = None, rng: RNGManager | None = None)[source]#

Methods

`__init__`(X_space, target[, task, ...])
`add_data`(df)	Adds data to the campaign.
`clear_data`()	Clears campaign data
`clear_objective`()	Clears the campaign objective function
`clear_output_constraints`()	Clears output constraints
`constrain_outputs`(constraints)	Sets optional output constraints for the campaign.
`copy`()	Creates a deep copy of the Campaign object.
`evaluate`(X_suggest)	Maps Optimizer.evaluate method
`evaluate_characterization`([X, PI_range])	Evaluate characterization metrics on specified points.
`fit`([fit_options])	Maps Optimizer.fit method
`initialize`(**design_kwargs)	Maps ExpDesigner.initialize method
`load_state`(obj_dict)	Loads the state of the campaign from a dictionary.
`save_state`()	Saves the state of the Campaign object as a dictionary.
`score_against_ground_truth`(X, y_true[, PI_range])	Score campaign predictions against ground truth (for benchmarking).
`set_X_space`(X_space)	Sets the campaign ParamSpace
`set_designer`(designer)	Sets the campaign experiment designer
`set_objective`(objective)	(Re)sets the campaign objective function
`set_optimizer`(optimizer)	Sets the campaign optimizer
`set_target`(target)	Sets the experimental target context for the campaign.
`suggest`(**optim_kwargs)	Maps Optimizer.suggest method

Attributes

`X`	Feature columns of the training data
`X_best`	Best performing X values
`X_space`	Campaign ParamSpace
`designer`	Campaign Experimental Designer
`f`	Experimental response data, in transformed space
`m_exp`	Number of observations in training data
`o`	Objective function evaluated on f
`objective`	Campaign Objective function
`optimizer`	Campaign Optimizer
`out`	Returns the objective function as appropriate, else the response data
`response_max`	Maximum response data in training set
`target`	Campaign experimental target(s)
`y`	Experimental response data

property X: DataFrame#: Feature columns of the training data

property X_best: DataFrame#: Best performing X values

property X_space: ParamSpace#: Campaign ParamSpace

add_data(df: DataFrame)[source]#

Adds data to the campaign.

Parameters:

Z_i (pd.DataFrame) – The data to be added to the campaign.

Raises:

KeyError – If all X_names are not in the dataset
KeyError – If all y_names are not in the dataset

clear_data()[source]#: Clears campaign data

clear_objective()[source]#: Clears the campaign objective function

clear_output_constraints()[source]#: Clears output constraints

constrain_outputs(constraints: Output_Constraint | list[Output_Constraint] | None) → None[source]#: Sets optional output constraints for the campaign.

copy()[source]#

Creates a deep copy of the Campaign object.

A shortcut for saving and then loading the state. The presence of the torch objects prevents a direct deepcopy.

Returns:: A deep copy of the Campaign object.
Return type:: Campaign

property designer: ExpDesigner#: Campaign Experimental Designer

evaluate(X_suggest: DataFrame)[source]#: Maps Optimizer.evaluate method

evaluate_characterization(X: DataFrame | int | None = None, PI_range: float = 0.7) → dict[source]#

Evaluate characterization metrics on specified points.

Parameters:

X (pd.DataFrame | int | None) – Points to evaluate (pd.DataFrame), number of Sobol samples (int), or None to use training data
PI_range (float) – Prediction interval coverage (0.7 or 0.95)

Returns:

Per-target and joint classification fractions

Return type:

dict

Raises:

ValueError – If campaign has no thresholds set

property f: Series | DataFrame#: Experimental response data, in transformed space

fit(fit_options: dict | None = None)[source]#

Maps Optimizer.fit method

Raises:: ValueError – If no data has been registered to the campaign

initialize(**design_kwargs)[source]#: Maps ExpDesigner.initialize method

classmethod load_state(obj_dict: dict)[source]#

Loads the state of the campaign from a dictionary.

Parameters:

cls (Campaign) – The class object.
obj_dict (dict) – A dictionary containing the campaign state.

Returns:

A new campaign object with the loaded state.

Return type:

Campaign

property m_exp: int#: Number of observations in training data

property o: Series | DataFrame#: Objective function evaluated on f

property objective: Objective | None#: Campaign Objective function

property optimizer: Optimizer#: Campaign Optimizer

property out: Series | DataFrame#: Returns the objective function as appropriate, else the response data

property response_max: float | Series#: Maximum response data in training set

save_state() → dict[source]#

Saves the state of the Campaign object as a dictionary.

Returns:: A dictionary containing the saved state of the Campaign object.
Return type:: dict

score_against_ground_truth(X: DataFrame, y_true, PI_range: float = 0.7) → dict[source]#

Score campaign predictions against ground truth (for benchmarking).

Parameters:

X (pd.DataFrame) – Points to evaluate
y_true (np.ndarray) – Ground truth values, shape (n_points, n_targets)
PI_range (float) – Prediction interval coverage

Returns:

Jaccard scores and confusion matrices

Return type:

dict

Raises:

ValueError – If campaign has no thresholds set

set_X_space(X_space: ParamSpace)[source]#: Sets the campaign ParamSpace

set_designer(designer: ExpDesigner)[source]#: Sets the campaign experiment designer

set_objective(objective: Objective | None)[source]#: (Re)sets the campaign objective function

set_optimizer(optimizer: Optimizer)[source]#: Sets the campaign optimizer

set_target(target: Target | list[Target])[source]#

Sets the experimental target context for the campaign.

Parameters:: target (Target | list[Target] | None) – The target or list of targets to set.

suggest(**optim_kwargs)[source]#: Maps Optimizer.suggest method

property target#: Campaign experimental target(s)

property y: Series | DataFrame#: Experimental response data