Fabric Expert Loops

---
name: fabric-expert-loops
description: "Use this sub-skill for Lightning Fabric expert-controlled PyTorch
  loops: setup, launch, backward, dataloaders, precision/devices, logging,
  checkpointing, wrapping, and custom trainer loops."
disable-model-invocation: true
metadata:
  disco-role: operating
license: Apache 2.0
---

# Fabric Expert Loops

Use this sub-skill when the user wants Lightning Fabric rather than the high-level `Trainer`: manual PyTorch training loops, custom loop engines, explicit optimizer stepping, gradient accumulation, checkpoint dictionaries, rank-aware printing, Fabric CLI launch, or wrapping existing PyTorch code with minimal abstraction.

## Route Here

- Convert a raw PyTorch loop to Fabric while preserving manual control over epochs, batches, optimizers, schedulers, metrics, and checkpoint timing.
- Build a custom trainer loop around `lightning.Fabric` or `lightning.fabric.Fabric`.
- Use `Fabric.setup`, `Fabric.setup_dataloaders`, `Fabric.backward`, `Fabric.save`, `Fabric.load`, `Fabric.print`, `Fabric.log`, and rank/world utilities.
- Choose practical Fabric constructor options for `accelerator`, `strategy`, `devices`, `num_nodes`, `precision`, `plugins`, `callbacks`, and `loggers`.
- Diagnose Fabric-specific launch, wrapping, dataloader, precision, checkpoint, and API-mixing failures.

## Route Elsewhere

- High-level `Trainer`, `LightningModule`, callbacks, and `LightningDataModule` training workflows: `../training-core/SKILL.md`.
- FSDP, DeepSpeed, DDP, TPU, MPS, GPU visibility, multi-node, and precision deep dives: `../distributed-accelerators/SKILL.md`.
- `LightningCLI` / YAML config-driven `Trainer` applications: `../cli-configuration/SKILL.md`.

## Start Here

1. Confirm the user really needs manual loop control. If not, route to `training-core` and recommend `Trainer`.
2. For Fabric, start with the API table in `references/api-reference.md` and the conversion patterns in `references/workflows.md`.
3. For a local environment sanity check, run `python sub-skills/fabric-expert-loops/scripts/fabric_smoke.py --help`, then `python sub-skills/fabric-expert-loops/scripts/fabric_smoke.py --max-steps 2 --checkpoint-path fabric-smoke.pt` from a writable working directory.
4. For launch syntax, use `fabric run --accelerator=cpu --devices=1 sub-skills/fabric-expert-loops/scripts/fabric_smoke.py --max-steps 2`. When using `fabric run`, do not also call `fabric.launch()` in user code.
5. If the issue involves hardware support or distributed strategy internals, cross-check with `../distributed-accelerators/SKILL.md` before giving final advice.

## References

- `references/api-reference.md`: Fabric imports, constructor, core methods, wrappers, launch CLI, logging, and checkpoint APIs.
- `references/workflows.md`: raw PyTorch conversion, gradient accumulation, custom trainer loops, dataloaders, checkpoint resume, and validation patterns.
- `references/troubleshooting.md`: install/import, optional dependencies, launch/API misuse, device/precision, dataloader, wrapping, and checkpoint failures.
- `scripts/fabric_smoke.py`: self-contained CPU-safe tiny Fabric training loop with synthetic tensors and optional checkpoint round-trip.