A Practical Setup and Workflow Document

INFN Roma Internal Note - Version 1.0 - 1 June 2025

Authors: Alessandro Bartoloni and Mustafa Mohammad Rafiei

Affiliations: INFN Roma I

Last Updated: — Mustafa Mohammad Rafiei 2025/06/18 12:19

This guide explains the process of extracting and processing AMS-02 data using ROOT, the NAIA framework, and HTCondor. First, having CERN and CNAF accounts is essential, and connecting to the "ui-ams" server is required. The initial setup includes creating SSH keys for secure remote access.

After preparing accounts, AlmaLinux 9.5 is installed as the recommended operating system. Then, Visual Studio Code (VS Code) is installed for code development, and the Remote - SSH extension is configured to connect to "ui-ams."

Once VS Code is set up, the NAIA library is installed on the CNAF server or a local machine. Projects using NAIA require configuring the CMakeLists.txt file, and directory structures are defined for organization. The NSL library is then installed, and the usage of both libraries within a project is explained.

Next, relevant C++ code is written, compiled, and executed. To enable parallel processing for ROOT data, HTCondor is configured, and necessary ".bashrc" and ".bash_profile" settings are applied on "ui-ams."

A list of ROOT data files is prepared, and a "run.sh" script is written for execution. Job files (.sub) are created for each data file and submitted to HTCondor for parallel processing. Any held jobs can be resubmitted.

After processing, output ".root" files are merged. A similar procedure is followed for Monte Carlo simulation data, where directory structures are set, file lists are created, and job submission occurs.

Monte Carlo jobs are submitted in parallel within HTCondor, and if needed, resubmissions are performed. Finally, the processed output ".root" files are merged.

This guide covers all essential steps for efficiently and systematically executing AMS-02 data analysis, ensuring an organized workflow from setup to final processing.

To access AMS computing resources, you must first request valid CNAF and CERN accounts. Please note that approval may take some time.

Once your accounts are approved and you receive your username and password, you can connect to CNAF services.

The ui-ams machine is a virtual machine hosted on a physical server known as the bastion.

To access ui-ams, you must first log in to the bastion server.

Steps:

Open a terminal and connect to the bastion:

  ssh UserName@bastion.cnaf.infn.it

After logging in, connect to the virtual machine:

  ssh UserName@ui-ams

Note: bastion.cnaf.infn.it is a real server, ui-ams is a virtual machine running on the bastion.

1.3 Creating SSH Keys for Passwordless Access This step is optional but highly recommended for avoiding repeated password entry.

  sudo dnf install openssh-clients -y

On AlmaLinux, this package is usually already installed.

Recommended (modern and secure):

  ssh-keygen -t ed25519 -C "your_email@example.com"

Alternative (if required for compatibility):

  ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

You can leave the passphrase empty or enter one for added security.

  ssh-copy-id username@bastion.cnaf.infn.it

If this fails, use the manual method below.

Manual Method (only if ssh-copy-id fails): Connect to the bastion:

  ssh username@bastion.cnaf.infn.it

On the server:

  mkdir -p ~/.ssh
  nano ~/.ssh/authorized_keys

On your local machine, open your public key file (~/.ssh/id_ed25519.pub or .id_rsa.pub) and copy its contents.

Paste the key into the authorized_keys file on the server.

Set proper permissions:

  chmod 700 ~/.ssh
  chmod 600 ~/.ssh/authorized_keys

Use ProxyJump to transfer your public key to the virtual machine:

  ssh-copy-id -o ProxyJump=UserName@bastion.cnaf.infn.it username@ui-ams

Edit your SSH config file:

  nano ~/.ssh/config

Add the following:

Host bastion
HostName bastion.cnaf.infn.it
User UserName

Host ui-ams
HostName ui-ams
User UserName
ProxyJump UserName@bastion.cnaf.infn.it
IdentityFile ~/.ssh/id_rsa

Now you can simply connect with:

  ssh ui-ams

If your system requires RSA for compatibility:

Generate RSA key pair:

  ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

Use the same ssh-copy-id steps to transfer the key to both servers. Your existing SSH config works the same way. If you want to specify the RSA key explicitly: Host ui-ams

  HostName ui-ams
  User UserName
  ProxyJump bastion
  IdentityFile ~/.ssh/id_rsa

Test the connection:

  ssh ui-ams

AlmaLinux 9.5 is the recommended OS for local development of NAIA/NSL‑based C++ analysis. You can either run it in a VM on top of Windows or install it alongside Windows (dual‑boot). Dual‑boot is preferred for full native performance.

2.1 Download the AlmaLinux 9.5 ISO - Official ISO & Cloud Images: → https://almalinux.org/get-almalinux/

- Installation Guide (step‑by‑step with screenshots): → https://wiki.almalinux.org/documentation/installation-guide.html

2.2 Installation Methods

- Virtual Machine (No disk repartitioning required)

recommended VM platforms:

1. Oracle VirtualBox → https://www.virtualbox.org/wiki/Downloads
2. VMware Workstation → https://www.vmware.com/products/workstation-pro.html

Example tutorial: “AlmaLinux 9.5 Installation on VirtualBox” → https://www.servermania.com/kb/articles/how-to-install-almalinux-in-virtualbox/

- Dual‑Boot with Windows (Full native performance, ideal for compiling/testing C++ code against ROOT, NAIA, NSL)

General dual‑boot tutorial: “How to Dual‑Boot Linux and Windows” → https://itsfoss.com/dual-boot-linux-windows-guide/

2.3 Quick Installation Steps

1. Create bootable USB with Rufus (Windows) or `dd` (Linux/macOS).
2. Boot from USB, choose “Install AlmaLinux 9.5.”
3. Partition disk: create or resize Windows partition, then allocate space for AlmaLinux.
4. Select software: include “Development Tools” group to get compilers/CMake.
5. Set hostname, user account, and firewall rules as needed.
6. Reboot and choose AlmaLinux or Windows at GRUB menu.

Note: Even though most heavy analysis runs on CNAF servers, having a local AlmaLinux 9.5 environment lets you quickly build and test your C++ code (with 1–2 ROOT input files) before scaling up to batch jobs on HTCondor.

Visual Studio Code (VS Code) is a lightweight yet powerful source-code editor developed by Microsoft. Known for its speed, extensibility, and robust feature set, it is widely used by developers. Note: VS Code also has versions for Windows and macOS.

Follow these steps to install Visual Studio Code (VS Code) on AlmaLinux 9.5:

Before installing, update your system to ensure it has the latest packages:

  sudo dnf update -y

To ensure the authenticity of the packages, import the Microsoft GPG key:

  sudo rpm --import https://packages.microsoft.com/keys/microsoft.asc

Create a repository file for VS Code:

  printf "[vscode]\nname=packages.microsoft.com\nbaseurl=https://packages.microsoft.com/yumrepos/vscode/\nenabled=1\ngpgcheck=1\nrepo_gpgcheck=1\ngpgkey=https://packages.microsoft.com/keys/microsoft.asc\nmetadata_expire=1h" | sudo tee -a /etc/yum.repos.d/vscode.repo

Now, install Visual Studio Code using the following command:

  sudo dnf install code -y

Once the installation is complete, you can launch Visual Studio Code by typing:

  code

Alternatively, you can open it via the graphical user interface (GUI).

To keep VS Code up to date, use the following command:

  sudo dnf update code -y

Alternatively, check for updates within the VS Code interface.

If you need to remove Visual Studio Code, use the following command:

  sudo dnf remove code -y

You can also delete the repository file by running:

  sudo rm -f /etc/yum.repos.d/vscode.repo

Note: Ensure you have internet access for these steps. If you're working offline, you can manually download the RPM package and install it. If you encounter issues like missing dependencies (e.g., `libffmpeg.so`), you may need to install additional libraries or use Flatpak/Snap.

Now that you've set up your SSH keys and configured access to `ui-ams` via the intermediate server (`bastion.cnaf.infn.it`), follow these steps to configure Visual Studio Code (VS Code) to connect to `ui-ams` via SSH.

Make sure you've already completed the SSH key generation and configuration for connecting to `ui-ams`.

If you haven't already, install Visual Studio Code on your AlmaLinux 9.5 machine.

To enable remote access via SSH, you'll need the "Remote - SSH" extension. Follow these steps:

- Open Visual Studio Code.

- Go to the Extensions view by pressing Ctrl+Shift+X or clicking the Extensions icon on the sidebar.

- Search for "Remote - SSH" (developed by Microsoft).

- Click Install to add the extension to VS Code.

Explanation: The Remote - SSH extension allows you to connect to remote servers via SSH, edit files, run terminal commands, and debug remotely as if the server were local.

VS Code's Remote - SSH extension uses your existing SSH configuration (`~/.ssh/config`) to connect to remote hosts.

Ensure your SSH config is correctly set up with the ProxyJump directive for `bastion.cnaf.infn.it`.

To initiate the connection:

- Click the green Remote-SSH button located in the bottom-left corner of VS Code (or press Ctrl+Shift+P and search for "Remote-SSH: Connect to Host").

- From the list of hosts, select ui-ams.

Explanation: The Remote - SSH extension reads the `~/.ssh/config` file and automatically routes the connection through `bastion.cnaf.infn.it` using the ProxyJump configuration.

On your first connection attempt, VS Code may ask you to enter the passphrase for your SSH key (if you set one). After authenticating, VS Code will establish the connection to `ui-ams`.

You may also be prompted to verify the server's fingerprint for security purposes. Type yes to continue.

Explanation: Since you’ve already copied your SSH public key to both servers, the connection should be passwordless unless you set a passphrase for your SSH key.

During the first connection, VS Code will automatically install a lightweight server component on `ui-ams`. Once installed, you'll be able to interact with `ui-ams` as if it were a local machine.

Explanation: The server component allows you to edit files, use the terminal, and install extensions on `ui-ams`.

After connecting, you can start working on `ui-ams`:

- Open Files/Folders: Use the File Explorer in VS Code to open a directory on `ui-ams` (e.g., `/home/your_username/myproject`).

- Use the Terminal: Open the integrated terminal (Ctrl+`) to run commands directly on `ui-ams`.

- Install Extensions Remotely: Install extensions (e.g., C++, Python, GitHub Copilot) on `ui-ams` to enhance your development workflow.

Explanation: Once connected, VS Code treats `ui-ams` as if it were a local machine. You can edit, run, and debug files directly on the remote server.

To ensure everything is set up correctly, try opening a file or running a command in the terminal (e.g., `pwd` should return `/home/your_username` on `ui-ams`).

Explanation: This confirms that VS Code is properly connected to `ui-ams`, and you're ready to work remotely. z

last edit — Alessandro Bartoloni 2025/05/31

For official instructions, refer to the NAIA documentation:

https://naia-readthedocs.readthedocs.io/en/1.2.0/build-install.html

To build and use NAIA locally, your system must meet the following requirements:

• A C++ compiler with full C++17 support (tested with GCC ≥ 12.1.0)
• CMake version ≥ 3.13
• ROOT built with C++17 support (tested with ROOT ≥ 6.28/04)

Supported platforms: CentOS7 and RHEL9 derivatives (e.g., AlmaLinux 9, Rocky Linux 9)

If your machine has access to CVMFS, you can use precompiled NAIA versions and required dependencies located at:

• `/cvmfs/ams.cern.ch/Offline/amsitaly/public/install/x86_64-centos7-gcc12.1/naia`
• `/cvmfs/ams.cern.ch/Offline/amsitaly/public/install/x86_64-el9-gcc12.1/naia`

Each version includes a ready-to-use environment setup script, e.g., for CentOS7:

  /cvmfs/ams.cern.ch/Offline/amsitaly/public/install/x86_64-centos7-gcc12.1/naia/v1.1.0/setenvs/setenv_gcc6.28_cc7.sh

Note: These requirements are only necessary if installing NAIA on a local machine. All dependencies are already pre-installed on CNAF (ui-ams).

Follow the steps below to build and install NAIA from source.

Choose one of the following methods (a CERN account is required):

  git clone --recursive https://username@gitlab.cern.ch:443/ams-italy/naia.git -b v1.2.0  #Kerberos
  git clone --recursive ssh://git@gitlab.cern.ch:7999/ams-italy/naia.git -b v1.2.0 #SSH
  git clone --recursive https://gitlab.cern.ch/ams-italy/naia.git -b v1.2.0 #HTTPS

*Note:* check for the latest version of NAIA , version 1.2.0 is used in the above command

Use the command

  mkdir ~/NAIA_library/naia.build ~/NAIA_library/naia.install

Assume your project structure is as follows:

  ~/NAIA_library/ ├── naia/ # Source directory (from git clone)
                  ├── naia.build/ # Build directory 
                  └── naia.install/ # Target installation directory==== III) Build and Install NAIA ====

Run the following commands:

  cd ~/NAIA_library/naia.build
  cmake ../naia -DCMAKE_INSTALL_PREFIX=../naia.install
  make all install

Edit your shell configuration files:

Open your .bashrc:

  nano ~/.bashrc

Add the following line at the end (replace <your_username> with your CNAF username):

  source /storage/gpfs_ams/ams/users/abartoloni/NAIA_library/naia/setenvs/setenv_gcc6.28_el9.sh

The setenv_gcc6.28_el9.sh script is located in the setenvs folder inside the NAIA source directory you cloned earlier.

Save and exit

Apply the changes:

  source ~/.bashrc

Repeat the process for .bash_profile:

  nano ~/.bash_profile

Add the same line:

  source /storage/gpfs_ams/ams/users/abartoloni/NAIA_library/naia/setenvs/setenv_gcc6.28_el9.sh

Then:

  source ~/.bash_profile

last edit — Alessandro Bartoloni 2025/05/31

To use NAIA ntuples in your C++ project, you need to include:

Header files located in:

  naia.install/include

Libraries located in:

  naia.install/lib/libNAIAUtility.so  
  naia.install/lib/libNAIAContainers.so  
  naia.install/lib/libNAIAChain.so

The recommended approach for integrating NAIA into your project is by using CMake.

To use the NAIA library in your project, it is recommended to use CMake, a flexible and powerful build system.

NAIA provides CMake configuration files that simplify the integration process by automatically handling include paths and library linking.

The following example sets up a basic C++ project that:

• Requires CMake version 3.10 or higher.
• Uses the C++17 standard.
• Depends on NAIA version 1.2.0 or newer.
• Builds an executable named main from the source file src/main.cpp.
• Links the executable with the NAIA::NAIAChain component of the NAIA library.

Below is a sample CMakeLists.txt file with inline comments explaining each step:

  
  # Specify the minimum required version of CMake to build the project
  cmake_minimum_required(VERSION 3.10)
   
  # Define the name of the project
  project(MyNAIAProject)
   
  # Set the C++ standard to C++17 (required by NAIA)
  set(CMAKE_CXX_STANDARD 17)
   
  # Find the NAIA library version 1.2.0 or higher; this is required to build the project
  find_package(NAIA 1.2.0 REQUIRED)
   
  # Define an executable named 'main' using the source file src/main.cpp
  add_executable(main src/main.cpp)
   
  # Link the 'main' executable with the NAIAChain component of NAIA
  # This makes NAIA functionality available in your code
  target_link_libraries(main PUBLIC NAIA::NAIAChain)

Assume the following structure for your project:

  ~/Project_one/
  ├── build/           # Directory where you build the project
  ├── src/             # Contains your C++ source files (e.g., main.cpp)
  └── CMakeLists.txt   # Your build configuration file

To compile and run the project:

a) Navigate to the build directory:

  cd ~/Project_one/build

b) Run CMake, pointing it to the NAIA installation:

  cmake .. -DNAIA_DIR=~/NAIA_library/naia.install/cmake

c) Build the executable:

 make

d) Run the compiled program:

 ./main input.root output.root

Note on running on CNAF computing facility: Running this on the ui-ams machine is acceptable for testing a small number of .root files. Avoid performing large-scale data analysis directly on ui-ams—it may lead to system crashes. For large jobs, please use HTCondor, as described in the following sections.

last edit — Alessandro Bartoloni 2025/05/31

The NAIA Selection Library(NSL) is a companion library developed specifically for use with the NAIA framework. While NAIA handles structured access to AMS ntuples and datasets, NSL provides a growing collection of utility functions and tools designed to simplify selection logic and analysis workflows.

Many functions in NSL significantly reduce code complexity and improve readability, allowing you to write cleaner, more maintainable analysis code. If you're working on an AMS project using NAIA, incorporating NSL can greatly enhance both development speed and clarity.

✅ Note: If you are working in an environment where NAIA is already installed and configured, you should be ready to go.

The requirements for installing NSL are largely the same as for NAIA:

• A C++ compiler with full C++17 support (tested with GCC ≥ 9.3.0)
• CMake version ≥ 3.13
• A ROOT installation compiled with C++17 support (tested with ROOT ≥ 6.22/08, recommended ≥ 6.26/02)

Follow these steps to build and install NSL:

I) Clone the NSL repository:

  git clone https://<username>@gitlab.cern.ch:443/ams-italy/nsl.git  # (Kerberos)
  git clone ssh://git@gitlab.cern.ch:7999/ams-italy/nsl.git           # (SSH)
  git clone https://gitlab.cern.ch/ams-italy/nsl.git                  # (HTTPS)

⚠️ Note: You need a valid CERN account to access the repository.

II) Create build and install directories:

  mkdir nsl.build nsl.install

Assume the following directory structure:

  $ Home/NSL_library/nsl           # NSL source directory
  $ Home/NSL_library/nsl.build     # Build directory
  $ Home/NSL_library/nsl.install   # Installation directory

III) Build and install NSL:

Before starting, ensure the NAIADIR environment variable is set properly.

  cd Home/NSL_library/nsl.build
  cmake ../nsl -DCMAKE_INSTALL_PREFIX=../nsl.install
  make all install

🧠 Tip: You can also add the NSL environment setup script to your .bashrc or .bash_profile to make it persistent across sessions (similar to NAIA).

last edit — Alessandro Bartoloni 2025/06/03

To develop a C++ project based on NAIA and NSL, you need to include both libraries properly.

Specifically, your project should have access to:

• The NSL headers located in nsl.install/include
• The NSL shared library: nsl.install/lib/libNSLSelections.so

Like NAIA, NSL exports a CMake target called NSL::NSLSelections, which should be linked in your project.

Important: Since NSL is an extension of NAIA, your project must fulfill all prerequisites for both libraries.

Here is a basic CMake configuration for a project that uses both NAIA and NSL:

 # Specify the minimum required version of CMake to build the project
cmake_minimum_required(VERSION 3.10)
 
# Define the name of the project
project(MyNAIAProject)
 
# Set the C++ standard to C++17 (required by NAIA)
set(CMAKE_CXX_STANDARD 17)
 
# Find the NAIA library version 1.2.0 or higher and NSL library; 
# this is required to build the project
find_package(NAIA 1.2.0 REQUIRED)
find_package(NSL REQUIRED)
 
# Define an executable named 'main' using the source file src/main.cpp
add_executable(main src/main.cpp)
 
# Link the 'main' executable with the NAIAChain component of NAIA and with 
# NSLSelections component of NSL 
# This makes NAIA and NSL functionality available in your code
target_link_libraries(main PUBLIC NAIA::NAIAChain NSL::NSLSelections)

Assume the following directory organization:

  Home/
  └── Project_two/
      ├── build/         # Build directory
      ├── src/           # Contains your main.cpp
      └── CMakeLists.txt # At the root of the project

Place your source file (e.g., main.cpp) inside the src/ directory.

Follow below:

a) Enter the "build" directory using the following command:

cd Home/Project_two/build  

b) Run following command:

cmake .. -DNAIA_DIR=Home/NAIA_library/naia.install/cmake -DNSL_DIR=Home/NSL_library/nsl.install/cmake 

c) For creating "main.exe", run the following command:

make  

d) To run the "main.exe", use the following command:

./main input.root output.root  

Note 1: if you used the above command for running the "main.exe", "ui-ams" machine directly do it. Just for testing of one "input.root" is OK but keep avoiding doing heavy analysis on the "ui-ams" because it can easily crash.

Note 2: For heavy analysis you should use HTCondor, which is explained in the following sections.

To analyze AMS raw data stored in .root files, you need a C++ code that is structured around the NAIA and NSL libraries. For learining purpose a complete example is available: a ready-made C++ code dedicated to proton analysis. This code was developed by F. Faldi, M. Orcinha, F. Donnini, and V. Formato. It includes:

• A functional implementation of data analysis using NAIA and NSL
• Supporting scripts to run the analysis pipeline
• Inline comments and documentation to guide users

The repository is accessible via the following CERN GitLab link:

🔗 Proton Analysis C++ code, a CERN account is required to access the repository.

This example serves as a practical starting point and reference for building your own analysis code tailored to different datasets or physics goals within the AMS framework.