.. _mdst:

====================
Belle II File Format
====================

The official standard Belle II file format is the mini data-summary table (mdst).

There is a ``basf2`` package (the mdst package) which defines this file format.
An mdst file contains a curated list of **post-reconstruction dataobjects** which are provided for analysis use.
The dataobjects are particularly important as they are the (only) information that is provided for high-level analysis.

These *mdst dataobjects* are optimised for minimal disk size per event.
This is important because the Belle II experiment will collect around :math:`5\times10^{10}` events, so data file size considerations will become rather critical.

.. seealso::

    `What is the difference between an mdst and a dst?
    <https://questions.belle2.org/question/219/what-is-the-difference-between-an-mdst-and-a-dst/>`_

Python interface
================

.. automodule:: mdst
   :members:

C++ dataobjects
===============

The post-reconstruction dataobjects are C++ classes found in the mdst dataobjects directory::

        ls $BELLE2_RELASE_DIR/mdst/dataobjects/include

Or in the C++ doxygen documentation :doxygen:`here <group__mdst__dataobjects>`.

ROOT and compatibility guarantee
================================

Mdst files are written by the :b2:mod:`RootOutput` module and are based on the ROOT file format.
However it is important to note that analysis of mdst with any software other than ``basf2`` is not supported or permitted.
I.e. use of the ``basf2`` framework and the :ref:`analysis` package is mandatory.

.. warning::

        A common misconception: Opening an mdst file with standard ROOT tools (e.g. with a TBrowser) may initially "work",
        but the results are not reproducible.

        Many dataobject member accessors require the ``basf2`` environment to return meaningful values.
        Segmentation faults and double-counting of tracks and/or clusters are very likely to be encountered.

However! Backward-compatibility is guaranteed for two major ``basf2`` releases and the supported light releases.

.. seealso:: `Backward compatibility <https://xwiki.desy.de/xwiki/rest/p/0a372>`__ on XWiki.

Related packages
================

The :ref:`skim` package defines a set of selection criteria to be applied to mdst files.
This will result in :ref:`analysis_udstoutput` (udst) files which also contain particle candidates.

.. seealso:: :ref:`analysis_particles`

.. seealso:: :ref:`analysis_udstoutput`

.. seealso:: :ref:`skim`