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

keys()[source]

An object providing a view on contained keys.

Return type

KeysView[str]

values()[source]

An object providing a view on contained values.

Return type

ValuesView[Any]

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

Values

copy()[source]

Returns a deepcopy of this Values.

Return type

Values

__len__()[source]

Return the number of elements in this Values

Return type

int

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]

storage_dim()[source]

Dimension of the underlying storage

Return type

int

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

Values

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

Values

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

Values

evalf()[source]

Numerical evaluation.

Return type

Values

identity()[source]

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

Return type

Values

compose(other)[source]

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

Parameters

other (Values) –

Return type

Values

inverse()[source]

Element-wise inverse of this Values

Return type

Values

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

Values

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

Values

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

Matrix

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

Matrix

format(indent=0)[source]

Pretty format as an indented tree.

Parameters

indent (int) – Number of spaces to indent

Return type

str

__repr__()[source]

String representation, simply calls format().

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

__eq__(other)[source]

Exact equality check.

Parameters

other (Any) –

Return type

bool

subs(*args, **kwargs)[source]

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

Parameters
  • args (Any) –

  • kwargs (Any) –

Return type

Values

simplify()[source]

Simplify each scalar element into a new instance.

Return type

Values

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

Values

dataclasses_to_values()[source]

Recursively convert dataclasses to Values

Return type

Values

to_numerical()[source]

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

Return type

Values

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]

__getstate__()[source]

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)[source]

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