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: exampleoutput_dir: resultsseed: 42n_runs: 1system:  molecules_dir: molecules  bath: []  bath_charge: 0  bath_spin: 1md:  n_steps: 10  timestep_fs: 0.5  temp_range: [300, 300]  bias:    type: nonemodel:  name: uma-s-1p1  task: omol  device: cpuexecution:  backend: serial  mds_per_block: 1  max_concurrent: 1output:  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:

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:

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:

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 Pathfrom chemistry_compute import Clientfrom 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:

See Inspect and recover a run for handling stage failures and Measure throughput and efficiency before tuning GPU block concurrency.

For completed trajectories, use partial frame reads 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.