SimAtomic API Documentation

Cloud-based Molecular Dynamics and Binding Free Energy Analysis

Overview

SimAtomic provides a complete computational pipeline for solvated protein, protein-ligand and protein-protein interaction studies, from molecular dynamics simulations through rigorous ensemble analysis to final binding free energy calculations.

SIMULATION

Stage 1

ANALYSIS

Stage 2

MM-PBSA

Stage 3

Stage Purpose
Simulation Run molecular dynamics to generate conformational ensembles
Analysis Cluster trajectories to identify distinct conformational states and select n representative structures
MM-PBSA Calculate binding free energies on the filtered subset for accurate affinity estimation

This approach ensures your binding energy calculations capture the full conformational diversity of the system rather than relying on a single snapshot.

Quick Start

1. Install the Client

bash 
pip install requests pyyaml

Copy simatomic_client.py to your working directory.

2. Initialize the Client

Python 
from simatomic_client import SimAtomicClient, get_configs, create_input_zip

client = SimAtomicClient(api_key="YOUR_API_KEY")

3. Load Configuration

Python 
config_map = dict(zip(
    ["mmpbsa", "analysis", "simulation"],
    get_configs("config.yaml")
))

Stage 1: Molecular Dynamics Simulation

What it does: Runs GPU-accelerated molecular dynamics on your protein complex, generating a trajectory that samples the conformational landscape.

Input

A zip file containing your prepared structure (PDB format).

Output

Trajectory files, energy-minimized structure, and topology files.

Python 
# Submit simulation job
job_id = client.run_job("my_complex_simulation_input.zip", config_map["simulation"])

# Poll until complete
results, _ = client.poll_job(job_id)
if results['job_status'] == "success":
    client.download_results(job_id)

Key Parameters

Configure these in config.yaml:

  • md_steps — Number of simulation steps
  • integrator_temperature — Simulation temperature (K)
  • md_save_interval — How often frames are saved

Stage 2: Ensemble Analysis

What it does: Analyzes your simulation trajectory using dimensionality reduction (TICA) and clustering (HDBSCAN) to identify distinct conformational states. Automatically selects 20 representative structures that capture the full conformational diversity.
Why this matters: Rather than calculating binding energy on arbitrary frames, this stage ensures your final calculations represent the true ensemble of states your complex samples.

Input

Create from simulation results:

Python 
analysis_zip = create_input_zip(
    "results_<job_id>.zip",  # Your simulation results
    job_id,
    "analysis"
)

Output

Interactive HTML dashboard showing clusters, representative structures, and trajectory metrics.

Python 
# Submit analysis job
analysis_job_id = client.run_job(analysis_zip, config_map["analysis"])

# Poll and download
results, _ = client.poll_job(analysis_job_id)
if results['job_status'] == "success":
    client.download_results(analysis_job_id)

Key Parameters

  • atom_selection — Atoms used for structural comparison (e.g., "name CA" for alpha carbons)
  • tica_lag_time — Time lag for kinetic analysis
  • min_cluster_size — Minimum structures per cluster

Stage 3: MM-PBSA Binding Free Energy

What it does: Calculates binding free energies using the MM-PBSA method on the 20 representative structures identified in Stage 2. This provides statistically meaningful binding affinity estimates.
Why 20 structures: This number balances computational cost with statistical rigor—enough diversity to capture conformational effects while remaining computationally tractable.

Input

Python 
mmpbsa_zip = create_input_zip(
    "results_<job_id>.zip",  # Your simulation results
    job_id,
    "mmpbsa"
)

Output

Binding free energy values with statistical measures (mean, standard deviation across the ensemble).

Python 
# Submit MM-PBSA job
mmpbsa_job_id = client.run_job(mmpbsa_zip, config_map["mmpbsa"])

# Poll and download
results, _ = client.poll_job(mmpbsa_job_id)
if results['job_status'] == "success":
    client.download_results(mmpbsa_job_id)

Key Parameters

  • igb — Generalized Born solvation model (5 or 8 recommended for protein-protein interactions)
  • use_decomp — Enable per-residue energy decomposition

API Reference

Endpoints

POST /api/v1/jobs

Submit a new simulation job

Request Body
  • file — Input zip file (multipart/form-data)
  • config — Job configuration object
GET /api/v1/jobs/{job_id}

Get job status and results

Response
  • job_id — Unique job identifier
  • job_status — Current status (queued, running, success, failed)
  • message — Status message or error details
GET /api/v1/jobs/{job_id}/download

Download result files

POST /api/v1/analysis

Submit ensemble analysis job

POST /api/v1/mmpbsa

Submit MM-PBSA calculation

Job Status

Jobs progress through these states:

Status Meaning
queued Job submitted, waiting to start
running Job is processing
success Job completed successfully
failed Job encountered an error

Input File Requirements

Simulation Input

Your input zip should contain:

  • Protein structure file (PDB format)
  • Ligand parameters (if applicable)

Analysis/MM-PBSA Input

Use create_input_zip() to automatically extract the required files from simulation results:

  • Trajectory (.xtc)
  • Energy-minimized structure (emin.pdb)
  • Topology files

Complete Example

Python 
import time
from simatomic_client import SimAtomicClient, get_configs, create_input_zip

# Initialize
client = SimAtomicClient(api_key="YOUR_API_KEY")
config_map = dict(zip(["mmpbsa", "analysis", "simulation"], get_configs("config.yaml")))

def wait_for_job(job_id):
    """Poll until job completes."""
    while True:
        results, _ = client.poll_job(job_id)
        status = results['job_status']
        if status == "success":
            client.download_results(job_id)
            return True
        elif status == "failed":
            print(f"Job failed: {results.get('message')}")
            return False
        time.sleep(90)

# Stage 1: Simulation
sim_job_id = client.run_job("complex_simulation_input.zip", config_map["simulation"])
wait_for_job(sim_job_id)

# Stage 2: Analysis (prepare input from simulation results)
analysis_zip = create_input_zip(f"results_{sim_job_id}.zip", sim_job_id, "analysis")
analysis_job_id = client.run_job(analysis_zip, config_map["analysis"])
wait_for_job(analysis_job_id)

# Stage 3: MM-PBSA (prepare input from simulation results)
mmpbsa_zip = create_input_zip(f"results_{sim_job_id}.zip", sim_job_id, "mmpbsa")
mmpbsa_job_id = client.run_job(mmpbsa_zip, config_map["mmpbsa"])
wait_for_job(mmpbsa_job_id)

print("Pipeline complete!")

Configuration Reference

Simulation Config

YAML 
simulation:
  md_steps: 500000
  integrator_temperature: 300
  md_save_interval: 1000
  pressure: 1.0
  nonbonded_cutoff: 1.0

Analysis Config

YAML 
analysis:
  atom_selection: "name CA"
  tica_lag_time: 10
  min_cluster_size: 50
  n_representatives: 20

MM-PBSA Config

YAML 
mmpbsa:
  igb: 5
  use_decomp: true
  saltcon: 0.15

Support

For API keys, technical support, or questions about your results, contact the SimAtomic team.

Email Support

info@simatomic.com

FAQ

Common questions answered

Contact Us

Get in touch