Build a reproducible
simulation workflow.

Python quick start

You need a SimAtomic API key, API access, compute credits, and a supported input archive. Request access and review compute pricing.

The standalone example uses requests and the HTTP workflow below. Set SIMATOMIC_API_KEY in your local environment, then run it with your input ZIP. Running the script uploads that archive and submits a paid compute job.

python -m pip install requests
python api_workflow_example.py input.zip

Download the complete Python example ↓

If you already use the SimAtomic Python client, keep your existing workflow with SimAtomicClient, get_configs, and create_input_zip. The examples below use that client. Contact SimAtomic for the current client and deployment configuration.

Prepare the input archive

Typical output includes an XTC trajectory, minimized coordinates, prepared system/topology files, and job metadata. Use matching topology and trajectory atom order. Do not rename an arbitrary trajectory to make it appear compatible.

1. Submit a simulation

import os
from simatomic_client import SimAtomicClient

client = SimAtomicClient(api_key=os.environ["SIMATOMIC_API_KEY"])
params = {"mode": "simulation", "md_steps": 1000}
job_id = client.run_job("input.zip", params)

run_job requests an upload URL, uploads the archive, queues the job, and requests worker startup. The returned job ID identifies the submitted run; submission is not completion. A 1,000-step example checks the workflow. Choose production duration using the parameter reference.

2. Wait for successful completion

import time

def wait_and_download(client, job_id, timeout_seconds=86400):
    deadline = time.monotonic() + timeout_seconds
    while time.monotonic() < deadline:
        result, completed_id = client.poll_job(job_id)
        state = result.get("job_status")
        if state == "success":
            return client.download_results(job_id)
        if state in {"failed", "error", "aborted", "cancelled", "canceled"}:
            raise RuntimeError(f"Job {job_id} ended: {state}")
        time.sleep(60)
    raise TimeoutError(f"Job {job_id} may still be running")

simulation_results = wait_and_download(client, job_id)

Queued or running jobs need more time. On failure, inspect the available logs and preparation messages. A polling timeout does not cancel compute; retain the job ID to check it later. Download links can expire, so request a fresh link when needed. Do not start dependent analysis until the simulation succeeds.

3. Analyze a completed trajectory

The ensemble-analysis path uses TICA and HDBSCAN to summarize sampled conformations and produce an HTML dashboard. The output depends on the trajectory, selected atoms, lag settings, and clustering choices. It does not guarantee exhaustive sampling.

from simatomic_client import create_input_zip

analysis_zip = create_input_zip(simulation_results, job_id, "analysis")
analysis_job = client.run_job(analysis_zip, {
    "mode": "analysis",
    "atom_selection": "name CA",
    "tica_lag_time": 30,
    "tica_dimensions": 5,
    "min_cluster_size": 10,
    "min_samples": 10,
})
analysis_results = wait_and_download(client, analysis_job)

These are example settings. Adjust them to saved-frame spacing and sampling length. You can also analyze downloaded trajectories with your own scripts, or ask Claude/Codex to save reproducible scripts and plots locally.

4. Optional end-point binding analysis

The MM/PBSA workflow currently targets protein–ligand systems with compatible topology export. Choose the ligand mask from the actual prepared topology, plus the sampling interval and solvent model. With a Generalized Born igb model, describe the calculation as MM/GBSA.

# Start from the compatible simulation output and its original job ID.
binding_zip = create_input_zip(simulation_results, job_id, "mmpbsa")
binding_params = {
    "mode": "mmpbsa",
    "ligand_chain_mask": ligand_mask,  # Set after checking the prepared topology.
    "igb": 5,
    "use_decomp": False,
}
binding_job = client.run_job(binding_zip, binding_params)
binding_results = wait_and_download(client, binding_job)

Do not copy a residue mask from another system. Frame bounds and stride must fit the trajectory. See scientific interpretation before using the result for comparisons or ranking.

Configuration

The Python client can load separate simulation, analysis, and MM/PBSA dictionaries from a YAML file. Install pyyaml when using this helper.

from simatomic_client import get_configs

mmpbsa_params, analysis_params, simulation_params = get_configs("config.yaml")

The YAML keys are mmpbsa_parameters, analysis_parameters, and simulation_parameters. Each dictionary includes its mode. Keep the configuration supplied for your deployment; see field names, units, and scientific defaults.

HTTP API reference

Base URL: https://app.simatomic.com/api/api_handler/
API authorization: X-API-Key header. POST requests use JSON. The routes below follow the SimAtomic Python client.

Use your API key only with the authenticated SimAtomic API. Use signed upload/download URLs as returned, without adding the API key to storage requests. MCP is a separate protocol endpoint; do not send these REST routes to mcp.simatomic.com/mcp.

Complete upload → run → download example

Download the standalone Python script. It uses the routes above, waits for completion, stops on a failed job, and saves the results ZIP. It does not automatically submit follow-up analysis. Inspect the script and set the input and run length before executing it.

MCP tools for Claude and Codex

Connect https://mcp.simatomic.com/mcp using Streamable HTTP. Follow the Claude Desktop guide or the Codex desktop guide for authorization and screenshots. The server advertises the accepted argument schema for each tool; that schema is the authority for assistant submissions.

Prompt: Inspect the current SimAtomic tool schemas. Check whether my protein and ligand fit the supported preparation workflow, then propose inputs, duration, output frequency, and analysis. Show the settings and wait for my approval before uploading or submitting a job.