:tocdepth: 1 ========== What's New ========== This page explains the new features in the current release. This cannot cover all the changes in all packages but should help users to find out what needs to be adapted when changing to the new release. .. contents:: Table of Contents :depth: 3 :local: .. important changes should go here. Especially things that break backwards compatibility Changes since release-05 ======================== .. rubric:: Photons generated by PHOTOS in continuum events Fixed the issue where PHOTOS photons were not correctly flagged in continuum events, e.g., charm decays (:issue:`BII-5934`). This was present in ``release-05-00-01`` and earlier, including MC13 files. .. include:: analysis/doc/whatsnew-since/release-05-00.txt .. include:: framework/doc/whatsnew-since/release-05-00.txt Changes since release-04 ======================== .. rubric:: Neutral hadrons from ECLClusters get momentum from the cluster energy Since ``release-04`` it has been possible to load ECLClusters under the neutral hadron hypothesis. Previously we assumed a mass when calculating the particle momentum, however this leads to problems when, for example, a :math:`K_L^0` deposits less than its mass energy in the ECL. This happens about 50% of the time. The momentum of neutral hadrons from the ECL is now set to the :b2:var:`clusterE`. .. rubric:: Bremsstrahlung correction The `BremsFinder` module has been developed to find relations between tracks and photons that are likely to have been emitted by these tracks via Bremsstrahlung. The matching quality figure of merit is based on the angular distance between the photon ECL cluster and the extrapolated hit position of the track at the ECL. The function `correctBrems` performs the actual correction. There is also a reimplementation of Belle's Bremsstrahlung correction approach of looking for photons in a cone around tracks (`correctBremsBelle`), which is recommended for ``b2bii`` analyses. .. warning:: While it is technically possible to perform a TreeFit after applying Bremsstrahlung correction, the fit performance is unfortunately quite bad. However, there is already an improvement in the pipeline that should fix this issue. It will probably be available in one of the next light releases. .. rubric:: MC reconstruction and MC matching The :b2:mod:`ParticleCombinerFromMC` module and its corresponding wrapper function `reconstructMCDecay` should be used instead of `findMCDecay` to reconstruct decay modes based on MC information. The DecayStringGrammar has been extended with new exception markers for Bremsstrahlung, decay in flight, and misidentification. Exceptions for the MC matching of daughter particles with the DecayStringGrammar are propagated to the mother particle. .. rubric:: Redefinition of angle variables The kinematic variables :b2:var:`decayAngle`, :b2:var:`daughterAngle` and :b2:var:`pointingAngle` now return the angle instead of its cosine. .. rubric:: Protection of ParticleLists and particle combinations It is no longer allowed to use the label ``"all"`` for a particle list if a cut is applied. Reconstructed decays need to preserve electric charge. However, this can be deactivated if you know what you are doing, e.g. in searches for New Physics. .. Detailed changes for the analysis package first, that's what user will want to see .. include:: analysis/doc/whatsnew-since/release-04-02.txt .. include:: analysis/doc/whatsnew-since/release-04-00.txt .. And then for framework as well. If something is more important we can always move it directly in here .. include:: framework/doc/whatsnew-since/release-04-00.txt .. Changes for decfiles package .. include:: decfiles/doc/whatsnew-since/release-04-02.txt .. Changes for b2bii here. .. include:: b2bii/doc/whatsnew-since/release-04-01.txt Changes since release-03 ======================== .. rubric:: Removal of default analysis path and ``NtupleTools`` .. warning:: The default path ("``analysis_main``") and the ``NtupleTools`` are now **removed**. This is a major backward-compatibility breaking change. Please update your user scripts to create your own path (`basf2.create_path`) and to use the `variable manager tools ` (such as `VariablesToNtuple `). If your previously working example script from ``release-03`` looked something like this: .. code-block:: python from basf2 import * from stdCharged import stdPi from modularAnalysis import * stdPi("good") ntupleFile("myFile.root") # <-- now removed ntupleTree("pi+:good", ['pi+', 'Momentum']) # <-- now removed process(analysis_main) print(statistics) You should update it to this: .. code-block:: python import basf2 # better not to import all from stdCharged import stdPi from modularAnalysis import variablesToNtuple mypath = basf2.Path() # create your own path (call it what you like) stdPi("good", path=mypath) variablesToNtuple("pi+:good", ['px', 'py', 'pz', 'E'], path=mypath) basf2.process(mypath) print(basf2.statistics) .. seealso:: The example scripts available here: .. code-block:: text $BELLE2_RELEASE_DIR/analysis/examples/VariableManager .. rubric:: Switch of beam spot information from nominal to measured values. The interaction point position and its uncertainties are now taken from the database with values provided by the tracking group. All beam kinematics information is also moved to the database, which will eventually be measured on data. For now they are the values provided by the accelerator. .. warning:: The previous definition of the boost included a small rotation to align it with the HER. This is no longer possible with the new structure. The definition of CMS is therefore slightly changed. The impact should be at the percent level. If you have a physics analysis sensitive to this change: please discuss with the software / performance groups and add a comment to :issue:`BII-4360`. .. seealso:: The beam information can be accessed with :b2:var:`Ecms`, :b2:var:`beamPx`, :b2:var:`beamPy`, :b2:var:`beamPz`, and :b2:var:`beamE`. .. note:: As a consequence of this, there is now a **difference** between the variables ( :b2:var:`dx`, :b2:var:`dy`, :b2:var:`dz` ) compared to ( :b2:var:`x`, :b2:var:`y`, :b2:var:`z` ); and similarly for variables ( :b2:var:`mcDecayVertexX`, :b2:var:`mcDecayVertexY`, :b2:var:`mcDecayVertexZ` ) compared to ( :b2:var:`mcDecayVertexFromIPX`, :b2:var:`mcDecayVertexFromIPY` and :b2:var:`mcDecayVertexFromIPZ` ). .. rubric:: Redesign of the Conditions Database Interface The configuration and handling of the connection to the conditions database has been completely rewritten in a more coherent and modular way. We now have a new and consistent configuration interface, global tag replay and advanced checks: If users specify a global tag to be used which is either marked as invalid in the database or which cannot be found in the database the processing is now aborted. See :ref:`conditionsdb_overview` for details. .. rubric:: Restrict usage of ``useDB=False`` for Geometry creation Creating the geometry from XML files instead of the configuration in the Database may lead to wrong results. So while the option ``useDB=False`` is still necessary to debug changes to the geometry definitions it is now restricted to only be used for ``exp, run = 0, 0`` to protect users from mistakes. This also changes the behavior of `add_simulation() ` and `add_reconstruction() `: If a list of components is provided this will now only change the digitization or reconstruction setup but will always use the full geometry from the database. .. rubric:: Loading ECLClusters under multiple hypotheses It is now possible to load :math:`K_L^0` particles from clusters in the ECL. This has several important consequences for the creation of particles and using combinations containing :math:`K_L^0` s or other neutral hadrons in the analysis package. This is handled correctly by the ParticleLoader and ParticleCombiner (the corresponding convenience functions are `modularAnalysis.fillParticleList` and `modularAnalysis.reconstructDecay`). Essentially: it is forbidden from now onwards for any other analysis modules to create particles. .. rubric:: Deprecated RAVE for analysis use The (external) `RAVE `_ vertex fitter is not maintained. Its use in analysis is therefore deprecated. We do not expect to *remove* it, but *do not recommend* its use for any real physics analyses other than benchmarking or legacy studies. Instead we recommend you use either KFit (`vertex.kFit`) for fast/simple fits, or TreeFit (`vertex.treeFit`) for more complex fits and fitting the full decay chain. Please check the :ref:`TreeFitter` pages for details about the constraints available. If you are unable to use TreeFitter because of missing functionality, please `submit a feature request `_! .. warning:: The default fitter for `vertex.fitVertex` has been changed to KFit. .. rubric:: Tidy up and rename of Helicity variables. Renamed helicity variables in the VariableManager following consistent logic. We added the new variable :b2:var:`cosAcoplanarityAngle`. .. warning:: ``cosHelicityAngle`` is now :b2:var:`cosHelicityAngleMomentum`, and :b2:var:`cosHelicityAngle` has a new definition (as in the PDG 2018, p. 722). +--------------------------------------+---------------------------------------------+ | Old name | New name | +======================================+=============================================+ | ``cosHelicityAngle`` | :b2:var:`cosHelicityAngleMomentum` | +--------------------------------------+---------------------------------------------+ | ``cosHelicityAnglePi0Dalitz`` | :b2:var:`cosHelicityAngleMomentumPi0Dalitz` | +--------------------------------------+---------------------------------------------+ | ``cosHelicityAngleIfCMSIsTheMother`` | :b2:var:`cosHelicityAngleBeamMomentum` | +--------------------------------------+---------------------------------------------+ .. rubric:: New DecayStringGrammar for custom MCMatching Users can use new DecayStringGrammar to set properties of the MCMatching. Then `isSignal`, `mcErrors` and other MCTruthVariables behave according to the property. Once DecayStringGrammar is used with `reconstructDecay`, users can use `isSignal` instead of several specific variables such as `isSignalAcceptMissingNeutrino`. If one doesn't use any new DecayStringGrammar, all MCTruthVariables work same as before. The grammar is useful to analyze inclusive processes with both fully-inclusive-method and sum-of-exclusive-method. There are also new helper functions `genNMissingDaughter` and `genNStepsToDaughter` to obtain the detailed MC information. You can find examples of usage in :ref:`Marker_of_unspecified_particle`, :ref:`Grammar_for_custom_MCMatching`. .. Now let's add the detailed changes for the analysis package first, that's what user will want to see .. include:: analysis/doc/whatsnew-since/release-03-02.txt .. And then for framework as well. If something is more important we can always move it directly in here .. include:: framework/doc/whatsnew-since/release-03-00.txt .. include:: ecl/doc/whatsnew-since/release-03-00.txt Changes since release-02-01 =========================== .. rubric:: Moved to C++17 The whole software including the ROOT in the externals is now compiled using the C++17 standard. This should not affect many users but there are a few rare cases where this might lead to compilation problems of analysis code as some deprecated features `have been removed `_. The most notable are * ``throw(TypeName)`` exception specifiers, just remove them. * ``std::auto_ptr`` which should be replaced by ``std::unique_ptr`` * some older parts of the ```` header. In particular if you compile a standalone program that links against the ROOT in the Belle2 externals this now also needs to be compiled in C++17 mode. You can do this by adding ``-std=c++17`` to the compiler arguments. .. note:: It's best to directly pass the output of ``root-config --cflags`` to the compiler. That way you always pass the correct flags needed for the particular ROOT version setup. .. rubric:: Build system moved to Python3 This is a major update of `SCons `_ but most users should not notice any difference except for two instances: * If you update an existing working directory from an older release you might run into an error .. code-block:: text scons: *** [...] TypeError : intern() argument 1 must be string, not unicode scons: building terminated because of errors. TypeError: intern() argument 1 must be string, not unicode: [...] In this case please remove all ``.scon*`` files in the top level of your software directory and rerun ``scons`` * In the unlikely case that you have custom ``SConscript`` files which are not Python 3 compatible you will have to :ref:`update them `. .. Now let's add the detailed changes for the analysis package first, that's what user will want to see .. include:: analysis/doc/whatsnew-since/release-02-01.txt .. And then for framework as well. If something is more important we can always move it directly in here .. include:: framework/doc/whatsnew-since/release-02-01.txt