symforce.values.generated_key_selection module#

The C++ Values object uses fixed-size Key structs that contain a char with integer subscript and superscript. SymPy symbols can have arbitrary string names. This module contains heuristics to map from string symbol names to Key types that are reasonably intuitive and debuggable. Some of these heuristics include:

Works best if the symbol names are snake case, although supports non-snake-case or strings that aren’t variable names. General strategy is to try the following for each name, until we find a key that is available to pick:

  1. The first letter of each word (words defined by separating on underscores)

  2. All the other characters in the name

For each character we try, we’ll prefer the lowercase version, and then the uppercase version if lowercase is taken. If the name has a number in it, we’ll first try using that as the subscript, or won’t use a subscript if there’s already a key with the same letter and subscript. For example:

pick_generated_keys_for_variable_names(['foo', 'foo2', 'foo_bar', 'foo_bar2', 'foo_baz'])

returns:

{
    'foo': ('f', None),
    'foo2': ('f', 2),
    'foo_bar': ('F', None),
    'foo_bar2': ('F', 2),
    'foo_baz': ('b', None)
}

For a more thorough example, see symforce_values_generated_key_selection_test.py.

class GeneratedKey(letter, sub=None)[source]#

Bases: tuple

A Key to generate, with a single letter and optional subscript

Parameters:

  • letter (str) –

  • sub (int | None) –

letter: str#

Alias for field number 0

sub: int | None#

Alias for field number 1

pick_generated_keys_for_variable_names(names, excluded_keys=None)[source]#

Pick a character (and possibly a subscript) to represent each string in names

See module docstring for the heuristics used to pick characters and subscripts

Parameters:

  • names (Sequence[str]) – List of strings to generate keys for

  • excluded_keys (Set[GeneratedKey] | None) – Set of GeneratedKeys to exclude from the allowed keys

Return type:

Dict[str, GeneratedKey]