= The !MarlinRave plugin =

We provide a Marlin Processor called !RaveVertexing based on Rave, which enables the Marlin user to use Rave vertexing functionality within Marlin. The Rave vertexing algorithms can be completely configured by means of the Marlin steer file. A second processor called !RaveKinematics allows application of kinematic constraints to precompiled event topologies.

== The !RaveVertexing processor ==

An exemplary steer file snippet should illustrate the configuration of the !RaveVertexing processor:
{{{
<processor name="MyRaveVertexing" type="RaveVertexing">
<!--RaveVertexing does vertex finding and fitting using multiple algorithms-->
  <!--Name of the input track collection-->
  <parameter name="Tracks" type="string">Tracks </parameter>
  <!--Method used for vertex finding and fitting-->
  <parameter name="Method" type="string">default </parameter>
  <!--Print results to stdout-->
  <parameter name="Verbose" type="int">0 </parameter>
  <!--Name of the reconstructed vertex collection-->
  <parameter name="Vertices" type="string">Vertices </parameter>
  <!--Name of output the collection of refitted tracks-->
  <parameter name="RefittedTracks" type="string"> </parameter>
  <!--Optional filename for textual output of all vertices for histogramming-->
  <parameter name="HistFile" type="string"> </parameter>
</processor>
}}}
As shown in this example, the !RaveVertexing processor needs an input collection, defined by the Tracks parameter, holding the tracks generated by a Tracking processor. It then uses an algorithm specified by the Method parameter to reconstruct vertices and to refit the input tracks. The results are then stored in collections named by the Vertices and !RefittedTracks parameters.

The Method string allows selection and full configuration od the available vertexing algorithms. See RaveMethods for detailed information.

== The !RaveKinematics processor ==

Again the XML snippet is used to illustrate the configuration:
{{{
<processor name="MyRaveKinematics" type="RaveKinematics">
<!--RaveKinematics uses a set of given particles to reconstruct the decay chain using the given constraints-->
  <!--Name of the input particle collection-->
  <parameter name="Particles" type="string" lcioInType="ReconstructedParticle">Particles </parameter>
  <!--Decay topology to be used for the fitting; registered: SingleVertex, TwoTrackMass, WW4Jet, -->
  <parameter name="Topology" type="string">SingleVertex </parameter>
  <!--Print results to stdout-->
  <!--Topology parameters forwarded to the selected topology-->
  <parameter name="Parameters" type="string"> </parameter>
  <parameter name="Verbose" type="int">0 </parameter>
  <!--Name of the output collection of particles linked to a decay chain-->
  <parameter name="KinematicParticles" type="string" lcioOutType="ReconstructedParticle">KinematicParticles </parameter>
  <!--Name of the reconstructed vertex collection linked to a decay chain-->
  <parameter name="KinematicVertices" type="string" lcioOutType="Vertex">KinematicVertices </parameter>
</processor>
}}}
The input in this case is a !ReconstructedParticle collection named Particles. The decay hypothesis is chosen by means of the Topology parameter which will be explained below. A string of parameters can be passed to the chosen topology. The `rave::KinematicTree` produced by the fitter is split into a !ReconstructedParticle and a Vertex collection to represent the edges and nodes of the tree.

Currently available topologies are:
 * !SingleVertex : Fits all particles to one vertex and returns a mother particle without further constraints
 * !TwoTrackMass : Does a similar job, but constraints the invariant mass of the first two found particles to a given value
 * WW4Jet : Reconstructs the masses of two Ws from four given jets. The input collection needs to have exactly four particles output by a !JetFinder and representing the jets.

=== Custom topologies ===

Arbitrary topologies can be used by inheriting the !KinematicTopology class provided by MarlinRave and implementing the interface. The implementation in form of one .cc file has to be copied into the "topologies" directory of the MarlinRave source tree and the build will automatically include the new topology during the next run. 

The perhaps most simple yet meaningful example is the !SingleVertex topology:
{{{
#include "KinematicTopology.h"
#include <rave/KinematicTreeFactory.h>

class TopologySingleVertex :
  public KinematicTopology
{
  public:
    std::string describe() const {
      return "Reconstructs a mother particle from all given daughters.";
    };

    rave::KinematicTree build(
      const rave::KinematicTreeFactory & factory,
      const std::vector< rave::KinematicParticle > & particles,
      const int verbose = 0) const
    {
      return factory.useVertexFitter( particles );
    };

    bool valid() const { return true; };
};

#include "TopologyBuilder.h"
namespace {
  TopologyBuilder<TopologySingleVertex> t( "SingleVertex", "Only vertex" );
}
}}}

The three methods implemented here are the minimum interface for a usable topology. The `describe` method should return a string explaining the decay hypothesis implemented by this topology and maybe commenting on the possible parameters accepted by the topology. The `valid` method provides simple means to check on the given parameters. I will explain later how to use parameters.

The central method of the topology is the `build` method. It is supplied with an instance of a `rave::KinematicTreeFactory` providing full access to the Rave kinematic fitting algorithms and with the input particles read from the Marlin reconstruction chain. It has to return a `rave::KinematicTree` holding the reconstructed decay tree as it may have looked like if the decay hypothesis assumed by the topology were true. In the case of the !SingleVertex topology the tree can be constructed and returned by one simple call. The `build` method of course will be significantly longer in more complex situations.

The WW4Jet topology is an example of a situation with a certain level of difficulty.