Named terrain | Unify PDB entities | Import guard

source/user_guide/advanced_topics/naming_and_variables.md

@@ -86,7 +86,6 @@ For links,
         cd_vel=gs.ti_vec3,            # com-based velocity (linear)
         root_COM=gs.ti_vec3,          # center of mass of the root link's subtree
         mass_sum=gs.ti_float,         # total mass of the subtree rooted at this link
-        COM=gs.ti_vec3,               # local center of mass of this link
         mass_shift=gs.ti_float,       # mass shift
         i_pos_shift=gs.ti_vec3,       # inertia position shift
         cfrc_flat_ang=gs.ti_vec3,     # com-based interaction force (angular)
@@ -215,7 +214,7 @@ For particles,
 * Static particle information (`particles_info`)
     ```python
     ti.types.struct(
-        mat_idx=gs.ti_int,            # material id
+        material_idx=gs.ti_int,       # material id
         mass=gs.ti_float,             # mass
         default_Jp=gs.ti_float,       # default volume ratio
         free=gs.ti_int,               # whether the particle is free; non-free particles behave as boundary conditions
@@ -291,7 +290,7 @@ For elements,
         mu=gs.ti_float,              # lame parameters (1)
         lam=gs.ti_float,             # lame parameters (2)
         mass_scaled=gs.ti_float,     # scaled element mass. The real mass is mass_scaled / self._vol_scale
-        mat_idx=gs.ti_int,           # material model index
+        material_idx=gs.ti_int,      # material model index
         B=gs.ti_mat3,                # the inverse of the undeformed shape matrix
         muscle_group=gs.ti_int,      # muscle/actuator group
         muscle_direction=gs.ti_vec3, # muscle/actuator direction
@@ -355,7 +354,7 @@ For particles,
         mass=gs.ti_float,                 # mass
         pos_rest=gs.ti_vec3,              # rest position
         rho_rest=gs.ti_float,             # rest density
-        mat_type=gs.ti_int,               # material type
+        material_type=gs.ti_int,          # material type
         mu_s=gs.ti_float,                 # static friction coefficient
         mu_k=gs.ti_float,                 # dynamic friction coefficient
         air_resistance=gs.ti_float,       # coefficient of drag / damping due to air

source/user_guide/getting_started/soft_robots.md

@@ -220,10 +220,10 @@ robot = scene.add_entity(
         fixed=True,
     ),
     material=gs.materials.Hybrid(
-        mat_rigid=gs.materials.Rigid(
+        material_rigid=gs.materials.Rigid(
             gravity_compensation=1.,
         ),
-        mat_soft=gs.materials.MPM.Muscle( # to allow setting group
+        material_soft=gs.materials.MPM.Muscle( # to allow setting group
             E=1e4,
             nu=0.45,
             rho=1000.,

source/user_guide/getting_started/terrain.md

@@ -140,8 +140,8 @@ For a complete list of keyword arguments please refer to the autogenerated API p
 ---
 
 ### Saving & re-using terrains
-When a terrain is first created Genesis serialises the watertight mesh, a simplified mesh for visuals, and the height map to `~/.genesis/assets/terrain/<name>/`.  By passing `from_stored="my_saved_terrain"` you can load it later without regeneration.
+When a terrain is created, Genesis generates the height map, the watertight mesh for collision detection and the simplified mesh for visuals. One can enable caching of the height map when a terrain is first created for a given set of options by passing `name="my_terrain"`, which would later be loaded from cache without regeneration. This is useful for reconstructing randomized terrains exactly.
 
 ---
 
-Happy climbing! 🧗‍♂️🏔️ 
+Happy climbing! 🧗‍♂️🏔️

source/user_guide/overview/installation.md

@@ -60,7 +60,42 @@ export OMNI_KIT_ACCEPT_EULA=yes
 
 ## Troubleshooting
 
-### Import error
+### Import Error
+
+#### 'Genesis hasn't been initialized'
+
+Genesis is not initialized, trying to import any engine-related submodule will raise an exception, e.g.;
+```python
+Traceback (most recent call last):
+  File "/home/jeremy/Downloads/Genesis_Jeremy/examples/./init_error.py", line 3, in <module>
+    from genesis.engine.entities import RigidEntity
+  File "/home/jeremy/.pyenv/versions/spider-genesis/lib/python3.11/site-packages/genesis/engine/entities/__init__.py", line 1, in <module>
+    from .avatar_entity import AvatarEntity
+  File "/home/jeremy/.pyenv/versions/spider-genesis/lib/python3.11/site-packages/genesis/engine/entities/avatar_entity/__init__.py", line 1, in <module>
+    from .avatar_entity import AvatarEntity
+  File "/home/jeremy/.pyenv/versions/spider-genesis/lib/python3.11/site-packages/genesis/engine/entities/avatar_entity/avatar_entity.py", line 6, in <module>
+    from ..rigid_entity import RigidEntity
+  File "/home/jeremy/.pyenv/versions/spider-genesis/lib/python3.11/site-packages/genesis/engine/entities/rigid_entity/__init__.py", line 1, in <module>
+    from .rigid_entity import RigidEntity
+  File "/home/jeremy/.pyenv/versions/spider-genesis/lib/python3.11/site-packages/genesis/engine/entities/rigid_entity/rigid_entity.py", line 14, in <module>
+    from genesis.utils import array_class
+  File "/home/jeremy/.pyenv/versions/spider-genesis/lib/python3.11/site-packages/genesis/utils/array_class.py", line 13, in <module>
+    gs.raise_exception("Genesis hasn't been initialized. Did you call `gs.init()`?")
+  File "/home/jeremy/.pyenv/versions/spider-genesis/lib/python3.11/site-packages/genesis/utils/misc.py", line 42, in raise_exception
+    raise gs.GenesisException(msg)
+genesis.GenesisException: Genesis hasn't been initialized. Did you call `gs.init()`?
+```
+
+This error is bug but expected. Any engine-related submodules must be imported after initializing Genesis to have the opportunity to configure low-level GsTaichi features such as fast cache mechanism or Gstaichi dynamic array mode. In practice, this limitation should not be a blocker for anybody, because engine-related classes are not meant to be instantiated manually. Still, it may be convenient to import them for type checking. If so, just use typing checking guard, e.g.:
+```python
+from typing import TYPE_CHECKING
+
+import genesis as gs
+if TYPE_CHECKING:
+    from genesis.engine.entities.drone_entity import DroneEntity
+```
+
+#### Circular Import Error
 
 Python would fail to (circular) import Genesis if the current directory is the source directory of Genesis. This is likely due to Genesis being installed WITHOUT enabling editable mode, either from PyPI Package Index or from source. The obvious workaround is moving out of the source directory of Genesis before running Python. The long-term solution is simply switching to editable install mode: first uninstall Python package `genesis-world`, then run `pip install -e '.[render]'` inside the source directory of Genesis.