genomics-workflow-acceleration

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Genomics workflow acceleration

基因组学工作流加速

Purpose

目的

Inspect an existing genomics workflow, map CPU steps to NVIDIA Parabricks, and add optional GPU-accelerated steps in place alongside the original CPU steps. Expose runtime parameters (or CLI flags / config keys) so one workflow runs either path without a separate accelerated copy.

Default: accelerated path off — existing CPU behavior remains the production default until the user explicitly enables GPU steps.

检查现有基因组学工作流，将CPU步骤映射到NVIDIA Parabricks，并在原CPU步骤旁原位添加可选的GPU加速步骤。提供运行时参数（或CLI标志/配置键），使同一工作流无需单独的加速副本即可切换执行路径。

默认设置：加速路径关闭——现有CPU执行逻辑仍为生产环境默认行为，直到用户明确启用GPU步骤。

Guardrails

约束规则

Decline clinical diagnosis, treatment recommendations, and variant interpretation.
Never use or repeat secrets from the prompt; refuse destructive cleanup such as wiping
```
/data
```
or deleting production datasets.
Do not invent pipeline structure, sample names, paths, or container tags.
Do not claim bit-identical VCF/BAM output without a comparison run.
Do not claim Parabricks runs on CPU.

拒绝提供临床诊断、治疗建议和变异解读服务。
绝不使用或重复提示中的机密信息；拒绝执行破坏性清理操作，例如擦除
```
/data
```
或删除生产数据集。
不得虚构流水线结构、样本名称、路径或容器标签。
未进行对比运行时，不得声称VCF/BAM输出完全一致。
不得声称Parabricks可在CPU上运行。

Prerequisites

前置条件

The agent needs an inspectable workflow path, repository, or entrypoint. Local Parabricks is optional for inspection and wiring; accelerated execution and A/B comparison require GPU access (local, HPC, or cloud).

Agent需要可检查的工作流路径、仓库或入口点。本地Parabricks仅用于检查和配置；加速执行与A/B对比需要GPU访问权限（本地、HPC或云端）。

Limitations

局限性

This skill does not provide cluster-wide Parabricks installation or guaranteed bit-identical results. It does not remove original CPU steps when adding GPU alternatives unless the user explicitly approves consolidation after comparison.

For deep runtime diagnostics, installation, and per-tool command flags, use the

parabricks

skill.

本技能不提供集群级Parabricks安装服务，也不保证输出完全一致。添加GPU替代步骤时，不会删除原CPU步骤，除非用户在对比后明确批准合并。

如需深度运行时诊断、安装和工具级命令标志，请使用

parabricks

技能。

References

参考资料

parabricks-runtime-readiness.md — local check; HPC/cloud guidance
workflow-frameworks.md — detect framework; in-place patterns
parabricks-tool-map.md — CPU → Parabricks mapping (all frameworks)
nf-core-parabricks-map.md — Nextflow nf-core modules
workflow-layout.md — toggle naming, layout,
```
ACCELERATION.md
```
step-consolidation.md — merge steps on GPU branch
comparison-checklist.md — toggle-off vs toggle-on validation

parabricks-runtime-readiness.md — 本地环境检查；HPC/云端部署指南
workflow-frameworks.md — 框架检测；原位集成模式
parabricks-tool-map.md — CPU→Parabricks映射（支持所有框架）
nf-core-parabricks-map.md — Nextflow nf-core模块
workflow-layout.md — 开关命名、布局、
```
ACCELERATION.md
```
规范
step-consolidation.md — GPU分支步骤合并
comparison-checklist.md — 开关关闭与开启状态的验证

Instructions

操作步骤

1. Intake and scope

1. 接收需求与范围确认

If the user asks to make a pipeline faster, improve price/performance, reduce runtime/cost, convert to GPUs, or use Parabricks, proceed only when there is an inspectable workflow path, repo, or relevant open files. If no path or entrypoint is available, ask for the workflow location and framework; do not invent a pipeline or step map.

Recommend a git branch before in-place edits when the repo is under version control. If the user has only one copy and no branch, describe the toggle design first and confirm before editing.

Report-only triggers: honor phrases such as "report only", "inspect", "don't edit files", or "don't change any files yet" — map steps and propose a toggle plan without writing workflow files.

当用户要求提升流水线速度、优化性价比、减少运行时间/成本、转换为GPU执行或使用Parabricks时，仅在存在可检查的工作流路径、仓库或相关已打开文件时继续操作。若没有路径或入口点，请询问工作流位置和框架；不得虚构流水线或步骤映射。

当仓库受版本控制时，建议在原位编辑前创建git分支。若用户仅有一份副本且无分支，请先说明开关设计方案，确认后再进行编辑。

仅报告触发条件：尊重“仅报告”“检查”“不要编辑文件”或“暂不修改任何文件”等表述——仅映射步骤并提出开关方案，不修改工作流文件。

2. Runtime readiness

2. 运行环境就绪性检查

Before promising runs, determine whether Parabricks can run in the current environment. Use the user's stated facts if provided; otherwise check only safe, short commands such as

nvidia-smi

and

pbrun --version

when appropriate. Record one of:

```
Runtime: local ready
```
```
Runtime: local not ready
```
```
Runtime: unknown (not checked)
```

If local runtime is not ready, still inspect and map the workflow. Ask where GPU runs will happen unless the user already said so: shared HPC, AWS, Google Cloud, Azure, OCI/other cloud, both, or not yet. Tailor run guidance to that target at a high level.

For detailed runtime assessment, read parabricks-runtime-readiness.md or delegate to the

parabricks

skill.

在承诺运行前，确定Parabricks能否在当前环境中运行。若用户已提供相关信息则使用该信息；否则仅在合适时执行安全、简短的命令，如

nvidia-smi

和

pbrun --version

。记录以下状态之一：

```
Runtime: local ready
```
（本地环境就绪）
```
Runtime: local not ready
```
（本地环境未就绪）
```
Runtime: unknown (not checked)
```
（未知状态，未检查）

若本地运行环境未就绪，仍需检查并映射工作流。询问GPU运行将在何处进行，除非用户已说明：共享HPC、AWS、Google Cloud、Azure、OCI/其他云平台、两者皆可，或尚未确定。针对目标环境提供高层次的运行指导。

如需详细的运行环境评估，请阅读parabricks-runtime-readiness.md或委托给

parabricks

技能。

3. Detect and inventory

3. 框架检测与清单整理

Detect the framework from the workflow path:

Framework	Markers	Inventory
Nextflow	`main.nf` , `nextflow.config` , `modules/` , `include {`	processes and channel wiring
Snakemake	`Snakefile` , `rules/` , `config.yaml`	rules, shell/script blocks, resources
WDL	`*.wdl` , `workflow {` , `task` , `call`	tasks, commands, runtime blocks
Python	`*.py` , `pyproject.toml` , CLI entrypoints	functions and subprocess/shell calls

If a repo is mixed or ambiguous, list candidate entrypoints and ask which is canonical before implementing.

从工作流路径检测框架：

框架	标识	清单内容
Nextflow	`main.nf` , `nextflow.config` , `modules/` , `include {`	流程与通道配置
Snakemake	`Snakefile` , `rules/` , `config.yaml`	规则、shell/脚本块、资源配置
WDL	`*.wdl` , `workflow {` , `task` , `call`	任务、命令、运行时块
Python	`*.py` , `pyproject.toml` , CLI入口点	函数与子进程/shell调用

若仓库混合多种框架或存在歧义，请列出候选入口点并询问哪个是标准入口点，再进行实现。

4. Map steps to Parabricks

4. 将步骤映射到Parabricks

Use parabricks-tool-map.md for all frameworks. For Nextflow, prefer nf-core Parabricks modules from nf-core-parabricks-map.md. For Snakemake, WDL, Python, or shell, use

pbrun

or the official Parabricks container; do not require Nextflow conversion.

Common mappings:

Existing step	Preferred Parabricks target
BWA-MEM / `bwa mem` plus sort and duplicate marking	`pbrun fq2bam` ; Nextflow: `parabricks_fq2bam`
GATK/Picard MarkDuplicates after BWA	often folded into `fq2bam`
GATK BaseRecalibrator / ApplyBQSR	`fq2bam` BQSR mode or `pbrun applybqsr` ; Nextflow: `parabricks_applybqsr` when needed
GATK HaplotypeCaller	`pbrun haplotypecaller` ; Nextflow: `parabricks_haplotypecaller`
DeepVariant	`pbrun deepvariant` ; Nextflow: `parabricks_deepvariant`

When recommending

fq2bam

, note it can consolidate alignment, sort, duplicate marking, and sometimes BQSR. For Nextflow

parabricks_fq2bam

, note the nf-core caveat that inputs must be copied into the work directory (consider

stageInMode 'copy'

), not symlink-staged.

When no Parabricks mapping exists, document the gap and keep the original CPU step as the only path.

使用parabricks-tool-map.md适配所有框架。对于Nextflow，优先使用nf-core-parabricks-map.md中的nf-core Parabricks模块。对于Snakemake、WDL、Python或shell，使用

pbrun

或官方Parabricks容器；无需强制转换为Nextflow。

常见映射：

现有步骤	推荐Parabricks目标
BWA-MEM / `bwa mem` 加排序和重复标记	`pbrun fq2bam` ；Nextflow： `parabricks_fq2bam`
BWA之后的GATK/Picard MarkDuplicates	通常整合到 `fq2bam` 中
GATK BaseRecalibrator / ApplyBQSR	`fq2bam` 的BQSR模式或 `pbrun applybqsr` ；Nextflow：必要时使用 `parabricks_applybqsr`
GATK HaplotypeCaller	`pbrun haplotypecaller` ；Nextflow： `parabricks_haplotypecaller`
DeepVariant	`pbrun deepvariant` ；Nextflow： `parabricks_deepvariant`

5. Report format

5. 报告格式

For inspection/report-only requests, do not edit files. Return:

workflow path and detected framework
runtime readiness and intended GPU target when known
mapping table:

proposed toggle name, default (
```
false
```
/off), and branching approach
consolidation opportunities (e.g. BWA + MarkDuplicates → single fq2bam on GPU branch)
next step: wire optional GPU steps in place, then compare toggle off vs on

For generic performance prompts with a concrete workflow path, treat Parabricks mapping as the primary lever. Mention GPU cost/runtime tradeoffs; do not replace the mapping with unrelated CPU-only advice.

对于仅检查/报告的请求，请勿编辑文件。返回内容包括：

工作流路径与检测到的框架
运行环境就绪性及已知的GPU目标环境
映射表：

建议的开关名称、默认值（
```
false
```
/关闭）和分支方案
合并优化机会（例如BWA + MarkDuplicates → GPU分支上的单个fq2bam步骤）
下一步：原位配置可选GPU步骤，然后对比开关关闭与开启状态的执行结果

对于带有具体工作流路径的通用性能优化请求，将Parabricks映射作为主要手段。提及GPU成本/运行时间的权衡；不得用无关的纯CPU优化建议替代映射方案。

6. Implement in place with optional accelerated steps

6. 原位实现可选加速步骤

Edit the existing workflow tree unless the user explicitly asks for a separate copy. Add Parabricks steps alongside CPU steps; route with a runtime toggle.

除非用户明确要求创建单独副本，否则编辑现有工作流目录。在CPU步骤旁添加Parabricks步骤；通过运行时开关路由执行路径。

Toggle contract

开关约定

Framework	Recommended toggle	Default
Nextflow	`params.use_parabricks` or `params.accelerated`	`false`
Snakemake	`config["use_parabricks"]` or `config.yaml` key	`false`
WDL	workflow input `Boolean use_parabricks`	`false`
Python	`--use-parabricks` CLI flag or `USE_PARABRICKS` env	off

Document toggle name, default, and example run commands in

ACCELERATION.md

框架	推荐开关	默认值
Nextflow	`params.use_parabricks` 或 `params.accelerated`	`false`
Snakemake	`config["use_parabricks"]` 或 `config.yaml` 中的键	`false`
WDL	工作流输入 `Boolean use_parabricks`	`false`
Python	`--use-parabricks` CLI标志或 `USE_PARABRICKS` 环境变量	关闭

在

ACCELERATION.md

中记录开关名称、默认值和示例运行命令。

Implementation patterns

实现模式

Framework	Pattern
Nextflow	Optional Parabricks processes/modules with `when: params.use_parabricks` on GPU path and `when: !params.use_parabricks` on CPU path. Profile or `-params-file accelerated.config` sets toggle on. GPU labels only on accelerated processes.
Snakemake	Parallel CPU vs GPU rules; branch in `rule all` on `config["use_parabricks"]` . `--configfile config.accelerated.yaml` or `--config use_parabricks=true` .
WDL	`if (use_parabricks) { call Parabricks_fq2bam } else { call BwaMem ... }` . GPU `runtime` only on Parabricks tasks.
Python	`--use-parabricks` flag; branch subprocess to `docker run ... pbrun` vs existing CPU commands.

Rules:

Do not delete original CPU steps when first adding acceleration.
Default off must reproduce today's CPU path.
Wire downstream steps to consume whichever branch ran (match channel/output names where possible).
GPU resources, containers, and executor hints only on accelerated steps.
Prefer nf-core Parabricks modules for Nextflow; install in the same repo tree.

Minimum

ACCELERATION.md

sections: toggle usage, runtime target, mappings, output wiring, consolidation opportunities, A/B comparison checklist.

See workflow-layout.md.

框架	模式
Nextflow	可选Parabricks流程/模块，GPU路径添加 `when: params.use_parabricks` ，CPU路径添加 `when: !params.use_parabricks` 。通过Profile或 `-params-file accelerated.config` 开启开关。仅在加速流程上添加GPU标签。
Snakemake	CPU与GPU规则并行；在 `rule all` 中根据 `config["use_parabricks"]` 分支。使用 `--configfile config.accelerated.yaml` 或 `--config use_parabricks=true` 开启开关。
WDL	`if (use_parabricks) { call Parabricks_fq2bam } else { call BwaMem ... }` 。仅在Parabricks任务上配置GPU `runtime` 。
Python	`--use-parabricks` 标志；根据标志分支到 `docker run ... pbrun` 或现有CPU命令。

规则：

首次添加加速步骤时，不得删除原CPU步骤。
默认关闭状态必须与当前CPU执行路径完全一致。
下游步骤需适配任意分支的输出（尽可能匹配通道/输出名称）。
GPU资源、容器和执行器提示仅配置在加速步骤上。
Nextflow优先使用nf-core Parabricks模块；安装在同一仓库目录中。

ACCELERATION.md

的最小内容包括：开关用法、运行目标环境、映射关系、输出配置、合并优化机会、A/B对比检查清单。

详见workflow-layout.md。

7. Consolidation iteration

7. 合并迭代优化

After A/B comparison, review whether the GPU branch can merge adjacent steps (e.g. BWA + sort + MarkDuplicates + BQSR → one

fq2bam

parabricks_fq2bam

Report-only: suggest merges and ask for approval. On approval: edit only the GPU branch (

when: params.use_parabricks

or equivalent), remove superseded GPU sub-steps, update Consolidation history in

ACCELERATION.md

, and remind the user to re-run toggle-off vs toggle-on comparison.

Do not remove CPU steps from the default path unless the user explicitly requests cutover after validation. Do not merge variant calling into fq2bam.

See step-consolidation.md.

完成A/B对比后，评估GPU分支是否可合并相邻步骤（例如BWA + 排序 + MarkDuplicates + BQSR → 单个

fq2bam

parabricks_fq2bam

步骤）。

仅报告：建议合并方案并请求批准。获得批准后：仅编辑GPU分支（

when: params.use_parabricks

或等效配置），移除已被替代的GPU子步骤，更新

ACCELERATION.md

中的合并历史，并提醒用户重新运行开关关闭与开启状态的对比。

除非用户在验证后明确要求切换，否则不得删除默认路径中的CPU步骤。不得将变异检测合并到fq2bam中。

详见step-consolidation.md。

8. Compare before production

8. 生产前对比验证

Never claim result parity. Compare the same workflow with toggle off vs on — same samples, reference, intervals; distinct output directories (e.g.

results-cpu/

results-gpu/

Use comparison-checklist.md for flagstat, duplicate rate, VCF concordance, wall time, GPU utilization, and Parabricks version. Record results in the A/B comparison section of

ACCELERATION.md

text

undefined

绝不声称结果一致。对比同一工作流在开关关闭与开启状态下的执行——使用相同样本、参考序列、区间；使用不同的输出目录（例如

results-cpu/

results-gpu/

）。

使用comparison-checklist.md检查flagstat、重复率、VCF一致性、运行时间、GPU利用率和Parabricks版本。将结果记录在

ACCELERATION.md

的A/B对比部分。

text

undefined

CPU path (default)

CPU路径（默认）

<framework-run-command> # toggle off

<framework-run-command> # 开关关闭

GPU path

GPU路径

<framework-run-command-with-toggle-on> # e.g. -params-file accelerated.config

undefined

<framework-run-command-with-toggle-on> # 例如：-params-file accelerated.config

undefined

9. Optional: benchmark and comparison artifacts

9. 可选：基准测试与对比工件

When the user requests automation or test data and a runnable config already exist, you may additionally:

Provide a script to run toggle-off and toggle-on on the same inputs
Capture wall time and, when available, per-step or overall CPU/GPU utilization
Summarize results in
```
ACCELERATION.md
```
or a simple HTML/markdown comparison table

If no test dataset exists, suggest creating a small subset run and document the comparison plan in

ACCELERATION.md

rather than blocking on custom scripts.

Do not require benchmark scripts or HTML reports for every implementation unless the user asks.

当用户要求自动化或已有测试数据和可运行配置时，可额外执行以下操作：

提供脚本，在相同输入上运行开关关闭与开启状态的执行
记录运行时间，以及可用时的步骤级或整体CPU/GPU利用率
在
```
ACCELERATION.md
```
或简单的HTML/Markdown对比表格中总结结果

若不存在测试数据集，建议创建小型子集运行，并在

ACCELERATION.md

中记录对比方案，而非因缺少自定义脚本而停滞。

除非用户要求，否则无需为每个实现提供基准测试脚本或HTML报告。

Troubleshooting

故障排除

Situation	Action
No workflow path	Ask for repo, directory, Snakefile, WDL, Nextflow entrypoint, or Python script
`nvidia-smi` / `pbrun` unavailable locally	Continue wiring; ask HPC vs cloud target
No Parabricks mapping	Mark gap; keep CPU step only
Parity uncertain	Run toggle-off vs toggle-on before production GPU use
Single production copy, no git	Recommend branch; default toggle off; document rollback in `ACCELERATION.md`

场景	操作
无工作流路径	询问仓库、目录、Snakefile、WDL、Nextflow入口点或Python脚本
本地无法运行 `nvidia-smi` / `pbrun`	继续配置；询问HPC或云端目标环境
无Parabricks映射	记录缺口；仅保留CPU步骤
一致性存疑	生产环境使用GPU前，运行开关关闭与开启状态的对比
仅一份生产副本，无git	建议创建分支；默认开关关闭；在 `ACCELERATION.md` 中记录回滚方案

Examples

示例

No path

无路径场景

User: "Make my genomics pipeline faster and convert it to GPUs."

Response: ask for workflow path and framework. Do not fabricate a pipeline map.

用户：“让我的基因组学流水线更快，并转换为GPU执行。”

回复：询问工作流路径和框架。不得虚构流水线映射。

Nextflow inspect (report only)

Nextflow检查（仅报告）

User: "Inspect

main.nf

for Parabricks opportunities — don't edit files."

Response: map BWA/MarkDuplicates/HaplotypeCaller to nf-core modules, propose

params.use_parabricks

default false, note fq2bam consolidation and symlink/copy constraint, reference nf-core docs. Do not modify files.

用户：“检查

main.nf

的Parabricks优化机会——不要编辑文件。”

回复：将BWA/MarkDuplicates/HaplotypeCaller映射到nf-core模块，建议

params.use_parabricks

默认值为false，说明fq2bam合并和符号链接/复制限制，参考nf-core文档。不得修改文件。

Nextflow in-place

Nextflow原位实现

Add

params.use_parabricks = false

, optional

parabricks_fq2bam

and

parabricks_haplotypecaller

with

when:

guards, keep CPU processes for default path, add

accelerated.config

, document both run commands in

ACCELERATION.md

添加

params.use_parabricks = false

，添加带

when:

guard的可选

parabricks_fq2bam

和

parabricks_haplotypecaller

，保留默认路径的CPU流程，添加

accelerated.config

，在

ACCELERATION.md

中记录两种运行命令。

Snakemake in-place

Snakemake原位实现

Add

use_parabricks: false

config.yaml

, parallel

pbrun fq2bam

and

pbrun haplotypecaller

rules with GPU resources, branch in

rule all

, document

snakemake --config use_parabricks=true

ACCELERATION.md

在

config.yaml

中添加

use_parabricks: false

，添加带GPU资源的并行

pbrun fq2bam

和

pbrun haplotypecaller

规则，在

rule all

中分支，在

ACCELERATION.md

中记录

snakemake --config use_parabricks=true

命令。

WDL in-place

WDL原位实现

Add

Boolean use_parabricks = false

, branch to Parabricks tasks when true, GPU runtime only on GPU branch, document input JSON for both modes in

ACCELERATION.md

添加

Boolean use_parabricks = false

，当值为true时分支到Parabricks任务，仅在GPU分支配置GPU运行时，在

ACCELERATION.md

中记录两种模式的输入JSON。

Python in-place

Python原位实现

Add

--use-parabricks

default false, branch subprocess to

pbrun

in container vs CPU commands, document both invocations in

ACCELERATION.md

添加

--use-parabricks

默认值为false，根据标志分支到容器中的

pbrun

或CPU命令，在

ACCELERATION.md

中记录两种调用方式。

Production single-copy request

生产单副本请求场景

User: "Replace BWA with Parabricks in our only

main.nf

— edit in place."

Response: optional Parabricks steps with toggle default off, keep CPU path, recommend git branch, document toggle and A/B in

ACCELERATION.md

, do not remove CPU steps without post-validation approval.

用户：“在我们唯一的

main.nf

中将BWA替换为Parabricks——原位编辑。”

回复：添加默认关闭的可选Parabricks步骤，保留CPU路径，建议创建git分支，在

ACCELERATION.md

中记录开关和A/B对比方案，未经验证后批准不得删除CPU步骤。