From be25daff67c05533993f7a1ba65b984cdefe40de Mon Sep 17 00:00:00 2001 From: hang-yin Date: Fri, 5 Jul 2024 16:52:53 -0700 Subject: [PATCH 1/3] Update vector env doc --- docs/modules/vector_environments.md | 36 +++++++++++++++++++++++++++++ mkdocs.yml | 1 + 2 files changed, 37 insertions(+) create mode 100644 docs/modules/vector_environments.md diff --git a/docs/modules/vector_environments.md b/docs/modules/vector_environments.md new file mode 100644 index 000000000..d0ef0ee78 --- /dev/null +++ b/docs/modules/vector_environments.md @@ -0,0 +1,36 @@ +--- +icon: material/earth +--- + +# 🌌 **Vector Environments** + +## Description + +To support large-scale parallelization, we now support vector environments. Each environment is similar to our regular [environment](./environments.md), but our simulator now can keep track of multiple environments simultaneously. We have implemented many vectorized operations to optimize the performance of these parallel environments, significantly improving speed. We are also actively working on further enhancements to make them even faster. Some use cases for this include reinforcement learning, parallelized training with domain randomization, and parallelized policy evaluation. + +## Usage + +Creating a minimal vector environment requires the definition of a config dictionary. This dictionary is copied across all environments: + +??? code "vec_env_simple.py" + ``` python linenums="1" + import omnigibson as og + cfg = { + "scene": { + "type": "InteractiveTraversableScene", + "scene_model": "Rs_int", + "load_object_categories": ["floors", "walls"], + }, + "objects": [], + "robots": [ + { + "type": "Fetch", + "obs_modalities": [], + } + ] + } + + vec_env = og.VectorEnvironment(num_envs=3, config=cfg) + actions = [...] + observations, rewards, terminates, truncates, infos = vec_env.step(actions) + ``` diff --git a/mkdocs.yml b/mkdocs.yml index 484a9384c..24a1a6530 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -100,6 +100,7 @@ nav: - Transition Rules: modules/transition_rules.md - Simulator: modules/simulator.md - Environments: modules/environments.md + - Vector Environments: modules/vector_environments.md - Tutorials: - Demo Collection: tutorials/demo_collection.md - API Reference: reference/* From ceb55f94228a1791054e013fcca60b53cfeb5a59 Mon Sep 17 00:00:00 2001 From: hang-yin Date: Tue, 9 Jul 2024 14:37:08 -0700 Subject: [PATCH 2/3] Update scene, simulator, systems, transition rules, and vec env modules --- docs/modules/scenes.md | 2 ++ docs/modules/simulator.md | 6 +++--- docs/modules/systems.md | 6 +++--- docs/modules/transition_rules.md | 2 +- docs/modules/vector_environments.md | 4 ++-- 5 files changed, 11 insertions(+), 9 deletions(-) diff --git a/docs/modules/scenes.md b/docs/modules/scenes.md index df38cffbb..3a61327ed 100644 --- a/docs/modules/scenes.md +++ b/docs/modules/scenes.md @@ -34,6 +34,8 @@ Alternatively, a scene can be directly imported at runtime by first creating the ### Runtime +To import an object into a scene, call `scene.add_object(obj)`. To remove an object from a scene, call `scene.remove_object(obj)`. + The scene keeps track of and organizes all imported objects via its owned `scene.object_registry`. Objects can quickly be queried by relevant property keys (1), such as `name`, `prim_path`, and `category`, from `env.scene.object_registry` as follows: { .annotate } diff --git a/docs/modules/simulator.md b/docs/modules/simulator.md index f7f56f349..c9eb8654d 100644 --- a/docs/modules/simulator.md +++ b/docs/modules/simulator.md @@ -6,20 +6,20 @@ icon: material/repeat ## Description -**`OmniGibson`**'s [Simulator](../reference/simulator.html) class is the global singleton that serves as the interface with omniverse's low-level physx (physics) backend. It provides utility functions for modulating the ongoing simulation as well as the low-level interface for importing scenes and objects. For standard use-cases, interfacing with the simulation exclusively through a created [environment](./environments.md) should be sufficient, though for more advanced or prototyping use-cases it may be common to interface via this simulator class. +**`OmniGibson`**'s [Simulator](../reference/simulator.html) class is the global singleton that serves as the interface with omniverse's low-level physx (physics) backend. It provides utility functions for modulating the ongoing simulation as well as the low-level interface for importing scenes and objects. For standard use-cases, interfacing with the simulation exclusively through a created [environment](./environments.md) or [vector environment](./vector_environments.md) should be sufficient, though for more advanced or prototyping use-cases it may be common to interface via this simulator class. ## Usage ### Creating -Because this `Simulator` is a global singleton, it is instantiated every time the stage is cleared and always occurs at the _very beginning_ of **`OmniGibson`**'s launching. This either occurs when an environment instance is created (`env = Environment(...)`), when `og.launch()` is explicitly called, or whenever the stage is reset. +Because this `Simulator` is a global singleton, it is instantiated every time the stage is cleared and always occurs at the _very beginning_ of **`OmniGibson`**'s launching. This either occurs when an environment instance is created (`env = Environment(...)` or `vec_env = VectorEnvironment(...)`), when `og.launch()` is explicitly called, or whenever the stage is reset. ### Runtime After **`OmniGibson`** is launched, the simulator interface can be accessed globally via `og.sim`. Below, we briefly describe multiple common usages of the simulation interface: #### Importing and Removing Scenes / Objects -The simulator can directly import a scene via `sim.import_scene(scene)`, and an object can be imported into a scene via `scene.import_object(object)`. The imported scene and its corresponding objects can be directly accessed through `sim.scenes`. To remove a desired object, call `sim.remove_object(object)`. The simulator can also clear all the scenes via `og.clear()`. +The simulator can directly import a scene via `sim.import_scene(scene)`. The imported scene and its corresponding objects can be directly accessed through `sim.scenes`. To remove a desired object, call `sim.remove_object(object)`. The simulator can also clear all the scenes via `og.clear()`. #### Propagating Physics The simulator can be manually stepped, with or without physics / rendering (`sim.step()`, `sim.step_physics()`, `sim.render()`), and can be stopped (`sim.stop()`), paused (`sim.pause()`), or played (`sim.play()`). Note that physics only runs when the simulator is playing! The current sim mode can be checked via `sim.is_stopped()`, `sim.is_paused()`, and `sim.is_playing()`. diff --git a/docs/modules/systems.md b/docs/modules/systems.md index 07fb20e4d..456f7aae5 100644 --- a/docs/modules/systems.md +++ b/docs/modules/systems.md @@ -6,15 +6,15 @@ icon: material/water-outline ## Description -**`OmniGibson`**'s [`System`](../reference/systems/base_system.html) class represents global singletons that encapsulate a single particle type. These system classes provide functionality for generating, tracking, and removing any number of particles arbitrarily located throughout the current scene. +**`OmniGibson`**'s [`System`](../reference/systems/base_system.html)s represents scene singletons that encapsulate a single particle type. These systems provide functionality for generating, tracking, and removing any number of particles arbitrarily located throughout the current scene. ## Usage ### Creating -For efficiency reasons, systems are created dynamically on an as-needed basis. A system can be dynamically created (or referenced, if it already exists) via `get_system(name)`, where `name` defines the name of the system. For a list of all possible system names, see `REGISTERED_SYSTEMS`. Both of these utility functions can be directly imported from `omnigibson.systems`. +For efficiency reasons, systems are created dynamically on an as-needed basis. A system can be dynamically created (or referenced, if it already exists) via `scene.get_system(name)`, where `name` defines the name of the system. If you do not wish to initialize a system when refrencing it, e.g. for performance reasons, use the `force_init` flag: `scene.get_system(name, force_init=False)`. For a list of all possible system names, see `scene.system_registry.objects`. ### Runtime -A given system can be accessed globally at any time via `get_system(...)`. Systems can generate particles via `system.generate_particles(...)`, track their states via `system.get_particles_position_orientation()`, and remove them via `system.remove_particles(...)`. Please refer to the [`System`'s API Reference](../reference/systems/base_system.html) for specific information regarding arguments. Moreover, specific subclasses may implement more complex generation behavior, such as `VisualParticleSystem`s `generate_group_particles(...)` which spawn visual (non-collidable) particles that are attached to a specific object. +A given system can be accessed at any time via `scene.get_system(...)`. Systems can generate particles via `system.generate_particles(...)`, track their states via `system.get_particles_position_orientation()`, and remove them via `system.remove_particles(...)`. Please refer to the [`System`'s API Reference](../reference/systems/base_system.html) for specific information regarding arguments. Moreover, specific subclasses may implement more complex generation behavior, such as `VisualParticleSystem`s `generate_group_particles(...)` which spawn visual (non-collidable) particles that are attached to a specific object. ## Types diff --git a/docs/modules/transition_rules.md b/docs/modules/transition_rules.md index a6930cd85..88b90a305 100644 --- a/docs/modules/transition_rules.md +++ b/docs/modules/transition_rules.md @@ -20,7 +20,7 @@ Transition rules are **`OmniGibson`**'s method for simulating complex physical p Because `TransitionRule`s are monolithic classes, these should be defined _before_ **`OmniGibson`** is launched. A rule can be easily extended by subclassing the `BaseTransitionRule` class and implementing the necessary functions. For a simple example, please see the [`SlicingRule`](../reference/transition_rules.html#transition_rules.SlicingRule) class. ### Runtime -At runtime, the monolithic [`TransitionRuleAPI`](../reference/transition_rules.html#transition_rules.TransitionRuleAPI) automatically handles the stepping and processing of all defined transition rule classes. For efficiency reasons, rules are dynamically loaded and checked based on the object / system set currently active in the simulator. A rule will only be checked if there is at least one valid candidate combination amongst the current object / system set. For example, if there is no sliceable object present in the simulator, then `SlicingRule` will not be active. Every time an object / system is added / removed from the simulator, all rules are refreshed so that the current active transition rule set is always accurate. +At runtime, each scene owns a [`TransitionRuleAPI`](../reference/transition_rules.html#transition_rules.TransitionRuleAPI) instance, which automatically handles the stepping and processing of all defined transition rule classes. For efficiency reasons, rules are dynamically loaded and checked based on the object / system set currently active in the scene. A rule will only be checked if there is at least one valid candidate combination amongst the current object / system set. For example, if there is no sliceable object present in this scene, then `SlicingRule` will not be active. Every time an object / system is added / removed from the scene, all rules are refreshed so that the current active transition rule set is always accurate. In general, you should not need to interface with the `TransitionRuleAPI` class at all -- if your rule implementation is correct, then the API will automatically handle the transition when the appropriate conditions are met! diff --git a/docs/modules/vector_environments.md b/docs/modules/vector_environments.md index d0ef0ee78..cde0c9652 100644 --- a/docs/modules/vector_environments.md +++ b/docs/modules/vector_environments.md @@ -1,12 +1,12 @@ --- -icon: material/earth +icon: octicons/stack-16 --- # 🌌 **Vector Environments** ## Description -To support large-scale parallelization, we now support vector environments. Each environment is similar to our regular [environment](./environments.md), but our simulator now can keep track of multiple environments simultaneously. We have implemented many vectorized operations to optimize the performance of these parallel environments, significantly improving speed. We are also actively working on further enhancements to make them even faster. Some use cases for this include reinforcement learning, parallelized training with domain randomization, and parallelized policy evaluation. +To support large-scale parallelization, we now support vector environments. Each environment is similar to our regular [environment](./environments.md), but our simulator now can keep track of multiple environments simultaneously. We have implemented many vectorized operations to optimize the performance of these parallel environments. We are also actively working on further enhancements to make them faster. Some use cases for this include reinforcement learning, parallelized training with domain randomization, and parallelized policy evaluation. ## Usage From 5ce7b045d449a8f4e850c87c97d9c7d13cea44ce Mon Sep 17 00:00:00 2001 From: hang-yin Date: Thu, 11 Jul 2024 16:26:42 -0700 Subject: [PATCH 3/3] Minor fix --- docs/modules/scenes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/modules/scenes.md b/docs/modules/scenes.md index 3a61327ed..014ebc7e6 100644 --- a/docs/modules/scenes.md +++ b/docs/modules/scenes.md @@ -34,7 +34,7 @@ Alternatively, a scene can be directly imported at runtime by first creating the ### Runtime -To import an object into a scene, call `scene.add_object(obj)`. To remove an object from a scene, call `scene.remove_object(obj)`. +To import an object into a scene, call `scene.add_object(obj)`. The scene keeps track of and organizes all imported objects via its owned `scene.object_registry`. Objects can quickly be queried by relevant property keys (1), such as `name`, `prim_path`, and `category`, from `env.scene.object_registry` as follows: { .annotate }