Reference/API

Training

graspkit.stages.trainer.Trainer(
exp_cfg: ExperimentConfig,
policy_cls: Callable[..., GraspPolicy] = GraspPolicy
)

Trains a GraspPolicy on GraspDataset batches, with DDP, checkpoints and periodic simulation evaluation.

Parameters
exp_cfgExperimentConfigrequired
policy_clsCallable[..., GraspPolicy]= GraspPolicy
Members
attribute[source]
Trainer.traj_builder: GraspTrajBuilder | None
attribute[source]
Trainer.evaluator: BaseEnv | None
method[source]
Trainer.train(
train_dataloader: DataLoader,
test_dataloader: DataLoader | None = None,
checkpoint_dir: Path | None = None,
metadata: dict | None = None,
resume: dict | None = None,
publish: Callable[[Path], None] | None = None
)

Train normally, or save resumable single-device milestones and publish them.

Parameters
train_dataloaderDataLoaderrequired
test_dataloaderDataLoader | None= None
checkpoint_dirPath | None= None
metadatadict | None= None
resumedict | None= None
publishCallable[[Path], None] | None= None
method[source]
Trainer.train_graph(
dataset: GraspDataset,
index_loader: DataLoader
)

train for TrainerConfig.cuda_graph: the same updates, with the step captured once as a CUDA graph.

Parameters
datasetGraspDatasetrequired
index_loaderDataLoaderrequired
method[source]
Trainer.evaluate(
test_dataloader: DataLoader,
num_samples_per_scene: int = 1
)
Parameters
test_dataloaderDataLoaderrequired
num_samples_per_sceneint= 1
graspkit.configs.experiment_config.TrainerConfig(
seed: int = 0,
evaluator: Optional[EnvConfig] = None,
eval_only: bool = False,
eval_on_train: bool = False,
track: bool = False,
wandb_project_name: str = 'GraspKit',
batch_size: int = 32,
eval_num_envs: int = 32,
max_eval_batches: int = 100,
eval_pen_threshold: float = 0.005,
total_iters: int = 100000,
num_dataloader_workers: int = 12,
lr: float = 0.0001,
weight_decay: float = 0.0001,
log_freq: int = 100,
eval_freq: int = 10000,
save_freq: int = 10000,
cuda_graph: bool = False,
fast_step: bool = False,
grad_clip_norm: float = 0.0
)

Training-loop parameters for Trainer.

AdamW's learning rate drops 10x at two thirds of total_iters; that schedule has no field.

Parameters
seedint= 0
evaluatorOptional[EnvConfig]= None
eval_onlybool= False
eval_on_trainbool= False
trackbool= False
wandb_project_namestr= 'GraspKit'
batch_sizeint= 32
eval_num_envsint= 32
max_eval_batchesint= 100
eval_pen_thresholdfloat= 0.005
total_itersint= 100000
num_dataloader_workersint= 12
lrfloat= 0.0001
weight_decayfloat= 0.0001
log_freqint= 100
eval_freqint= 10000
save_freqint= 10000
cuda_graphbool= False
fast_stepbool= False
grad_clip_normfloat= 0.0
Members
attribute[source]
TrainerConfig.seed: int = 0

Seeds model initialization, dataset workers and sampling.

attribute[source]
TrainerConfig.evaluator: Optional[EnvConfig] = None

Simulation for periodic evaluation, built with build_env; None disables evaluation.

attribute[source]
TrainerConfig.eval_only: bool = False

Skip training, load ExperimentConfig.ckpt_path and evaluate one trajectory per scene.

attribute[source]
TrainerConfig.eval_on_train: bool = False

Evaluate on the train split instead of test, for small scene sets without test scenes.

attribute[source]
TrainerConfig.track: bool = False

Log to Weights & Biases, which also syncs the TensorBoard scalars.

attribute[source]
TrainerConfig.wandb_project_name: str = 'GraspKit'

W&B project used when track is set.

attribute[source]
TrainerConfig.batch_size: int = 32

Global batch size in scenes; each DDP rank gets batch_size // world_size.

attribute[source]
TrainerConfig.eval_num_envs: int = 32

Evaluator parallelism; capped at batch_size during training.

attribute[source]
TrainerConfig.max_eval_batches: int = 100

Stop evaluation after this many data-loader batches.

attribute[source]
TrainerConfig.eval_pen_threshold: float = 0.005

Penetration depth (m) below which an eval grasp counts toward pass-rate (report-only).

attribute[source]
TrainerConfig.total_iters: int = 100000

Final training iteration; the loop runs iterations 0 through this value.

attribute[source]
TrainerConfig.num_dataloader_workers: int = 12

Worker processes for the training and evaluation data loaders.

attribute[source]
TrainerConfig.lr: float = 0.0001

AdamW learning rate.

attribute[source]
TrainerConfig.weight_decay: float = 0.0001

AdamW weight decay.

attribute[source]
TrainerConfig.log_freq: int = 100

Iterations between loss logs, and TensorBoard scalars when tracking.

attribute[source]
TrainerConfig.eval_freq: int = 10000

Iterations between simulation evaluations; iteration 0 is skipped.

attribute[source]
TrainerConfig.save_freq: int = 10000

Iterations between iter_<N>.pt checkpoints, iteration 0 included.

attribute[source]
TrainerConfig.cuda_graph: bool = False

Capture training on prepared HDF5 views as a CUDA graph; single GPU without evaluation.

attribute[source]
TrainerConfig.fast_step: bool = False

Use TF32 and fused AdamW for ordinary training steps.

attribute[source]
TrainerConfig.grad_clip_norm: float = 0.0

Clip the gradient norm before an optimizer step; zero disables clipping.

graspkit.datasets.grasp_dataset.GraspDataset(
cfg: DatasetConfig,
h5_path: str,
scene_description_path: str,
split: Literal['train', 'test'] | None = 'train',
indices_only: bool = False
)
Bases: Dataset

Per-scene point-cloud observations and successful grasp trajectories from a processed HDF5.

Parameters
cfgDatasetConfigrequired
h5_pathstrrequired
scene_description_pathstrrequired
splitLiteral['train', 'test'] | None= 'train'
indices_onlybool= False
Members
method[source]
GraspDataset.to_device(
device: str | torch.device
) -> dict[str, torch.Tensor]

Load prepared observations and actions once for CUDA batch gathering.

Parameters
devicestr | torch.devicerequired
Returns
dict[str, torch.Tensor]
graspkit.configs.experiment_config.DatasetConfig(
num_actions: int = 64,
num_points: int = 2048,
return_actions: bool = True,
return_graspness: bool = False,
return_object_pointcloud_only: bool = False,
cache_in_memory: bool = False,
return_rgb: bool = True,
fuse_views: int = 0,
view_noise: float = 0.0,
point_noise: float = 0.0,
aug_prob: float = 0.0,
aug_keep_min: float = 0.1,
aug_voxel_max: float = 0.0,
aug_drop_wrist_prob: float = 0.0,
aug_rgb_prob: float = 0.0
)

Dataset loading parameters for GraspDataset.

One index is one scene, not one grasp; raw views resample points and actions on every access.

Parameters
num_actionsint= 64
num_pointsint= 2048
return_actionsbool= True
return_graspnessbool= False
return_object_pointcloud_onlybool= False
cache_in_memorybool= False
return_rgbbool= True
fuse_viewsint= 0
view_noisefloat= 0.0
point_noisefloat= 0.0
aug_probfloat= 0.0
aug_keep_minfloat= 0.1
aug_voxel_maxfloat= 0.0
aug_drop_wrist_probfloat= 0.0
aug_rgb_probfloat= 0.0
Members
attribute[source]
DatasetConfig.num_actions: int = 64

Successful action trajectories sampled per scene, with replacement when a scene has fewer.

attribute[source]
DatasetConfig.num_points: int = 2048

Point-cloud points per scene, with replacement when the cloud is smaller.

attribute[source]
DatasetConfig.return_actions: bool = True

Return the (num_actions, 3, D) supervision tensor; training needs it and evaluation turns it off.

attribute[source]
DatasetConfig.return_graspness: bool = False

Return per-point graspness and the best conditioning-point indices, for local-feature SpConv policies; needs data processed with enable_contact_extraction.

attribute[source]
DatasetConfig.return_object_pointcloud_only: bool = False

Sample only target-object points instead of the full cropped scene cloud.

attribute[source]
DatasetConfig.cache_in_memory: bool = False

Cache observations and actions in RAM; sampling stays unchanged.

attribute[source]
DatasetConfig.return_rgb: bool = True

Include RGB and camera poses when available.

attribute[source]
DatasetConfig.fuse_views: int = 0

Object-only multi-view data: fuse view 0 (the head) with up to this many other views, a random count per sample, into one cloud. 0: one random view.

attribute[source]
DatasetConfig.view_noise: float = 0.0

With fuse_views: std of each view's rigid misalignment, meters (translation) and x10 radians (rotation).

attribute[source]
DatasetConfig.point_noise: float = 0.0

With fuse_views: std of per-point Gaussian noise (m).

attribute[source]
DatasetConfig.aug_prob: float = 0.0

With fuse_views: probability of the perception augmentation (datasets/perception_aug.py) per sample; needs renders that keep the neighbours (extract_segments=[]) and camera poses in the processed h5.

attribute[source]
DatasetConfig.aug_keep_min: float = 0.1

Perception aug: fused-cloud keep fraction, log-uniform in [aug_keep_min, 1].

attribute[source]
DatasetConfig.aug_voxel_max: float = 0.0

Perception aug: voxel dedup size (m), applied with p 0.5 (the old gate pipeline's 3 mm thinning).

attribute[source]
DatasetConfig.aug_drop_wrist_prob: float = 0.0

Perception aug: probability of the head view alone (no wrist view).

attribute[source]
DatasetConfig.aug_rgb_prob: float = 0.0

Perception aug: probability of the RGB / MoGe depth-error model (per sample).