# Molclaw Run Bioemu

> Run BioEmu sequence sampling and extract ensemble structures for downstream conformation analysis.

- Skill: `internscience/molclaw-run-bioemu` (Agent Skill)
- Install (CLI): `npx skillmds@latest add internscience/molclaw-run-bioemu`
- Raw SKILL.md: https://api.skillmd.com/api/skills/internscience/molclaw-run-bioemu/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT license
- Author: internscience (https://skillmd.com/u/internscience)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/internscience/molclaw-run-bioemu

---


# BioEmu Sampling and Structure Extraction

Note: 
- Local files are not directly accessible by the server. Please upload them to the server using `molclaw-file-transfer` before execution. 
- For PDB file inputs, it is recommended to preprocess them using `molclaw-pdbfixer` before execution.
- Please refer to skill `molclaw-scp-server` to complete tool invocation.

## Usage

### 1. BioEmu Sampling

The description of tool *run_bioemu*.

```tex
Generate BioEmu conformational samples for a sequence, store outputs under the shared result root, and return run metadata and key artifacts.
Args:
    sequence (str): Input sequence string or a path (FASTA/A3M) readable by BioEmu.
    num_samples (int): Number of conformational samples to generate.
    export_pdbs (bool): If True, export individual PDB files for each sample (default False).
    dry_run (bool): If True, validate inputs and create run directory without executing BioEmu.
Return:
    status (str): 'success' or 'error'.
    msg (str): Human-readable summary or error message.
    command (str): The invoked command ('run_bioemu').
    run_dir (str|None): Path to the run-specific output directory under tool_result/bioemu_result.
    output_dir (str|None): Same as `run_dir` for compatibility.
    files (List[str]|None): Sorted list of generated files under the run directory.
    pdb_path (str|None): First detected PDB file path if present.
    xtc_path (str|None): First detected XTC file path if present.
    sampling_statistics (dict|None): Parsed sampling statistics if available.
    sampling_statistics_path (str|None): Path to sampling_statistics.json if present.
    sequence_input (str|None): Resolved sequence or input path echoed by BioEmu.
    num_samples_requested (int|None): Number of requested samples echoed back.
    export_pdbs (bool|None): Whether PDB export was requested.
```

How to use tool *run_bioemu* :

```python
response = await client.session.call_tool(
    "run_bioemu",
    arguments={
        "sequence": "GYDPETGTWG",
        "num_samples": 5,
        "export_pdbs": False,
        "dry_run": True
    }
)
result = client.parse_result(response)
key_output = result["run_dir"]

```

#### Example parameter sets

```python
# 1) Main mode: short sampling from sequence string
{
    "sequence": "GYDPETGTWG",
    "num_samples": 5,
    "export_pdbs": False,
    "dry_run": False
}

# 2) Variant mode: FASTA file input with PDB export
{
    "sequence": "relative/path/to/sequence.fasta",
    "num_samples": 200,
    "export_pdbs": True,
    "dry_run": False
}
```

### 2. BioEmu Structure Extraction

The description of tool *extract_bioemu_structures*.

```tex
Extracts per-conformation structures and ensemble metadata from a BioEmu output directory for post-processing workflows.
Args:
    input_dir (str): BioEmu output directory containing topology PDB and XTC trajectory.
    prefix (str): Prefix for individual PDB filenames, default 'conf'.
    merge_pdb (bool): Export merged multi-model PDB, default False.
    extract_npz (bool): Extract NPZ payload data when present, default False.
    no_individual_pdbs (bool): Skip individual PDB exports, default False.
    no_stats (bool): Skip ensemble statistics computation, default False.
    sidechain_relax (bool): Run sidechain relaxation step, default False.
    dry_run (bool): Validate input and prepare output directory without extraction, default False.
Return:
    status (str): 'success', 'partial_success', or 'error'.
    msg (str): Human-readable extraction summary.
    output_dir (str): Run-specific directory under tool_result/bioemu_result.
    input_dir (str): Resolved BioEmu input directory.
    pdb_path (str | None): Resolved topology PDB path.
    xtc_path (str | None): Resolved trajectory XTC path.
    individual_pdb_dir (str): Directory for individual extracted PDB files.
    merged_pdb_path (str | None): Path to merged PDB file if requested.
    ensemble_statistics_path (str | None): Path to ensemble statistics JSON when generated.
    files (List[str]): Generated file paths relative to output_dir (e.g., 'individual_pdbs/conf_0000.pdb').
    exported_individual_count (int): Number of individual PDB files exported.
    stats_available (bool): Whether statistics were generated.
```

How to use tool *extract_bioemu_structures* :

```python
response = await client.session.call_tool(
    "extract_bioemu_structures",
    arguments={
        "input_dir": "/path/to/bioemu_run_dir",
        "prefix": "conf",
        "merge_pdb": False,
        "extract_npz": False,
        "no_individual_pdbs": False,
        "no_stats": False,
        "sidechain_relax": False,
        "dry_run": False
    }
)
result = client.parse_result(response)
key_output = result["individual_pdb_dir"]

```

#### Example parameter sets

```python
# 1) Main mode: extract individual PDBs + stats
{
    "input_dir": "/path/to/bioemu_run_dir",
    "prefix": "conf",
    "merge_pdb": False,
    "extract_npz": False,
    "no_individual_pdbs": False,
    "no_stats": False,
    "sidechain_relax": False,
    "dry_run": False
}

# 2) Variant mode: merged PDB + NPZ extraction
{
    "input_dir": "relative/path/to/bioemu_output",
    "prefix": "sample",
    "merge_pdb": True,
    "extract_npz": True,
    "no_individual_pdbs": True,
    "no_stats": False,
    "sidechain_relax": False,
    "dry_run": False
}
```

### 3. End-to-End Collaboration Workflow

Use the two tools in sequence via API calls:
1. Call *run_bioemu* to produce sampling outputs and get `run_dir`.
2. Pass that `run_dir` to *extract_bioemu_structures* for per-frame structure extraction.

```python
client = DrugSDAClient("https://scp.intern-ai.org.cn/api/v1/mcp/2/DrugSDA-Tool")
if not await client.connect():
    print("connection failed")
    return

run_resp = await client.session.call_tool(
    "run_bioemu",
    arguments={
        "sequence": "GYDPETGTWG",
        "num_samples": 5,
        "export_pdbs": False,
        "dry_run": False
    }
)
run_result = client.parse_result(run_resp)
bioemu_run_dir = run_result["run_dir"]

extract_resp = await client.session.call_tool(
    "extract_bioemu_structures",
    arguments={
        "input_dir": bioemu_run_dir,
        "prefix": "conf",
        "merge_pdb": False,
        "extract_npz": False,
        "no_individual_pdbs": False,
        "no_stats": False,
        "sidechain_relax": False,
        "dry_run": False
    }
)
extract_result = client.parse_result(extract_resp)
key_output = extract_result["files"]

await client.disconnect() 
```