> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lyceum.technology/llms.txt
> Use this file to discover all available pages before exploring further.

# Pythia

> Automatically find the right GPU for your PyTorch workload

Pythia analyzes the computational characteristics of your PyTorch workloads and maps them to the GPU architectures that deliver the best performance-cost efficiency. Instead of guessing which GPU you need or over-provisioning expensive resources, Pythia provides clear, evidence-based guidance on which option matches your requirements.

<Info>
  Pythia currently evaluates T4, A100, and H100 GPUs.
</Info>

## What You Get

Run a single command and Pythia will:

* **Predict memory requirements** to identify compatible hardware
* **Estimate runtime** for each GPU option
* **Recommend the best GPU** based on your workload

```
╭─────────────────────── GPU Selection Results ───────────────────────╮
│                                                                     │
│  ✓ Analysis complete                                                │
│                                                                     │
│  Recommended: A100 (40 GB VRAM)                                     │
│                                                                     │
╰─────────────────────────────────────────────────────────────────────╯

          Performance Results
┏━━━━━━┳━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━┓
┃ GPU  ┃ Status  ┃    Time ┃    Cost ┃
┡━━━━━━╇━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━┩
│ T4   │ success │   8.2hr │   $2.46 │
│ A100 │ success │   3.1hr │   $5.27 │
│ H100 │ success │   1.8hr │  $10.44 │
└──────┴─────────┴─────────┴─────────┘

              Compatible GPUs
┏━━━━━━━┳━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━━┓
┃ GPU   ┃  VRAM ┃ GPUs Needed ┃ Utilization ┃
┡━━━━━━━╇━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━┩
│ T4    │ 16 GB │           1 │         68% │
│ A100  │ 40 GB │           1 │         27% │
│ H100  │ 80 GB │           1 │         14% │
└───────┴───────┴─────────────┴─────────────┘
```

## CLI Usage

### Run GPU Selection

```bash theme={null}
lyceum gpu-selection run train.py
```

Pass script arguments after `--`:

```bash theme={null}
lyceum gpu-selection run train.py -- --epochs 10 --lr 0.001
```

### Options

| Option               | Description                                         |
| -------------------- | --------------------------------------------------- |
| `-f, --file-name`    | Name for the execution                              |
| `-t, --timeout`      | Timeout per sub-job in seconds (1-600, default: 60) |
| `-r, --requirements` | Requirements file path or pip requirements string   |
| `--import`           | Pre-import modules (can be used multiple times)     |
| `--no-config`        | Skip workspace config from `.lyceum/config.json`    |
| `-d, --debug`        | Show detailed debug information                     |

### Check Status

```bash theme={null}
lyceum gpu-selection status <execution_id>
```

## Requirements

<AccordionGroup>
  <Accordion title="Supported code">
    * Single Python script as entry point (executed as main)
    * Must target CUDA/GPU as the PyTorch device
    * Command-line arguments are supported
    * PyTorch and PyTorch Lightning
    * Imported models (Hugging Face, torchvision, timm)
    * Single model, single GPU
  </Accordion>

  <Accordion title="Not supported">
    * Jupyter notebooks (not supported at this point)
    * Advanced or custom gradient manipulation
    * CUDA extensions that bypass PyTorch tensors
  </Accordion>
</AccordionGroup>

## Prediction Details

<AccordionGroup>
  <Accordion title="Memory prediction">
    Predicts training and inference memory for a single model. Accounts for gradients, model weights, activations, optimizers, and mixed-precision.

    Does not account for data transfer outside the training/inference loop or operator memory overhead (intermediate tensors).
  </Accordion>

  <Accordion title="Runtime prediction">
    Estimates inference/training loop time based on iteration time.

    Does not account for VM startup time or initial data downloading and loading.
  </Accordion>
</AccordionGroup>