# Behavior Domain Definition Language
**Note: If you are interested in the BEHAVIOR-100 version of BDDL, please go to the tags menu and navigate to the latest 1.x.x version.**
The Behavior Domain Definition Language (BDDL) is a domain-specific language designed for the Benchmark for Everyday Household Activities in Virtual, Interactive, and ecOlogical enviRonments (BEHAVIOR).
BDDL is a predicate logic-based language inspired by, but distinct from, the Planning Domain Definition Language [1]. It defines each BEHAVIOR activity definition as a BDDL `problem`, consisting of of a categorized object list (`:objects`), an initial condition that has only ground literals (`:init`), and a goal condition that is a logical expression (`:goal`).
## Installation
### Recommended: pip
The easiest way to install BDDL is through pip. To get the BEHAVIOR-1K version, run the below command:
```bash
pip install -u bddl
```
Otherwise, for the latest BEHAVIOR-100 release, you can run the below command:
```bash
pip install -u bddl==1.*
```
### From source
To install a modifiable copy of BDDL, clone this repository locally:
```bash
git clone https://github.com/StanfordVL/bddl.git
```
then run setup:
```bash
cd bddl
python setup.py install
```
## Example BDDL activity
```
(define
(problem cleaning_the_pool_0)
(:domain igibson)
(:objects
pool.n.01_1 - pool.n.01
floor.n.01_1 - floor.n.01
scrub_brush.n.01_1 - scrub_brush.n.01
shelf.n.01_1 - shelf.n.01
detergent.n.02_1 - detergent.n.02
sink.n.01_1 - sink.n.01
agent.n.01_1 - agent.n.01
)
(:init
(ontop pool.n.01_1 floor.n.01_1)
(stained pool.n.01_1)
(ontop scrub_brush.n.01_1 floor.n.01_1)
(ontop detergent.n.02_1 floor.n.01_1)
(inroom shelf.n.01_1 garage)
(inroom floor.n.01_1 garage)
(inroom sink.n.01_1 storage_room)
(ontop agent.n.01_1 floor.n.01_1)
)
(:goal
(and
(ontop ?pool.n.01_1 ?floor.n.01_1)
(not
(stained ?pool.n.01_1)
)
(ontop ?scrub_brush.n.01_1 ?shelf.n.01_1)
(ontop ?detergent.n.02_1 ?floor.n.01_1)
)
)
)
```
The `:objects` and `:init` sections specify the initial state than an agent will start in, located as specified in `:init`. The `inroom` predicate specifies which scene objects must be present, and other binary kinematic predicates (`ontop`, `inside`, etc.) specify where small objects should be sampled. The BDDL functionality sends a representation of these conditions to sampling functionality implemented in a simulator (such as iGibson 2.0) to be sampled into a physical instance of the activity.
The `:goal` section specifies the condition that the agent must satisfy to be successful on the activity. BDDL is entirely process-agnostic, specifiying only the simulator state that must be reached for success.
## Example code usage
### Without simulator
You will typically want to use BEHAVIOR activities with a simulator. To use a BEHAVIOR activity without a simulator, use the following code.
```
from bddl.activity import Conditions
behavior_activity = "storing_the_groceries" # the activity you want to try, full list in bddl/bddl/activity_definitions
activity_definition = 0 # the specific definition you want to use. As of BEHAVIOR100 2021, this should always be 0.
simulator = "omnigibson" # this does not require an actual simulator, just a domain file (e.g. activity_definitions/domain_omnigibson.bddl). You can make your own if desired.
conds = Conditions(behavior_activity, activity_definition, simulator)
# You can now use the functions in bddl/activity.py to interact with the conds object. This generally requires a backend that's based on the simulator; in this case, you can use a stub backend. You can create something similar to, or directly use, the TrivialBackend, TrivialObject, TrivialSimulator, and various Trivial*Predicate classes found in bddl/bddl/trivial_backend.py.
```
### With simulator
To use a BEHAVIOR activity with a simulator, create a subclass of `BDDLBackend` for your simulator. An example for OmniGibson is found [here](https://github.com/StanfordVL/OmniGibson/omnigibson/utils/bddl_utils.py#L169). This will require an implementation of sampling functionality or pre-sampled scenes that satisfy the activity's initial condition and implementation for checking each type of binary kinematic predicate (e.g. `ontop`, `nextto`) and unary nonkinematic predicate (e.g. `cooked`, `saturated`).
## Logic evaluator for goal
When using BEHAVIOR activities with a simulator, the goal condition is evaluated at every simulator step by calling `bddl.activity.evaluate_goal_conditions(goal_conditions)`, where `goal_conditions` is the output of `bddl.activity.get_goal_conditions(conds, backend, scope)`, and `scope` is the output of `bddl.activity.get_scope(conds)` that has then been populated by mapping the string identifiers to actual objects from your simulator. `bddl.logic_base` and `bddl.condition_evaluation` contain the actual evaluation functionality. Atomic formulae that interface directly with the simulator are implemented in `bddl.logic_base`. These require the simulator checking functions for various predicates to be implemented, and are the leaf nodes of the compositional expression making up a goal condition or the list of literals making up an initial condition. Logical operators are implemented in `bddl.condition_evaluation`, and form a compositional structure of the condition to evaluate.
## Solver for ground goal solutions
`bddl.condition_evaluation` also contains basic functionality to generate ground solutions to a compositional goal condition, including one that may contain quantification. This functionality is much like a very simple, unoptimized logic program, and will return a subset of solutions in cases where the solution set is too large to compute due to exponential growth. To enable this, set `generate_ground_options=True` when using `bddl.activity`.
# Using BEHAVIOR with a new simulator
Using BEHAVIOR activities with a new simulator requires implementing its functional requirements for that simulator, as has been done for OmniGibson [4].
### Implementation of BDDL predicates as simulated object states
To simulate a BEHAVIOR activity, the simulator must be able to simulate every predicate involved in that activity. The full list of predicates is at [TODO add list of predicates to config]. For any one activity, the required predicates can be found by reading its BDDL problem (in activity_definitions/<activity_name>/.)
Implementing these requires 1) a simulator-specific child class of the `BDDLBackend` class and 2) implementations of object states such as `cooked` and `ontop` that can both **instantiate** an object as e.g. `cooked` or `not cooked`, and **check** whether the predicate is true for a given object.
**1. Child of `BDDLBACKEND`:** This class has one method, `get_predicate_class`. It must take string tokens of predicates from BDDL problems (e.g. `"cooked"`, `"ontop"`) and map them to the simulator's object states..
**2. Simulated object states:** For any object in a BEHAVIOR activity, it must be instantiated in certain simulated states and be checked for certain simulated states, as specified by a BDDL problem. `BDDLBackend` expects state implementations that are object agnostic, but the implementation is ultimately up to the user. Assuming object-agnostic states, each one should be able to take an object and instantiate that object with the given state if applicable, and check whether that object is in that state or not. Example: [OmniGibson's object state implementations](https://github.com/StanfordVL/OmniGibson/omnigibson/object_states).
*Note on binary predicates:* in BDDL, certain binary predicates are kinematic (`ontop`, `nextto`, `touching`, etc.). Instantiating objects in the associated simulator states is more complex than instantiating objects in unary predicates' states due to potential for failure based on physical constraints of the scene and multiple possibilities for object pairing, especially when implementing scene-agnostic instantiation capable of generating infinite distinct episodes. Please look at the setter methods of kinematic states in OmniGibson for a robust example capable of instantiating BEHAVIOR activities with many objects.
# Testing
To test the predicate evaluator, run `pytest` in project root.
To add a test, create a new python file under the tests directory, and add
additional functions prefixed with `test_` which include assert statements that
should evaluate true.
# References
[1] M. Ghallab, A. Howe, C. Knoblock, D. McDermott, A. Ram, M. Veloso, D. Weld, & D. Wilkins. PDDL - The Planning Domain Definition Language. Yale Center for Computational Vision and Control, TR-98-003/DCS TR-1165 (1998). [Online].
[2] PDDL Parser (2020). Version 1.1. [Source code]. https://github.com/pucrs-automated-planning/pddl-parser.
[3] C. Li*, F. Xia*, R. Martín-Martín*, M. Lingelbach, S. Srivastava, B. Shen, K. Vainio, C. Gokmen, G. Dharan, T. Jain, A. Kurenkov, C. K. Liu, H. Gweon, J. Wu, L. Fei-Fei, S. Savarese. iGibson 2.0: Object-Centric Simulation for Robot Learning of Everyday Household Tasks. CoRL 2021.
[4] C. Li*, R. Zhang*, J. Wong*, C. Gokmen*, S. Srivastava*, R. Martín-Martín*, C. Wang*, G. Levine*, M. Lingelbach, J. Sun, M. Anvari, M. Hwang, M. Sharma, A. Aydin, D. Bansal, S. Hunter, K.-Y. Kim, A. Lou, C. R. Matthews, I. Villa-Renteria, J. H. Tang, C. Tang, F. Xia, S. Savarese, H. Gweon, C. K. Liu, J. Wu, L. Fei-Fei. BEHAVIOR-1K: A Benchmark for Embodied AI with 1,000 Everyday Activities and Realistic Simulation. CoRL 2022.
Raw data
{
"_id": null,
"home_page": "https://github.com/StanfordVL/bddl",
"name": "bddl",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "Stanford University",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/4b/0d/337303552268eea2967bd86cf1deab8fa034c8b84680b53a4e0e2df643ec/bddl-3.5.0.tar.gz",
"platform": null,
"description": "# Behavior Domain Definition Language \n\n**Note: If you are interested in the BEHAVIOR-100 version of BDDL, please go to the tags menu and navigate to the latest 1.x.x version.**\n\nThe Behavior Domain Definition Language (BDDL) is a domain-specific language designed for the Benchmark for Everyday Household Activities in Virtual, Interactive, and ecOlogical enviRonments (BEHAVIOR). \n\nBDDL is a predicate logic-based language inspired by, but distinct from, the Planning Domain Definition Language [1]. It defines each BEHAVIOR activity definition as a BDDL `problem`, consisting of of a categorized object list (`:objects`), an initial condition that has only ground literals (`:init`), and a goal condition that is a logical expression (`:goal`). \n\n## Installation\n\n### Recommended: pip\nThe easiest way to install BDDL is through pip. To get the BEHAVIOR-1K version, run the below command:\n\n```bash\npip install -u bddl\n```\n\nOtherwise, for the latest BEHAVIOR-100 release, you can run the below command:\n\n```bash\npip install -u bddl==1.*\n```\n\n### From source\n\nTo install a modifiable copy of BDDL, clone this repository locally:\n```bash\ngit clone https://github.com/StanfordVL/bddl.git\n```\n\nthen run setup: \n```bash\ncd bddl\npython setup.py install\n```\n\n## Example BDDL activity\n\n```\n(define \n (problem cleaning_the_pool_0)\n (:domain igibson)\n\n (:objects\n \tpool.n.01_1 - pool.n.01\n \tfloor.n.01_1 - floor.n.01\n \tscrub_brush.n.01_1 - scrub_brush.n.01\n \tshelf.n.01_1 - shelf.n.01\n \tdetergent.n.02_1 - detergent.n.02\n sink.n.01_1 - sink.n.01\n \tagent.n.01_1 - agent.n.01\n )\n \n (:init \n (ontop pool.n.01_1 floor.n.01_1) \n (stained pool.n.01_1) \n (ontop scrub_brush.n.01_1 floor.n.01_1) \n (ontop detergent.n.02_1 floor.n.01_1) \n (inroom shelf.n.01_1 garage) \n (inroom floor.n.01_1 garage) \n (inroom sink.n.01_1 storage_room)\n (ontop agent.n.01_1 floor.n.01_1)\n )\n \n (:goal \n (and \n (ontop ?pool.n.01_1 ?floor.n.01_1) \n (not \n (stained ?pool.n.01_1)\n ) \n (ontop ?scrub_brush.n.01_1 ?shelf.n.01_1) \n (ontop ?detergent.n.02_1 ?floor.n.01_1)\n )\n )\n)\n```\n\nThe `:objects` and `:init` sections specify the initial state than an agent will start in, located as specified in `:init`. The `inroom` predicate specifies which scene objects must be present, and other binary kinematic predicates (`ontop`, `inside`, etc.) specify where small objects should be sampled. The BDDL functionality sends a representation of these conditions to sampling functionality implemented in a simulator (such as iGibson 2.0) to be sampled into a physical instance of the activity. \n\nThe `:goal` section specifies the condition that the agent must satisfy to be successful on the activity. BDDL is entirely process-agnostic, specifiying only the simulator state that must be reached for success. \n\n## Example code usage\n\n### Without simulator \n\nYou will typically want to use BEHAVIOR activities with a simulator. To use a BEHAVIOR activity without a simulator, use the following code. \n```\nfrom bddl.activity import Conditions \n\nbehavior_activity = \"storing_the_groceries\" # the activity you want to try, full list in bddl/bddl/activity_definitions\nactivity_definition = 0 # the specific definition you want to use. As of BEHAVIOR100 2021, this should always be 0.\nsimulator = \"omnigibson\" # this does not require an actual simulator, just a domain file (e.g. activity_definitions/domain_omnigibson.bddl). You can make your own if desired.\n\nconds = Conditions(behavior_activity, activity_definition, simulator)\n\n# You can now use the functions in bddl/activity.py to interact with the conds object. This generally requires a backend that's based on the simulator; in this case, you can use a stub backend. You can create something similar to, or directly use, the TrivialBackend, TrivialObject, TrivialSimulator, and various Trivial*Predicate classes found in bddl/bddl/trivial_backend.py.\n```\n\n### With simulator \n\nTo use a BEHAVIOR activity with a simulator, create a subclass of `BDDLBackend` for your simulator. An example for OmniGibson is found [here](https://github.com/StanfordVL/OmniGibson/omnigibson/utils/bddl_utils.py#L169). This will require an implementation of sampling functionality or pre-sampled scenes that satisfy the activity's initial condition and implementation for checking each type of binary kinematic predicate (e.g. `ontop`, `nextto`) and unary nonkinematic predicate (e.g. `cooked`, `saturated`). \n\n## Logic evaluator for goal\n\nWhen using BEHAVIOR activities with a simulator, the goal condition is evaluated at every simulator step by calling `bddl.activity.evaluate_goal_conditions(goal_conditions)`, where `goal_conditions` is the output of `bddl.activity.get_goal_conditions(conds, backend, scope)`, and `scope` is the output of `bddl.activity.get_scope(conds)` that has then been populated by mapping the string identifiers to actual objects from your simulator. `bddl.logic_base` and `bddl.condition_evaluation` contain the actual evaluation functionality. Atomic formulae that interface directly with the simulator are implemented in `bddl.logic_base`. These require the simulator checking functions for various predicates to be implemented, and are the leaf nodes of the compositional expression making up a goal condition or the list of literals making up an initial condition. Logical operators are implemented in `bddl.condition_evaluation`, and form a compositional structure of the condition to evaluate. \n\n## Solver for ground goal solutions\n\n`bddl.condition_evaluation` also contains basic functionality to generate ground solutions to a compositional goal condition, including one that may contain quantification. This functionality is much like a very simple, unoptimized logic program, and will return a subset of solutions in cases where the solution set is too large to compute due to exponential growth. To enable this, set `generate_ground_options=True` when using `bddl.activity`.\n\n# Using BEHAVIOR with a new simulator \n\nUsing BEHAVIOR activities with a new simulator requires implementing its functional requirements for that simulator, as has been done for OmniGibson [4]. \n\n### Implementation of BDDL predicates as simulated object states\n\nTo simulate a BEHAVIOR activity, the simulator must be able to simulate every predicate involved in that activity. The full list of predicates is at [TODO add list of predicates to config]. For any one activity, the required predicates can be found by reading its BDDL problem (in activity_definitions/<activity_name>/.) \n\nImplementing these requires 1) a simulator-specific child class of the `BDDLBackend` class and 2) implementations of object states such as `cooked` and `ontop` that can both **instantiate** an object as e.g. `cooked` or `not cooked`, and **check** whether the predicate is true for a given object. \n\n**1. Child of `BDDLBACKEND`:** This class has one method, `get_predicate_class`. It must take string tokens of predicates from BDDL problems (e.g. `\"cooked\"`, `\"ontop\"`) and map them to the simulator's object states.. \n\n**2. Simulated object states:** For any object in a BEHAVIOR activity, it must be instantiated in certain simulated states and be checked for certain simulated states, as specified by a BDDL problem. `BDDLBackend` expects state implementations that are object agnostic, but the implementation is ultimately up to the user. Assuming object-agnostic states, each one should be able to take an object and instantiate that object with the given state if applicable, and check whether that object is in that state or not. Example: [OmniGibson's object state implementations](https://github.com/StanfordVL/OmniGibson/omnigibson/object_states). \n\n*Note on binary predicates:* in BDDL, certain binary predicates are kinematic (`ontop`, `nextto`, `touching`, etc.). Instantiating objects in the associated simulator states is more complex than instantiating objects in unary predicates' states due to potential for failure based on physical constraints of the scene and multiple possibilities for object pairing, especially when implementing scene-agnostic instantiation capable of generating infinite distinct episodes. Please look at the setter methods of kinematic states in OmniGibson for a robust example capable of instantiating BEHAVIOR activities with many objects. \n\n# Testing\n\nTo test the predicate evaluator, run `pytest` in project root.\n\nTo add a test, create a new python file under the tests directory, and add\nadditional functions prefixed with `test_` which include assert statements that\nshould evaluate true.\n\n# References \n\n[1] M. Ghallab, A. Howe, C. Knoblock, D. McDermott, A. Ram, M. Veloso, D. Weld, & D. Wilkins. PDDL - The Planning Domain Definition Language. Yale Center for Computational Vision and Control, TR-98-003/DCS TR-1165 (1998). [Online].\n\n[2] PDDL Parser (2020). Version 1.1. [Source code]. https://github.com/pucrs-automated-planning/pddl-parser. \n\n[3] C. Li*, F. Xia*, R. Mart\u00edn-Mart\u00edn*, M. Lingelbach, S. Srivastava, B. Shen, K. Vainio, C. Gokmen, G. Dharan, T. Jain, A. Kurenkov, C. K. Liu, H. Gweon, J. Wu, L. Fei-Fei, S. Savarese. iGibson 2.0: Object-Centric Simulation for Robot Learning of Everyday Household Tasks. CoRL 2021. \n\n[4] C. Li*, R. Zhang*, J. Wong*, C. Gokmen*, S. Srivastava*, R. Mart\u00edn-Mart\u00edn*, C. Wang*, G. Levine*, M. Lingelbach, J. Sun, M. Anvari, M. Hwang, M. Sharma, A. Aydin, D. Bansal, S. Hunter, K.-Y. Kim, A. Lou, C. R. Matthews, I. Villa-Renteria, J. H. Tang, C. Tang, F. Xia, S. Savarese, H. Gweon, C. K. Liu, J. Wu, L. Fei-Fei. BEHAVIOR-1K: A Benchmark for Embodied AI with 1,000 Everyday Activities and Realistic Simulation. CoRL 2022. \n",
"bugtrack_url": null,
"license": "",
"summary": "",
"version": "3.5.0",
"project_urls": {
"Homepage": "https://github.com/StanfordVL/bddl"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "4b0d337303552268eea2967bd86cf1deab8fa034c8b84680b53a4e0e2df643ec",
"md5": "b2d2f8128973f34507993a5d737c0b17",
"sha256": "1c994730d65170a2331224fdaf58e8c0e3862defd019099e42fa1ba656c2ce92"
},
"downloads": -1,
"filename": "bddl-3.5.0.tar.gz",
"has_sig": false,
"md5_digest": "b2d2f8128973f34507993a5d737c0b17",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 1622553,
"upload_time": "2024-03-18T01:13:29",
"upload_time_iso_8601": "2024-03-18T01:13:29.926594Z",
"url": "https://files.pythonhosted.org/packages/4b/0d/337303552268eea2967bd86cf1deab8fa034c8b84680b53a4e0e2df643ec/bddl-3.5.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-18 01:13:29",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "StanfordVL",
"github_project": "bddl",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "bddl"
}
JSON
