symforce.values.values module

class Values(_dict=None, **kwargs)

Bases: MutableMapping[str, Any]

Ordered dictionary serializable storage. This class is the basis for specifying both inputs and outputs in symforce. The hierarchy of nested values get code generated into types, and several methods of access and introspection are provided that reduce downstream complexity.

Includes standard operator[] access to keys and values.

attr

Access with dot notation, such as v.attr.states.x0 instead of v['states.x0'].

dict

Underlying storage - ordered dictionary

keys()

An object providing a view on contained keys.

Return type:

KeysView[str]

values()

An object providing a view on contained values.

Return type:

ValuesView[Any]

items()

An object providing a view on contained key/value pairs.

Return type:

ItemsView[str, Any]

get(key, default=None)

Return the value for key if key is in the dictionary, else default.

Parameters:

• key (str) –

• default (any) – Default value if key is not present.

Returns:

any – self[key] or default

Return type:

Any

__deepcopy__(memo)

Returns a deepcopy of this Values.

Use copy.deepcopy to call.

Parameters:

memo (Dict[int, Any]) –

Return type:

Values

copy()

Returns a deepcopy of this Values.

Return type:

Values

__len__()

Return the number of elements in this Values

Return type:

int

index()

Returns the index with structural information to reconstruct this values in from_storage().

Return type:

Dict[str, IndexEntry]

static get_index_from_items(items)

Builds an index from a list of key/value pairs of objects. This function can be called recursively either for the items of a Values object or for the items of a list (using e.g. zip(my_keys, my_list), where my_keys are some arbitrary names for each element in my_list)

Parameters:

items (Iterable[Tuple[str, Any]]) –

Return type:

Dict[str, IndexEntry]

items_recursive()

Returns a flat list of key/value pairs for every element in this object in insertion order of highest level dot separated key.

Return type:

List[Tuple[str, Any]]

keys_recursive()

Returns a flat list of unique keys for every element in this object in insertion order of highest level dot separated key.

Return type:

List[str]

values_recursive()

Returns a flat list of elements stored in this Values object in insertion order of highest level dot separated key.

Return type:

List[Any]

subkeys_recursive()

Returns a flat list of subkeys for every element in this object in insertion order of highest level dot separated key. Unlike keys_recursive(), subkeys_recursive does not return dot-separated keys.

Return type:

List[str]

scalar_keys_recursive()

Returns a flat list of keys to each scalar in this object in insertion order of highest level dot separated key.

Return type:

List[str]

storage_dim()

Dimension of the underlying storage

Return type:

int

to_storage()

Returns a flat list of unique values for every scalar element in this object.

Return type:

List[Any]

classmethod from_storage_index(vector_values, indices)

Takes a vectorized values and corresponding indices and reconstructs the original form. Reverse of to_storage().

Parameters:

• vector_values (list) – Vectorized values

• indices (dict(str, list)) – Dict of key to the source (index, datatype, shape, item_index)

Return type:

Values

from_storage(elements)

Create a Values object with the same structure as self but constructed from a flat list representation. Opposite of to_storage().

Parameters:

elements (List[float]) –

Return type:

Values

symbolic(name, **kwargs)

Create a Values object with the same structure as self, where each element is a symbolic element with the given name prefix. Kwargs are forwarded to sf.Symbol (for example, sympy assumptions).

Parameters:

• name (str) –

• kwargs (Dict) –

Return type:

Values

evalf()

Numerical evaluation.

Return type:

Values

identity()

Returns Values object with same structure as self, but with each element as an identity element.

Return type:

Values

compose(other)

Element-wise compose of each element with another Values of identical structure

Parameters:

other (Values) –

Return type:

Values

inverse()

Element-wise inverse of this Values

Return type:

Values

tangent_dim()

Sum of the dimensions of the embedded manifold of each element

Return type:

int

from_tangent(vec, epsilon=0.0)

Returns a Values object with the same structure as self, but by computing each element using the mapping from its corresponding tangent space vector about identity into a group element.

Parameters:

• vec (List[float]) –

• epsilon (float) –

Return type:

Values

to_tangent(epsilon=0.0)

Returns flat vector representing concatenated tangent spaces of each element.

Parameters:

epsilon (float) –

Return type:

List[float]

retract(vec, epsilon=0.0)

Apply a perturbation vec in the concatenated tangent spaces of each element. Often used in optimization to update nonlinear values from an update step in the tangent space.

NOTE(aaron): We have to override the default LieGroup implementation of retract because not all values we can store here obey retract(a, vec) = compose(a, from_tangent(vec))

Parameters:

• vec (List[float]) –

• epsilon (float) –

Return type:

Values

local_coordinates(b, epsilon=0.0)

Computes a perturbation in the combined tangent space around self to produce b. Often used in optimization to minimize the distance between two group elements.

NOTE(aaron): We have to override the default LieGroup implementation of local_coordinates because not all values we can store here obey local_coordinates(a, b) = to_tangent(between(a, b))

Parameters:

• b (Values) –

• epsilon (float) –

Return type:

List[float]

storage_D_tangent(epsilon=0.0)

Returns a matrix with dimensions (storage_dim x tangent_dim) which represents the jacobian of the flat storage space of self wrt to the flat tangent space of self. The resulting jacobian is a block diagonal matrix, where each block corresponds to the storage_D_tangent for a single element or is zero.

Parameters:

epsilon (float) –

Return type:

Matrix

tangent_D_storage(epsilon=0.0)

Returns a matrix with dimensions (tangent_dim x storage_dim) which represents the jacobian of the flat tangent space of self wrt to the flat storage space of self. The resulting jacobian is a block diagonal matrix, where each block corresponds to the tangent_D_storage for a single element or is zero.

Parameters:

epsilon (float) –

Return type:

Matrix

format(indent=0)

Pretty format as an indented tree.

Parameters:

indent (int) – Number of spaces to indent

Returns:

str

Return type:

str

__repr__()

String representation, simply calls format().

Return type:

str

__setitem__(key, value)

Set an entry at a given path in the Values, creating the path if it doesn’t exist

This means that intermediate Values objects along the path will be created. Intermediate sequences (lists) will be created or appended to only if the index requested is no more than 1 past the current length - e.g. values['foo[0]'] = 5 will create the foo list with one entry (5) if the foo list did not previously exist, and values['foo[1]'] = 6 will append 6 to the foo list if it previously had length 1.

Parameters:

• key (str) –

• value (Any) –

Return type:

None

scope(scope)

Context manager to apply a name scope to both keys added to the values and new symbols created within the with block.

Parameters:

scope (str) –

Return type:

Iterator[None]

add(value, **kwargs)

Add a symbol into the values using its given name, either a Symbol or a string. Allows avoiding duplication of the sort v['foo'] = sf.Symbol('foo').

Parameters:

• value (Symbol or str) –

• kwargs (Any) –

Return type:

None

__eq__(other)

Exact equality check.

Parameters:

other (Any) –

Return type:

bool

subs(*args, **kwargs)

Substitute given values of each scalar element into a new instance.

Parameters:

• args (Any) –

• kwargs (Any) –

Return type:

Values

simplify()

Simplify each scalar element into a new instance.

Return type:

Values

apply_to_leaves(func)

Apply the given function to each leaf node of the Values, and return a new Values. This currently also converts any dataclasses to Values.

Parameters:

func (Callable[[Any], Any]) –

Return type:

Values

dataclasses_to_values()

Recursively convert dataclasses to Values

Return type:

Values

static from_dataclass(d)

Convert a dataclass to a Values object.

Parameters:

d (Dataclass) –

Return type:

Values

to_dataclass(d)

Convert this Values object to a dataclass.

Parameters:

d (Type[Dataclass]) –

Return type:

Dataclass

to_numerical()

Convert any symbolic types in this Values to numerical quantities. This currently also converts any dataclasses to Values.

Return type:

Values

to_dict()

Converts this Values object and any Values or Dataclass objects contained within it to dict objects. This is different from dict because dict can have leaves which are Values objects, whereas the dict returned by this function recursively converts all Values and Dataclass objects into dicts.

Return type:

Dict[str, Any]

__getstate__()

Called when pickling this Values. Because some symengine objects cannot be pickled, we first convert any symbolic types to numerical types, and then store the data + index.

Return type:

Dict[str, Any]

__setstate__(d)

Called when unpickling a Values object. Rebuilds the Values object using the storage data and index of the pickled object.

Parameters:

d (Dict[str, Any]) –

Return type:

None