Fastfold AI Docs

Submit OpenMM workflows from local files, generic payloads, or existing fold jobs.

Use OpenMM to run calvados_openmm_v1 workflows.

Quick reference

Workflow: calvados_openmm_v1 · task inference_calvados_openmm
CLI: fastfold-cli workflows openmm from-manual-files …, from-fold-job <job_id>, from-workflow …, extract-frame … — see SDK CLI
Docker Hub: fastfold/calvados-openmm (default tag from deployment; API list examples use fastfold/calvados-openmm:latest)

Metrics and Artifacts

After a run completes, files and plots are attached to the workflow task as library items. Declared metric field names and artifact path patterns (for composer tooling and docs) come from POST /v1/workflows/node/output-schema with workflowTaskTypeId: inference_calvados_openmm.

`GET /v1/workflows/task-results/<workflow_id>`

Each task row includes output_library_items (files in your library). parsed_results is only populated for BoltzGen tasks; OpenMM reads artifacts from output_library_items.

Declared keys (`output-schema`)

The response lists availableOutput[] entries with name, type, and description.

Scalars (examples):

Name	Type	Description
`metrics.ligand_detected`	key/boolean	Ligand atoms detected
`metrics.rmsd.mean_angstrom`	key/float	Mean RMSD (Å)
`metrics.rmsd.stddev_angstrom`	key/float	RMSD σ (Å)
`metrics.rmsf.mean_angstrom`	key/float	Mean RMSF (Å)
`metrics.rmsf.stddev_angstrom`	key/float	RMSF σ (Å)
`metrics.rmsf.max_residue`	key/integer	Residue index with highest RMSF
`metrics.radius_of_gyration.mean_angstrom`	key/float	Mean Rg (Å)
`metrics.radius_of_gyration.stddev_angstrom`	key/float	Rg σ (Å)
`metrics.free_energy_landscape.min_frame`	key/integer	FEL minimum frame
`metrics.free_energy_landscape.min_time_ns`	key/float	Time at FEL minimum (ns)
`metrics.free_energy_landscape.min_rmsd_angstrom`	key/float	RMSD at minimum (Å)
`metrics.free_energy_landscape.min_rg_angstrom`	key/float	Rg at minimum (Å)
`metrics.binding_energy.available`	key/boolean	Binding energy computed
`metrics.binding_energy.mean_kj_per_mol`	key/float	Mean interaction energy
`metrics.binding_energy.stddev_kj_per_mol`	key/float	Binding energy σ
`metrics.protein_ligand_distance.available`	key/boolean	PL distance computed
`metrics.protein_ligand_distance.mean_angstrom`	key/float	Mean min distance (Å)
`metrics.protein_ligand_distance.stddev_angstrom`	key/float	Distance σ (Å)

Files (patterns):

Name	Type	Description
`analysis/metrics.json`	file/JSON	MD quick analysis JSON
`analysis/*_rmsd.png`	file/PNG	RMSD plot
`analysis/*_rmsf.png`	file/PNG	RMSF plot
`analysis/*_rg.png`	file/PNG	Rg plot
`analysis/*_fel.png`	file/PNG	FEL plot
`analysis/*_binding_energy.png`	file/PNG	Binding energy plot
`analysis/*_pl_distance.png`	file/PNG	Protein–ligand distance plot

SDK and CLI

from fastfold import Client

client = Client()
out = client.workflows.task_results(workflow_id)
print(out.raw)  # tasksResults[], per-task output_library_items

fastfold-cli workflows task-results <workflow_id>
fastfold-cli workflows task-results <workflow_id> --json

First run from local PDB + PAE files

This example uses an AlphaFold-style structure file and PAE JSON, and does not depend on an existing fold job.

from fastfold import Client

client = Client()
workflow = client.openmm.submit_from_manual_files(
    pdb_path="./protein.pdb",
    pae_path="./pae.json",
    simulation_name="AF-P00698",
    residue_profile="calvados3",
    temp=293.15,
    ionic=0.15,
    ph=7.5,
    step_size_ns=0.01,
    sim_length_ns=10.0,
    box_length=50,
)
print(workflow.workflow_id)

fastfold-cli workflows openmm from-manual-files \
  --pdb ./protein.pdb \
  --pae ./pae.json \
  --simulation-name AF-P00698 \
  --force-field calvados3 \
  --temperature 293.15 \
  --ionic 0.15 \
  --ph 7.5 \
  --step-size-ns 0.01 \
  --sim-length-ns 10 \
  --box-length 50

Required local files:

structure file: .pdb or .cif
PAE file: .json

Download the exact AlphaFold DB files used in this example:

You can keep the original filenames, or rename them locally to protein.pdb and pae.json to match the commands below.

Tip: Keep the structure file and PAE JSON from the same AlphaFold prediction. Mixing files from different predictions can produce invalid residue-to-error alignment.

Full input schema

Use this section as a reference for the full workflow_input shape currently accepted by the backend for OpenMM runs:

{
  "workflow_name": "calvados_openmm_v1",
  "name": "AF-P00698",
  "create_mode": "",
  "workflow_input": {
    "name": "AF-P00698",
    "preset": "single_af_go",
    "force_field_family": "calvados",
    "residue_profile": "calvados3",
    "residues_csv": "",
    "temp": 293.15,
    "ionic": 0.15,
    "pH": 7.5,
    "step_size_ns": 0.01,
    "sim_length_ns": 10.0,
    "box_length": 50,
    "files": {
      "residues": {
        "libraryItemId": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
        "fileName": "calvados3_residues.csv"
      },
      "pdb": {
        "libraryItemId": "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb",
        "fileName": "protein.pdb"
      },
      "pae": {
        "libraryItemId": "cccccccc-cccc-cccc-cccc-cccccccccccc",
        "fileName": "pae.json"
      },
      "fasta": {
        "libraryItemId": "dddddddd-dddd-dddd-dddd-dddddddddddd",
        "fileName": "sequence.fasta"
      }
    },
    "sequences": [
      {
        "proteinChain": {
          "sequence": "MKTIIALSYIFCLVFA",
          "chain_id": "A"
        }
      }
    ],
    "config": {
      "box_eq": false,
      "pressure": [1.0, 1.0, 1.0]
    },
    "component_defaults": {
      "periodic": true,
      "charge_termini": "both",
      "charged_N_terminal_amine": true,
      "charged_C_terminal_carboxyl": true,
      "charged_histidine": false
    },
    "sourceType": "fold_job",
    "sourceJobId": "eeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee",
    "sourceJobRunId": "ffffffff-ffff-ffff-ffff-ffffffffffff",
    "sourceSequenceId": "11111111-2222-3333-4444-555555555555",
    "sourceNoPaeMode": "no_go_fasta_fallback"
  }
}

Field notes:

preset must be one of single_af_go, single_idr_fasta, or single_idr_box_eq.
workflow_input.files is always required.
workflow_input.files.residues is required in the validated payload, but the backend can auto-materialize it from residue_profile or inline residues_csv.
single_af_go requires workflow_input.files.pdb and workflow_input.files.pae.
single_idr_fasta and single_idr_box_eq require either workflow_input.files.fasta or workflow_input.sequences.
workflow_input.config.box_eq is a boolean.
workflow_input.config.pressure must be an array of 3 numbers.
workflow_input.component_defaults.charge_termini must be one of both, N, C, or none.
The backend also accepts top-level aliases like box_eq, pressure, periodic, charged_N_terminal_amine, charged_C_terminal_carboxyl, charged_histidine, and normalizes them into config or component_defaults.
sourceType, sourceJobId, sourceJobRunId, and sourceSequenceId are the fold-linked mode fields. They are not required for a first manual run.
create_mode is optional. Advanced draft-YAML flows use draft_yml.

Generic payload file

If you upload the structure and PAE files to the library first, the packaged payload file matches the request body closely:

Note: Use the manual-file helper for a first run. Use the generic payload form when you are scripting library uploads and want a request body that mirrors the API shape directly.

{
  "workflow_name": "calvados_openmm_v1",
  "name": "AF-P00698",
  "workflow_input": {
    "name": "AF-P00698",
    "preset": "single_af_go",
    "force_field_family": "calvados",
    "residue_profile": "calvados3",
    "temp": 293.15,
    "ionic": 0.15,
    "pH": 7.5,
    "step_size_ns": 0.01,
    "sim_length_ns": 10.0,
    "box_length": 50,
    "files": {
      "pdb": { "libraryItemId": "...", "fileName": "protein.pdb" },
      "pae": { "libraryItemId": "...", "fileName": "pae.json" }
    }
  }
}

fastfold-cli workflows create --payload-file fastfold/examples/openmm/from_manual_files.json

From a fold job

from fastfold import Client

client = Client()
workflow = client.openmm.submit_from_fold_job(
    "550e8400-e29b-41d4-a716-446655440000",
    simulation_name="openmm_demo",
    sim_length_ns=0.2,
)
print(workflow.workflow_id)

fastfold-cli workflows openmm from-fold-job 550e8400-e29b-41d4-a716-446655440000

Existing workflow -> new OpenMM workflow

from fastfold import Client

client = Client()
workflow = client.openmm.submit_from_workflow(
    "af2473ef-820d-44df-98fe-fa15103157d5",
    simulation_name="rerun_openmm",
)
print(workflow.workflow_id)

Extract a frame

from fastfold import Client

client = Client()
frame = client.openmm.extract_frame(
    "af2473ef-820d-44df-98fe-fa15103157d5",
    time_ns=10.0,
)
print(frame.pdb_url)

fastfold-cli workflows openmm extract-frame af2473ef-820d-44df-98fe-fa15103157d5 --time-ns 10

Related API docs:

OpenMM

On this page