MAIGO

Imported from vvuvv31/MAIGO (AGENTS.md). Install upstream with npx skills add vvuvv31/MAIGO. Copyright stays with the author.

• 当前仓库的主要目标是实现基于TOPAS提取数据复刻出来A_Data-Driven_Fragmentation_Model_for_Carbon_Therapy_GPU-Accelerated_Monte-Carlo_Dose_Recalculation文章中的GPU加速

• gpu需要在沙盒外才能看到，始终允许在沙盒外运行GPU蒙卡code，gpu版本为sm_75，GPU型号为 RTX 2080Ti

• sycl相关的工具也需要在沙盒外调用，始终允许

• Never submit or run GPU jobs on a remote host or cluster.

• 不要尝试使用1D dose scorer，使用3D dose scorer然后对横向求和来代替1D scorer

• 不要考虑FP32的问题，FP64相比较FP32只能提高不到1%的精度

• 当粒子数太多的时候需要拆分成多个任务，例如一次只跑1/10粒子数，然后再合并结果，防止溢出，检测到次级粒子overflow就需要拆分重跑

• ct不要走四分类包，只走 Schneider 分区。

• ct在计算gamma通过率的时候，首先需要根据RTSTRUCTURE的body做mask，只计算body内的voxel，然后根据DTA把搜索步长修改为1/10*DTA，对于0的DTA则不需要修改步长

Git branch workflow

• 当前开发、文档和新提交的目标分支为 master，远端为 origin/master。
• 原 fred 开发线迁移为 master；不要再向 origin/fred 提交或推送。
• legacy 保留迁移前的 master（8716e7c975e5255a747a46286f3b2581d645bf18）， 仅供历史查询，不作为新功能或当前物理数据的默认分支。
• docs/archive 中的旧分支名称、历史 URL 和原始记录保留原样，不是当前执行指令。
• 仅在用户明确要求时 commit / push；默认分支约定不等于自动推送授权。
• 提交时区分已完成改动与未验收候选，不把无关工作树修改、大数据包或 scratch 自动加入提交。

Schneider CT minimum validated physics-data stack

• Schneider CT production/research runs must use at least the currently validated schneider_physics_bundle_v2_1 stack. Never downgrade, alias, or silently fall back to an older package, rate table, schema, projectile registry, or water/ four-class data path.
• The current minimum accepted files are:
  • primary rate: data/schneider/schneider_inelastic_rates_v2_1.bin (SCHNRATE v3), SHA256 086ef97dbf323dc2681d5f6c5257e78c87446050f6fb628f3b0f8b24211a8370;
  • primary CINEL03 package: data/schneider/cinel03_c12_targets_v2_1.bin (CINPKG04 v4), SHA256 a690fb06ae97946bbc167501380fbcfa465b51e61cbedfaba7d3d373655a7ea2;
  • secondary rate: data/schneider/secondary_inelastic_rates_v2_1.bin (SCHN2RAT v3), SHA256 6aa679ee162c7a47b82da715ea1333b21b4056b6480596d8d6243a96edb67258;
  • secondary CINEL03 package: data/schneider/cinel03_secondary_targets_v2_1_14p.bin (CINPKG04 v4, 14-projectile registry), SHA256 a0dc4259b856f0b0e7665672a64589ea4cd64ca304cae75fca16d6de50fc8006;
  • Schneider stopping table: data/schneider/schneider_stopping_v1.bin (SCHNSTOP v1), SHA256 9786dba071f61e660fcc5940a844e8109c4e480ccb603d7929d2fcfaae152c2f;
  • strict-dose section-0 delta-tail table: data/schneider/schneider_section0_c12_delta_tail_v1.csv, SHA256 ff6140f13dcfb4c6f739d6efe56941da6af4749d311e29182601f310a1184aa5.
• data/schneider/schneider_physics_bundle_v2_1.json and data/schneider/v2_1_data_manifest.json are authoritative. Before a Schneider CT run, execute python3 tools/verify_schneider_v2_1_data.py; any missing file, SHA/size mismatch, lower binary version, missing 14-projectile coverage, or v1 artifact placed at a v2.1 path is a hard failure.
• A newer data package may replace this minimum only when it has explicit TOPAS/Geant4 provenance, passes the same or stronger manifest verification, host/device lookup tests, 50k closure gates, one-shard A/B Gamma gate, and a zero-overflow full validation. Until those gates pass, continue using the exact v2.1 stack above; never use a lower version as a compatibility fallback.

Unified EM production integration exception (user-authorized 2026-09-13)

• 用户已明确允许本次例外：将 g4_material_joint_v1（水、25 个 Schneider 分区、 全部 18 种带电离子）接入正式运行选项及生产配置，无需等待低密度阈值闭合和 患者 Gamma 验收完成。该授权允许本次配置/代码修改、验证、第二次 commit 和 push。

• 例外仅适用于 data/em/unified_em_v1.bin，SHA256 8c5d970b3b639bfca2f448730271bed4fc04721aba73100e2efbe09dffe44855。 不取消上文 v2.1 核数据最低要求，不允许旧包回退。

• 正式运行仍必须校验包哈希、材料/离子覆盖、能量记账和 overflow；原发及次级 开启原生涨落，straggling_scale=1.0，使用精确 CT 体素边界。

• 质量报告和文档必须保留低密度 production-cut 阈值区与患者 Gamma 精度验收 尚未完成的说明；运行质量通过不等于上述精度已验证。其他包不继承本次例外。

• 如果没有说明在哪里运行，topas任务就在本地使用sbatch运行，数据放置在本地/mnt/sda/wuwei目录下

• 如果指定了运行的位置，例如v@10.10.10.216，cluster，则不必非要在本地sbatch，且明确允许提交

• topas的extension放在/home/wuwei/topas目录下，如果需要重新编译，source code和build都在/home/wuwei/topas目录下

• 所有任务最多一共使用192线程，内存占用160G

• 提交多个任务的时候按照计算量分配线程/内存数量，控制任务差不多时间完成，防止低能快速跑完了，高能还需要跑很久

• 例如100MeV/u分配10个线程的话，200MeV/u分配20线程，300MeV/u分配30线程。按照剩余（192-已使用）的数量动态按比例分配

• 任务在提交的时候会出现短暂的InvalidAccount，不需要当作异常，只需要等1-3分钟后再检查即可

#!/bin/bash
#SBATCH --job-name=xxx       # 任务名称
#SBATCH --partition=compute        # 默认计算分区 (无需修改)
#SBATCH --nodes=1                  # 申请 1 台主机
#SBATCH --cpus-per-task=50         # 申请分配的 CPU 核心数 (根据需要设定)
#SBATCH --mem=50G                  # 申请分配的内存 (根据需要设定)
#SBATCH --output=/mnt/sda/%u/job_%j.log   # 运行日志保存到 15TB 数据盘 (%u 代表当前用户, %j 代表任务ID)
#SBATCH --error=/mnt/sda/%u/job_%j.err    # 错误日志

command

File editing rules

When modifying source files:

• Prefer the native file-editing mechanism over manually constructing unified diffs.
• Do not repeatedly retry the same git apply strategy after a malformed patch.
• If git apply reports corrupt patch, retry at most once.
• After the second failure, switch editing strategy:
  • use a direct file edit,
  • or use a small Python/scripted replacement,
  • or regenerate the target section from the current file contents.
• Before constructing a patch, re-read the relevant section of the target file.
• For large edits, make smaller independent edits instead of one large handwritten patch.
• After editing, inspect git diff --check and git diff before proceeding.
• Never spend more than two attempts fixing patch syntax.

Eligible warp / warp/SM failed-attempt ledger

• Any experiment intended to improve registers/thread, theoretical or actual warps/SM, active/eligible warps, occupancy, long-scoreboard, local-memory traffic, or block co-residency that fails its promotion gate must be appended to docs/eligible_warp_failed_attempts.md before the task is considered complete or committed.
• Record the actual launched kernel, baseline/candidate resource and timing measurements, correctness gates, evidence paths, final disposition, and the new evidence required before retrying. Write unmeasured fields as unmeasured; never infer spills from stack size or module time from a stall percentage.
• Keep the ledger append-only. Correct an earlier entry with a dated superseding note instead of silently deleting the failed attempt.

Condensed delta production integration (user-authorized 2026-09-15)

• 用户已验收并要求将两矩 Gamma δ 聚合及解析 Poisson 分步修正接入正式生产，允许 commit/push。
• 该授权包含由固定统一 EM 核心包派生的 data/em/unified_em_delta_moments_v2.bin，SHA256 c551bc52fa30ff7e3ea229c8b89792e8ecd2b0fb12f18fcad50d1c6f206bc7cc；源包哈希和上文一致。用 tools/build_delta_moments.py 生成并严格校验。
• 不改变 v2.1 核数据最低要求、独立核弹性的研究状态、原生受限涨落 scale=1 与精确 CT 边界；患者 BODY Gamma 和低密度阈值验证仍待完成。