# Run molecular simulations

Submit an MD configuration that simulates trajectories, parses reaction events and publishes observations.

Submit a molecular dynamics (MD) configuration with a single command. The platform automatically chains three jobs—**simulate** (`md-simulate@1`), **parse** (`md-parse@1`), and **publish** (`md-publish@1`)—so your laptop can disconnect as soon as the run is submitted.

## 1. Configure your simulation (`run.yaml`)

Start from `compute/md/examples/job/run.yaml`:


```yaml
experiment: example
output_dir: results
seed: 42
n_runs: 1
system:
  molecules_dir: molecules
  bath: []
  bath_charge: 0
  bath_spin: 1
md:
  n_steps: 10
  timestep_fs: 0.5
  temp_range: [300, 300]
  bias:
    type: none
model:
  name: uma-s-1p1
  task: omol
  device: cpu
execution:
  backend: serial
  mds_per_block: 1
  max_concurrent: 1
output:
  write_xyz: true
```


Key fields to set for your run:

- **`system.molecules_dir`** — Directory of `.xyz` files relative to `run.yaml` (for example, `molecules/hydrogen.xyz`).
- **`system.bath_charge` & `system.bath_spin`** — Net charge and spin multiplicity (`1` = singlet, `2` = doublet, `3` = triplet).
- **`md.n_steps` & `md.timestep_fs`** — Number of integration steps and timestep in femtoseconds.
- **`model.name` & `model.device`** — Model checkpoint name (or worker path/URI) and device (`cpu` or `cuda`). Workers load the GPU checkpoint directly; it is not uploaded from your laptop.

## 2. Submit and check status from the CLI

Submit `run.yaml` using `ct-cli md submit`:

```bash
ct-cli md submit compute/md/examples/job/run.yaml --wait
```

```text
Run 0195f3d0-3333-7000-8000-000000000003: succeeded
  simulate  0195f3d0-1111-7000-8000-000000000001
  parse     0195f3d0-2222-7000-8000-000000000002
  publish   0195f3d0-3333-7000-8000-000000000003
```

Check the progress of all three stages at any time with the returned `RUN_UUID`:

```bash
ct-cli md status RUN_UUID
```

To inspect logs or download artifacts for a specific stage (`simulate`, `parse`, or `publish`), pass that stage's job UUID to `ct-cli logs` or `ct-cli fetch`:

```bash
ct-cli logs STAGE_JOB_UUID
ct-cli fetch STAGE_JOB_UUID --output ./md-evidence
```

## 3. Submit from Python

If you are driving simulations from a Python script instead of the CLI, call `mdagent.submission.submit`:

```python
from pathlib import Path
from chemistry_compute import Client
from mdagent.submission import submit

client = Client.from_login()
run = submit(client, Path("compute/md/examples/job/run.yaml"))
print(run.id, run.simulate.id, run.parse.id, run.publish.id)

publication = run.result(timeout=3600)
print(publication.runs, publication.frames, publication.events)
```

> **Note:** Each call to `ct-cli md submit` or `submit(...)` starts a new 3-stage simulation run. Use either the CLI or Python for a given run, not both.

## 4. What each stage does (and how to recover)

| Stage                  | Worker pool                  | What it produces                                                           |
| ---------------------- | ---------------------------- | -------------------------------------------------------------------------- |
| **1. `md-simulate@1`** | GPU / Ray (or CPU for tests) | Integrates trajectories and uploads raw trajectory files.                  |
| **2. `md-parse@1`**    | CPU                          | Extracts reaction events and builds an upload spool.                       |
| **3. `md-publish@1`**  | CPU                          | Canonicalizes species, maps atoms, and saves observations to your project. |

If your network connection drops while submitting `ct-cli md submit`, reconcile the original request without starting a duplicate run:

```bash
ct-cli md submit --request-id RUN_UUID
```

See [Inspect and recover a run](/operate/recovery/) for handling stage failures and [Measure throughput and efficiency](/test/throughput/) before tuning GPU block concurrency.

For completed trajectories, use [partial frame reads](/operate/files/#5-choose-partial-reads-or-a-full-download)
to inspect a window without downloading all coordinates. Bulk analysis should download the original
Parquet artifact once and process it locally. The same guide explains sharing accepted artifacts
between jobs and reading encrypted Parquet through the shared helper.