Merge pull request #789 from StanfordVL/doc-update-multiple-envs

Doc update multiple envs

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)`.
+
 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 }
 

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()`.

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
 

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!
 

docs/modules/vector_environments.md

@@ -0,0 +1,36 @@
+---
+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. 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
+
+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)
+    ```

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/*