cernml4reco/deepjetcore3

DeepJetCore Docker镜像文档

注意事项

由于uproot近期更新，若在最新容器中遇到导入问题，请将import uproot改为import uproot3。

镜像概述

DeepJetCore是一个用于高能物理(HEP)领域深度神经网络训练和评估的工具包。该镜像提供内存外训练、重采样和基本评估等核心功能，适用于处理HEP领域的大规模数据。使用时，用户只需适配两个文件：训练数据结构（描述如何从ROOT树填充numpy数组）和DNN模型本身，两者需在额外的用户包中定义。

引用说明：若使用DeepJetCore或相关容器，请在（内部）文档和报告中提及，并引用zenodo条目：[***]

核心功能与特性

• 内存外训练：支持处理超出内存容量的大规模数据集
• 数据重采样：提供灵活的数据重采样机制
• 基本评估工具：包含ROC曲线绘制等基础评估功能
• 灵活的数据接口：支持从ROOT文件读取数据并转换为训练格式
• 不规则张量支持：部分支持一维不规则张量（ragged tensors）
• 多环境支持：提供Docker/Singularity容器及Conda环境配置

使用场景

• 高能物理实验中的粒子识别、能量重建等任务的深度学习模型训练
• 需要处理大规模ROOT格式数据的神经网络训练
• HEP领域深度学习模型的评估与性能分析

安装与设置

容器构建与使用

每个版本的容器均发布在DockerHub，最新发布版本已标记，latest标签对应开发中的master分支。

镜像拉取

bash
docker pull cernml4reco/deepjetcore3:latest

容器构建（高级用户）

构建分为两阶段：

1. 构建基础容器（包含系统依赖包，需编译ROOT）：

   bash
   cd docker
   docker build -f Dockerfile_base -t cernml4reco/djcbase:py3 .
   

2. 构建DeepJetCore容器（基于基础容器）：

   注意：请使用发布版本，而非开发中的master分支！

CERN用户快速启动

• 有权限访问Cernbox的用户可通过预配置脚本运行：

  bash
  /eos/home-j/jkiesele/singularity/run_deepjetcore3.sh
  

• 若在lxplus7上运行：

  bash
  /eos/home-j/jkiesele/singularity/run_deepjetcore3_lxplus.sh
  

  订阅e-group ml-deepjetcore的用户可获得容器读取权限

Singularity缓存设置

Singularity缓存目录通常位于~/.singularity/cache，可能占用大量空间。建议将缓存设置到/tmp或work afs：

bash
export SINGULARITY_CACHEDIR="/tmp/$(whoami)/singularity"

提示：Singularity有时需要尝试2-3次才能成功拉取容器，容器启动后运行稳定。"缺少用户组"的提示可安全忽略。

环境变量注意事项

• 禁止在bashrc中重置LD_LIBRARY或PYTHONPATH环境变量
• 移除bashrc中的Anaconda路径，避免覆盖容器内的环境变量
• 容器内需要保持干净的环境状态

Conda环境构建（无Docker/Singularity时）

bash
git clone https://github.com/DL4Jets/DeepJetCore.git
cd DeepJetCore
# 创建环境（包含ROOT、tensorflow-gpu、CUDA等，耗时较长）
conda env create -f conda_env.yml  # 若失败，使用conda_env_exact.yml（版本完全固定）
conda activate DJC2
# 设置路径
source docker_env.sh
# 编译模块
cd compiled 
make -f Makefile_conda -j4  # Conda需要 slightly不同的库名称

使用方法

基本工作流程

DeepJetCore是工具集，不提供现成训练代码。需通过createSubpackage.py创建包含示例代码的子包（subpackage）。使用--data选项可生成约150MB的示例数据集。子包创建脚本会输出详细使用说明，以下为基本流程：

1. 设置环境：在子包目录中source环境脚本（env.sh），不要在DeepJetCore目录中执行

2. 定义训练数据结构：

   • 指定从输入ROOT文件读取哪些分支
   • 定义如何组织为DNN输入格式
   • 示例位于subpackage/modules/datastructures

3. 转换ROOT文件为训练格式： 使用convertFromSource.py转换数据，输入为包含ROOT文件列表的文本文件：

   bash
   # 转换训练数据
   convertFromSource.py -i <输入文本文件> -o <训练文件输出目录> -c TrainData_example
   

   TrainData_example为之前定义的数据结构，测试数据将直接从源文件读取

4. 模型训练： convertFromSource.py生成数据文件和描述符（dataCollection.djcdc），将其传入训练脚本：

   bash
   python3 training_example.py /path/to/data/dataCollection.djcdc <模型输出目录>
   

   查看更多选项：python3 training_example.py -h

5. 模型预测： 对测试数据进行预测：

   bash
   predict.py /path/to/the/model.h5 /path/to/the/training/dataCollection.djcdc <测试文件列表文本> <预测输出目录>
   

   注意：预测输出可能较大（示例中不会）

6. 结果评估： 使用DeepJetCore/evaluation/evaluation.py中的工具绘制ROC曲线等，输入为predict.py生成的文本文件

数据流程图示

• 训练流程：!https://github.com/DL4Jets/DeepJetCore/blob/master/training_pipeline.png "训练数据流程"
• 预测流程：!https://github.com/DL4Jets/DeepJetCore/blob/master/predict_pipeline.png "预测数据流程"

TrainData定义与版本升级（从1.X到2.X/3.X）

主要变更

• 数据格式重大变更，1.X版本数据需重新转换
• 接口轻微调整
• master分支已切换到TensorFlow 2.0，可能需要适配子包

TensorFlow 1.X兼容处理

旧子包可在__init__.py中添加以下代码以兼容TensorFlow 2.0：

python
import sys
import tensorflow 
tensorflow.compat.v1.disable_eager_execution()
sys.modules["tensorflow"]=tensorflow.compat.v1

TrainData类接口

TrainData类已大幅简化，仅需定义以下接口函数（其他函数已弃用）：

1. createWeighterObjects(self, allsourcefiles)（可选）

   • 用途：创建依赖整个数据集的字典对象（如归一化参数）
   • 返回：权重对象字典

2. **convertFromSourceFile(self, filename, weighterobjects, istraining, kwargs)（必需）

   • 用途：定义从一个源文件转换为一个输出文件的规则
   • 输入：源文件名、权重对象、是否为训练数据
   • 返回：三个列表（特征数组列表、真值数组列表、权重数组列表，权重数组列表可为空）

3. writeOutPrediction(self, predicted, features, truth, weights, outfilename, inputfile)（必需）

   • 用途：定义网络输出如何写入输出格式（如ROOT树）
   • 输入：预测结果、特征、真值、权重、输出文件名、输入源文件名
   • 返回：无

权重功能迁移

内置权重功能需在用户代码中重新实现（在createWeighterObjects中），旧实现参考：https://github.com/DL4Jets/DeepJetCore/blob/1.X/TrainData.py#L657-L672

不规则张量（Ragged Tensors）

部分支持一维不规则张量（第一维度不规则），适用于每个事件输入数量不同但特征长度固定的场景。

使用方法

1. convertFromSourceFile需返回DeepJetCore.SimpleArray对象列表（而非numpy数组列表）
2. SimpleArray由两个numpy数组构造：
   • 行分割数组（row splits，int类型，与TensorFlow不规则数组格式相同）
   • 数据数组（0维和1维展平）
3. 构造方式：createFromNumpy(data, row_splits)

训练时处理

模型将接收张量列表，第一个为数据，第二个为行分割，真值处理方式相同，以规避Keras对不规则张量的支持限制。

直接使用数据管道

可绕过training_base类直接使用数据管道，示例代码：

python
from DeepJetCore.DataCollection import DataCollection
train_data = DataCollection("path/to/your/dataCollection.dc")

# 从训练数据中拆分10%作为验证数据
val_data = train_data.split(0.9) 

# 设置批大小
# 若数据在维度1不规则，批大小为每批最大元素数
# 例如：批大小100时，50+48个元素的两个样本会组成一批（共98个元素）
train_data.setBatchSize(100) 

# 准备生成器
gen = train_data.invokeGenerator()

#  epoch循环
for epoch in range(num_epochs):
    gen.shuffleFilelist()
    gen.prepareNextEpoch()
    
    # 不规则数据时，批次数可能因epoch而异
    nbatches = gen.getNBatches()
    generator = gen.feedNumpyData()
    
    for b in range(nbatches):
        if gen.isEmpty():
            raise Exception("数据耗尽（可能文件损坏）") 
        
        # 权重可选，每个均为numpy数组列表
        features_list, truth_list, weight_list = next(generator)
        
        # 训练代码

开发者指南

开发建议：

1. 创建并运行容器
2. 将路径重定向到开发目录，通过sourc docker_env.sh设置环境
3. 在compiled目录编译包：

   bash
   cd compiled
   make -j5