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.x0 instead of v[‘states.x0’].
- Parameters:
_dict (
Optional
[Dict
[str
,Any
]]) –kwargs (
Any
) –
- __init__(_dict=None, **kwargs)[source]¶
Create like a Python dict.
- Parameters:
_dict (dict) – Initial values in as a dictionary
kwargs (dict) – Initial values
- items()[source]¶
An object providng a view on contained key/value pairs.
- Return type:
ItemsView
[str
,Any
]
- get(key, default=None)[source]¶
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:
self[key] or default
- Return type:
any
- __deepcopy__(memo)[source]¶
Returns a deepcopy of this Values.
Use copy.deepcopy to call.
- Parameters:
memo (
Dict
[int
,Any
]) –- Return type:
- index()[source]¶
Returns the index with structural information to reconstruct this values in
from_storage()
.- Return type:
Dict
[str
,IndexEntry
]
- 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), 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()[source]¶
Returns a flat list of key/value pairs for every element in this object in insertion order of highest level dot seperated key.
- Return type:
List
[Tuple
[str
,Any
]]
- keys_recursive()[source]¶
Returns a flat list of unique keys for every element in this object in insertion order of highest level dot seperated key.
- Return type:
List
[str
]
- values_recursive()[source]¶
Returns a flat list of elements stored in this Values object in insertion order of highest level dot seperated key.
- Return type:
List
[Any
]
- subkeys_recursive()[source]¶
Returns a flat list of subkeys for every element in this object in insertion order of highest level dot seperated key. Unlike keys_recursive, subkeys_recursive does not return dot-separated keys.
- Return type:
List
[str
]
- scalar_keys_recursive()[source]¶
Returns a flat list of keys to each scalar in this object in insertion order of highest level dot seperated key.
- Return type:
List
[str
]
- to_storage()[source]¶
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)[source]¶
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:
- 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().
- Parameters:
elements (
List
[float
]) –- Return type:
- 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).
- Parameters:
name (
str
) –kwargs (
Dict
) –
- Return type:
- 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
- tangent_dim()[source]¶
Sum of the dimensions of the embedded manifold of each element
- Return type:
int
- 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.
- Parameters:
vec (
List
[float
]) –epsilon (
float
) –
- Return type:
- to_tangent(epsilon=0.0)[source]¶
Returns flat vector representing concatentated tangent spaces of each element.
- Parameters:
epsilon (
float
) –- Return type:
List
[float
]
- retract(vec, epsilon=0.0)[source]¶
Apply a pertubation 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:
- local_coordinates(b, epsilon=0.0)[source]¶
Computes a pertubation 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()[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:
- format(indent=0)[source]¶
Pretty format as an indented tree.
- Parameters:
indent (int) – Number of spaces to indent
- Return type:
str
- __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]’] = 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 previosly had length 1.
- Parameters:
key (
str
) –value (
Any
) –
- Return type:
None
- 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.
- Parameters:
scope (
str
) –- Return type:
Iterator
[None
]
- 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’).
- Parameters:
value (Symbol or str) –
kwargs (
Any
) –
- Return type:
None
- subs(*args, **kwargs)[source]¶
Substitute given values of each scalar element into a new instance.
- Parameters:
args (
Any
) –kwargs (
Any
) –
- Return type:
- 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.
- Parameters:
func (
Callable
[[Any
],Any
]) –- Return type:
- 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 self.dict because self.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
]