.. _`tutorial basics`:

Pipeline Application
====================

This chapter will give a brief example of how to run the *pipeline application*
from command line.

Working on LXPLUS
-----------------

A public build of NA64sw is available for LXPLUS users by path
``/cvmfs/na64.cern.ch/sft/LCG_105/x86_64-el9-gcc13-opt/``
and it's ready for public disposal. This build relies on more recent
system software components, so one have to override LXPLUS' default environment
with a special command before proceed with this tutorial:

.. code-block:: shell

    $ source /cvmfs/na64.cern.ch/sft/LCG_105/x86_64-el9-gcc13-opt/this-env.sh
    $ module load na64sw/0.6.9-opt

* LCG (provided by CERN) of certain version is used to provide common
  up-to-date environment for software build
* Linux environment modules are used to provide switchable environment on top
  of LCG.

Once above commands evaluated in the command line, one can run the software,
for instance:

.. code-block:: shell

    $ na64sw-pipe --help

The main application provided by NA64sw is ``na64sw-pipe``. This is a
versatile entry point to data processing procedures for common needs.

Running the app
---------------

One can run immediately on some raw NA64 data chunk (we specify a
number of events to read with ``-N/--max-events`` argument, otherwise
processing whole chunk may take some time):

.. code-block:: shell

    $ na64sw-pipe -N 1000 /eos/experiment/na64/data/cdr/cdr01002-003292.dat

The application will read data from provided file and perform
a series of procedures on every event taken from the chunk. Result of this
data processing shall appear in a current working directory
in a newly created ``processed.root`` file.

During the operation a minimal set of messages is performed by default, so do
not worry about quiet output.

.. tip::

  One can view output file with ROOT by opening it with ``TBrowser`` for instance.

  .. code-block:: shell

      $ root
      root> new TBrowser

  Find the ``processed.root`` file on the tree-view panel and open it by
  double-clicking on its icon.

.. figure:: https://cernbox.cern.ch/index.php/s/5VbqX1w2GsXnz9X/download

Within this file, various histograms shall appear. It contains some pretty
basic plots (similar to ones generated by the ``COOOL``) or more complex plots
related to reconstructed data analysis.

What precisely shall appear in this file is defined by special configuration
files that we will further refer as *pipeline configs*. By default,
``na64sw-pipe`` uses one located at ``$NA64SW_PREFIX/share/na64sw/run/default.yaml``.
This is pretty generic one, intended to perform common lowest-level
reconstruction.

There are more specialized one. For instance,
``$NA64SW_PREFIX/share/na64sw/run/std/apv.yaml``
does only basic reconstruction for APV detectors, without reconstruction on
calorimeters *and building any plots* in the output file.
You may provide *pipeline config* with ``-r/--run`` option, like:

.. code-block:: shell

    $ na64sw-pipe -N 1000 --run $NA64SW_PREFIX/share/na64sw/run/std/apv.yaml \
            /eos/experiment/na64/data/cdr/cdr01002-003292.dat

*Config file essentially defines what the pipeline actually does*. One can have
different *pipeline config* files for, say, calorimeters calibration
and another, way more complex, for physical analysis.

Getting help
------------

The ``na64sw-pipe`` application provides basic reference on its command line
interface with ``-h/--help`` option. Using these options one can:

* Change the type of the input data source -- NA64 MC output files, use
  ``p348reco`` reconstruction results as an input, etc.
* Name the output file (instead of default ``processed.root``)
* Provide calibration settings and logging configuration from different locations
* Specify additional loadable runtime extensions: user's handlers, calibration
  data formats, input codecs, etc

This options are not logically related to the analysis iself (run config is
responsible for that), but adjusts application behaviour for certain
environment (to be ran, for instance under CERN's HTCondor batch system).