Options

class pyvbmc.vbmc.Options(default_options_path: str, evaluation_parameters: dict = None, user_options: dict = None)

Store and validate VBMC options.

Parameters:

default_options_pathstr

The path to the default options. May be absolute or relative to this directory.

evaluation_parametersdict

Parameters used to evaluate the options.

user_optionsdict

User defined values to overwrite default options.

Attributes:

useroptionsset

Options that have been set by the user. Values named here are not overwritten by load_options_file().

eval(key: str, evaluation_parameters: dict)

Evaluate an option using evaluation_parameters if it is a callable, otherwise return the value of the option.

A callable evaluated with a single parameter receives its value by keyword when it takes an argument of that name (a parameter so named that is not positional-only, or **kwargs), and by position otherwise, as MATLAB VBMC’s misc/evaloption_vbmc.m calls option(N), so the name of a single parameter does not matter. A callable whose signature cannot be read receives it by position. With several parameters it receives them as keyword arguments, and its parameters have to carry their names.

Parameters:

keystr

The name of the option.

evaluation_parametersdict

Parameters for the option in case it is a callable, by name. They are ignored if it is not a callable.

Returns:

valobject

Value of the object which has been evaluated if it is a callable.

classmethod init_from_existing_options(default_options_path: str, evaluation_parameters: dict = None, other: Options = None)

Initialize an options instance using default options and another options instance.

Only the user-definied options from the other object will overwrite the default options. Everything else will come from the default options.

Parameters:

default_options_pathstr

The path to the default options. May be absolute or relative to this directory.

evaluation_parametersdict

Parameters used to evaluate the options.

otherOptions

User defined values to overwrite default options.

Returns:

new_optionsOptions

The new options object with the values merged as described above.

integer_vars_mask(D: int)

Read the integer_vars option as a mask over the variables.

A boolean array with one entry per variable is that mask. An array of integers holds the 0-based indices of the integer variables, which have to be distinct and within range. An array of D integers that are all zero or one reads as either and is refused.

Parameters:

Dint

The number of variables.

Returns:

masknp.ndarray

A boolean array of length D, True at the variables that take only integer values.

Raises:

ValueError

When the value is neither a boolean mask of length D nor an array of distinct indices within range.

load_options_file(options_path: str, evaluation_parameters: dict = None, as_user_options: bool = False)

Load options from an ini file and evaluate them using the specified evaluation_parameters.

Note that strings starting with # in the .ini file act as description to the option in the following line.

Parameters:

options_pathstr

The path to an options.ini file that should be loaded. May be absolute or relative to this directory.

evaluation_parametersdict, optional

Parameters used to evaluate the options.

as_user_optionsbool, optional

Whether the file states the user’s choices rather than the defaults PyVBMC ships. The options it sets then join useroptions, so that they survive a later load and are not replaced by update_defaults(). Default False.

uncertainty_handling_on()

Whether the run treats the target log-density as noisy.

It does when the target returns its own noise estimate (specify_target_noise) or when uncertainty_handling asks for the noise level to be inferred.

Returns:

onbool

Whether uncertainty handling is on.

Raises:

ValueError

When uncertainty_handling holds a value that is neither a boolean nor empty, when specify_target_noise holds a value that is not a boolean, or when uncertainty_handling is off while specify_target_noise is set.

update_defaults()

Change defaults as needed based on values of other options.

validate_option_names(options_paths: list)

Check that ini files specified by the list of options_paths contain the option names from this options object at least once.

Note that this method checks not if there are option names in files that are not in the object. After option names are validated, initialization is flagged as complete and self.is_initialized is set to True to prevent further modification of options.

Parameters:

options_pathslist of str

A list of paths to ini files can contain the allowed option names.

Raises:

ValueError

Raised when an option exists in this object but not in one of the specified ini files.

validate_run_limits()

Check the limits on iterations and function evaluations.

max_fun_evals and max_iter have to be positive integers, as misc/setupoptions_vbmc.m:109-114 requires, or infinity for no limit. min_iter has to be a finite non-negative integer, 0 for a run without a minimum: the minimum holds back every termination, the one on the budget of evaluations included unless the run accounts for evaluations made before it (precomputed_evaluations or an initialization_cost), so a run under an infinite one would never stop, or would stop only at its budget. A floating value that lands on an integer counts. A max_iter below min_iter is raised to it, as misc/setupoptions_vbmc.m:115-119 does.

Raises:

ValueError

When max_fun_evals or max_iter is not a positive integer, or min_iter is not a finite non-negative integer.

validate_supplied_option_names(names)

Check that every name of names is one PyVBMC declares.

Parameters:

namesiterable of str

The option names a caller supplied.

Raises:

ValueError

Raised when a name is declared by neither of the shipped ini files.