API Reference¶

class marsopt.Study(double initial_noise=0.33, str direction='minimize', n_init_points=None, final_noise=None, double epsilon=1.0, elite_window=None, random_state=None, verbose=True)¶

Mixed Adaptive Random Search for Optimization

__init__()¶

Initialize the Study.

Parameters:

initial_noise (float, default = 0.33) – Initial noise level.
direction (str, default = "minimize") – Direction of optimization, either “minimize” or “maximize”.
n_init_points (int, default = None) – Number of initial random points. If None, it is set as: max(10, round(sqrt(n_trials)))
final_noise (float, default = None) – Final noise level. If None, it is set as: max(1e-7, min(1.0 / n_trials, initial_noise))
epsilon (float, default = 1.0) – Epsilon-greedy exploration constant. At each adaptive trial, with probability epsilon / (t + 1) a uniform random sample is drawn instead of the elite-guided step (harmonic decay).
elite_window (int, default = None) – If set, only the most recent elite_window completed trials are considered for elite selection. If None, full history is used.
random_state (int, default = None) – Seed for reproducibility. Uses PCG64 BitGenerator internally. If None, a random SeedSequence is used.
verbose (bool, default = True) – Whether to print logs during optimization.

direction¶

str

Type:: direction

elite_window¶

object

Type:: elite_window

epsilon¶

‘double’

Type:: epsilon

final_noise¶

object

Type:: final_noise

initial_noise¶

‘double’

Type:: initial_noise

n_init_points¶

object

Type:: n_init_points

n_trials¶

‘int’

Type:: n_trials

optimize(self, objective_function, int n_trials)¶

Runs the optimization loop.

Parameters:

objective_function (Callable[[Trial], Union[float, int]]) – The function to optimize.
n_trials (int) – The number of trials.

Return type:

None

verbose¶

‘bool’

Type:: verbose

class marsopt.Trial(study, trial_id)¶

Represents a single trial in the optimization process.

Parameters:

study (Study)
trial_id (int)

add_attr(self, str name, value)¶

Add a user-defined attribute to the trial.

Parameters:

name (str) – The name of the attribute.
value (Any) – The value of the attribute.

Return type:

None

suggest_categorical(self, str name, list categories)¶

Suggest a categorical variable value.

Parameters:

name (str) – The name of the variable.
categories (List[str]) – A list of valid string categorical values.

Returns:

The suggested categorical string value.

Return type:

str

suggest_float(self, str name, double low, double high, bool log=False)¶

Suggest a floating-point variable value.

Parameters:

name (str) – The name of the variable.
low (float) – The lower bound of the variable range.
high (float) – The upper bound of the variable range.
log (bool) – Whether the variable is log-scaled.

Returns:

The suggested floating-point value.

Return type:

float

suggest_int(self, str name, int low, int high, bool log=False)¶

Suggest an integer variable value.

Parameters:

name (str) – The name of the variable.
low (int) – The lower bound of the variable range.
high (int) – The upper bound of the variable range.
log (bool) – Whether the variable is log-scaled.

Returns:

The suggested integer value.

Return type:

int