Settings¶

BayBE provides a variety of settings that can be configured to change its behavior. These settings can be adjusted using environment variables or by modifying the baybe.settings.active_settings object in various ways, as detailed below.

Available Settings¶

The following settings are available:

Setting	Description
`cache_campaign_recommendations`	Controls if `Campaign` objects cache their latest set of recommendations.
`cache_directory`	The directory used for persistent caching on disk. Set to `""` or `None` to disable caching.
`parallelize_simulation_runs`	Controls if simulation runs with `xyzpy` are executed in parallel.
`preprocess_dataframes`	Controls if incoming user dataframes are preprocessed (i.e., dtype-converted and validated) before use.
`random_seed`	The used random seed.
`use_fpsample`	Controls if `fpsample` acceleration is to be used, if available.
`use_polars_for_constraints`	Controls if `polars` acceleration is to be used for discrete constraints, if available.
`use_single_precision_numpy`	Controls the floating point precision used for `numpy` arrays.
`use_single_precision_torch`	Controls the floating point precision used for `torch` tensors.

For more information, click on the respective link or have a look at the Settings class documentation.

Changing Settings¶

BayBE offers flexible control over its settings, allowing you to adjust them in different ways, adapted to your specific needs and use cases. If you want to understand the underlying mechanism in detail, have a look here. Otherwise, simply choose the most suitable option from the following alternatives:

Direct Assignment¶

You can change any specific setting by directly assigning a new value to the corresponding attribute of the active_settings object. For example, to set a value for random_seed, simply run:

from baybe import active_settings

active_settings.random_seed = 1337

Validation

To avoid silent bugs, BayBE automatically validates if the referenced setting attribute exists and if the assigned value is compatible:

from baybe import active_settings

active_settings.non_existent_setting = 1337  # <-- error!
active_settings.preprocess_dataframes = "not_representing_a_boolean"  # <-- error!

Joint Activation¶

While you can change several settings one at a time using direct assignment, a more convenient way is to instantiate a baybe.settings.Settings object, which allows to define multiple settings at once. In order for the settings to take effect, call its activate() method:

from baybe import Settings, active_settings

assert active_settings.parallelize_simulation_runs is True
assert active_settings.use_polars_for_constraints is True

Settings(parallelize_simulation_runs=False, use_polars_for_constraints=False).activate()

assert active_settings.parallelize_simulation_runs is False
assert active_settings.use_polars_for_constraints is False

Delayed Activation¶

Adjusting settings via the Settings class has the additional benefit that it allows you to delay the activation of a particular settings configuration to a later point, giving you the possibility to store and organize several configurations in your code. For example:

from baybe import Settings

slow_and_pedantic = Settings(preprocess_dataframes=True, use_fpsample=False)
fast_and_furious = Settings(preprocess_dataframes=False, use_fpsample=True)

You can then active these configurations in various places and in different ways:

Manual Activation¶

To manually activate a particular settings configuration, use its activate() method. The previously active settings will be automatically remembered and can easily be restored at a later point using the corresponding restore_previous() method:

assert active_settings.preprocess_dataframes is True
fast_and_furious.activate()
assert active_settings.preprocess_dataframes is False
fast_and_furious.restore_previous()
assert active_settings.preprocess_dataframes is True

Restoring Previous Settings

Note that restore_previous() restores the settings that were active at the time of the activate() call, not the previously active settings. The latter might potentially have changed in the meantime, depending on execution flow:

from baybe import Settings, active_settings

s_0 = Settings(random_seed=0).activate()
assert active_settings.random_seed == 0

s_42 = Settings(random_seed=42).activate()
assert active_settings.random_seed == 42

s_1337 = Settings(random_seed=1337).activate()
assert active_settings.random_seed == 1337

# At this point, the active seed is 1337, and the previous active seed was 42.
# However, the effect of "restoring settings" crucially depends on which object is used:

s_42.restore_previous()
assert active_settings.random_seed == 0  # <-- the seed before s_42 got activated

s_1337.restore_previous()
assert active_settings.random_seed == 42  # <-- the seed before s_42 got activated

Context Activation¶

Using restore_previous() can be useful in special cases where settings objects need to be passed around. However, in most cases where settings should be activated temporarily within a specific scope, a more convenient approach is to use a context manager:

assert active_settings.preprocess_dataframes is True

# Within the context, the specified settings become active
with fast_and_furious:
    assert active_settings.preprocess_dataframes is False

# Outside the context, the previous settings are restored
assert active_settings.preprocess_dataframes is True

Decorator Activation¶

Finally, Settings objects can also be used to decorate callables, activating the corresponding configuration for the duration of the call:

assert active_settings.preprocess_dataframes is True

@fast_and_furious
def regret_nothing():
    assert active_settings.preprocess_dataframes is False

regret_nothing()  # <-- the assert passes

assert active_settings.preprocess_dataframes is True

Environment Variables¶

Settings can also be controlled via environment variables, which is particularly useful for deploying applications in different environments without having to change any underlying code.

Each individual setting attribute has a corresponding environment variable, written in uppercase letters and prefixed with BAYBE_. For example, the preprocess_dataframes attribute is linked to the BAYBE_PREPROCESS_DATAFRAMES environment variable.

When present, these variables can be used to populate settings attributes instead of falling back to defaults, which is controlled via the restore_environment flag. For further details on how they interact with other value sources and how they affect the initialization of the active_settings at startup time, have a look at our initialization precedence section.

Activation Logic¶

The activation of settings follows two simple rules that allow you to understand the implications of modifying Settings objects:

When executing code, BayBE always reads the current value of settings from the active_settings object, meaning that any changes to this object immediately take effect.
An activate() call on a Settings object copies its attribute values to those of the active_settings object and stores a copy of the previously active values in the object on which the call was made.

This explains, for instance, why:

Direct assignments to attributes of active_settings take immediate global effect.
Calling activate() on a Settings object is equivalent to directly assigning all of its attribute values to the active_settings object one by one.
Adjusting the attribute of any Settings object other than active_settings has no immediate effect on the active settings until its activate() method is called, no matter if it has been activated before or not.
You can restore the settings that were active previous to an activate() call using the restore_previous() method.

Initialization Precedence¶

Initializing a new Settings object follows a specific order of precedence. Specifically, the value of each attribute is determined by whichever of the following rules applies first:

If a value is passed explicitly to the Settings constructor, it always takes the highest precedence.
If restore_environment=True is passed, the value of the setting’s corresponding environment variable is used, provided it exists.
If restore_defaults=True is passed, the default value for the attribute defined by the class is used.
If none of the above applies, the current value from active_settings is retained.

Exception: Random Seed Management

A notable exception to the above rules applies to managing random seeds, for reasons detailed in the Random Seed Control section.

Active Settings Initialization

For convenience, restore_environment is set to True when initializing the active active_settings object at package import time, so that environment variables automatically take effect.

Random Seed Control¶

Unlike other BayBE setting attributes, whose values remain static until changed explicitly, the states of random number generators (RNG) naturally evolve as random numbers are drawn during code execution. Applying the same manipulation rules to random_seed as we do to other settings attributes would therefore lead to rather unexpected behavior from a user’s perspective, especially since the seed value is only used to initialize the RNG states and remains unchanged while the latter progress.

To align RNG control with user expectations, random seed mechanics thus slightly deviate from the otherwise general rules outlined in this user guide:

In contrast to what is dictated by the initialization precedence, specifying a random seed via the BAYBE_RANDOM_SEED environment variable only affects the initialization of the active active_settings object at session start, but has no effect on the instantiation of subsequent Settings objects.
Likewise, Settings objects created by the user do not adopt the random seed from the active_settings object, which avoids unintended RNG state resets when activating such objects.
When restoring previous settings, the RNG states are only reverted if the Settings object in question explicitly specified a random seed during its activation (i.e., the RNG state was deliberately controlled). If no seed was specified, the RNG state remains untouched.