minibwa/minibwa_dist/features.toml at dist · nh13/minibwa

Repository navigation

History

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

129

130

131

132

133

134

135

136

137

138

139

140

141

142

143

144

145

146

147

148

149

150

151

152

153

154

155

156

157

158

159

160

161

162

163

164

165

166

167

168

169

170

171

172

173

174

175

176

177

178

179

180

181

182

183

184

185

186

187

188

189

190

191

192

193

194

195

196

197

198

199

200

201

202

203

204

205

206

207

208

209

210

211

212

213

214

215

216

217

218

219

220

221

222

223

224

225

226

227

228

229

230

231

232

233

234

235

236

237

238

239

240

241

242

243

244

245

246

247

248

249

250

251

252

253

254

255

256

# The minibwa distribution manifest. See ephemeral/2026-08-01-...-design.md.

# Merge order is significant: disjoint features first, the hub (alt-liftgroup) last.

# `required = true` aborts the build on conflict; false drops the feature and files an issue.

# --- tooling: must be present on `dist` so scheduled workflows can run ---

[[feature]]

name = "ops-distro"

branch = "ops/distro"

required = true

output = "identical"

# Never offer this upstream: it is the distribution's own machinery, not a

# change to the aligner. Marked here so `nomination_candidates` does not have to

# know this one entry's name.

upstreamable = false

summary = "distribution manifest, assembly engine and workflows"

upstream = { status = "unsubmitted" }

# --- minimal feature-vs-feature overlap: mostly conflict only with upstream ---

# Exception: single-copy-parser and extd2-avx512 both edit Makefile, so they can

# also conflict with each other.

[[feature]]

name = "ll-affine-reassoc"

branch = "perf/ll-sse-affine-reassoc-arm"

required = false

output = "identical"

summary = "reassociate the affine-gap recurrence in ksw2_ll for arm64"

upstream = { pr = 37, status = "rejected" }

[[feature]]

name = "ksw2-extension-kernels"

branch = "perf/ksw2-extension-kernels"

required = false

output = "identical"

summary = "shuffle-LUT prepass, one-vext rail shift, 16-wide exact-max and NEON BIT direction bytes in ksw2_extd2/extz2; +11% HiFi and +10% ONT on arm64, +7% on x86"

upstream = { pr = 64, status = "open" }

[[feature]]

name = "single-copy-parser"

branch = "feat/single-copy-parser"

required = false

output = "identical"

# Unlike the two coordinator-side features further down, this one eliminates a copy

# rather than moving it to another thread, so it genuinely reduces total work and its

# ladder increment (0.67-1.24 pp) sits inside what returning that CPU to the mapping

# threads can buy (<= 0.85 pp at 16 threads). Not implicated in their batch-count

# artifact -- though it has not itself been confirmed at production scale either.

summary = "read FASTQ records with a single copy instead of two; 0.67-1.24 pp whole-stack ladder increment"

upstream = { status = "unsubmitted" }

[[feature]]

name = "index-threads-v2"

branch = "feat/index-threads-v2"

required = false

output = "identical"

# Static suite: asserts the OpenMP parallelization stays inside mb_bwt_libsais. The

# byte-identity gate cannot see a same-output slowdown, so a merge that drops the

# parallelization would pass it silently; this catches that on every sync.

tests = "test/index-threads"

summary = "parallelize the SA-to-BWT pipeline (OpenMP, gated on the existing LIBSAIS_OPENMP probe)"

upstream = { status = "unsubmitted" }

[[feature]]

name = "extd2-avx512"

branch = "extd2-avx512-dispatch"

required = false

output = "identical"

summary = "AVX2/AVX-512 ksw_extd2 with runtime dispatch; pays on HiFi/ONT"

upstream = { pr = 20, status = "open" }

[[feature]]

name = "radix-key-width"

branch = "perf/radix-key-width"

required = false

output = "identical"

# Touches seed.c/map-algo.c/lchain.c/pe.c/mbpriv.h, which the alt-liftgroup hub

# also edits -- so it stays in this disjoint cluster (merged before the hub) and

# overlaps no other feature here.

# upstreamable = false: kept downstream-only by request; the reconcile bot must not

# nominate it. (The win is real per-sort but ~0 end-to-end, so it is not worth an

# upstream PR on its own.)

upstreamable = false

summary = "right-size klib radix key widths -- 5-byte genome-coordinate and 4-byte int32 chain-score sorts; byte-identical, 1.5-4.9x per-sort but <~1% of map CPU"

upstream = { status = "unsubmitted" }

# smem-search-memtraffic graduated: upstream took the occ prefetch as lh3/minibwa#65

# (c42d875), so master carries it and the block is deleted per "Removing a feature".

# Recording status = "merged" is not an option -- the parser rejects graduated

# statuses precisely so a block like this cannot linger and conflict every night.

# The weekly reconciler would normally do this deletion for us, but it keys on the

# PR number recorded in the block, and this one said `unsubmitted`: the PR was opened

# from a separate r421-based branch (perf/smem-prefetch-occ) rather than the frozen

# feature branch, so there was no number here to notice going merged.

# --- shared-file features ---

# The two features below are coordinator-side, and their ladder increments are an

# artifact of the ladder's input size. Both were measured on `wgs-1M`, which is only

# four mini-batches at the default -K 100m, and a coordinator-side change can reach

# the wall clock ONLY through pipeline starvation -- the fill and drain during which

# no mapping is in flight. That is an O(1) cost: measured at 8.0% of the parallel

# budget with 2 batches, 4.55% with 4, and a fixed ~0.9 thread-s beyond ~60.

# Confirmed on c8g.4xlarge at -t 16, rung 7 vs rung 9, rep spread 0.02-0.20%:

# 2 batches +3.66pp | 4 (default) +3.72pp | 7 +2.30pp | 13 +1.13pp

# 31 +0.04pp | 61 -0.06pp | and wgs-5M at the default -K, 15 batches, +1.09pp

# So the gain is gone above ~31 batches ~= 3.1 Gbp ~= 10M pairs, which every

# production WGS input exceeds. Quote the dependence, not a bare percentage.

# See ephemeral/finding--ladder-batch-count.md.

[[feature]]

name = "inline-appenders"

branch = "feat/inline-appenders"

required = false

output = "identical"

summary = "format SAM/PAF records with inline appenders; with parallel-encode worth +3.7 pp at the default -K on wgs-1M but ~0 above ~10M pairs (input-size dependent, see notes)"

upstream = { pr = 32, status = "rejected" }

[[feature]]

name = "parallel-encode"

branch = "feat/parallel-encode"

required = false

output = "identical"

# Relocates work rather than removing it -- total process CPU is unchanged (medians

# 102.9-104.4 s either way) -- so it can only pay while the coordinator is on the

# critical path. Hence the batch-count dependence documented above.

summary = "format SAM/PAF in the mapping step instead of the output thread; relocates work rather than removing it, so it pays only on inputs small enough to be starvation-bound"

upstream = { pr = 33, status = "open" }

[[feature]]

name = "meth-cleanups"

branch = "chore/meth-cleanups"

required = false

output = "identical"

# Genuinely comment-only: the align.c hunk replaces a "TODO: check if this is

# correct" with the explanation, leaving the code line byte-identical, and the

# minibwa.h hunk documents b_ts. Plus one new CI test. No scoring change.

summary = "a --meth CI test; documents the mb_align1_inv strand flip and b_ts (comments only)"

upstream = { pr = 19, status = "rejected" }

[[feature]]

name = "meth-sam-tags"

branch = "feat/issue-14-meth-sam-tags"

required = false

output = "conditional"

condition = "--meth is set"

negative = "align the chrM fixture without --meth; SAM must be byte-identical to stock"

summary = "emit Bismark-compatible XR/XG/XM tags"

upstream = { pr = 15, status = "open" }

[[feature]]

name = "soft-clip-penalty"

branch = "feat/soft-clip-penalty"

required = false

output = "conditional"

condition = "-L is set"

negative = "align the chrM fixture without -L; SAM must be byte-identical to stock"

summary = "5'/3' soft-clip penalty (-L)"

upstream = { pr = 13, status = "rejected" }

[[feature]]

name = "submem-ablation"

branch = "feat/submem-ablation"

required = false

output = "conditional"

condition = "--max-sub-occ or --min-sub-occ is set"

negative = "align the chrM fixture with neither flag; SAM must be byte-identical to stock"

summary = "expose --max-sub-occ and --min-sub-occ ablation flags"

upstream = { pr = 12, status = "rejected" }

# --- SA-density / regime / backend features (index + map side) ---

# Appended after the shared-file features and before the hub so every feature

# above keeps its existing merge order (and its rerere pre-images). cp-occ-backend

# is stacked on sa-regime-picker (its branch contains it), so it MUST merge after

# it; only its incremental cp_occ delta lands once sa-regime-picker is already in.

[[feature]]

name = "sa-default-u3"

branch = "sa-default-u3"

required = false

output = "identical"

summary = "default the SA sample rate to 1/8 (-u 3); ~5-6% faster mapping for ~+3 GB RAM on hg38, all native densities byte-identical"

upstream = { status = "unsubmitted" }

[[feature]]

name = "sa-regime-picker"

branch = "sa-regime-picker"

required = false

output = "identical"

summary = "--index-regime picker with auto speed/memory selection over byte-identical native SA densities (--index-mem, --list-regimes)"

upstream = { status = "unsubmitted" }

[[feature]]

name = "cp-occ-backend"

branch = "feat/cp-occ-backend"

required = false

output = "conditional"

condition = "built with make B2=1 and a cp_occ (-b2) regime is selected"

negative = "align the chrM fixture with a stock (non-B2) build; SAM must be byte-identical to stock"

summary = "compile-optional cp_occ (bwa-mem2/mem3 FM-index) seeding backend (make B2=1); ~5-12% faster at matched density, differs from native for ~0.05% of reads (MAPQ-0 multimappers)"

upstream = { status = "unsubmitted" }

[[feature]]

name = "sa-batch-128"

branch = "perf/sa-batch-128"

required = false

output = "identical"

summary = "raise the SA-lookup batch depth in mb_anchor 20 -> 128 so more SA walks overlap; +1.9% WGS / +3.9% HiFi on arm64, +0.5% on x86 AVX2"

upstream = { status = "unsubmitted" }

# --- the hub: touches 9 shared files, merges last, never blocks the build ---

[[feature]]

name = "alt-liftgroup"

branch = "feat/alt-aware-liftgroup"

required = false

output = "conditional"

condition = "the index has ALT contigs"

negative = "align the chrM fixture (no ALT contigs); SAM must be byte-identical to stock"

# The negative case above is all byte-identity can prove: with no ALT contigs the

# feature is inert. Its ~1,350 active lines only run when a .alt is present, and

# these suites are the only thing that exercises them.

tests = "test/altlg"

summary = "ALT-aware mapping via post-extension liftover groups"

upstream = { status = "unsubmitted" }

# --- the graveyard: never built, never nominated for upstreaming ---

[[withdrawn]]

name = "pe-mapq-low-copy-repeats"

branch = "fix/pe-mapq-low-copy-repeats"

report = "reports/2026-07-20-minibwa-meth-pe-mapq-wrongchrom-negative-result.md"

summary = """AUC flat at -2.6e-5 and strictly dominated by raising the mapQ threshold: \

unpatched at mapQ>=30 gives the same 1,336 errors as patched at mapQ>=20, with 69,269 more \

correct reads. The wrong-chromosome tail is a base-rate artifact, not a calibration defect."""

[[withdrawn]]

name = "rescue-window-gate"

branch = "perf/rescue-window-gate"

report = "reports/2026-08-01-mate-rescue-window-gate.md"

summary = """Large speedups (-5.5% WGS, -44.9% Hi-C) but every ablation level moves confident \

placements on real data (WGS L4: 1 in 4,300 at MAPQ>=10). The simulated ROC that passed was the \

wrong experiment. The Hi-C half is void too: that arm ran without --hic, which already skips all \

mate rescue, so it timed a configuration nobody should use for the assay (5.9-7.9x on 100k HG002 \

pairs; proper-paired 88,411 -> 0). The idea it was said to leave behind -- skip rescue when the \

insert-size distribution is uninformative -- is already implemented twice: --hic for the whole \

assay, and the per-read futility gate at pe.c:358, whose constants (10, 0.33) match bwa-mem3's \

--rescue-skip. See reports/2026-08-08-hic-mate-rescue-futility.md."""

[[withdrawn]]

name = "pe-encode-vectorize"

branch = "perf/pe-encode-vectorize"

report = "reports/2026-08-06-pe-encode-vectorize-x86-regression.md"

summary = """Flat on arm64 and a reproducible cost on x86 (+0.34pp gcc t=5.3, +0.54pp clang \

t=11.3), standalone rather than an adjacency artifact. The premise holds -- the revcomp does \

auto-vectorize, identically on both architectures -- but the split makes loop 2 reload with \

16-byte vector loads what scalar loop 1 just wrote byte-by-byte, which defeats x86 \

store-to-load forwarding. Moot regardless: the nt4 encode is absent from a profile, under 0.1% \

of runtime, so nothing here was worth optimizing."""

FilesExpand file tree

features.toml

Latest commit

History

features.toml

File metadata and controls