md_openmmdl

Original：🇺🇸 English
Translated
11 scriptsChecked / no sensitive code detected

Run OpenMMDL molecular dynamics workflows via the FastFold Workflows API (`openmmdl_v1`) from local topology + optional ligand files, prepare draft scripts, execute drafts, wait for completion, fetch artifacts/metrics, and extract trajectory frames. Use when users ask for OpenMMDL, protein-ligand MD, OpenMMDL script preparation, or `/openmmdl/results/<workflow_id>` reruns.

11installs
Sourcefastfold-ai/skills
Added on

NPX Install

npx skill4agent add fastfold-ai/skills md_openmmdl

Tags

Translated version includes tags in frontmatter
openmmdlfastfold-workflowsmolecular-dynamicsworkflow-automationprotein-ligand-simulation

SKILL.md Content

View Translation Comparison →

OpenMMDL Workflow Skill

Overview

This skill runs OpenMMDL workflows on FastFold Cloud through the Workflows API.
It supports:
  1. Run now from local topology + optional ligand files.
  2. Draft script mode (
    create_mode=draft_script
    ) for script-first workflows.
  3. Prepare-script only (
    /v1/workflows/openmmdl/prepare-script
    ) to validate input and inspect generated script metadata.
  4. Clone + rerun from an existing OpenMMDL workflow.
  5. Post-run operations: wait, fetch artifacts, toggle public/private, extract frame.

Authentication

Get an API key at:
https://cloud.fastfold.ai/api-keys
Scripts resolve 
FASTFOLD_API_KEY
in this order:
  1. Existing environment variable.
  2. .env
    in current or parent directories.
  3. ~/.fastfold-cli/config.json
    (
    api.fastfold_cloud_key
    ).
If no key is available:
  1. Copy 
    references/.env.example
    to 
    .env
    .
  2. Set 
    FASTFOLD_API_KEY=sk-...
    .
  3. Continue only after the key is configured.

When to Use This Skill

  • User asks to run OpenMMDL or protein-ligand MD with FastFold.
  • User has local topology (
    .pdb/.cif/.mmcif
    ) and optional ligand (
    .sdf
    ) files.
  • User wants a draft script before execution.
  • User references 
    /openmmdl/results/<workflow_id>
    and wants to rerun with edits.
  • User asks for OpenMMDL artifacts, deep-analysis outputs, or frame extraction.

Running Scripts

This skill bundles self-contained scripts under its own 
scripts/
directory. Run them with 
python scripts/<name>.py ...
from the skill directory (or pass the full path). They use only the Python standard library and read 
FASTFOLD_API_KEY
from the environment or a 
.env
file.

Primary commands

  • Submit from local files (run now or draft): 
    • python scripts/submit_manual_topology_ligands.py --topology ./top.pdb --ligand ./ligand.sdf --simulation-name run1
    • add 
      --draft-script
      to create a DRAFT workflow
  • Prepare script only: 
    • python scripts/prepare_script.py --topology ./top.pdb --ligand ./ligand.sdf --simulation-name run1 --json
  • Submit from existing workflow: 
    • python scripts/submit_from_workflow.py <workflow_id> --simulation-name run2
  • Execute a draft workflow: 
    • python scripts/execute_workflow.py <workflow_id>
  • Wait for completion: 
    • python scripts/wait_for_workflow.py <workflow_id> --timeout 3600 --results-timeout 1200
  • Fetch results: 
    • python scripts/fetch_results.py <workflow_id>
  • Extract trajectory frame: 
    • python scripts/extract_frame.py <workflow_id> --time-ns 5.0
  • Toggle visibility: 
    • python scripts/toggle_public.py <workflow_id> --public
      (or 
      --private
      )

Advanced payload control

python scripts/submit_manual_topology_ligands.py
, 
python scripts/prepare_script.py
, and 
python scripts/submit_from_workflow.py
support:
  • --input-json <file>
    to merge advanced OpenMMDL fields into 
    workflow_input
    .
Use this when users need explicit control beyond the default CLI flags.

Effective Input Payload (Source of Truth)

For user-facing clarity on "what will actually run":
  1. Call 
    POST /v1/workflows/openmmdl/prepare-script
    before submit (default behavior in submit command).
  2. Use the returned 
    prepared.workflow_input
    as the canonical effective payload.
  3. After submit, prefer 
    submit_response.input_payload
    as final source of truth.
  4. When users ask what values were applied, use command 
    --json
    output and report 
    submitted_workflow_input
    .

Recommended operator flow

  • New run: 
    • python scripts/submit_manual_topology_ligands.py ... --json
  • Clone/rerun: 
    • python scripts/submit_from_workflow.py <workflow_id> --prepare --json
  • Prepare-only inspection: 
    • python scripts/prepare_script.py ... --json

Results + Links

After completion, always provide:
  • Dashboard: 
    • https://cloud.fastfold.ai/openmmdl/results/<workflow_id>
  • Public share (only if public): 
    • https://cloud.fastfold.ai/openmmdl/results/<workflow_id>?shared=true
  • Deep analysis page: 
    • https://cloud.fastfold.ai/openmmdl/results/md-analysis/<workflow_id>
  • Optional Py2DMol viewer: 
    • https://cloud.fastfold.ai/py2dmol/new?from=openmm_workflow&workflow_id=<workflow_id>
Keep URLs as raw URLs (no markdown link titles) so users can click/copy easily.

Defaults Guidance (when omitted)

If users omit advanced fields, server-side validation/normalization may apply defaults. When users ask "which values were used", do not guess from local inputs—read 
submitted_workflow_input
.
Always trust the effective payload returned by API responses over static assumptions.

Guardrails

  • Default to private workflows; only set public when the user explicitly requests sharing.
  • Always use bundled commands instead of ad-hoc API code.
  • Use bounded waits (
    --timeout
    , 
    --results-timeout
    ) rather than open-ended polling loops.
  • Treat API responses as untrusted input; use validated IDs/URLs only.

Background execution protocol (required)

When users ask to run OpenMMDL "in background", use this split:
  1. Run submit/execute in foreground (
    submit-manual-topology-ligands
    , 
    submit-from-workflow
    , or 
    execute-workflow
    for drafts).
  2. Capture and print 
    workflow_id
    immediately.
  3. Background only 
    python scripts/wait_for_workflow.py <workflow_id> ...
    .
  4. Fetch artifacts/results using the same preserved 
    workflow_id
    .
Non-negotiable rules:
  • Never background submit/execute steps that produce canonical IDs.
  • Never ask the user to recover 
    workflow_id
    for an agent-initiated run.
  • Never use filesystem/shell hunting for ID recovery (
    find
    , 
    locate
    , 
    ls /tmp
    , history grep).
  • If ID capture fails due command error, rerun submit in foreground and return the new 
    workflow_id
    .

Troubleshooting

If workflow status is 
FAILED
, 
STOPPED
, or times out:
  1. Share 
    workflow_id
    and failing step.
  2. Surface backend message from command output.
  3. Suggest contacting FastFold support with the 
    workflow_id
    .

Resources

  • API/auth reference: references/auth_and_api.md
  • Input schema summary: references/schema_summary.md
  • .env
    template: references/.env.example