planning-structs 0.1.0__py3-none-any.whl

planning_structs/__init__.py

@@ -0,0 +1,18 @@
+"""
+Typed STRIPS planning structures: domains, their groundings on object sets, symbolic action models
+and traces. No dependencies.
+"""
+from importlib.metadata import PackageNotFoundError, version
+
+from planning_structs.action_model import ActionModel, Literal
+from planning_structs.domain import ActionSchema, Domain, Predicate, Type
+from planning_structs.instance import Action, Instance, Object, Proposition
+from planning_structs.trace import Trace
+
+try:
+    __version__ = version("planning-structs")
+except PackageNotFoundError:          # running from a source checkout without installation
+    __version__ = "0.0.0+unknown"
+
+__all__ = ["Type", "Predicate", "ActionSchema", "Domain", "Object", "Proposition", "Action", "Instance",
+           "ActionModel", "Literal", "Trace", "__version__"]

planning_structs/action_model.py

@@ -0,0 +1,66 @@
+"""
+A symbolic (discrete) lifted STRIPS action model over a Domain.
+
+Each literal of an action schema is a (predicate, binding) pair, where the binding lists, for each
+predicate position, the 1-based position of the action parameter it refers to. For example, in
+`turn-on(?s, ?r)` the literal `(in ?s ?r)` is (in, (1, 2)).
+
+Action model learners (e.g. ROSAME) can return their result as an ActionModel, which can then be
+inspected, compared with a reference (`==`, `diff`) or written out.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Dict, List, Tuple
+
+from planning_structs.domain import Domain, Predicate
+
+Literal = Tuple[Predicate, Tuple[int, ...]]
+
+
+@dataclass(eq=False)
+class ActionModel:
+    domain: Domain
+    preconditions: Dict[str, List[Literal]] = field(default_factory=dict)
+    add_effects: Dict[str, List[Literal]] = field(default_factory=dict)
+    del_effects: Dict[str, List[Literal]] = field(default_factory=dict)
+
+    def schema(self, name: str) -> Tuple[List[Literal], List[Literal], List[Literal]]:
+        """(preconditions, add effects, delete effects) of one action schema."""
+        return (self.preconditions.get(name, []), self.add_effects.get(name, []), self.del_effects.get(name, []))
+
+    @staticmethod
+    def literal_str(lit: Literal, parameter_names=None) -> str:
+        p, x = lit
+        names = parameter_names or [f"?x{i}" for i in range(1, max(x, default=0) + 1)]
+        return f"({p.name}{''.join(' ' + names[i - 1] for i in x)})"
+
+    def _key(self):
+        schemas = {a.name for a in self.domain.action_schemas}
+        return {n: tuple(frozenset((p.name, x) for p, x in lits) for lits in self.schema(n)) for n in schemas}
+
+    def __eq__(self, other) -> bool:
+        """Same literals per action schema (by name), regardless of order."""
+        return isinstance(other, ActionModel) and self._key() == other._key()
+
+    def diff(self, other: "ActionModel") -> List[str]:
+        """Readable differences from another model, e.g. a reference: one line per literal that is
+        in only one of the two (empty if they are equal)."""
+        mine, theirs, out = self._key(), other._key(), []
+        for name in sorted(set(mine) | set(theirs)):
+            for part, a, b in zip(("precondition", "add effect", "delete effect"),
+                                  mine.get(name, (frozenset(),) * 3), theirs.get(name, (frozenset(),) * 3)):
+                for p, x in sorted(a - b):
+                    out.append(f"{name}: {part} ({p}{''.join(f' ?x{i}' for i in x)}) only in this model")
+                for p, x in sorted(b - a):
+                    out.append(f"{name}: {part} ({p}{''.join(f' ?x{i}' for i in x)}) only in the other model")
+        return out
+
+    def __str__(self) -> str:
+        lines = []
+        for a in self.domain.action_schemas:
+            names = [f"?x{i}" for i in range(1, a.arity + 1)]
+            pre, add, dele = self.schema(a.name)
+            fmt = lambda lits: " ".join(self.literal_str(l, names) for l in lits) or "-"
+            lines.append(f"{a.name}({', '.join(names)})\n  pre: {fmt(pre)}\n  add: {fmt(add)}\n  del: {fmt(dele)}")
+        return "\n".join(lines)

planning_structs/domain.py

@@ -0,0 +1,184 @@
+"""
+Typed STRIPS domains: types (single inheritance), predicates and action schemas.
+
+A Domain also enumerates, for every (action schema, predicate) pair, the bindings x that map each
+predicate position to a distinct, type-compatible action parameter position (1-based). Every
+(schema, predicate, binding) triple is one slot of the lifted action model that ROSAME learns.
+"""
+from __future__ import annotations
+from dataclasses import dataclass, field
+from itertools import permutations
+from typing import Dict, List, Optional, Set, Tuple
+
+@dataclass(eq=True, frozen=True)
+class Type:
+    name: str
+    parent: Optional["Type"] = field(default=None, compare=False)
+
+    def is_child_of(self, ancestor: "Type") -> bool:
+        """Returns True iff self is the same as ancestor or a descendant."""
+        t = self
+        while t is not None:
+            if t.name == ancestor.name:
+                return True
+            t = object.__getattribute__(t, "parent")  # avoid dataclass frozen recursion
+        return False
+
+    def __str__(self):
+        return self.name
+
+
+@dataclass(eq=True, frozen=True)
+class Predicate:
+    name: str
+    arity: int
+    types: Tuple[Type, ...]  # length = arity (unpadded)
+
+    def __str__(self):
+        return f"{self.name}([{', '.join([t.name for t in self.types])}])"
+
+
+@dataclass(eq=True, frozen=True)
+class ActionSchema:
+    name: str
+    arity: int
+    types: Tuple[Type, ...]  # length = arity (unpadded)
+
+    def __str__(self):
+        return f"{self.name}([{', '.join([t.name for t in self.types])}])"
+
+
+class Domain:
+    """
+    Domain(types, predicates, action_schemas)
+    - types: List[Tuple[name, parent_name_or_None]]
+    - predicates: List[Tuple[name, List[type_names]]]
+    - action_schemas: List[Tuple[name, List[type_names]]]
+    """
+    def __init__(self, types, predicates, action_schemas, name: str | None = None):
+        # store name if provided
+        self.name = name
+
+        self.types_set, self._types_dict, self._edges = self.build_types(types)
+        self.predicates: List[Predicate] = self.build_predicates(predicates)
+        self.action_schemas: List[ActionSchema] = self.build_action_schemas(action_schemas)
+
+        # arity stats (for padding)
+        self.max_pred_arity = max((p.arity for p in self.predicates), default=0)
+        self.max_action_arity = max((a.arity for a in self.action_schemas), default=0)
+
+        # all valid bindings (padded to max_pred_arity with 0s)
+        self.predicate_arguments: Dict[Tuple[ActionSchema, Predicate], List[Tuple[int, ...]]] = \
+            self.build_predicate_arguments()
+
+    # --------- building blocks ---------
+
+    def build_types(self, types_spec):
+        """
+        types_spec: List[Tuple[name, parent_name_or_None]]
+        Returns: (types_set, name->Type dict, edges[parent, child] sorted)
+        Behavior:
+          - Ensures a base 'object' type exists.
+          - Any type declared as a root (parent=None) and not named 'object'
+            is silently attached under 'object'.
+          - Any parent name that appears but isn't declared is created as a root,
+            then also attached under 'object'.
+        """
+        # 1) Collect declared relations
+        name_to_parent = {n: p for n, p in types_spec}
+
+        # 2) Ensure 'object' exists as explicit root
+        if "object" not in name_to_parent:
+            name_to_parent["object"] = None
+
+        # 3) If a parent name appears that isn't declared, create it (root for now)
+        for _, p in types_spec:
+            if p is not None and p not in name_to_parent:
+                name_to_parent[p] = None  # implicit node
+
+        # 4) Attach all roots (except 'object') under 'object'
+        #    This handles the "loosely declared several roots" case.
+        for n, p in list(name_to_parent.items()):
+            if p is None and n != "object":
+                name_to_parent[n] = "object"
+
+        # --- Build Type objects with cycle detection ---
+        cache = {}  # name -> Type
+        visiting = set()
+
+        def build(n: str):
+            if n in cache:
+                return cache[n]
+            if n in visiting:
+                raise ValueError(f"Cycle detected in type hierarchy at '{n}'")
+            visiting.add(n)
+            parent_name = name_to_parent.get(n, None)
+            parent_obj = build(parent_name) if parent_name is not None else None
+            t = Type(name=n, parent=parent_obj)
+            cache[n] = t
+            visiting.remove(n)
+            return t
+
+        # Build all nodes (declared + implicit)
+        for n in list(name_to_parent.keys()):
+            build(n)
+
+        # Deterministic edges: (parent, child) excluding roots
+        edges = sorted((p, c) for c, p in name_to_parent.items() if p is not None)
+
+        types_set = set(cache.values())
+        return types_set, cache, edges
+
+    def build_predicates(self, predicates_spec) -> list[Predicate]:
+        preds = []
+        for (name, params) in predicates_spec:
+            types = tuple(self._types_dict[tn] for tn in params)
+            preds.append(Predicate(name=name, arity=len(types), types=types))
+        self._pred_map = {p.name: p for p in preds}
+        return preds
+
+    def build_action_schemas(self, schemas_spec) -> list[ActionSchema]:
+        acts = []
+        for (name, params) in schemas_spec:
+            types = tuple(self._types_dict[tn] for tn in params)
+            acts.append(ActionSchema(name=name, arity=len(types), types=types))
+        self._act_map = {a.name: a for a in acts}
+        return acts
+
+    def _type_match(self, x_tuple: Tuple[int, ...], a: ActionSchema, p: Predicate) -> bool:
+        """
+        x_tuple is a length p.arity tuple of integers in 1..a.arity (positions),
+        mapping predicate positions -> action positions.
+        Zeros are for padded predicate positions and are handled elsewhere; here we only check 1..p.arity.
+        """
+        for i in range(p.arity):
+            ai = x_tuple[i]
+            # ai is in 1..a.arity
+            if not a.types[ai - 1].is_child_of(p.types[i]):
+                return False
+        return True
+
+    def build_predicate_arguments(self):
+        """
+        For each (a, p), enumerate all valid bindings of length == p.arity
+        mapping predicate positions -> distinct action positions.
+        """
+        res = {}
+        for a in self.action_schemas:
+            for p in self.predicates:
+                valid = []
+                if a.arity >= p.arity:
+                    for x in permutations(range(1, a.arity + 1), p.arity):
+                        if self._type_match(x, a, p):
+                            valid.append(x)
+                res[(a, p)] = valid
+        return res
+
+    def get_type(self, type_name: str) -> Optional[Type]:
+        return self._types_dict.get(type_name)
+
+    def get_action_schema(self, act_name: str) -> Optional[ActionSchema]:
+        return self._act_map.get(act_name)
+
+    def get_predicate(self, pred_name: str) -> Optional[Predicate]:
+        return self._pred_map.get(pred_name)

planning_structs/instance.py

@@ -0,0 +1,129 @@
+"""
+Grounding of a Domain on a set of objects: objects, propositions and grounded actions.
+
+Order conventions (relied on throughout the package):
+  - propositions: for each predicate in domain order, every tuple of *distinct*, type-compatible
+    objects in lexicographic order of their positions in the object list;
+  - actions: the same, for each action schema in domain order.
+Object names never affect these orders, only the sequence of object types does.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from itertools import product
+from typing import Dict, List, Optional, Sequence, Tuple
+
+from planning_structs.domain import ActionSchema, Domain, Predicate, Type
+
+
+def objs2str(args: Tuple["Object", ...]) -> str:
+    return "_".join(o.name for o in args) if args else ""
+
+
+@dataclass(eq=True, frozen=True)
+class Object:
+    name: str
+    type: Type
+
+    def __str__(self) -> str:
+        return f"{self.name}: {self.type.name}"
+
+
+@dataclass(eq=True, frozen=True)
+class Proposition:
+    """Grounded predicate application with Object arguments."""
+    predicate: Predicate
+    args: Tuple[Object, ...]
+
+    @property
+    def arity(self) -> int:
+        return len(self.args)
+
+    def __str__(self) -> str:
+        return self.predicate.name if not self.args else f"{self.predicate.name}_{objs2str(self.args)}"
+
+
+@dataclass(eq=True, frozen=True)
+class Action:
+    """Grounded action with Object arguments."""
+    action_schema: ActionSchema
+    args: Tuple[Object, ...]
+
+    @property
+    def arity(self) -> int:
+        return len(self.args)
+
+    def __str__(self) -> str:
+        return self.action_schema.name if not self.args else f"{self.action_schema.name}_{objs2str(self.args)}"
+
+
+def _groundings(objects: Sequence[Object], types: Sequence[Type]):
+    """Tuples of distinct objects whose types match `types`, in lexicographic position order
+    (identical to filtering itertools.permutations(objects, len(types)) by type, but only visits
+    type-compatible candidates)."""
+    cands = [[i for i, o in enumerate(objects) if o.type.is_child_of(t)] for t in types]
+    for idx in product(*cands):
+        if len(set(idx)) == len(idx):
+            yield tuple(objects[i] for i in idx)
+
+
+class Instance:
+    """
+    Objects, propositions and grounded actions of a Domain for one object set.
+
+    Groundings use distinct objects for distinct parameters (injective bindings), matching the
+    bindings enumerated by Domain. Propositions are built on construction; grounded actions are
+    built on first access to `actions`, since their number grows with the action arity and can be
+    very large (code that only grounds observed actions never needs them).
+    """
+
+    def __init__(self, domain: Domain, objects: Sequence[Tuple[str, str]]):
+        self.domain = domain
+        self.objects: List[Object] = self._build_objects(objects)
+        self.propositions: List[Proposition] = [Proposition(p, args) for p in domain.predicates
+                                                for args in _groundings(self.objects, p.types)]
+        self.prop_index: Dict[Tuple[Predicate, Tuple[Object, ...]], int] = {
+            (p.predicate, p.args): i for i, p in enumerate(self.propositions)}
+        self._objects_dict: Dict[str, Object] = {o.name: o for o in self.objects}
+        self._actions: Optional[List[Action]] = None
+        self._actions_dict: Optional[Dict[Tuple[ActionSchema, Tuple[Object, ...]], Action]] = None
+
+    def _build_objects(self, objects: Sequence[Tuple[str, str]]) -> List[Object]:
+        objs: List[Object] = []
+        for name, type_name in objects:
+            t = self.domain.get_type(type_name)
+            if t is None:
+                raise ValueError(f"Unknown type '{type_name}' for object '{name}'.")
+            objs.append(Object(name=name, type=t))
+        return objs
+
+    # ---------- grounded actions (lazy) ----------
+
+    @property
+    def actions(self) -> List[Action]:
+        if self._actions is None:
+            self._actions = [Action(a, args) for a in self.domain.action_schemas
+                             for args in _groundings(self.objects, a.types)]
+            self._actions_dict = {(a.action_schema, a.args): a for a in self._actions}
+        return self._actions
+
+    # ---------- lookups ----------
+
+    def get_object(self, name: str) -> Optional[Object]:
+        return self._objects_dict.get(name)
+
+    def get_action(self, action_schema: ActionSchema, args: Sequence[Object]) -> Optional[Action]:
+        self.actions
+        return self._actions_dict.get((action_schema, tuple(args)))
+
+    def get_proposition(self, predicate: Predicate, args: Sequence[Object]) -> Optional[Proposition]:
+        i = self.prop_index.get((predicate, tuple(args)))
+        return None if i is None else self.propositions[i]
+
+    @property
+    def num_actions(self) -> int:
+        return len(self.actions)
+
+    @property
+    def num_propositions(self) -> int:
+        return len(self.propositions)

planning_structs/trace.py

@@ -0,0 +1,39 @@
+"""
+Traces: sequences of states and actions over one object set.
+
+    Trace(objects=[("r1", "room"), ("r2", "room"), ("s1", "switch")],
+          states=[["(robot-at r1)", "(off s1)"], ["(robot-at r2)", "(off s1)"]],
+          actions=["(move r1 r2)"])
+
+Atoms and actions may be written "(in s1 r2)", "in s1 r2", ("in", "s1", "r2") or ("in", ("s1", "r2")).
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Sequence, Tuple
+
+
+@dataclass
+class Trace:
+    """One trace of T transitions.
+
+    objects  [(name, type), ...]: every object the states and actions mention, including domain
+             constants.
+    states   T + 1 states. Each state is an iterable of true atoms, a dict {atom: probability} (atoms
+             not listed have probability 0), or a vector of probabilities over the propositions of
+             Instance(domain, objects), in their order; a whole [T + 1, P] array is also accepted.
+    actions  T actions; None marks an unknown action.
+    """
+    objects: Sequence[Tuple[str, str]]
+    states: Any
+    actions: Sequence[Any]
+
+    def __post_init__(self) -> None:
+        if hasattr(self.states, "__len__") and len(self.states) != len(self.actions) + 1:
+            raise ValueError(f"a trace with {len(self.actions)} actions needs {len(self.actions) + 1} states, "
+                             f"got {len(self.states)}")
+
+    @property
+    def length(self) -> int:
+        """Number of transitions."""
+        return len(self.actions)

planning_structs-0.1.0.dist-info/METADATA

@@ -0,0 +1,85 @@
+Metadata-Version: 2.5
+Name: planning-structs
+Version: 0.1.0
+Summary: Typed STRIPS planning structures: domains, groundings, symbolic action models and traces
+Project-URL: Homepage, https://github.com/xikaioliver/planning-structs
+Project-URL: Issues, https://github.com/xikaioliver/planning-structs/issues
+Author: Kai Xi, Stephen Gould, Sylvie Thiébaux
+License-Expression: CC-BY-4.0
+License-File: LICENSE
+Keywords: PDDL,STRIPS,action models,planning
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == 'test'
+Description-Content-Type: text/markdown
+
+# planning-structs
+
+Typed STRIPS planning structures in plain Python, with no dependencies: domains, their groundings on
+object sets, symbolic action models and traces. It is the structure layer of
+[ROSAME](https://github.com/xikaioliver/ROSAME) and of other projects on learning planning models.
+
+```bash
+pip install planning-structs
+```
+
+## Overview
+
+```python
+from planning_structs import Domain, Instance, ActionModel, Trace
+
+# A domain: types (single inheritance), predicates and action schemas with typed parameters.
+domain = Domain(types=[("room", None), ("device", None), ("switch", "device")],
+                predicates=[("robot-at", ["room"]), ("in", ["device", "room"]), ("on", ["switch"])],
+                action_schemas=[("move", ["room", "room"]), ("turn-on", ["switch", "room"])],
+                name="switches")
+
+# Its grounding on an object set: propositions (built at once) and actions (built on first use).
+instance = Instance(domain, [("r1", "room"), ("r2", "room"), ("s1", "switch")])
+print([str(p) for p in instance.propositions])     # robot-at_r1, robot-at_r2, in_s1_r1, ...
+print(instance.num_actions)
+
+# The lifted literals ("bindings") an action schema can have over each predicate:
+move, robot_at = domain.get_action_schema("move"), domain.get_predicate("robot-at")
+print(domain.predicate_arguments[(move, robot_at)])  # [(1,), (2,)]: robot-at(?x1), robot-at(?x2)
+
+# A symbolic action model: per action schema, preconditions, add and delete effects.
+model = ActionModel(domain)
+model.preconditions["move"] = [(robot_at, (1,))]
+model.add_effects["move"] = [(robot_at, (2,))]
+model.del_effects["move"] = [(robot_at, (1,))]
+print(model)
+
+# A trace: objects, T + 1 states (true atoms, {atom: probability}, or vectors) and T actions.
+trace = Trace(objects=[("r1", "room"), ("r2", "room")],
+              states=[["(robot-at r1)"], ["(robot-at r2)"]],
+              actions=["(move r1 r2)"])
+```
+
+## Conventions
+
+- **Types** form a tree under `object`; `t.is_child_of(u)` is true when `t` is `u` or a descendant.
+- **Bindings.** `domain.predicate_arguments[(schema, predicate)]` lists every way to fill the
+  predicate's positions with distinct, type-compatible parameters of the schema, as tuples of 1-based
+  parameter positions. In `move(?from, ?to)`, `(connected ?to ?from)` is the binding `(2, 1)`.
+- **Grounding order.** Propositions: predicates in domain order, then tuples of *distinct*,
+  type-compatible objects in lexicographic order of their positions in the object list. Actions: the
+  same for action schemas. Only the sequence of object types matters, not the names.
+- **Action models** compare with `==` regardless of literal order; `a.diff(b)` lists the literals
+  present in only one of them.
+
+## Versions
+
+Semantic versioning; see [CHANGELOG.md](CHANGELOG.md). Additions arrive in minor releases and stay
+compatible with code written for earlier ones.
+
+## License
+
+See [LICENSE](LICENSE).

planning_structs-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+planning_structs/__init__.py,sha256=HjCgBAOV1JY5ZEvW9IFWqIaVntlsS_s0bfUl496ou84,797
+planning_structs/action_model.py,sha256=bEFv82P-Vflq4M3bzxZN5QU8a0nLiA5fIU_jz5x-CR4,3200
+planning_structs/domain.py,sha256=4qJmVFU3LDZK9k8MaRlYce6p2sZyxjYVC4_wYln7oCs,7041
+planning_structs/instance.py,sha256=ber6yXHN3TVIjVQpCctRe4NpjX7jRRSUNlXN7OzKiI8,4974
+planning_structs/trace.py,sha256=Nz0mfbM-7YrXNhSxgOSiimL2_kI3Ky8ezOL5N1VJPrU,1507
+planning_structs-0.1.0.dist-info/METADATA,sha256=mN-HcDrdRsQg0y9ANePJUmHv2IZCY_MF8XLD9OvCc3g,3876
+planning_structs-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+planning_structs-0.1.0.dist-info/licenses/LICENSE,sha256=nl8bPGELnC2lwxO_gdV3p9Gs7Ghr2wOE7e-m3w-QzZQ,18656
+planning_structs-0.1.0.dist-info/RECORD,,

planning_structs-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

planning_structs-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,395 @@
+Attribution 4.0 International
+
+=======================================================================
+
+Creative Commons Corporation ("Creative Commons") is not a law firm and
+does not provide legal services or legal advice. Distribution of
+Creative Commons public licenses does not create a lawyer-client or
+other relationship. Creative Commons makes its licenses and related
+information available on an "as-is" basis. Creative Commons gives no
+warranties regarding its licenses, any material licensed under their
+terms and conditions, or any related information. Creative Commons
+disclaims all liability for damages resulting from their use to the
+fullest extent possible.
+
+Using Creative Commons Public Licenses
+
+Creative Commons public licenses provide a standard set of terms and
+conditions that creators and other rights holders may use to share
+original works of authorship and other material subject to copyright
+and certain other rights specified in the public license below. The
+following considerations are for informational purposes only, are not
+exhaustive, and do not form part of our licenses.
+
+     Considerations for licensors: Our public licenses are
+     intended for use by those authorized to give the public
+     permission to use material in ways otherwise restricted by
+     copyright and certain other rights. Our licenses are
+     irrevocable. Licensors should read and understand the terms
+     and conditions of the license they choose before applying it.
+     Licensors should also secure all rights necessary before
+     applying our licenses so that the public can reuse the
+     material as expected. Licensors should clearly mark any
+     material not subject to the license. This includes other CC-
+     licensed material, or material used under an exception or
+     limitation to copyright. More considerations for licensors:
+    wiki.creativecommons.org/Considerations_for_licensors
+
+     Considerations for the public: By using one of our public
+     licenses, a licensor grants the public permission to use the
+     licensed material under specified terms and conditions. If
+     the licensor's permission is not necessary for any reason--for
+     example, because of any applicable exception or limitation to
+     copyright--then that use is not regulated by the license. Our
+     licenses grant only permissions under copyright and certain
+     other rights that a licensor has authority to grant. Use of
+     the licensed material may still be restricted for other
+     reasons, including because others have copyright or other
+     rights in the material. A licensor may make special requests,
+     such as asking that all changes be marked or described.
+     Although not required by our licenses, you are encouraged to
+     respect those requests where reasonable. More considerations
+     for the public:
+    wiki.creativecommons.org/Considerations_for_licensees
+
+=======================================================================
+
+Creative Commons Attribution 4.0 International Public License
+
+By exercising the Licensed Rights (defined below), You accept and agree
+to be bound by the terms and conditions of this Creative Commons
+Attribution 4.0 International Public License ("Public License"). To the
+extent this Public License may be interpreted as a contract, You are
+granted the Licensed Rights in consideration of Your acceptance of
+these terms and conditions, and the Licensor grants You such rights in
+consideration of benefits the Licensor receives from making the
+Licensed Material available under these terms and conditions.
+
+
+Section 1 -- Definitions.
+
+  a. Adapted Material means material subject to Copyright and Similar
+     Rights that is derived from or based upon the Licensed Material
+     and in which the Licensed Material is translated, altered,
+     arranged, transformed, or otherwise modified in a manner requiring
+     permission under the Copyright and Similar Rights held by the
+     Licensor. For purposes of this Public License, where the Licensed
+     Material is a musical work, performance, or sound recording,
+     Adapted Material is always produced where the Licensed Material is
+     synched in timed relation with a moving image.
+
+  b. Adapter's License means the license You apply to Your Copyright
+     and Similar Rights in Your contributions to Adapted Material in
+     accordance with the terms and conditions of this Public License.
+
+  c. Copyright and Similar Rights means copyright and/or similar rights
+     closely related to copyright including, without limitation,
+     performance, broadcast, sound recording, and Sui Generis Database
+     Rights, without regard to how the rights are labeled or
+     categorized. For purposes of this Public License, the rights
+     specified in Section 2(b)(1)-(2) are not Copyright and Similar
+     Rights.
+
+  d. Effective Technological Measures means those measures that, in the
+     absence of proper authority, may not be circumvented under laws
+     fulfilling obligations under Article 11 of the WIPO Copyright
+     Treaty adopted on December 20, 1996, and/or similar international
+     agreements.
+
+  e. Exceptions and Limitations means fair use, fair dealing, and/or
+     any other exception or limitation to Copyright and Similar Rights
+     that applies to Your use of the Licensed Material.
+
+  f. Licensed Material means the artistic or literary work, database,
+     or other material to which the Licensor applied this Public
+     License.
+
+  g. Licensed Rights means the rights granted to You subject to the
+     terms and conditions of this Public License, which are limited to
+     all Copyright and Similar Rights that apply to Your use of the
+     Licensed Material and that the Licensor has authority to license.
+
+  h. Licensor means the individual(s) or entity(ies) granting rights
+     under this Public License.
+
+  i. Share means to provide material to the public by any means or
+     process that requires permission under the Licensed Rights, such
+     as reproduction, public display, public performance, distribution,
+     dissemination, communication, or importation, and to make material
+     available to the public including in ways that members of the
+     public may access the material from a place and at a time
+     individually chosen by them.
+
+  j. Sui Generis Database Rights means rights other than copyright
+     resulting from Directive 96/9/EC of the European Parliament and of
+     the Council of 11 March 1996 on the legal protection of databases,
+     as amended and/or succeeded, as well as other essentially
+     equivalent rights anywhere in the world.
+
+  k. You means the individual or entity exercising the Licensed Rights
+     under this Public License. Your has a corresponding meaning.
+
+
+Section 2 -- Scope.
+
+  a. License grant.
+
+       1. Subject to the terms and conditions of this Public License,
+          the Licensor hereby grants You a worldwide, royalty-free,
+          non-sublicensable, non-exclusive, irrevocable license to
+          exercise the Licensed Rights in the Licensed Material to:
+
+            a. reproduce and Share the Licensed Material, in whole or
+               in part; and
+
+            b. produce, reproduce, and Share Adapted Material.
+
+       2. Exceptions and Limitations. For the avoidance of doubt, where
+          Exceptions and Limitations apply to Your use, this Public
+          License does not apply, and You do not need to comply with
+          its terms and conditions.
+
+       3. Term. The term of this Public License is specified in Section
+          6(a).
+
+       4. Media and formats; technical modifications allowed. The
+          Licensor authorizes You to exercise the Licensed Rights in
+          all media and formats whether now known or hereafter created,
+          and to make technical modifications necessary to do so. The
+          Licensor waives and/or agrees not to assert any right or
+          authority to forbid You from making technical modifications
+          necessary to exercise the Licensed Rights, including
+          technical modifications necessary to circumvent Effective
+          Technological Measures. For purposes of this Public License,
+          simply making modifications authorized by this Section 2(a)
+          (4) never produces Adapted Material.
+
+       5. Downstream recipients.
+
+            a. Offer from the Licensor -- Licensed Material. Every
+               recipient of the Licensed Material automatically
+               receives an offer from the Licensor to exercise the
+               Licensed Rights under the terms and conditions of this
+               Public License.
+
+            b. No downstream restrictions. You may not offer or impose
+               any additional or different terms or conditions on, or
+               apply any Effective Technological Measures to, the
+               Licensed Material if doing so restricts exercise of the
+               Licensed Rights by any recipient of the Licensed
+               Material.
+
+       6. No endorsement. Nothing in this Public License constitutes or
+          may be construed as permission to assert or imply that You
+          are, or that Your use of the Licensed Material is, connected
+          with, or sponsored, endorsed, or granted official status by,
+          the Licensor or others designated to receive attribution as
+          provided in Section 3(a)(1)(A)(i).
+
+  b. Other rights.
+
+       1. Moral rights, such as the right of integrity, are not
+          licensed under this Public License, nor are publicity,
+          privacy, and/or other similar personality rights; however, to
+          the extent possible, the Licensor waives and/or agrees not to
+          assert any such rights held by the Licensor to the limited
+          extent necessary to allow You to exercise the Licensed
+          Rights, but not otherwise.
+
+       2. Patent and trademark rights are not licensed under this
+          Public License.
+
+       3. To the extent possible, the Licensor waives any right to
+          collect royalties from You for the exercise of the Licensed
+          Rights, whether directly or through a collecting society
+          under any voluntary or waivable statutory or compulsory
+          licensing scheme. In all other cases the Licensor expressly
+          reserves any right to collect such royalties.
+
+
+Section 3 -- License Conditions.
+
+Your exercise of the Licensed Rights is expressly made subject to the
+following conditions.
+
+  a. Attribution.
+
+       1. If You Share the Licensed Material (including in modified
+          form), You must:
+
+            a. retain the following if it is supplied by the Licensor
+               with the Licensed Material:
+
+                 i. identification of the creator(s) of the Licensed
+                    Material and any others designated to receive
+                    attribution, in any reasonable manner requested by
+                    the Licensor (including by pseudonym if
+                    designated);
+
+                ii. a copyright notice;
+
+               iii. a notice that refers to this Public License;
+
+                iv. a notice that refers to the disclaimer of
+                    warranties;
+
+                 v. a URI or hyperlink to the Licensed Material to the
+                    extent reasonably practicable;
+
+            b. indicate if You modified the Licensed Material and
+               retain an indication of any previous modifications; and
+
+            c. indicate the Licensed Material is licensed under this
+               Public License, and include the text of, or the URI or
+               hyperlink to, this Public License.
+
+       2. You may satisfy the conditions in Section 3(a)(1) in any
+          reasonable manner based on the medium, means, and context in
+          which You Share the Licensed Material. For example, it may be
+          reasonable to satisfy the conditions by providing a URI or
+          hyperlink to a resource that includes the required
+          information.
+
+       3. If requested by the Licensor, You must remove any of the
+          information required by Section 3(a)(1)(A) to the extent
+          reasonably practicable.
+
+       4. If You Share Adapted Material You produce, the Adapter's
+          License You apply must not prevent recipients of the Adapted
+          Material from complying with this Public License.
+
+
+Section 4 -- Sui Generis Database Rights.
+
+Where the Licensed Rights include Sui Generis Database Rights that
+apply to Your use of the Licensed Material:
+
+  a. for the avoidance of doubt, Section 2(a)(1) grants You the right
+     to extract, reuse, reproduce, and Share all or a substantial
+     portion of the contents of the database;
+
+  b. if You include all or a substantial portion of the database
+     contents in a database in which You have Sui Generis Database
+     Rights, then the database in which You have Sui Generis Database
+     Rights (but not its individual contents) is Adapted Material; and
+
+  c. You must comply with the conditions in Section 3(a) if You Share
+     all or a substantial portion of the contents of the database.
+
+For the avoidance of doubt, this Section 4 supplements and does not
+replace Your obligations under this Public License where the Licensed
+Rights include other Copyright and Similar Rights.
+
+
+Section 5 -- Disclaimer of Warranties and Limitation of Liability.
+
+  a. UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE
+     EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS
+     AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF
+     ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS,
+     IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION,
+     WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR
+     PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS,
+     ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT
+     KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT
+     ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU.
+
+  b. TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE
+     TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION,
+     NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT,
+     INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES,
+     COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR
+     USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN
+     ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR
+     DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR
+     IN PART, THIS LIMITATION MAY NOT APPLY TO YOU.
+
+  c. The disclaimer of warranties and limitation of liability provided
+     above shall be interpreted in a manner that, to the extent
+     possible, most closely approximates an absolute disclaimer and
+     waiver of all liability.
+
+
+Section 6 -- Term and Termination.
+
+  a. This Public License applies for the term of the Copyright and
+     Similar Rights licensed here. However, if You fail to comply with
+     this Public License, then Your rights under this Public License
+     terminate automatically.
+
+  b. Where Your right to use the Licensed Material has terminated under
+     Section 6(a), it reinstates:
+
+       1. automatically as of the date the violation is cured, provided
+          it is cured within 30 days of Your discovery of the
+          violation; or
+
+       2. upon express reinstatement by the Licensor.
+
+     For the avoidance of doubt, this Section 6(b) does not affect any
+     right the Licensor may have to seek remedies for Your violations
+     of this Public License.
+
+  c. For the avoidance of doubt, the Licensor may also offer the
+     Licensed Material under separate terms or conditions or stop
+     distributing the Licensed Material at any time; however, doing so
+     will not terminate this Public License.
+
+  d. Sections 1, 5, 6, 7, and 8 survive termination of this Public
+     License.
+
+
+Section 7 -- Other Terms and Conditions.
+
+  a. The Licensor shall not be bound by any additional or different
+     terms or conditions communicated by You unless expressly agreed.
+
+  b. Any arrangements, understandings, or agreements regarding the
+     Licensed Material not stated herein are separate from and
+     independent of the terms and conditions of this Public License.
+
+
+Section 8 -- Interpretation.
+
+  a. For the avoidance of doubt, this Public License does not, and
+     shall not be interpreted to, reduce, limit, restrict, or impose
+     conditions on any use of the Licensed Material that could lawfully
+     be made without permission under this Public License.
+
+  b. To the extent possible, if any provision of this Public License is
+     deemed unenforceable, it shall be automatically reformed to the
+     minimum extent necessary to make it enforceable. If the provision
+     cannot be reformed, it shall be severed from this Public License
+     without affecting the enforceability of the remaining terms and
+     conditions.
+
+  c. No term or condition of this Public License will be waived and no
+     failure to comply consented to unless expressly agreed to by the
+     Licensor.
+
+  d. Nothing in this Public License constitutes or may be interpreted
+     as a limitation upon, or waiver of, any privileges and immunities
+     that apply to the Licensor or You, including from the legal
+     processes of any jurisdiction or authority.
+
+
+=======================================================================
+
+Creative Commons is not a party to its public
+licenses. Notwithstanding, Creative Commons may elect to apply one of
+its public licenses to material it publishes and in those instances
+will be considered the “Licensor.” The text of the Creative Commons
+public licenses is dedicated to the public domain under the CC0 Public
+Domain Dedication. Except for the limited purpose of indicating that
+material is shared under a Creative Commons public license or as
+otherwise permitted by the Creative Commons policies published at
+creativecommons.org/policies, Creative Commons does not authorize the
+use of the trademark "Creative Commons" or any other trademark or logo
+of Creative Commons without its prior written consent including,
+without limitation, in connection with any unauthorized modifications
+to any of its public licenses or any other arrangements,
+understandings, or agreements concerning use of licensed material. For
+the avoidance of doubt, this paragraph does not form part of the
+public licenses.
+
+Creative Commons may be contacted at creativecommons.org.