用于访问ATLAS xAOD文件的函数分析描述语言后端。
项目描述
func_adl_xAOD
将 qastle 转换为在ATLAS xAOD后端上运行的后端。
简介
这允许您查询以ATLAS xAOD格式编写的root文件中存储的分层数据。此代码允许您查询这些数据。
功能
以下是支持 xAOD C++翻译器的部分功能的简要列表。
Python
支持许多但并非所有Python语言的部分。一般来说，任何是语句或流程控制的都不是支持的。例如，没有 if 或 while 或 for 语句。赋值不受支持，这听起来可能很有限 - 但这是一个功能实现，所以比人们想象的要少。
以下是一些支持的语言部分
- 函数调用、方法调用、属性引用和lambda调用（以及lambda函数），有一些限制。
- 数组中的整数索引
- 有限的元组支持，作为收集信息或作为输出到ROOT文件的方式。
- 有限的列表支持（与上面相同）。特别是，不支持的
append方法，因为它修改了列表而不是创建一个新的列表。 - 一元、二元和比较操作。仅支持两个参数的比较（例如
a > b而不是a > b > c）。 - 使用
and和or来组合条件表达式。注意，当编写表达式时，它被写作&和|，因为python要求and和or返回bool类型。 - 条件 if 表达式 (
10 if a > 10 else 20) - 浮点数、整数和字符串。
xAOD 函数
只要所需的参数是基本类型，就可以调用由 C++ 对象支持的函数。以下列出了附加到 ATLAS xAOD 数据模型中各种对象的特殊 额外 函数。
事件
事件对象具有以下特殊函数以访问集合
Jets、Tracks、EventInfo、TruthParticles、Electrons、Muons和MissingET。每个函数接受一个参数，即 xAOD 中的银行名称。例如，对于电子，可以传递"Electrons"。
添加新集合相当简单。
喷射对象
模板函数在 python 中还不适用。
getAttribute- 此函数是模板化的，因此必须以getAttributeFloat或getAttributeVectorFloat的形式调用。
数学
- 数学运算符：+、-、*、/、%，**
- 比较运算符：<、<=、>、>=、==、!=
- 一元运算符：+、-、not
- 数学函数来自 C++
cmath库：sin、cos、tan、acos、asin、atan、atan2、sinh、cosh、tanh、asinh、acosh、atanh、exp、ldexp、log、ln、log10、exp2、expm1、ilogb、log1p、log2、scalbn、scalbln、pow、sqrt、cbrt、hypot、erf、erfc、tgamma、lgamma、ceil、floor、fmod、trunc、round、rint、nearbyint、remainder、remquo、copysign、nan、nextafter、nexttoward、fdim、fmax、fmin、fabs、abs、fma。 - 不要在调用中使用
math.sin。然而，sin是可以接受的。如果你这样做，你将在解析期间遇到一个异常，它不知道如何翻译math。 - 对于像
sum、min、max等东西，请使用Sum、Min、MaxLINQ 谓词。
元数据
可以将元数据注入到 qastle 查询中，以改变 C++ 代码生成的行为。下面的每个子部分都有不同类型的元数据。为了调用此功能，请使用 Metadata 调用，该调用以输入流为输入，并输出相同的流，但参数是一个包含元数据的字典。
关于元数据的几点
- 没有两个元数据块可以具有相同的名称和不同的内容。然而，它们可以有不同的依赖关系。在这种情况下，多个块被视为一个块，其依赖关系是并集。
- 如果无法完成依赖图或发现循环依赖关系，则引发异常 (
ValueError)。
方法返回类型
如果您有一个返回非标准类型的函数，请使用此元数据类型指定后端返回类型。此元数据有两种不同的形式 - 一种用于返回单个项目，另一种用于返回项目集合。
对于 单个项目
| 密钥 | 描述 | 示例 |
|---|---|---|
| metadata_type | 元数据类型 | "add_method_type_info" |
| type_string | 方法应用的对象，完全限定，C++ | "xAOD::Jet" |
| method_name | 方法名称 | "pT" |
| return_type | 返回类型，C++，完全限定 | "float"、"float*"、"float**" |
| deref_count | 调用此方法前解引用对象次数（可选） | 2 |
注意：deref_count用于对象可以通过解引用“隐藏”地保留其他对象时（例如，通过重载运算符operator*）。如果为零（由于operator*很少被重载，所以通常为零），则可以省略。
对于集合
| 密钥 | 描述 | 示例 |
|---|---|---|
| metadata_type | 元数据类型 | "add_method_type_info" |
| type_string | 方法应用的对象，完全限定，C++ | "xAOD::Jet" |
| method_name | 方法名称 | "jetWeights" |
| return_type_element | 集合元素的类型 | "float" |
| return_type_collection | 集合的类型 | vector<float>, vector<float>* |
| deref_count | 调用此方法前解引用对象次数（可选） | 2 |
C++ 内联函数和方法
这些是内联函数 - 它们被放在代码中，被大括号包围。只有result被声明在外面，并预期在块内部设置。这种机制还可以指定方法。在这种情况下，应指定可选参数instance_obj。
| 密钥 | 描述 | 示例 |
|---|---|---|
| metadata_type | 元数据类型 | "add_cpp_function" |
| name | C++ 函数名称 | "DeltaR" |
| include_files | 包含文件列表 | [vector, TLorentzVector.h] |
| arguments | 参数名称列表 | [vec1, vec2] |
| code | 代码行列表 | ["auto t = (vec1+vec2);", "auto result = t.m();"] |
| instance_object | 仅当这是对象替换时存在。它指定应替换为当前对象的代码字符串 | "xAOD::Jet_vt" |
| method_object | 可以调用此方法的对象名称。仅当这是方法时存在。 | "obj_j" |
| result_name | 如果不使用result，应使用什么（可选） |
"my_result" |
| return_type | C++ 返回类型 | double |
| return_is_collection | 如果为真，则返回值为return_type的集合 |
True |
注意，对result_name进行了非常简单的替换，因此它需要是一个完全独特的名称。后端可能会根据解析表达式的复杂性将result更改为其他名称（如r232）。
如果发送了具有相同名称的两个函数，它们必须相同，否则行为是未定义的。
作业脚本
ATLAS 运行作业脚本来配置其环境。这些脚本用于执行诸如应用校正等操作。此块允许动态添加这些脚本。在 ATLAS 中，这些作业脚本为 Python。
| 密钥 | 描述 | 示例 |
|---|---|---|
| metadata_type | 元数据类型 | "add_job_script" |
| name | 此脚本块名称 | "apply_corrections" |
| script | Python 行列表 | ["calibration = makeAnalysis('mc')", "job.addSequence(calibration)"] |
| depends_on | 应在其后出现的其他脚本块列表 | ["correction_setup"] |
将从depends_on条目构建一个依赖图，否则块将随机出现。
注意：目前 CMS 后端将忽略发送给它的任何作业脚本元数据。
事件级集合
CMS 和 ATLAS 将其基本重建对象存储为集合（例如，喷气机等）。您可以使用以下元数据动态定义新集合
对于ATLAS
| 密钥 | 描述 | 示例 |
|---|---|---|
| metadata_type | 元数据类型 | "add_atlas_event_collection_info" |
| name | 集合名称（用于从数据集对象访问） | "TruthParticles" |
| include_files | 访问集合时使用的包含文件列表 | ['file1.h', 'file2.h'] |
| container_type | 填充的容器对象 | "xAOD::ElectronContainer" |
| element_type | 容器中的元素。在 ATLAS 中这是一个指针。 | "xAOD::Electron" |
| contains_collection | 某些项是单例（如EventInfo） |
True或False |
对于CMS AOD
| 密钥 | 描述 | 示例 |
|---|---|---|
| metadata_type | 元数据类型 | "add_cms_aod_event_collection_info" |
| name | 集合名称（用于从数据集对象访问） | "Vertex" |
| include_files | 访问集合时使用的包含文件列表 | ['DataFormats/VertexReco/interface/Vertex.h'] |
| container_type | 填充的容器对象 | "reco::VertexCollection" |
| element_type | 容器中的元素。 | "reco::Vertex" |
| contains_collection | 某些项是单例（如EventInfo） |
True或False |
| element_pointer | 指示元素类型是否为指针 | True或False |
针对 CMS miniAOD
| 密钥 | 描述 | 示例 |
|---|---|---|
| metadata_type | 元数据类型 | "add_cms_miniaod_event_collection_info" |
| name | 集合名称（用于从数据集对象访问） | "Muon" |
| include_files | 访问集合时使用的包含文件列表 | [DataFormats/PatCandidates/interface/Muon.h] |
| container_type | 填充的容器对象 | "pat::MuonCollection" |
| element_type | 容器中的元素。 | "pat::Muon" |
| contains_collection | 某些项是单例（如EventInfo） |
True或False |
| element_pointer | 指示元素类型是否为指针 | True或False |
代码块
代码块提供了一种将各种C++行注入代码的方法。有多种选项，可以使用任意组合的键。
| 密钥 | 描述 | 示例 |
|---|---|---|
| metadata_type | 元数据类型 | "inject_code" |
| name | 代码块名称 | "code_block_1" |
| body_includes | 要包含在C++文件（query.cpp）中的文件列表。 |
["file1.hpp", "file2.hpp"] |
| header_includes | 要包含在C++头文件（query.hpp）中的文件列表。 |
["file1.hpp", "file2.hpp"] |
| private_members | 要声明的类实例变量列表（query.hpp） |
["int first;", "int second;"] |
| instance_initialization | 在主C++类文件（query.cpp）的构造函数中添加的初始化器 |
["first(10)", "second(10)"] |
| ctor_lines | 要添加到构造函数体的C++行（query.cpp） |
["second = first * 10;"] |
| link_libraries | 要添加到CMake LINK_LIBRARIES列表中的项（CMakeLists.txt） |
["TrigDecisionToolLib"] |
注意事项
- 注意有分号和没有分号的项。这是至关重要的 - 系统不会在这些情况下添加它们！
- 虽然单个
inject_code元数据块内行的顺序将保持不变，但不同的块可能被任意重新排序。 - 包含文件始终使用双引号：
#include "file1.hpp" - 代码块名称在任何地方都没有使用，并且它必须是唯一的。如果有两个代码块以相同的名称提交但内容不同，将生成错误。
Docker镜像
只有在你针对本地文件运行时（例如，使用xAODDataset或类似），此元数据才能使用。它允许你配置你想要运行的镜像。
| 密钥 | 描述 | 示例 |
|---|---|---|
| metadata_type | 元数据类型 | "inject_code" |
| image | 要运行的Docker镜像和标签 | "atlas/analysisbase:21.2.195" |
输出格式
仅xAOD代码将func_adl表达式渲染为ROOT文件。ROOT文件在其根目录中包含一个简单的TTree。
- 如果
AsROOTTTree是顶级func_adl节点，则树名和文件名来自该表达式。只有Pythontuples序列或单个项可以被AsROOTTTree理解。 - 如果
Select序列的最后一个func_adl表达式是int或double，则将生成一个名为xaod_output.root的文件，它将包含一个名为atlas_xaod_tree的单列TTree，列名为col1。 - 如果最后一个
func_adl表达式是tuple的Select序列，则将生成一个名为xaod_output.root的文件，它将包含一个名为atlas_xaod_tree的TTree，具有名为col1、col2等的列。 - 如果最后一个
func_adl表达式是字典的Select序列，则将生成一个名为xaod_output.root的文件，它将包含一个名为atlas_xaod_tree的TTree，列名来自字典键。
ServiceX（以及servicex前端包）可以将从ROOT转换为其他格式，如pandas.DataFrame或awkward数组。
测试和开发
设置开发环境
- 创建虚拟环境后，执行本地设置：
pip install -e .[test]
要运行测试
pytest -m "not atlas_xaod_runner and not cms_runner"将运行快速测试。pytest -m "atlas_xaod_runner"、pytest -m "cms_aod_runner"和pytest -m "cms_miniaod_runner"将分别运行ATLAS xAOD、CMS AOD和CMS miniAOD的慢速测试，这些测试需要你在命令行上安装docker。由于通过Python的os.system涉及到docker，因此测试执行器需要有可用的docker。- GitHub上的CI已配置为针对Python
3.7、3.8和3.9运行测试（仅非xaod-runner测试）。
贡献
- 在其他仓库或分支上开发
- 向
master分支提交PR。
一般来说，master分支应始终通过所有测试。发布是通过在master分支上打标签来完成的。
发布到PyPi
- 通过在GitHub的Web界面中声明新的发布（或预发布）来自动化
本地运行
设计用于本地运行，如果你在本地机器上安装了docker，则可以设置并使用xAOD后端。要使用此功能，您首先需要安装本地的这个包版本
pip install func_adl_xAOD[local]
然后，您可以使用xAODDataset对象、CMSRun1AODDataset对象和CMSRun2miniAODDataset来执行在本地运行的ATLAS或CMS Run 1 AOD的docker镜像上的qastle。
- 在构造函数的参数中指定您要运行的文件的本地路径
- 文件将顺序运行，并且是阻塞的
- 此代码是为开发和测试工作设计的，并不适用于在本地文件上大规模运行生产环境（尽管这并非不可能）。
当发生奇怪的事情并且您真的想查看C++输出时，您可以通过在执行xAOD后端之前包含以下代码来实现。这将打开日志记录，将运行输出和用于执行查询的C++头文件和源文件输出。
import logging
logging.basicConfig()
logging.getLogger("func_adl_xAOD.common.local_dataset").setLevel(level=logging.DEBUG)
- 一般来说，前两行是笔记簿等中一个好的选择。它允许您看到警告消息的来源，并在事情出错时可能有所帮助。
请注意，一些本地运行器将使用docker卷来缓存校准文件等。如果您需要一个真正的全新开始，您需要首先删除卷。
下载文件
下载适用于您平台的文件。如果您不确定选择哪个，请了解有关安装包的更多信息。
源分布
构建分布
func_adl_xAOD-2.1.3.tar.gz的哈希值
| 算法 | 哈希摘要 | |
|---|---|---|
| SHA256 | 5b9d141def191761d86b15dd576d1c88d536098b3844ff9fd9cfee9117e915fd |
|
| MD5 | 927a72becd07a6ab9cb8f0515dc417f1 |
|
| BLAKE2b-256 | 47f9554834a68b15d332439264c96203469876ead16ad7bd7eed8304ad873696 |
func_adl_xAOD-2.1.3-py3-none-any.whl的哈希值
| 算法 | 哈希摘要 | |
|---|---|---|
| SHA256 | 20dbaf7195c2e154d66bd9795314cb12fa8abd72c8a3be5826fb4edabb917408 |
|
| MD5 | 58517a93d4143c63f997af8ad1ffc319 |
|
| BLAKE2b-256 | 56babc23bbe8e006718dfa3001858dbe5ddb7631cdf9b3a8c9bad26052d16a41 |