cres

这个crate实现了用于蒙特卡洛碰撞事件样本中消除负权重的单元格重采样算法。该算法在以下文献中描述：

《蒙特卡洛样本中负权重的无偏消除》
J. Andersen, A. Maier
arXiv:2109.07851

在大型高多重性蒙特卡洛事件样本中高效消除负权重
Jeppe R. Andersen, Andreas Maier, Daniel Maître
arXiv:2303.15246

安装

如果您的系统上已安装 Rust 和 Cargo，请运行

cargo install cres

预编译的可执行文件可在 hepforge 上找到。

要安装开发版本，请运行

cargo install --git https://github.com/a-maier/cres

请查阅 功能部分 了解更多选项。

要生成shell命令补全，请运行

cres-generate-shell-completion SHELL

对于 bash 和 fish，命令补全应在下次登录后生效。对于其他shell，补全代码将写入标准输出。如果您不确定如何处理它，请查阅shell的文档。要列出支持的shell，请运行

cres-generate-shell-completion --help

使用方法

基本用法是

cres -a JETALGO -R JETR --jetpt JETPT --max-cell-size R -o OUTDIR EVENTFILES...

这将从 HepMC2 或 Les Houches 事件格式中读取多个输入事件文件，这些文件包含混合权重的事件，并为每个文件生成一个输出文件，该文件位于 OUTDIR 中，并且来自负权重的贡献更小。输入文件可以使用 bzip2、gzip、zstd 或 lz4 进行压缩。输入格式将自动检测。

我们建议将喷气算法 JETALGO、喷气半径 JETR 和最小喷气横动量 JETPT 设置为与生成输入事件时使用的相同值。支持的喷气算法包括 anti-kt、kt 和 Cambridge-Aachen。当包括 QED 修正时（例如通过 shower），还应设置 --leptonalgorithm、--leptonradius 和 --leptonpt。

设置最大单元格半径 R 是可选的，但强烈推荐。较小的值会导致重采样速度更快，并且扩散效应更小。较大的值可以消除更多的负权重。建议从 1 到 10 之间的值开始，并根据需要进行调整。

选项

要查看带有简短描述的完整选项列表，请运行

cres --help

最重要的选项包括

• --max-cell-size 可用于限制生成的单元大小。这确保了权重只会在足够相似的事件之间传递。缺点是并非所有负事件权重都将被移除。

  当单元大小限制较小时，单元重采样速度会更快。因此，建议从较小的值开始，例如10，如果留下太多负权重，则逐渐增加值。

• --leptonalgorithm、--leptonradius、--leptonpt 用于电子和光子的聚类。这些选项应在包含QED校正时设置，例如通过喷注。

• --ptweight 指定了横动量对动量p和q之间距离的影响程度，根据以下公式

  d(p, q) = \sqrt{ ptweight^2 (p_\perp - q_\perp)^2 + \sum (p_i - q_i)^2 }
  

• 除了重采样外，使用 --minweight 事件也会进行去权重。权重小于 w < minweight 的事件将以概率 1 - |w| / minweight 被丢弃，否则重新加权到 sign(w) * minweight。最后，将所有事件权重重新缩放到原始权重总和的精确值。去权重的种子可以通过 --seed 选项选择。

选项太多

为了避免命令行混乱，可以将选项保存在argfile中。每行应恰好包含一个选项，选项名和值必须由 '=' 分隔。例如

--jetalgorithm=anti-kt
--jetradius=0.4
--jetpt=30

可以使用以下方式使用argfile

cres @argfile -o OUT.HEPMC2 IN.HEPMC2

扩展到大型样本

理想情况下，cres 应尽可能运行尽可能多的事件。不建议在多个节点上进行原始并行化，因为单元重采样质量不会从更高的事件统计中受益。

对于由许多较小子样本组成的大型样本，建议以下工作流程

1. 运行

    cres-partition @partitionargs -o partition --regions N SUBSAMPLE.HEPMC2
   

   单个子样本，例如10^6事件。 N 是 cres 应在以后并行运行在上的节点数。 cres-partition 应足够快且内存高效，可以在单个节点上运行。

2. 使用步骤1中创建的 partition 文件，运行

    cres-classify @classifyargs -p partition SUBSAMPLE.HEPMC2
   

   每个子样本。每个子样本都可以并行处理。这将 SUBSAMPLE 分割成 N 部分 SUBSAMPLE.X.HEPMC2。

3. 对于每个部分 X，在所有子样本上运行 cres

    cres @argfile SUBSAMPLE0.X.HEPMC2 SUBSAMPLE1.X.HEPMC2 ...
   

   每个实例都可以在单独的节点上运行。

环境变量

CRES_LOG 环境变量允许对命令行输出进行精细控制。例如，要查看喷注聚类的调试输出，请设置

CRES_LOG=jetty=debug,cres=info

有关全面文档，请参阅 env_logger crate。

默认情况下，cres会尽可能使用尽可能多的核心。对于小事件样本，限制线程数量可能会更快。您可以通过--threads命令行选项或RAYON_NUM_THREADS环境变量来设置线程数量。

功能

要安装具有附加功能的cres，请将--features name1,name2添加到您的安装命令中。默认功能无需手动添加。要禁用它们，请添加--no-default-features标志。

默认功能

• multiweight：启用在单个运行中处理多个权重的--weights选项。如果您只想考虑单个权重，可以禁用此功能以节省一些内存和计算时间。

• lhef：支持读取和写入Les Houches事件格式文件。

非默认功能

• ntuple：支持读取和写入ROOT ntuple文件。这需要一个较新的libclang版本和一个带有root-config的执行路径的ROOT安装。

• stripper-xml：对STRIPPER使用的XML格式的实验性支持。

• capi：启用C API以将cres用作C库。有关示例，请参阅示例子目录。API有限，且仅适用于类Unix平台。根据请求将扩展。

作为库使用

为了像自定义距离函数一样拥有完整的灵活性，cres可以用作库。有关示例，请参阅示例子目录。API在docs.rs上进行了文档记录。