FunctionLogger

class pyvbmc.function_logger.FunctionLogger(fun, D: int, noise_flag: bool, uncertainty_handling_level: int, cache_size: int = 500, parameter_transformer: ParameterTransformer = None, vectorized_target: bool = False)

Class that evaluates a function and caches its values.

Parameters:

funcallable

The function to be logged. fun must take a vector input and return a scalar value and, optionally, the (estimated) SD of the returned value (if the function fun is stochastic); an array of one element stands for its element, for the value and the SD alike. If vectorized_target is true, fun instead takes an (N, D) array and returns an (N,) or (N, 1) array, or a pair of those arrays for user-provided noise.

Dint

The number of dimensions that the function takes as input.

noise_flagbool

Whether the function fun is stochastic or not. It is True exactly when uncertainty_handling_level is above 0.

uncertainty_handling_level{0, 1, 2}

The uncertainty handling level which can be one of (0: none; 1: unknown noise level; 2: user-provided noise).

cache_sizeint, optional

The initial size of caching table (default 500).

parameter_transformerParameterTransformer, optional

A ParameterTransformer is required to transform the parameters between constrained and unconstrained space, by default None.

vectorized_targetbool, optional

Whether fun accepts a two-dimensional batch and returns one value per row. Default False.

__call__(x: ndarray)

Evaluates the function FUN at x and caches values.

Parameters:

xnp.ndarray

The point, in the transformed space, at which the function will be evaluated; the function is called with the point mapped to the original space. The shape of x should be (1, D) or (D,).

Returns:

f_valfloat

The value that the logger holds for the point in the transformed space: the observation in the original space, pooled with the earlier observations at the same point, plus log_abs_det_jacobian of the parameter transformer at x where the logger has a transformer.

SDfloat or None

The SD of this observation: the one the function returned at uncertainty handling level 2, 1 at level 1, and None at level 0.

idxint

The index of the last updated entry.

Raises:

ValueError

If the input cannot be coerced to 1-D.

ValueError

Raise if the function value is not a finite real-valued scalar.

ValueError

Raise if the (estimated) SD (second function output) is not a finite, positive real-valued scalar.

add(x: ndarray, f_val_orig: float, f_sd: float = None, fun_eval_time=nan)

Add an previously evaluated function sample to the function cache.

Parameters:

xnp.ndarray

The point, in the transformed space, at whose image in the original space the function has been evaluated. The shape of x should be (1, D) or (D,).

f_val_origfloat

The result of the evaluation of the function, in the original space.

f_sdfloat, optional

The (estimated) SD of the added value. At uncertainty handling level 2 it is required, the noise of an observation being the caller’s to provide; at level 1 it defaults to 1 and at level 0 it is ignored. By default None.

fun_eval_timefloat

The duration of the time it took to evaluate the function, by default np.nan.

Returns:

f_valfloat

The value that the logger holds for the point in the transformed space: f_val_orig, pooled with the earlier observations at the same point, plus log_abs_det_jacobian of the parameter transformer at x where the logger has a transformer.

SDfloat or None

The SD of this observation: f_sd at uncertainty handling level 2, f_sd or 1 at level 1, and None at level 0.

idxint

The index of the last updated entry.

Raises:

ValueError

If the input cannot be coerced to 1-D.

ValueError

Raise if the function value is not a finite real-valued scalar.

ValueError

Raise if f_sd is missing at uncertainty handling level 2.

ValueError

Raise if the (estimated) SD (second function output) is not a finite, positive real-valued scalar.

finalize()

Remove unused caching entries.

Batch evaluation

FunctionLogger.batch_call evaluates missing rows in one target call while retaining the complete input row order.