Introducing PartialOrder

CHANGELOG.rst

@@ -13,6 +13,7 @@ Unreleased
 **Added**
 
 * Added support for MoveIt on ROS Noetic
+* In`compas.datastructures`, added `Plan`, `PlannedAction`, `Action` and `IntegerIdGenerator`
 
 **Changed**
 

src/compas_fab/datastructures/__init__.py

@@ -0,0 +1,16 @@
+from .plan import (
+    Action,
+    DependencyIdException,
+    IntegerIdGenerator,
+    Plan,
+    PlannedAction
+)
+
+
+__all__ = [
+    'Action',
+    'DependencyIdException',
+    'IntegerIdGenerator',
+    'Plan',
+    'PlannedAction',
+]

src/compas_fab/datastructures/plan.py

@@ -0,0 +1,368 @@
+from __future__ import absolute_import
+from __future__ import division
+from __future__ import print_function
+
+import json
+import threading
+from collections import OrderedDict
+from itertools import count
+
+from compas.base import Base
+from compas.datastructures import Datastructure
+from compas.utilities import DataDecoder
+from compas.utilities import DataEncoder
+
+
+__all__ = [
+    'Action',
+    'DependencyIdException',
+    'IntegerIdGenerator',
+    'Plan',
+    'PlannedAction',
+]
+
+
+class IntegerIdGenerator(Base):
+    """Generator object yielding integers sequentially in a thread safe manner.
+
+    Parameters
+    ----------
+    start_value : :obj:`int`
+        First value to be yielded by the generator.
+    """
+    def __init__(self, start_value=1):
+        super(IntegerIdGenerator, self).__init__()
+        self.last_generated = start_value - 1
+        self._lock = threading.Lock()
+        self._generator = count(start_value)
+
+    def __next__(self):
+        with self._lock:
+            self.last_generated = next(self._generator)
+            return self.last_generated
+
+    @property
+    def data(self):
+        return {
+            'start_value': self.last_generated + 1
+        }
+
+    def to_data(self):
+        return self.data
+
+    @classmethod
+    def from_data(cls, data):
+        return cls(data['start_value'])
+
+    @classmethod
+    def from_json(cls, filepath):
+        with open(filepath, 'r') as fp:
+            data = json.load(fp, cls=DataDecoder)
+        return cls.from_data(data)
+
+    def to_json(self, filepath, pretty=False):
+        with open(filepath, 'w+') as f:
+            if pretty:
+                json.dump(self.data, f, sort_keys=True, indent=4, cls=DataEncoder)
+            else:
+                json.dump(self.data, f, cls=DataEncoder)
+
+
+class DependencyIdException(Exception):
+    """Indicates invalid ids given as dependencies."""
+    def __init__(self, invalid_ids, pa_id=None):
+        message = self.compose_message(invalid_ids, pa_id)
+        super(DependencyIdException, self).__init__(message)
+
+    @staticmethod
+    def compose_message(invalid_ids, pa_id):
+        if pa_id:
+            return 'Planned action {} has invalid dependency ids {}'.format(pa_id, invalid_ids)
+        return 'Found invalid dependency ids {}'.format(invalid_ids)
+
+
+class Plan(Datastructure):
+    """Data structure for holding the information of a partially ordered plan
+    (a directed acyclic graph).  The content of any event of the plan is contained
+    in an :class:`compas_fab.datastructures.Action`. An event is scheduled and
+    added to the plan through a :class:`compas_fab.datastructures.PlannedAction`.
+    The dependency ids of a planned action can be thought of as pointers to the
+    parents of that planned action.
+
+    Parameters
+    ----------
+    planned_actions : list of :class:`compas_fab.datastructures.PlannedAction`
+        The planned actions will be stored as an ordered dictionary, so their
+        ids should be distinct.  Defaults to an empty list.
+    id_generator : Generator[Hashable, None, None]
+        Object which generates keys (via ``next()``) for
+        :class:`compas_fab.datastructures.Action`s added using this object's
+        methods.  Defaults to :class:`compas_fab.datastructures.IntegerIdGenerator`.
+    """
+    def __init__(self, planned_actions=None, id_generator=None):
+        super(Plan, self).__init__()
+        planned_actions = planned_actions or []
+        self.planned_actions = planned_actions
+        if id_generator is None:
+            try:
+                start_value = max(self.planned_actions.keys()) + 1 if self.planned_actions else 1
+            except Exception:
+                raise Exception('Given ids not compatible with default id_generator.')
+            id_generator = IntegerIdGenerator(start_value)
+        self._id_generator = id_generator
+
+    @property
+    def planned_actions(self):
+        return self._planned_actions
+
+    @planned_actions.setter
+    def planned_actions(self, planned_actions):
+        self._planned_actions = OrderedDict({pa.id: pa for pa in planned_actions})
+        self.check_all_dependency_ids()
+
+    def plan_action(self, action, dependency_ids):
+        """Adds the action to the plan with the given dependencies,
+        and generates an id for the newly planned action.
+
+        Parameters
+        ----------
+        action : :class:`comaps_fab.datastructures.Action`
+            The action to be added to the plan.
+        dependency_ids : set or list
+            The keys of the already planned actions that the new action
+            is dependent on.
+
+        Returns
+        -------
+            The id of the newly planned.
+        """
+        self.check_dependency_ids(dependency_ids)
+        action_id = self._get_next_action_id()
+        planned_action = PlannedAction(action_id, action, dependency_ids)
+        self.planned_actions[action_id] = planned_action
+        return action_id
+
+    def append_action(self, action):
+        """Adds the action to the plan dependent on the last action added
+        to the plan, and generates an id for this newly planned action.
+
+        Parameters
+        ----------
+        action : :class:`comaps_fab.datastructures.Action`
+            The action to be added to the plan.
+
+        Returns
+        -------
+            The id of the newly planned.
+        """
+        dependency_ids = set()
+        if self.planned_actions:
+            last_action_id = self._get_last_action_id()
+            dependency_ids = {last_action_id}
+        return self.plan_action(action, dependency_ids)
+
+    def remove_action_by_id(self, action_id):
+        """Removes the action with the given id from the plan and all its
+        dependencies.
+
+        Parameters
+        ----------
+        action_id : Hashable
+            Id of the planned action to be removed.
+
+        Returns
+        -------
+        :class:`compas_fab.datastructure.Action`
+        The action of the removed :class:`compas_fab.datastructure.PlannedAction`
+        """
+        planned_action = self.planned_actions.pop(action_id)
+        for pa in self.planned_actions.values():
+            pa.dependency_ids.discard(action_id)
+        return planned_action.action
+
+    def _get_last_action_id(self):
+        last_action_id, last_action = self.planned_actions.popitem()
+        self.planned_actions[last_action_id] = last_action
+        return last_action_id
+
+    def _get_next_action_id(self):
+        return next(self._id_generator)
+
+    def check_dependency_ids(self, dependency_ids, planned_action_id=None):
+        """Checks whether the given dependency ids exist in the plan.
+
+        Parameters
+        ----------
+        dependency_ids : set or list
+            The dependency ids to be validated.
+        planned_action_id : Hashable
+            The id of the associated planned action.  Used only in
+            the error message.  Defaults to ``None``.
+
+        Raises
+        ------
+        :class:`compas_fab.datastructures.DependencyIdException`
+        """
+        dependency_ids = set(dependency_ids)
+        if not dependency_ids.issubset(self.planned_actions):
+            invalid_ids = dependency_ids.difference(self.planned_actions)
+            raise DependencyIdException(invalid_ids, planned_action_id)
+
+    def check_all_dependency_ids(self):
+        """Checks whether the dependency ids of all the planned actions
+        are ids of planned actions in the plan.
+
+        Raises
+        ------
+        :class:`compas_fab.datastructures.DependencyIdException`
+        """
+        for pa_id, planned_action in self.planned_actions.items():
+            self.check_dependency_ids(planned_action.dependency_ids, pa_id)
+
+    def check_for_cycles(self):
+        """"Checks whether cycles exist in the dependency graph."""
+        self.check_all_dependency_ids()
+
+        def helper(cur, v, r):
+            v[cur] = True
+            r[cur] = True
+            for dep_id in self.planned_actions[cur].dependency_ids:
+                if not v[dep_id]:
+                    helper(dep_id, v, r)
+                elif r[dep_id]:
+                    raise Exception("Cycle found with action ids {}".format([pa_id for pa_id, seen in r.items() if seen]))
+            r[cur] = False
+
+        visited = {pa_id: False for pa_id in self.planned_actions}
+        rec_dict = {pa_id: False for pa_id in self.planned_actions}
+
+        for pa_id in self.planned_actions:
+            if not visited[pa_id]:
+                helper(pa_id, visited, rec_dict)
+
+    def linear_sort(self):
+        """Sorts the planned actions linearly respecting the dependency ids.
+
+        Returns
+        -------
+        :obj:`list` of :class:`compas_fab.datastructure.Action`
+        """
+        self.check_for_cycles()
+
+        def helper(s, v, cur_id):
+            v.add(cur_id)
+            action = self.planned_actions[cur_id]
+            for dep_id in action.dependency_ids:
+                if dep_id not in v:
+                    helper(s, v, dep_id)
+            s.append(action)
+
+        stack = []
+        visited = set()
+
+        for action_id in self.planned_actions:
+            if action_id not in visited:
+                helper(stack, visited, action_id)
+
+        return stack
+
+    @property
+    def data(self):
+        return dict(
+            planned_actions=list(self.planned_actions.values()),
+            id_generator=self._id_generator,
+        )
+
+    @data.setter
+    def data(self, data):
+        self.planned_actions = data['planned_actions']
+        self._id_generator = data['id_generator']
+
+    @classmethod
+    def from_data(cls, data):
+        return cls(**data)
+
+
+class PlannedAction(Datastructure):
+    """Represents an action which has been scheduled in a plan.
+
+    Parameters
+    ----------
+    action_id : Hashable
+        An identifier of the action.  Used by other actions and the plan
+        it is associated with.
+    action : :class:`compas_fab.datastructures.Action`
+        The action to be planned.
+    dependency_ids : set or list
+        The ids of the actions upon which `action` is dependent.
+    """
+    def __init__(self, action_id, action, dependency_ids):
+        super(PlannedAction, self).__init__()
+        self.id = action_id
+        self.action = action
+        self.dependency_ids = dependency_ids
+
+    @property
+    def dependency_ids(self):
+        return self._dependency_ids
+
+    @dependency_ids.setter
+    def dependency_ids(self, value):
+        self._dependency_ids = set(value)
+
+    def __str__(self):
+        return 'PlannedAction<id={}, action={}>'.format(self.id, self.action)
+
+    @property
+    def data(self):
+        return dict(
+            action_id=self.id,
+            action=self.action,
+            # sets are not json serializable
+            dependency_ids=list(self.dependency_ids),
+        )
+
+    @data.setter
+    def data(self, data):
+        self.id = data['action_id']
+        self.action = data['action']
+        self.dependency_ids = data['dependency_ids']
+
+    @classmethod
+    def from_data(cls, data):
+        return cls(**data)
+
+
+class Action(Datastructure):
+    """Abstract representation of an event independent of its timing.
+
+    Parameters
+    ----------
+    name : :obj:`str`
+        The name of the action.
+    parameters : dict
+        Any other content associated to the action housed in key-value pairs.
+    """
+    def __init__(self, name, parameters=None):
+        super(Action, self).__init__()
+        self.name = name
+        self.parameters = parameters or {}
+
+    def __str__(self):
+        return 'Action<name={}>'.format(self.name)
+
+    @property
+    def data(self):
+        return dict(
+            name=self.name,
+            parameters=self.parameters,
+        )
+
+    @data.setter
+    def data(self, data):
+        self.name = data['name']
+        self.parameters = data['parameters']
+
+    @classmethod
+    def from_data(cls, data):
+        return cls(**data)