timor.configuration_search.LiuIterator

Classes

Indices

Wrapper to collect the current state/module indexed when iterating over a library

Science2019

This iterator returns assemblies according to the criteria defined in the paper:

Functions

alphanumeric_sort_db(db)

Helper method to sort a module db alphabetically

Module Contents

class timor.configuration_search.LiuIterator.Indices

Wrapper to collect the current state/module indexed when iterating over a library

base: int
eef: int
joints: int
valid_joint_combination_id: int
class timor.configuration_search.LiuIterator.Science2019(db, min_dof=0, max_dof=6, min_links_between_joints=0, max_links_between_joints=3, max_links_before_first_joint=0, max_links_after_last_joint=0)
Inheritance diagram of timor.configuration_search.LiuIterator.Science2019

This iterator returns assemblies according to the criteria defined in the paper:

“Effortless creation of safe robots from timor.Modules through self-programming and self-verification” by M. Althoff, A. Giusti, S.B. Liu, A.Pereira, https://mediatum.ub.tum.de/doc/1506779/gy8gyea2c5vyn65ely4bnzom6.Althoff-2019-ScienceRobotics.pdf

Iteration happens in a depth-first manner, iterating over links the fastest, then joint combinations, then end-effectors and slowest over bases.

This class is named after the author who initially came up with the idea of the here implemented search space reduction, Stefan Liu.

The following constraints reduce the search space of possible assemblies:

  • The robot is a serial chain of modules. Every module has a proximal (=female) and a distal (=male) connector.

  • A maximum number of degrees of freedom (default: 6)

  • There are never two joints mounted directly after one another

  • There is a maximum of three static links in between two joints

  • The first module must be a joint module (this is not explicitly mentioned in the paper but can be derived from the modules they used)

  • The last module before the end-effector must be a joint. This can theoretically be relaxed in the future.

This implementation of the LiuIterator allows for a bit more flexibility than the one mentioned in the paper:

Parameters:

  • db (timor.Module.ModulesDB) – The database to build the assembly from. To work properly, every module in the db should clearly belong to one of the four categories {base, joint module, link module, end-effector}. Sane behavior for databases with multi-joint or other complex modules is not guaranteed

  • min_dof (int) – The minimum number of joints in the robot.

  • max_dof (int) – The maximum number of joints in the robot. The end-effector is not counted as a degree of freedom. Changing the default from 6 to another value would mean to differ from the paper. Other than the method from the referenced paper, min_dof is not implicitly equal to max_dof.

  • min_links_between_joints (int) – The minimum number of links between two joints in an assembly.

  • max_links_between_joints (int) – The maximum number of links between two joints. Default 3 is from Liu paper.

  • max_links_before_first_joint (int) – The maximum number of links between a base and the first joint.

  • max_links_after_last_joint (int) – The maximum number of links between the last joint and the end-effector.

__class_getitem__
__iter__()

Iterators are self-iterable: https://peps.python.org/pep-0234/

__len__()

Calculates and returns the total number of possible assemblies created by this iterator.

__next__()

Iterate over:

  • Bases

  • Joints+Links

  • End-Effectors

in a depth first manner. Really rough estimation: 0.2ms per call on 1 processor

Raises:

StopIteration

Return type:

timor.Module.ModuleAssembly

__slots__ = ()
classmethod __subclasshook__(C)
_check_db_valid()

Performs some sanity checks on the given db to validate made assumptions on its structure.

Those are:

  • There’s at least one base, joint link and end-effector [crucial]

  • All modules are connectable [not necessary, but instantiating two iterators would be preferred if not]

  • Every link and joint module has a distal/male and a proximal/female part [crucial]

  • All bases connect to adjacent modules using the same connector/interface [rp]

  • All end effectors connect to adjacent modules using the same connector/interface [rp] rp = “relaxation possible but adaption of class methods necessary”

_current_joint_combination: Tuple[str, Ellipsis]
_current_num_joint_combinations: int
_current_num_joint_modules: int
_db: timor.Module.ModulesDB
_extract_connections()

Maps modules to possible connecting modules

Note: this unidirectional extraction of possible connections is possible because this class works with the crucial simplification that we have unidirectional modules with a distal and proximal part! :return: For each module in the DB, extracts which modules can follow

Return type:

Dict[str, Tuple[str, Ellipsis]]

abstractmethod _extract_eef_distance()

For each module, calculates the “shortest path” to the end effector,

Returns:

_identify_augmented_base_eef()

Extracts all possible “augmented” bases and end effectors.

What we do here is defining an extended base and extended end-effector. Every possible combination of base and attached links as well as every possible combination of static links and end-effector is extracted and will be treated as a different base/eef “module” from here on.

Returns:

A tuple of two tuples. The first tuple contains all possible combinations of base and attached links. The second tuple contains all possible combinations of static links and end-effector.

Return type:

Tuple[Tuple[Tuple[str, Ellipsis], Ellipsis], Tuple[Tuple[str, Ellipsis], Ellipsis]]

_identify_base_chain_eef()

For all augmented bases, end-effectors, returns a mapping to functional joint combinations in between

_identify_joint_combinations()
Returns:

A tuple with all possible (allowed) combinations of joints, ordered from base to eef

Return type:

Tuple[Tuple[str, Ellipsis], Ellipsis]

Extracts possible tuples of links as they could be built in an assembly.

Note: Without any filters, this will generate

sum_over_0_max_in_between_links [num_different_links^max_links_between_joints]

combinations (which may become infeasible large in max_links_between_joints is not chosen carefully). Even with filters, this can grow rapidly! :return: A tuple with all possible (allowed) combinations of links that can be in between two joints

Return type:

Tuple[Tuple[str, Ellipsis], Ellipsis]

Enumerates all possible combinations of links in between two joints

Returns a mapping from every possible combination of parent and child joint to link combinations that can be in between.

Returns:

A mapping from (parent_joint_id, child_joint_id) to a tuple of tuples, each of which contains between one and max_links_between_joints integers that index the classes link modules

Return type:

Dict[Tuple[str, str], Tuple[Tuple[int, Ellipsis], Ellipsis]]

_increment_base()

Iterates over bases. Does not raise StopIteration, this needs to be done in the __next__ method!

_increment_end_effector()

Iterates over end effectors available

_increment_joint_combination()

Iterates over joint combinations available

Iterates over link combinations available

Parameters:

idx (int)

_increment_state()

Call after every iteration to return the next element when calling __next__ the next time

_state: Indices
augmented_bases: Tuple[Tuple[str, Ellipsis], Ellipsis] = ()
augmented_end_effectors: Tuple[Tuple[str, Ellipsis], Ellipsis] = ()
bases: Tuple[timor.Module.AtomicModule]
property current_base: Tuple[str, Ellipsis]

Utility property to return the IDs of the currently used augmented base

Return type:

Tuple[str, Ellipsis]

property current_eef: Tuple[str, Ellipsis]

Utility property to return the IDs of the currently used augmented end-effector

Return type:

Tuple[str, Ellipsis]

property db: timor.Module.ModulesDB

Wrapper property to avoid resetting the db

Return type:

timor.Module.ModulesDB

end_effectors: Tuple[timor.Module.AtomicModule]
joint_combinations: Tuple[Tuple[str, Ellipsis], Ellipsis]
joint_combinations_for_base_eef: Dict[Tuple[str, str], Tuple[int]]
joints: Tuple[timor.Module.AtomicModule]
max_dof: int
min_dof: int
module_connects: Dict[str, Tuple[str, Ellipsis]]
reset()

Resets the indices used to iterate over modules.

Return type:

None

property state: Indices

Implementation as property necessary to define abstractmethod

Return type:

Indices

property valid_joint_combinations: Tuple[int]

Returns a tuple of integers indexing the self.joint_combinations attribute.

This tuple contains only these indices that are valid for the current combination of base and end-effector.

Return type:

Tuple[int]

timor.configuration_search.LiuIterator.alphanumeric_sort_db(db)

Helper method to sort a module db alphabetically

Parameters:

db (timor.Module.ModulesDB)

Return type:

Tuple[timor.Module.AtomicModule, Ellipsis]