跳转到主要内容

用于访问ATLAS xAOD文件的函数分析描述语言后端。

项目描述

func_adl_xAOD

qastle 转换为在ATLAS xAOD后端上运行的后端。

GitHub Actions Status Code Coverage

PyPI version Supported Python versions

简介

这允许您查询以ATLAS xAOD格式编写的root文件中存储的分层数据。此代码允许您查询这些数据。

功能

以下是支持 xAOD C++翻译器的部分功能的简要列表。

Python

支持许多但并非所有Python语言的部分。一般来说,任何是语句或流程控制的都不是支持的。例如,没有 ifwhilefor 语句。赋值不受支持,这听起来可能很有限 - 但这是一个功能实现,所以比人们想象的要少。

以下是一些支持的语言部分

  • 函数调用、方法调用、属性引用和lambda调用(以及lambda函数),有一些限制。
  • 数组中的整数索引
  • 有限的元组支持,作为收集信息或作为输出到ROOT文件的方式。
  • 有限的列表支持(与上面相同)。特别是,不支持的 append 方法,因为它修改了列表而不是创建一个新的列表。
  • 一元、二元和比较操作。仅支持两个参数的比较(例如 a > b 而不是 a > b > c)。
  • 使用 andor 来组合条件表达式。注意,当编写表达式时,它被写作 &|,因为 python 要求 andor 返回 bool 类型。
  • 条件 if 表达式 (10 if a > 10 else 20)
  • 浮点数、整数和字符串。

xAOD 函数

只要所需的参数是基本类型,就可以调用由 C++ 对象支持的函数。以下列出了附加到 ATLAS xAOD 数据模型中各种对象的特殊 额外 函数。

事件

事件对象具有以下特殊函数以访问集合

  • JetsTracksEventInfoTruthParticlesElectronsMuonsMissingET。每个函数接受一个参数,即 xAOD 中的银行名称。例如,对于电子,可以传递 "Electrons"

添加新集合相当简单。

喷射对象

模板函数在 python 中还不适用。

  • getAttribute - 此函数是模板化的,因此必须以 getAttributeFloatgetAttributeVectorFloat 的形式调用。

数学

  • 数学运算符:+、-、*、/、%,**
  • 比较运算符:<、<=、>、>=、==、!=
  • 一元运算符:+、-、not
  • 数学函数来自 C++ cmathsincostanacosasinatanatan2sinhcoshtanhasinhacoshatanhexpldexploglnlog10exp2expm1ilogblog1plog2scalbnscalblnpowsqrtcbrthypoterferfctgammalgammaceilfloorfmodtruncroundrintnearbyintremainderremquocopysignnannextafternexttowardfdimfmaxfminfabsabsfma
  • 不要在调用中使用 math.sin。然而,sin 是可以接受的。如果你这样做,你将在解析期间遇到一个异常,它不知道如何翻译 math
  • 对于像 summinmax 等东西,请使用 SumMinMax 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 TrueFalse

对于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 TrueFalse
element_pointer 指示元素类型是否为指针 TrueFalse

针对 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 TrueFalse
element_pointer 指示元素类型是否为指针 TrueFalse

代码块

代码块提供了一种将各种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节点,则树名和文件名来自该表达式。只有Python tuples序列或单个项可以被AsROOTTTree理解。
  • 如果Select序列的最后一个func_adl表达式是intdouble,则将生成一个名为xaod_output.root的文件,它将包含一个名为atlas_xaod_tree的单列TTree,列名为col1
  • 如果最后一个func_adl表达式是tupleSelect序列,则将生成一个名为xaod_output.root的文件,它将包含一个名为atlas_xaod_treeTTree,具有名为col1col2等的列。
  • 如果最后一个func_adl表达式是字典的Select序列,则将生成一个名为xaod_output.root的文件,它将包含一个名为atlas_xaod_treeTTree,列名来自字典键。

ServiceX(以及servicex前端包)可以将从ROOT转换为其他格式,如pandas.DataFrameawkward数组。

测试和开发

设置开发环境

  • 创建虚拟环境后,执行本地设置: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.73.83.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卷来缓存校准文件等。如果您需要一个真正的全新开始,您需要首先删除卷。

项目详情


发布历史 发布通知 | RSS源

下载文件

下载适用于您平台的文件。如果您不确定选择哪个,请了解有关安装包的更多信息。

源分布

func_adl_xAOD-2.1.3.tar.gz (64.1 kB 查看哈希值)

上传时间

构建分布

func_adl_xAOD-2.1.3-py3-none-any.whl (72.3 kB 查看哈希值)

上传时间 Python 3

由以下提供支持