分析产出

学习目标

理解使用 Analysis Productions 的必要性
浏览一些已有的产出示例
自行创建并提交一个产出

在本地运行 DaVinci 对于测试选项文件很方便，但若要为完整分析生成全部 ROOT ntuples，则几乎不可行。过去，人们通常把作业提交到网格：将大量 DaVinci 作业发送到批处理计算资源（某些场景下这仍然有用------参见旧的 Run 1/2 课程了解具体做法）。然而，这种方式仍存在以下缺点：

对于大数据集，需要长时间手动监控网格作业；
如果多个分析独立地产生相似的 ntuples，会浪费计算资源；
Ntuples 可能丢失，或在分析人员离开后被人为删除，影响分析的可追溯性。

Analysis Productions 的目标正是把造 ntuples 的过程中心化、自动化，并记录数据集的生成方式。在 Run 3 中，这是官方推荐的生成分析 ntuples 的方法。

监控产出

在具体讲解如何操作之前，我们先来看一个真实产出的最终结果。打开 Analysis Productions 网页，进入 Productions 页面。右侧会出现一个新的菜单，列出所有已存在的productions。利用右侧搜索栏，可以查找任何感兴趣的production，例如输入bs2dsk_run3。此时应返回一条结果，点击它即可展示该production下的所有作业表。

表中每一行对应该production的一个作业，显示以下信息： - 作业状态（如 READY、ACTIVE） - 作业名称（如 bs2dspi_2024data_down） - 下一次 housekeeping 检查的时间、创建时间、最后更新时间 - 所对应的Analysis Productions仓库版本、production ID 与 sample IDs

如需查看某个作业的更多详情，只需点击该行，即可跳转到作业摘要页面。下图即为该页面展示的作业元数据。

An AP job summary

这部分内容展示了重要信息的摘要，例如作业状态、其产出版本、输出文件所需的总存储空间以及用于提交产出的合并请求。若要查看用于设置产出的输入脚本，可点击合并请求的链接。

下一幅图展示了产出输出位置的列表方式。可以使用 PFN（物理文件名称）或 LFN（逻辑文件名称）来访问输出，所有能够访问 CVMFS（ CERN 虚拟文件系统）的系统都应能识别 PFN。

An AP job output

现在，让我们尝试通过以下命令访问其中一个文件：

root -l root://eoslhcb.cern.ch//eos/lhcb/grid/prod/lhcb/anaprod/lhcb/LHCb/Collision24/DATA.ROOT/00228025/0000/00228025_00000001_1.data.root

在 ROOT 中，你可以通过执行TBrowser b（或其他你选择的方法）来浏览这个文件。

创建自己的产出

为了练习，我们现在将逐步创建一个简单的产出。有关更高级用法的详细信息，请参阅《分析产出文档》

首先创建一个工作文件夹，然后将分析产出仓库克隆到该文件夹中：

git clone ssh://git@gitlab.cern.ch:7999/lhcb-datapkg/AnalysisProductions.git
cd AnalysisProductions

在修改任何文件前，先为你本次练习创建并切换到新分支：

git checkout -b ${USER}/starterkit-practice

现在，我们需要创建一个文件夹来存储为新产出添加的所有内容。对于这个练习产出，我们将延续前几节课中使用的衰变过程 \( B^+ \to (J/\psi \to \mu^+ \mu^-) K^+ \) ，因此应该给文件夹起一个合适的名称：

mkdir starterkit

进入这个新目录（cd starterkit），然后开始添加我们需要的文件。首先是 DaVincim选项文件。如果你有前几节课中创建的可正常运行的选项文件，将其复制到这里，并用你选择的文本编辑器打开。

如果没有之前的选项文件，或者遇到问题，可以使用这个选项文件。

接下来需要的是一个.yaml文件，用于配置作业。创建一个名为info.yaml的新文件，并添加以下内容：

defaults:
  application: DaVinci/v65r0
  output: DATA.ROOT
  options:
    entrypoint: starterkit.dv_basic:main
    extra_options:
      input_type: ROOT 
      input_raw_format: 0.5
      simulation: false
      input_process: "TurboPass"
      geometry_version: run3/2024.Q1.2-v00.00
      conditions_version: master
      lumi: true
      data_type: "Upgrade"
      input_stream: b2cc
  inform:
    - cernusername
  wg: B2CC

Bu2JpsiK_24c4_MagDown:
  input:
    bk_query: "/LHCb/Collision24/Beam6800GeV-VeloClosed-MagDown/Real Data/Sprucing24c4/94000000/B2CC.DST"

此处，无缩进的行为作业名称（ defaults 行具有特殊含义），缩进的行则是施加于对应作业的选项。用该文件将生成一个名为 Bu2JpsiK_24c4_MagDown 的作业，它会读取给定 bookkeeping 路径的数据。所有置于 defaults 下的选项会自动应用于其余所有作业------这一机制可避免重复配置。本例所用选项均来自 Run 3 DaVinci 课程：

application：所用 DaVinci 版本。此处选 v65r0 ；可在此处查阅可用版本。
wg：所属工作组。因涉及 \( B^+ \to (J/\psi \to \mu^+ \mu^-) K^+ \) 衰变，设其为B2CC。
inform：可选填邮箱地址，用于接收作业状态通知。
options：运行 DaVinci 时的配置，直接沿用 Run 3 DaVinci 课程中的设置。
output：输出 .root ntuple 文件名，生成后会被注册到 Bookkeeping。
input：待处理数据的 Bookkeeping 路径，该路径在 Bookkeeping lesson中已确定，且仅适用于 24c4 磁向下数据，因此不应放在defaults下。

如需查看全部可用选项及其允许值，请参阅官方文档。

添加磁场向上作业

当前配置仅生成 24c4 磁向下数据 ntuple。请尝试在info.yaml中补充，使其同时生成 24c4 磁向上数据的作业。提示：正确的.DST文件路径可通过 bookkeeping 工具查找。

示例

由于我们已使用defaults作业模板，新增作业只需极少量改动：复制最后3行，重命名为 Bu2JpsiK_24c4_MagUp，并填入对应的 bookkeeping 路径即可，示例 YAML 文件可在此下载。

为便于他人理解，最后应编写README.md一份用 Markdown 撰写的可读文档，用于说明该 production 的关键信息。若不知如何下笔，可参考现有 productions 的README获取灵感。

本地测试

至此我们已拥有所需全部文件，接下来应在本地验证 production 是否正确运行。所有测试均通过lb-ap命令完成。

请先返回仓库根目录（AnalysisProductions），然后执行：

Usage: lb-ap [OPTIONS] COMMAND [ARGS]...

  Command line tool for the LHCb AnalysisProductions

Options:
  --version
  --help     Show this message and exit.

Commands:
  login        Login to the Analysis Productions API
  versions     List the available tags of the Analysis Productions...
  clone        Clone the AnalysisProductions repository and do lb-ap...
  checkout     Clean out the current copy of the specified production and...
  list         List the available production folders by running 'lb-ap list'
  list-checks  List the checks for a specific production by running lb-ap...
  render       Render the info.yaml for a given production
  validate     Validate the configuration for a given production
  test         Execute a job locally
  check        Run checks for a production
  ci-checks    Helper function for running checks in the CI.
  debug        Start an interactive session inside the job's environment
  reproduce    Reproduce an existing online test locally
  parse-log    Read a Gaudi log file and extract information

lb-ap这个命令能让我们执行多种不同的测试。我们先从lb-ap list开始，它会显示所有的产出。希望你能在这个列表中看到自己新建的产出（starterkit）！你也可以用它来列出特定产出中的所有作业，只需运行lb-ap list starterkit即可。如果你之前为磁铁向上的情况添加了第二个作业，这个命令的输出应该如下所示：

The available jobs for starterkit are: 
* Bu2JpsiK_24c4_MagDown
* Bu2JpsiK_24c4_MagUp

最重要的测试是验证产出是否能成功运行并生成所需的 nutuple 。lb-ap命令也可用于此目的。要测试磁场向下的作业，请运行以下命令：

lb-ap test starterkit Bu2JpsiK_24c4_MagDown

在会话中首次运行此命令时，请记住使用lhcb-proxy-init激活代理。作为额外的安全步骤，系统还会提示你登录 CERN 单点登录（Single Sign-On）。

此时，DaVinci 将使用你在info.yaml中指定的数据和选项文件运行。你应该会看到 DaVinci 的输出，与之前手动运行时看到的类似，随后会出现一条完成消息，告知你测试生成的输出文件的位置。

你会发现系统创建了一个local-tests目录，其中记录了所有已运行的本地测试。导航到output文件夹，检查生成的文件。其中包括各种日志文件，以及一个类似00012345_00006789_1.DATA.ROOT的.ROOT文件。

让我们打开这个.root文件，检查一切是否正常。与之前的操作类似，运行root -l 00012345_00006789_1.DATA.ROOT，在加载该 ntuple 的情况下打开 ROOT ，然后通过运行TBrowser b（或其他方式）查看内容。花点时间浏览一下，确保所有内容都正常。

有用的资源

如果在创建实际产出时遇到问题，以下是一些寻求帮助的好地方：

对于选项文件相关问题，可尝试 DaVinci Mattermost channel 或 lhcb-davinci mailing list。

对于info.yaml文件相关问题，或与分析产出框架有关的任何其他问题，可尝试 Analysis Productions Mattermost channel ，或联系分析产出协调员（点击此处查看具体人员）。

创建合并请求

既然我们已经测试了所有更改，并确保一切按预期工作，就可以通过创建合并请求（merge request）将其提交到主仓库。首先提交更改：

git add dv_basic.py info.yaml README.md
git commit -m "Add starterkit example production"

然后通过以下命令推送更改：

git push origin ${USER}/starterkit-practice

完成后，系统会提供一个链接，用于为你的新分支创建合并请求。在浏览器中打开该链接，并为其指定合适的名称和描述。

Warning

如果按照本教程操作，请在你的合并请求上添加Starterkit (not for merge)标签！对于实际产出，请确保遵循合并请求描述模板中的说明。然后你就可以提交合并请求了。

由于这只是练习，你的请求实际上不会被合并，但仍会自动运行一些测试。要查看这些测试，请进入合并请求的"Pipelines" 标签，点击流水线编号（例如 "#1958388" ）打开它。在底部，你会看到一个test作业 - 点击它，会显示测试作业的输出。这些测试需要一些时间才能完成，因此可能仍在进行中。前几行内容应类似于:

Running with gitlab_runner_api 0.1.dev42+g457dbd5
INFO:Creating new pipeline for ID 1958388
ALWAYS:Results will be available at https://lhcb-analysis-productions.web.cern.ch/1958388/

你可以在浏览器中打开该链接查看测试作业的状态（示例见此处）。几分钟后，测试应已完成 - 如果一切顺利，你现在已经成功准备好你的第一个产出了！

分析产出数据

我们创建了一个独立的 Python 包APD，可用于帮助你访问分析产出的输出。在作业输出页面的底部，你可以找到使用它的示例。对于这个入门套件示例，我们可以这样做：

from apd import AnalysisData
datasets = AnalysisData("dpa", "starterkit")
bu2jpsik_24c4_magdown = datasets(name="bu2jpsik_24c4_magdown")

这将创建bu2jpsik_24c4_magdown，作为该作业输出的所有 PFN 的列表。然后，你可以使用你偏好的基于 Python 的 ROOT 来访问这些文件。

实际产出的后续步骤

如前所述，本课程中的测试产出不会被合并，因为这只是练习。如果这是一个实际产出，在合并之前还需要采取一些额外步骤。

你应该尝试联系其他可能也想使用这些 ntuple 的人，看看他们是否想添加或修改某些内容。这通常通过你的工作组进行（要么通过电子邮件，要么对于新产出，在工作组会议上进行展示）。为此，你可以先联系你的工作组召集人（点击此处查看具体人员）。

此外，分析产出协调员可能也会对你的添加 / 更改提供一些反馈。