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

# Run Your First Experiment

> Launch your first GPU-powered experiment in Hubify Labs, from setup to results in minutes.

# Run Your First Experiment

This guide walks you through running your first experiment on GPU compute. We will use a simple MCMC chain as an example, but the workflow applies to any experiment type.

## Prerequisites

* A lab created ([create one first](/guides/create-lab))
* GPU compute connected ([set up RunPod](/guides/gpu-setup)), or use CPU for this tutorial

## Overview

Every experiment follows the same lifecycle:

```
DRAFT → QUEUED → RUNNING → QC_GATE → COMPLETE
```

You define it. The orchestrator queues it. An agent runs it on a GPU pod. QC validates the results. Done.

## Option 1: Natural Language

The fastest way to run an experiment is to describe it to the orchestrator.

<Tabs>
  <Tab title="Web UI">
    Open the Orchestrator Chat in Captain View and type:

    ```
    Run a test MCMC chain with 1000 samples on the base Planck dataset.
    Use an H100 pod. Save the chain output and a posterior plot.
    ```

    The orchestrator will:

    1. Create the experiment (EXP-001)
    2. Allocate an H100 pod
    3. Assign the Research Lead
    4. Execute and report back when complete
  </Tab>

  <Tab title="CLI">
    ```bash theme={null}
    hubify experiment run "Test MCMC chain, 1000 samples, Planck base, H100 pod"
    ```
  </Tab>
</Tabs>

## Option 2: Structured Definition

For more control, define the experiment explicitly.

<Steps>
  <Step title="Write a config file">
    Create an experiment config:

    ```yaml theme={null}
    # experiment.yaml
    name: "test-mcmc-planck"
    description: "Test MCMC chain on Planck base likelihood"
    script: run_cobaya.py
    config: planck_base.yaml
    pod:
      gpu: h100
      timeout: 2h
    outputs:
      - chain_samples.txt
      - posterior_plot.png
    qc:
      convergence_threshold: 1.10  # Relaxed for test run
      min_samples: 1000
    ```
  </Step>

  <Step title="Submit the experiment">
    ```bash theme={null}
    hubify experiment run --file experiment.yaml
    ```
  </Step>

  <Step title="Watch the logs">
    ```bash theme={null}
    hubify logs EXP-001 --follow
    ```

    You will see real-time output from the pod:

    ```
    [10:42:01] Pod provisioned: h100-abc123
    [10:42:15] Environment initialized
    [10:42:20] Starting Cobaya MCMC sampler...
    [10:43:05] Sample 100/1000
    [10:44:12] Sample 500/1000
    [10:45:30] Sample 1000/1000
    [10:45:31] Chain complete. Writing output...
    [10:45:35] QC gate: checking convergence...
    [10:45:36] QC PASS: R-hat = 1.04 (threshold: 1.10)
    [10:45:37] Experiment COMPLETE
    ```
  </Step>

  <Step title="Review results">
    ```bash theme={null}
    # View experiment summary
    hubify experiment status EXP-001

    # Download outputs
    hubify experiment outputs EXP-001 --download ./results/

    # View in Data Explorer
    hubify data open EXP-001
    ```
  </Step>
</Steps>

## Understanding the Output

After completion, your experiment includes:

| Output                 | Description                                           |
| ---------------------- | ----------------------------------------------------- |
| `chain_samples.txt`    | Raw MCMC chain (space-delimited, weights in column 1) |
| `posterior_plot.png`   | Auto-generated posterior distribution                 |
| `experiment_log.txt`   | Full execution log                                    |
| `qc_report.json`       | QC gate results (convergence, completeness)           |
| `reproducibility.json` | Git SHA, dependencies, config checksums               |

## What Happens Next

The Houston Method requires every completed experiment to generate follow-up tasks:

1. **Scientific analysis**, What do the results mean?
2. **Knowledge base update**, Record findings in the wiki
3. **Paper integration**, Tag results for paper sections if applicable
4. **Queue expansion**, Generate 5-15 new tasks based on what was learned

The orchestrator handles this automatically after QC passes.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Experiment stuck in QUEUED">
    Check that compute is connected and pods are available:

    ```bash theme={null}
    hubify pod list
    hubify pod budget
    ```
  </Accordion>

  <Accordion title="QC gate failed">
    View the QC report for details:

    ```bash theme={null}
    hubify experiment qc EXP-001
    ```

    Common fixes: increase sample count, check input data, adjust convergence threshold.
  </Accordion>

  <Accordion title="Pod crashed mid-experiment">
    Resume from the last checkpoint:

    ```bash theme={null}
    hubify experiment resume EXP-001 --from-checkpoint latest
    ```
  </Accordion>
</AccordionGroup>