symforce.values.values module¶
- class Values(_dict=None, **kwargs)[source]¶
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.x0instead ofv['states.x0'].
- dict¶
Underlying storage - ordered dictionary
- index()[source]¶
Returns the index with structural information to reconstruct this values in
from_storage().- Return type:
- static get_index_from_items(items)[source]¶
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), wheremy_keysare some arbitrary names for each element inmy_list)
- items_recursive()[source]¶
Returns a flat list of key/value pairs for every element in this object in insertion order of highest level dot separated key.
- keys_recursive()[source]¶
Returns a flat list of unique keys for every element in this object in insertion order of highest level dot separated key.
- values_recursive()[source]¶
Returns a flat list of elements stored in this Values object in insertion order of highest level dot separated key.
- subkeys_recursive()[source]¶
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_recursivedoes not return dot-separated keys.
- scalar_keys_recursive()[source]¶
Returns a flat list of keys to each scalar in this object in insertion order of highest level dot separated key.
- classmethod from_storage_index(vector_values, indices)[source]¶
Takes a vectorized values and corresponding indices and reconstructs the original form. Reverse of
to_storage().
- from_storage(elements)[source]¶
Create a Values object with the same structure as self but constructed from a flat list representation. Opposite of
to_storage().
- symbolic(name, **kwargs)[source]¶
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).
- identity()[source]¶
Returns Values object with same structure as self, but with each element as an identity element.
- Return type:
- compose(other)[source]¶
Element-wise compose of each element with another Values of identical structure
- from_tangent(vec, epsilon=0.0)[source]¶
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.
- to_tangent(epsilon=0.0)[source]¶
Returns flat vector representing concatenated tangent spaces of each element.
- retract(vec, epsilon=0.0)[source]¶
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))
- local_coordinates(b, epsilon=0.0)[source]¶
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))
- storage_D_tangent()[source]¶
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.
- Return type:
- tangent_D_storage()[source]¶
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.
- Return type:
- __setitem__(key, value)[source]¶
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]'] = 5will create thefoolist with one entry (5) if thefoolist did not previously exist, andvalues['foo[1]'] = 6will append 6 to thefoolist if it previously had length 1.
- scope(scope)[source]¶
Context manager to apply a name scope to both keys added to the values and new symbols created within the with block.
- add(value, **kwargs)[source]¶
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').
- apply_to_leaves(func)[source]¶
Apply the given function to each leaf node of the Values, and return a new Values. This currently also converts any dataclasses to Values.
- to_numerical()[source]¶
Convert any symbolic types in this Values to numerical quantities. This currently also converts any dataclasses to Values.
- Return type:
- to_dict()[source]¶
Converts this Values object and any Values or Dataclass objects contained within it to dict objects. This is different from
dictbecausedictcan have leaves which are Values objects, whereas the dict returned by this function recursively converts all Values and Dataclass objects into dicts.