Highlevel Experiments

---
name: highlevel-experiments
description: "Use Tianshou 2.0.1 high-level experiment builders for declarative
  Gymnasium-style RL experiments with minimal boilerplate."
disable-model-invocation: true
metadata:
  disco-role: operating
license: MIT
---

# High-Level Experiments

Use this sub-skill when a user asks for Tianshou's declarative high-level API, `ExperimentBuilder`, `DQNExperimentBuilder`, `PPOExperimentBuilder`, `SACExperimentBuilder`, algorithm params dataclasses, experiment configs, persistence/watch settings, or a quick builder-based experiment skeleton.

## Use This For

- Applying existing Tianshou algorithms to Gymnasium-style tasks with `EnvFactoryRegistered`, `ExperimentConfig`, and an on-policy or off-policy training config.
- Building `DQNExperimentBuilder`, `PPOExperimentBuilder`, `SACExperimentBuilder`, and related algorithm-specific builders with concise `with_*` chains.
- Disabling persistence, logs, watch/render, or GPU defaults for safe smoke tests and notebook/CI snippets.
- Translating simple procedural experiment requests into a high-level builder when no custom collector, policy, or trainer loop is required.

## Route Elsewhere

- Use `../procedural-training/SKILL.md` for manual network, policy, optimizer, collector, replay buffer, trainer, or custom algorithm wiring.
- Use `../data-collection/SKILL.md` for replay buffer mechanics, collector hooks, buffer sizing internals, and custom collection flows.
- Use `../envs-and-vectorization/SKILL.md` for optional environment engines, custom vectorization, EnvPool, Ray, Atari wrappers, MuJoCo/Box2D installs, or environment registration failures.

## Fast Start

1. Confirm the task id is available through Gymnasium and whether it has discrete or continuous actions.
2. Choose `EnvFactoryRegistered(task=..., venv_type=VectorEnvType.DUMMY)` for portable local smokes; use heavier vector types only when dependencies and multiprocessing constraints are known.
3. Set `ExperimentConfig(persistence_enabled=False, log_file_enabled=False, watch=False, device="cpu")` for safe construction and CI checks.
4. Pick `OffPolicyTrainingConfig` for DQN/SAC/DDPG/TD3/REDQ/IQN or `OnPolicyTrainingConfig` for PPO/A2C/TRPO/NPG/Reinforce.
5. Instantiate the algorithm builder, chain the matching params and default model/actor/critic factories, then call `.build()` for a construction check or `.run()` only for a deliberate training run.
6. Add `EpochStopCallbackRewardThreshold(...)` only when the experiment will actually train and test reward thresholds are meaningful.

## References

- `references/workflows.md` gives builder recipes, config decisions, persistence/watch/logging cautions, and high-level-to-procedural crossover guidance.
- `references/api-reference.md` summarizes current public high-level classes, builder methods, signatures, defaults, and algorithm-family mapping.
- `references/troubleshooting.md` covers API-v2 migration confusion, optional environment dependencies, persistence/logging directories, GPU defaults, parameter symptoms, and workflow failures.
- `scripts/check_highlevel_cartpole.py` imports high-level APIs and builds a bounded CartPole DQN experiment without long training, rendering, downloads, or source-checkout access.

## Guardrails

- Keep examples self-contained and runnable from an installed `tianshou` package; do not require the original repository checkout.
- Default new high-level smokes to CPU, `VectorEnvType.DUMMY`, `persistence_enabled=False`, and `watch=False` unless the user asks to train/watch/save.
- Do not use high-level builders when the user needs custom replay-buffer internals, collector hooks, or a custom training loop; route to the focused sibling sub-skill.
- Treat Atari, MuJoCo, Box2D, VizDoom, EnvPool, Ray, and robotics tasks as optional dependency areas that need explicit environment support before running.