用于访问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
、Max
LINQ 谓词。
元数据
可以将元数据注入到 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 |