Presets¶

A preset is a saved group of parameter values. Instead of overriding multiple values every time you want a particular configuration, give those values a name and apply them all at once with a preset. This is useful for creating defined variations of models such as different sizes and feature sets.

Declaring presets¶

Presets are declared alongside fields using Preset.

Params classModel class

Define a presets tuple of Preset as a Params subclass attribute:

class P(Params):
    width = Float(10.0, min=5, max=200)
    thickness = Float(3.0, min=1, max=20)

    presets = (
        Preset("small", width=15.0, thickness=2.0),
        Preset("large", width=100.0, thickness=10.0),
    )

Define a presets tuple of Preset as a Model subclass attribute:

class MyBox(Model):
    width = Float(10.0, min=5, max=200)
    thickness = Float(3.0, min=1, max=20)

    presets = (
        Preset("small", width=15.0, thickness=2.0),
        Preset("large", width=100.0, thickness=10.0),
    )

    def build(self):
        pass

Presets don't need to cover every field. Any field not listed in a preset keeps its default value.

Using presets via the CLI¶

Select a preset with --preset:

bdbox with filebdbox with moduleDirect with fileDirect with module

bdbox model.py --preset large

bdbox mypackage.mymodule --preset large

python model.py --preset large

python -m mypackage.mymodule --preset large

Tip

Use export --all-presets to export a model rendered with every preset to a separate file all at once.

Combining presets with overrides¶

Specific field values take precedence over preset values. Use a preset as a baseline and adjust individual fields as needed. For example, in the CLI:

bdbox with filebdbox with moduleDirect with fileDirect with module

bdbox model.py --preset large --thickness 5.0

bdbox mypackage.mymodule --preset large --thickness 5.0

python model.py --preset large --thickness 5.0

python -m mypackage.mymodule --preset large --thickness 5.0

Field value precedence, from highest to lowest:

Field override values
Preset values
Field default values

Preset descriptions¶

Presets accept an optional description shown in --help output:

Preset("large", description="Extra large version", width=100.0, thickness=10.0)

Programmatic use¶

Presets can be applied when instantiating a Model or Params subclass in code.

Apply a preset by name:
```
model = MyBox(preset="large")
```

Apply a preset and override additional fields:

model = MyBox(preset="large", thickness=5.0)

with_preset is equivalent but may more easily pass static type checks:
```
model = MyBox.with_preset("large", thickness=5.0)
```