初始化与后端#

每个 Genesis World 程序都从一次 gs.init() 调用开始。它会选择计算后端、确定数值精度、为随机数生成器设置种子并配置日志：这些全局状态是此后构建的每个场景所依赖的基础。请在构造 gs.Scene 或任何选项对象之前调用一次。如果跳过它，第一次 API 调用就会抛出 GenesisException: Genesis hasn't been initialized. Did you call gs.init()?。

最小示例#

import genesis as gs

gs.init(backend=gs.gpu)

大多数程序需要的就这些：如果 GPU 可用就在 GPU 上运行，否则回退到 CPU。gs.init() 只接受关键字参数，下文将介绍实际使用中会遇到的参数。

选择后端#

backend 参数选择物理仿真运行的设备。请传入以下后端常量之一：

后端

运行于

gs.gpu

可用的最佳 GPU，支持自动回退（见下文）。

gs.cpu

CPU。

gs.cuda

NVIDIA CUDA GPU。

gs.amdgpu

AMD ROCm GPU。

gs.metal

Apple Silicon GPU。

Genesis World 按 CUDA → AMD → Metal → CPU 的顺序解析 gs.gpu（以及默认的 backend=None），采用在你的机器上第一个成功初始化的后端，因此 gs.gpu 可以跨硬件移植。如果没有可用的 GPU，它会回退到 CPU 并记录一条警告，而不是直接失败。

gs.init(backend=gs.gpu)   # portable: use a GPU if present, else CPU
gs.init(backend=gs.cpu)   # force CPU, e.g. for CI or debugging

初始化之后，可以在 gs 模块上读取解析后的后端和底层的 PyTorch 设备：

gs.init(backend=gs.gpu)
print(gs.backend)  # the backend actually selected, e.g. gs.cuda
print(gs.device)   # the torch.device tensors are placed on

Note

gs.init() 在每个进程中只能调用一次。再次调用会抛出 Genesis already initialized.。如需重新初始化，请先用 gs.destroy() 销毁当前后端。

精度#

precision 选择整个仿真中使用的浮点宽度。默认值为 "32"（单精度），"64" 则选择双精度：

gs.init(backend=gs.gpu, precision="64")

单精度更快、占用内存更少；双精度能在刚性较强或病态的场景中提供更高的数值余量，但会牺牲速度。这一选择还涉及三个细节：

  • 整数索引始终为 32 位，与 precision 无关。只有浮点数值会切换。

  • Apple Metal 不支持双精度。 在 backend=gs.metal 时请求 precision="64" 会抛出错误。

  • gs.init() 不会改变 PyTorch 的全局默认 dtype 和设备。你自己创建的张量需要设置 dtype=gs.tc_float 和 device=gs.device，才能与仿真匹配。

约定 介绍了 API 返回的 dtype。

可复现性#

传入 seed 可以让一次运行可重复。它会同时为 Python、NumPy、PyTorch 和 Quadrants 编译器设置种子：

gs.init(backend=gs.gpu, seed=0)

在 GPU 上，仅设置种子并不能保证逐位确定性，因为某些内核默认就是非确定性的。要获得完全确定性的运行，请加上 debug=True：

gs.init(backend=gs.cpu, seed=0, debug=True)

debug=True 会启用 PyTorch 的确定性算法、禁用 cuDNN 自动调优，并将日志级别提升到 DEBUG。它适合用来复现缺陷或验证结果，而不是用于生产运行，因为确定性内核要慢得多；在必须保证确定性的场合应坚持使用 gs.cpu，因为 GPU 后端只部分支持确定性。

确定性模式#

use_deterministic_algorithms=True 保证场景能够以完全相同的方式重放 rollout：重置场景，用相同的输入驱动它，在给定机器上每一步都会逐位复现上一次运行。

gs.init(backend=gs.gpu, use_deterministic_algorithms=True)

默认值为 use_deterministic_algorithms=None，此时会启用该模式，除非 performance_mode=True，后者情况下该模式保持关闭。传入 False 或 True 可以分别覆盖这两种默认行为。这一保证的代价是吞吐量，因此性能模式会将其关闭。关闭后，只要有助于提速，Genesis 就可以在运行时自行决定如何执行计算，而不要求每次做出相同的决定。目前这种自由度用于在多种实现之间做选择：同一计算有若干个可互换的实现，每个都针对不同的工作负载编写；仿真运行时，每个调用点都会为自己的候选实现计时，并选用对场景当前状态最快的那个。

可互换实现在构造上计算的是相同的内容，但结果只会在浮点噪声范围内一致，而仿真会放大这种差异，直到两次运行出现肉眼可见的分歧。因此，哪一步运行了哪个实现，本身就成了轨迹的一部分，而这一点完全不可复现：计时取决于机器的繁忙程度，测量值会跨重置不断累积，所以 rollout 还取决于该进程此前运行过的所有内容。这些测量值是有意累积的——训练循环中的环境会不断重置，常常一次重置一个，如果每次重置都重新开始测量，它们就会一直停留在测量阶段，而无法利用已测量的结果。确定性模式则完全放弃这种自由度：所有这类选择都会预先确定，采用适合大多数场景的选项，之后不再更改。

因此，它的代价取决于场景以及场景状态的演化程度：如果预定选择恰好就是本来会选中的那个，代价为零；而只要本来会由另一个实现接管，代价最多可达两种实现之间的差距。在吞吐量优先的场合，尤其是策略训练中，先用 use_deterministic_algorithms=False 测量你的场景，再决定是否保留该模式；如果要比较两次运行或排查分歧，则保持启用。

也可以手动做出选择：通过 Quadrants 的 QD_PERFDISPATCH_FORCE 环境变量固定某一个实现。这样会像确定性模式一样去掉测量，因此本身也是可复现的。如果确定性模式选定的实现不适合你的场景，就可以使用这种方式。对于约束求解——目前这一选择最重要的地方——有两个候选项：

# One thread per environment, each solved as a whole; favored when the environment count alone keeps the GPU busy.
QD_PERFDISPATCH_FORCE=func_solve_body:func_solve_body_monolith python my_script.py

# Parallelism inside each environment; favored when too few environments run to keep the GPU busy on their own.
QD_PERFDISPATCH_FORCE=func_solve_body:func_solve_decomposed python my_script.py

请注意，这只是指定内部实现的一种变通方法：它不属于公共 API，可能在任何版本中更改或消失。

日志#

gs.init() 会创建日志记录器，并通过 gs.logger 暴露。用 logging_level 控制其详细程度；未设置时默认为 "info"（当 debug=True 时为 "debug"）。

gs.init(backend=gs.gpu, logging_level="warning")  # quiet: warnings and errors only

设置 logger_verbose_time=True 后，每行日志会以完整时间戳作为前缀，而不是仅显示经过的时间。theme 参数（"dark"、"light" 或 "raw"）控制日志行的打印方式："dark" 和 "light" 会按对应背景色的终端为日志着色；"raw" 则输出无颜色、无横幅框、无 emoji 的朴素紧凑行，适合日志文件、持续集成和编码智能体。

性能模式#

启用 performance_mode=True 后，编译器会把静态张量形状固化到内核中，使仿真速度提升约 30%，代价是场景变化时需要重新编译（可能耗时数分钟）。在研究、调试和交互式工作中请保持关闭；在场景固定的策略训练和生产运行中则开启。

gs.init(backend=gs.gpu, performance_mode=True)  # fixed scene, maximum throughput

另请参阅#

  • 安装：安装 Genesis World 及其 GPU 驱动。

  • 选项系统：初始化之后配置场景本身。

  • 约定：API 遵循的坐标、单位、张量形状和 dtype 约定。

  • 你好，Genesis World：最小化的端到端场景。