Skip to content

Commit f62a4e3

Browse files
Kashu7100Kashu7100
committed
Merge remote-tracking branch 'origin/main' into feat-gui
2 parents 0da4d94 + 69028c3 commit f62a4e3

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

68 files changed

+3458
-3721
lines changed

‎.github/contributing/ARCHITECTURE.md‎

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
# Genesis Architecture
2+
3+
## Project Structure
4+
5+
```
6+
Genesis/
7+
├── genesis/ # Main source code
8+
│ ├── __init__.py # Entry point, gs.init(), global state
9+
│ ├── engine/ # Core simulation engine
10+
│ │ ├── scene.py # Scene class - main API entry point
11+
│ │ ├── simulator.py # Manages all solvers
12+
│ │ ├── entities/ # Entity types (RigidEntity, MPMEntity, etc.)
13+
│ │ ├── solvers/ # Physics solvers
14+
│ │ │ ├── rigid/ # Rigid body solver
15+
│ │ │ ├── mpm_solver.py # Material Point Method
16+
│ │ │ ├── sph_solver.py # Smoothed Particle Hydrodynamics
17+
│ │ │ ├── fem_solver.py # Finite Element Method
18+
│ │ │ ├── pbd_solver.py # Position Based Dynamics
19+
│ │ │ └── sf_solver.py # Stable Fluid
20+
│ │ ├── materials/ # Material definitions per solver
21+
│ │ └── couplers/ # Inter-solver coupling
22+
│ ├── options/ # Configuration classes (Pydantic models)
23+
│ │ ├── morphs.py # Shape definitions (Box, Mesh, URDF, MJCF)
24+
│ │ ├── solvers.py # Solver configuration options
25+
│ │ └── surfaces.py # Surface properties
26+
│ ├── vis/ # Visualization (Visualizer, Camera, Viewer)
27+
│ ├── sensors/ # Sensor systems (camera, IMU, etc.)
28+
│ └── utils/ # Utilities (mesh, geometry, etc.)
29+
├── tests/ # Test files
30+
├── examples/ # Example scripts
31+
└── genesis/assets/ # Built-in meshes, URDFs, textures
32+
```
33+
34+
## Core Components Flow
35+
36+
```
37+
gs.init() → Scene → Simulator → Solvers → Entities
38+
↓
39+
Visualizer → Viewer / Cameras
40+
```
41+
42+
## Entities
43+
44+
Entities are physical objects in the simulation:
45+
46+
| Entity Type | Solver | Use Case |
47+
|-------------|--------|----------|
48+
| `RigidEntity` | Rigid | Robots, rigid objects |
49+
| `MPMEntity` | MPM | Deformable solids, granular materials |
50+
| `SPHEntity` | SPH | Liquids, fluids |
51+
| `FEMEntity` | FEM | Finite element deformable bodies |
52+
| `PBD2DEntity`, `PBD3DEntity` | PBD | Cloth, soft bodies |
53+
| `DroneEntity` | Rigid | Quadcopters with aerodynamics |
54+
| `ToolEntity` | Tool | Cutting/interaction tools |
55+
56+
Location: `genesis/engine/entities/`
57+
58+
## Morphs
59+
60+
Morphs define geometry and initial pose (solver-agnostic):
61+
62+
```python
63+
# Primitives
64+
gs.morphs.Box(size=(1, 1, 1), pos=(0, 0, 0.5))
65+
gs.morphs.Sphere(radius=0.5, pos=(0, 0, 1))
66+
gs.morphs.Plane()
67+
68+
# Robot descriptions
69+
gs.morphs.URDF(file="path/to/robot.urdf", fixed=True)
70+
gs.morphs.MJCF(file="path/to/robot.xml")
71+
```
72+
73+
Location: `genesis/options/morphs.py`
74+
75+
## Materials
76+
77+
Materials define physical properties and determine which solver handles the entity:
78+
79+
```python
80+
gs.materials.Rigid(rho=1000)
81+
gs.materials.MPM.Elastic(E=1e5, nu=0.3)
82+
gs.materials.SPH.Liquid(sampler="pbs")
83+
gs.materials.PBD.Cloth(stretch_compliance=0.0)
84+
```
85+
86+
Location: `genesis/engine/materials/`
87+
88+
## Solvers
89+
90+
| Solver | Options Class | Purpose |
91+
|--------|--------------|---------|
92+
| Rigid | `gs.options.RigidOptions` | Articulated rigid body dynamics |
93+
| MPM | `gs.options.MPMOptions` | Continuum mechanics |
94+
| SPH | `gs.options.SPHOptions` | Fluid simulation |
95+
| FEM | `gs.options.FEMOptions` | Finite element deformation |
96+
| PBD | `gs.options.PBDOptions` | Fast soft body simulation |
97+
| SF | `gs.options.SFOptions` | Eulerian fluid/smoke |
98+
99+
Location: `genesis/engine/solvers/`
100+
101+
## Key Files Reference
102+
103+
| File | Purpose |
104+
|------|---------|
105+
| `genesis/__init__.py` | Package entry, `gs.init()`, global state |
106+
| `genesis/engine/scene.py` | `Scene` class - main user interface |
107+
| `genesis/engine/simulator.py` | `Simulator` - manages all solvers |
108+
| `genesis/options/morphs.py` | Shape/geometry definitions |
109+
| `genesis/options/solvers.py` | Solver option classes |

‎.github/contributing/CODING_CONVENTIONS.md‎

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
# Coding Conventions
2+
3+
## Import Pattern
4+
5+
```python
6+
import genesis as gs
7+
import genesis.utils.geom as gu
8+
import numpy as np
9+
import torch
10+
```
11+
12+
## Naming Conventions
13+
14+
- Classes: `PascalCase` (e.g., `RigidEntity`, `SimOptions`)
15+
- Functions/methods: `snake_case` (e.g., `add_entity`, `get_dofs_position`)
16+
- Constants: `UPPER_CASE` (e.g., `EPS`, `GS_ARCH`)
17+
- Private: `_leading_underscore` (e.g., `_initialized`)
18+
19+
## Configuration via Pydantic Options
20+
21+
All configuration uses Pydantic models in `genesis/options/`:
22+
23+
```python
24+
scene = gs.Scene(
25+
sim_options=gs.options.SimOptions(dt=0.01, substeps=2),
26+
rigid_options=gs.options.RigidOptions(enable_collision=True),
27+
vis_options=gs.options.VisOptions(show_world_frame=True),
28+
)
29+
```
30+
31+
## Tensor Operations
32+
33+
Genesis uses PyTorch tensors on `gs.device`:
34+
35+
```python
36+
# Always specify device
37+
positions = torch.zeros(n_envs, n_dofs, device=gs.device)
38+
39+
# Convert numpy to torch
40+
torch_tensor = torch.from_numpy(numpy_array).to(gs.device)
41+
```
42+
43+
## Error Handling
44+
45+
```python
46+
# Use Genesis exception for domain errors
47+
gs.raise_exception("Invalid parameter value")
48+
49+
# Use warnings for non-critical issues
50+
gs.logger.warning("Deprecated feature used")
51+
```
52+
53+
## Build Pattern
54+
55+
Always call `scene.build()` before simulation:
56+
57+
```python
58+
scene = gs.Scene()
59+
scene.add_entity(...) # Add all entities first
60+
scene.build(n_envs=1) # Compile kernels
61+
scene.step() # Now safe to step
62+
```
63+
64+
## Backend Selection
65+
66+
```python
67+
import genesis as gs
68+
69+
# CPU backend (default for debug mode)
70+
gs.init(backend=gs.cpu)
71+
72+
# GPU backend (auto-selects CUDA/Metal/Vulkan)
73+
gs.init(backend=gs.gpu)
74+
75+
# Explicit precision
76+
gs.init(backend=gs.gpu, precision="32") # or "64"
77+
```
78+
79+
## Common API Patterns
80+
81+
### Basic Simulation Loop
82+
83+
```python
84+
import genesis as gs
85+
86+
gs.init(backend=gs.gpu)
87+
scene = gs.Scene(show_viewer=True)
88+
89+
plane = scene.add_entity(gs.morphs.Plane())
90+
robot = scene.add_entity(
91+
gs.morphs.MJCF(file="xml/franka_emika_panda/panda.xml"),
92+
material=gs.materials.Rigid(),
93+
)
94+
95+
scene.build()
96+
97+
for _ in range(1000):
98+
scene.step()
99+
```
100+
101+
### Parallel Environments
102+
103+
```python
104+
import genesis as gs
105+
import torch
106+
107+
gs.init(backend=gs.gpu)
108+
scene = gs.Scene(show_viewer=False)
109+
robot = scene.add_entity(gs.morphs.MJCF(file="xml/franka_emika_panda/panda.xml"))
110+
111+
# Build with multiple environments
112+
n_envs = 100
113+
scene.build(n_envs=n_envs, env_spacing=(1.0, 1.0))
114+
115+
# Control all environments at once
116+
target = torch.zeros(n_envs, robot.n_dofs, device=gs.device)
117+
robot.control_dofs_position(target)
118+
```

‎.github/contributing/EXAMPLES.md‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
# Examples Reference
2+
3+
Location: `examples/` (105 files total)
4+
5+
## Running Examples
6+
7+
```bash
8+
uv run examples/tutorials/hello_genesis.py
9+
uv run examples/rigid/single_franka.py
10+
```
11+
12+
## Categories
13+
14+
| Directory | Files | Description |
15+
|-----------|-------|-------------|
16+
| `tutorials/` | 18 | Getting started guides |
17+
| `rigid/` | 29 | Rigid body and robot examples |
18+
| `coupling/` | 11 | Multi-physics coupling |
19+
| `drone/` | 7 | Quadcopter simulations |
20+
| `IPC_Solver/` | 5 | IPC contact examples |
21+
| `locomotion/` | 4 | Quadruped training |
22+
| `manipulation/` | 4 | Grasping and manipulation |
23+
| `rendering/` | 4 | Rendering demos |
24+
| `sensors/` | 4 | Sensor examples |
25+
| `sap_coupling/` | 4 | SAP coupling examples |
26+
| `collision/` | 3 | Collision demos |
27+
| `speed_benchmark/` | 3 | Performance benchmarks |
28+
29+
## Key Examples
30+
31+
### Getting Started
32+
- `tutorials/hello_genesis.py` - Basic introduction
33+
- `tutorials/control_your_robot.py` - Robot control basics
34+
- `tutorials/parallel_simulation.py` - Batched environments
35+
36+
### Robotics
37+
- `rigid/single_franka.py` - Single Franka arm
38+
- `rigid/ik_franka.py` - Inverse kinematics
39+
- `rigid/domain_randomization.py` - Domain randomization
40+
41+
### Multi-Physics
42+
- `coupling/cloth_on_rigid.py` - Cloth-rigid coupling
43+
- `coupling/sph_rigid.py` - Fluid-rigid coupling
44+
- `coupling/sand_wheel.py` - Granular-rigid coupling
45+
46+
### Training
47+
- `locomotion/go2_env.py` - Quadruped RL environment
48+
- `manipulation/grasp_env.py` - Grasping RL environment

.github/CONTRIBUTING.md renamed to .github/contributing/PULL_REQUESTS.md

File renamed without changes.

‎.github/contributing/TESTING.md‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
# Testing Guide
2+
3+
## Environment Setup
4+
5+
Use `uv` for running tests:
6+
7+
```bash
8+
# Setup environment (if not already done)
9+
uv sync
10+
11+
# Install PyTorch for your platform (see README.md)
12+
uv pip install torch --index-url https://download.pytorch.org/whl/cu126 # NVIDIA
13+
```
14+
15+
## Running Tests
16+
17+
```bash
18+
# Run all tests (parallel, excludes benchmarks and examples)
19+
uv run pytest tests/
20+
21+
# Run specific test file
22+
uv run pytest tests/test_rigid_physics.py
23+
24+
# Run with GPU backend
25+
uv run pytest tests/ --backend=gpu
26+
27+
# Run with visualization (disables parallelism)
28+
uv run pytest tests/ --vis
29+
30+
# Run in debug mode
31+
uv run pytest tests/ --dev
32+
33+
# Run specific markers
34+
uv run pytest tests/ -m required
35+
uv run pytest tests/ -m "not slow"
36+
37+
# In restricted environments (sandboxes, containers), disable retry plugins:
38+
uv run pytest tests/ -p no:pytest-retry -p no:rerunfailures
39+
```
40+
41+
## Test Markers
42+
43+
| Marker | Description |
44+
|--------|-------------|
45+
| `required` | Minimal test set that must pass before merging |
46+
| `slow` | Tests taking >100s |
47+
| `examples` | Example scripts |
48+
| `benchmarks` | Performance benchmarks |
49+
50+
## Key Fixtures
51+
52+
From `tests/conftest.py`:
53+
54+
| Fixture | Scope | Description |
55+
|---------|-------|-------------|
56+
| `initialize_genesis` | function | Auto-initializes and destroys Genesis per test |
57+
| `backend` | session | Returns configured backend (gs.cpu/gs.gpu) |
58+
| `precision` | function | Returns precision ("32" or "64") |
59+
| `show_viewer` | session | Whether viewer is enabled |
60+
| `tol` | function | Tolerance based on precision |
61+
62+
## Writing Tests
63+
64+
```python
65+
import pytest
66+
import genesis as gs
67+
68+
def test_example(initialize_genesis, backend):
69+
"""Test runs with auto-initialized Genesis."""
70+
scene = gs.Scene()
71+
entity = scene.add_entity(gs.morphs.Box(size=(1, 1, 1)))
72+
scene.build()
73+
scene.step()
74+
assert entity.get_pos()[2] > 0
75+
76+
@pytest.mark.slow
77+
def test_long_simulation(initialize_genesis):
78+
"""Mark slow tests explicitly."""
79+
pass
80+
81+
@pytest.mark.required
82+
def test_critical_feature(initialize_genesis):
83+
"""Mark tests that must always pass."""
84+
pass
85+
```
86+
87+
## CI Requirements
88+
89+
Before submitting a PR, ensure tests pass locally:
90+
91+
```bash
92+
uv run pytest -v -m required tests/
93+
```

‎.github/pull_request_template.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
11
<!-- Thanks for sending a pull request! Please:
22
3-
1. Follow our contributor guidelines:
4-
https://github.com/Genesis-Embodied-AI/Genesis/blob/main/.github/CONTRIBUTING.md
5-
2. Prepare your PR according to the "Submitting Code Changes"
6-
section of https://github.com/Genesis-Embodied-AI/Genesis/blob/main/.github/CONTRIBUTING.md
3+
1. Follow our contributor guidelines:
4+
https://github.com/Genesis-Embodied-AI/Genesis/blob/main/.github/contributing/PULL_REQUESTS.md
5+
2. Prepare your PR according to the "Submitting Code Changes"
6+
section of https://github.com/Genesis-Embodied-AI/Genesis/blob/main/.github/contributing/PULL_REQUESTS.md
77
3. Provide a concise summary of your changes in the Title above
88
4. Prefix the title according to the type of issue you are addressing. Use:
99
- [BUG FIX] for non-breaking changes which fix an issue

0 commit comments

Comments
 (0)