Expression Function Plugins

Expression Functions are plugins that define the functions that can be used in Pavilion expressions, both within normal Pavilion strings and in result evaluations.

pavilion.expression_functions.get_plugin(name: str) → FunctionPlugin | None

Get the function plugin called ‘name’. Returns None if a plugin with the given name does not exist.

pavilion.expression_functions.list_plugins()

Return the list of function plugin names.

pavilion.expression_functions.register_core_plugins()

Find all the core function plugins and activate them.

FunctionPlugin Base Classes

Contains the base Expression Function plugin class.

pavilion.expression_functions.base.num(val)

Return val as an int, float, or bool, depending on what it most closely resembles.

pavilion.expression_functions.base.flag(flag_str: str, val: str) → str

Return a flag string for a boolean variable, if the variable is set, or an empty string otherwise.

pavilion.expression_functions.base.sopt(option_str: str, val: str | List[str]) → str

Return an option string for a variable, if it has a non-null value, or an empty string otherwise. For a list, create separate option string for each value in the list.

pavilion.expression_functions.base.opt(option_str: str, val: str | List[str], delimiter=',') → str

Return an option string for a variable, if it has a non-null value, or an empty string otherwise. For a list, create a single option string by concatenating the values in the list.

class pavilion.expression_functions.base.Opt(sub_spec: Any)

Bases: object

An optional arg spec, the contained spec is checked if the value is given.

class pavilion.expression_functions.base.MaybeList(sub_spec: Any)

Bases: object

An arg spec that can be either some type, or a list of that same type.

resolve(arg) → Any

class pavilion.expression_functions.base.FunctionPlugin(name, arg_specs, description=None, priority=10)

Bases: IPlugin

Plugin base class for math functions.

Child classes must override __init__ (as is typical for Pavilion plugin), and must also provide a method to act as the function itself. This method must have the same name as the plugin (ie. The ‘max’ plugin must have a ‘max’ method), and take the arguments the function expects.

VALID_SPEC_TYPES = (<class 'int'>, <class 'float'>, <class 'str'>, <class 'bool'>, <function num>, <class 'pavilion.expression_functions.base.Opt'>, <class 'pavilion.expression_functions.base.MaybeList'>, None)

NAME_RE = re.compile('[a-zA-Z][a-zA-Z0-9_]*$')

PRIO_CORE = 0

PRIO_COMMON = 10

PRIO_USER = 20

core = False

property path

The path to the file containing this result parser plugin.

property signature

Generate a function signature for this function. :newlines: Put each argument on a separate line.

property long_description

Return the docstring for the function.

activate()

Yapsy runs this when adding the plugin. Add our plugin to the registry of function plugins.

deactivate()

Yapsy runs this when removing the plugin. Plugins will only be removed by unit tests.

register_core_plugins()

Find all the core function plugins and activate them.

Core Function Plugins

Contains the base expression plugins in a single module to speed Pavilion loading.

class pavilion.expression_functions.core.AllPlugin

Bases: CoreFunctionPlugin

Return whether all of the items in the given list are true.

static all(items)

Just use the built-in all function.

class pavilion.expression_functions.core.AnyPlugin

Bases: CoreFunctionPlugin

Return whether any of the items in the given list are true.

static any(items)

Just use the built-in any function.

class pavilion.expression_functions.core.AvgPlugin

Bases: CoreFunctionPlugin

Get the average of the given numbers.

static avg(vals)

Get the average of vals. Will always return a float.

class pavilion.expression_functions.core.CeilPlugin

Bases: CoreFunctionPlugin

Get the integer ceiling of the given number.

static ceil(val)

Round the given number up to the nearest int.

class pavilion.expression_functions.core.CoreFunctionPlugin(name, arg_specs, description=None)

Bases: FunctionPlugin

A function plugin that sets defaults for core plugins. Use when adding additional function plugins to the core_functions module. Classes that inherit from this will automatically be added as function plugins. If adding non-core functions, use the standard plugin mechanisms.

core = True

class pavilion.expression_functions.core.FactorsPlugin

Bases: CoreFunctionPlugin

Get the factors of the given positive integer.

static factors(val: int) → Tuple[int, ...]

Get the factors of the given positive integer.

class pavilion.expression_functions.core.FlagPlugin

Bases: CoreFunctionPlugin

Convert a boolean(-ish) config option into a UNIX-style flag.

static flag(flag_str: str, val: str)

class pavilion.expression_functions.core.FloorPlugin

Bases: CoreFunctionPlugin

Get the floor of the given number.

static floor(val)

Round the given number down to the nearest int.

class pavilion.expression_functions.core.HighPassFilter

Bases: CoreFunctionPlugin

Given the ‘value_dict’, return a new dictionary that contains only items that exceed ‘limit’. For dicts of dicts, you must specify an item_key to check limit against.

Examples:

Given dict ‘data={a: 1, b: 2, c: 3, d: 4}’, high_pass_filter(data, 3) would return a dict with the ‘c’ and ‘d’ keys removed.

Given dict ‘data={foo: {a: 5}, bar: {a: 100}}, baz: {a: 20}}’ high_pass_filter(data, 20, ‘a’) would return a dict containing only key ‘foo’ and its value/s.

static high_pass_filter(value_dict: Dict, limit: int | float, item_key: str | None = None) → Dict

Return only items > limit

class pavilion.expression_functions.core.IntPlugin

Bases: CoreFunctionPlugin

Convert integer strings to ints of arbitrary bases.

static int(value, base)

Convert the given string ‘value’ as an integer of the given base. Bases from 2-32 are allowed.

class pavilion.expression_functions.core.KeysPlugin

Bases: CoreFunctionPlugin

Return the keys of a given dict.

static keys(arg)

Return a (sorted) list of keys for the given dictionary.

class pavilion.expression_functions.core.LenPlugin

Bases: CoreFunctionPlugin

Return the length of the given item, where item can be a string, list, or dict.

static len(arg)

Just return the length of the argument.

signature = 'len(list|dict|str)'

class pavilion.expression_functions.core.LogPlugin

Bases: CoreFunctionPlugin

Take the log of the given number to the given base.

static log(val: num, base: num)

Take the log of the given number to the given base.

class pavilion.expression_functions.core.LowPassFilter

Bases: CoreFunctionPlugin

Given the ‘value_dict’, return a new dictionary that contains only items that are less than ‘limit’. For dicts of dicts, you must specify a sub-key to check ‘limit’ against. See ‘high_pass_filter’ for examples.

static low_pass_filter(value_dict: Dict, limit: int | float, item_key: str | None = None) → Dict

Return only items > limit

class pavilion.expression_functions.core.MaxPlugin

Bases: CoreFunctionPlugin

Get the max of the given numbers.

static max(vals)

Get the max of vals.

class pavilion.expression_functions.core.MidFactorsPlugin

Bases: CoreFunctionPlugin

Get the two middle factors of the given number. For example, if the number provided is 28, which has the factors [1, 2, 4, 7, 14, 28], the middle two factors of that list would be [4, 7].

static midfactors(val: int) → Tuple[int, int]

Get the middle factors of val. Will always return a list of 2 ints.

class pavilion.expression_functions.core.MinPlugin

Bases: CoreFunctionPlugin

Get the min of the given numbers.

static min(vals)

Get the min of vals.

class pavilion.expression_functions.core.MultipleOfTwoPlugin

Bases: CoreFunctionPlugin

Given a number, produce a list of integers from 1 to that number (inclusive), scaling by factors of 2 until the final value is reached.

static multiples_of_two(val: int) → List[int]

Provide a list of values from 1 to val where each value is double the previous value until the provided value is reached.

class pavilion.expression_functions.core.OptPlugin

Bases: CoreFunctionPlugin

Convert a config option into a UNIX-style option string. If the option is a list, concatenate the elements of the list to form a single option.

static opt(opt_str: str, val: str | List[str], delimiter: str = ',') → str

class pavilion.expression_functions.core.Outliers

Bases: CoreFunctionPlugin

Calculate outliers given a list of values and a separate list of their associated names. The lists should be the same length, and in matching order (which Pavilion should generally guarantee). A value is flagged as an outlier if it is more than ‘limit’ standard deviations from the mean of the values.

Produces a dict of name -> (val - mean)/stddev for only those values flagged as outliers.

Ex: ‘bad_nodes: ‘outliers(n.*.speed, keys(n), 2.0)` This would find any nodes with a speed more than 2.0 std deviations from the mean.

static outliers(values: List[num], names: List[str], limit: float)

Create the outlier dict.

class pavilion.expression_functions.core.RandomPlugin

Bases: CoreFunctionPlugin

Return a random number in [0,1).

static random()

Return a random float in [0,1).

class pavilion.expression_functions.core.Range

Bases: CoreFunctionPlugin

Return a list of numbers from a..b, not inclusive of b.

static range(start, end)

Calculate the range.

class pavilion.expression_functions.core.RegexSearch

Bases: CoreFunctionPlugin

Search for the given regular expression. Returns the matched text or, if a matching group (limit 1) was used, the matched group. Returns an empty string on no match. Regexes use Python’s regex syntax.

static re_search(regex, data)

Search for the given regex in data.

class pavilion.expression_functions.core.Replace

Bases: CoreFunctionPlugin

Replace substrings from a given string.

static replace(string: str, find: str, replacement: str)

Replace all instances of ‘find’ with ‘replacement’ in ‘string’.

class pavilion.expression_functions.core.RoundDigPlugin

Bases: CoreFunctionPlugin

Round the number to N decimal places: round_dig(12.12341234, 3) -> 12.123

static round_dig(val: float, places: int)

Round the given number to the nearest int.

class pavilion.expression_functions.core.RoundPlugin

Bases: CoreFunctionPlugin

Round the given number to the nearest integer.

static round(val: float)

Round the given number to the nearest int.

class pavilion.expression_functions.core.SoptPlugin

Bases: CoreFunctionPlugin

Convert a config option into a UNIX-style option string. If the option is a list, create a separate option string for each element.

static sopt(opt_str: str, val: str | List[str]) → str

class pavilion.expression_functions.core.Sqrt

Bases: CoreFunctionPlugin

Calculate the square root of a given number. Yes, people can just do X^(1/2), but most people forget that.

static sqrt(value: num)

Take a square root.

class pavilion.expression_functions.core.SumPlugin

Bases: CoreFunctionPlugin

Get the floating point sum of the given numbers.

static sum(vals)

Get the sum of the given numbers. Will return an int if all arguments are ints, otherwise returns a float.