Anatomy of a Gulliver fit

Dramatis Personae

• module: a Gulliver-using IceTray module; usually one of:

  • I3SimpleFitter

  • I3IterativeFitter

  • I3ParaboloidFitter

• seed service: object of a class deriving from I3SeedServiceBase

• parametrization service: object of a class deriving from I3ParametrizationBase

• likelihood service: object of a class deriving from I3EventLogLikelihoodBase

• minimizer service: object of a class deriving from I3MinimizerBase

• gulliver: object of type I3Gulliver (derives from I3GulliverBase); data member of module

Act I: Configuration

1. tray configuration

2. service instantiation and configuration

• By services we mean:

  • seed service

  • parametrization service

  • likelihood service

  • minimizer service

• Services can be created in the traditional way with a service factory added to the tray.

• Services can be also created as independent python objects, to be passed directly as argument to the corresponding service configuration parameter in the Gulliver module(s).

3. Module instantiation and configuration: an I3Gulliver object is created and linked with 3 services from the context:

• likelihood service

• parametrization service

• minimizer service

Note

The seed service is not fed to gulliver, it stays separate.

Act II: Getting Ready For The Fit

0. The likelihood service is told to run SetGeometry on the G-Frame

1. module arrives at the P-Frame.

2. module gives event data (P-frame) to the seed service via SetEvent(frame) and asks the seed service how many seeds are available.

3. module starts loop over all available seeds.

4. module provides seed (I3EventHypothesis) and physics frame to gulliver.

5. gulliver gives event data (P-frame) to likelihood; gets the multiplicity \(N_{\rm mult}\).

6. gulliver gives event data (P-frame) to parametrization; gets number of free parameters \(N_{\rm par}\).

7. gulliver computes number of degrees of freedom \({\rm NDF} = N_{\rm mult} - N_{\rm par}\).

8. \({\rm NDF} \leq 0\): gulliver decides that the fit FAILs.

9. Check if minimizer wants to use gradient:

   • likelihood service should be able to deliver gradients.

   • parametrization service should be able to compute chain rules.

   Note

   Minimizer parameters are not necessarily the same as the physics variables; e.g. \(\log(E)\) instead of \(E\), or Cartesian direction parametrization instead of polar.

10. gulliver gives the seed hypothesis to the parametrization service; this updates the current event hypothesis.

11. parametrization service returns parameter initialization specifications for the fitting parameters:

    • Initial values of free parameters

    • Step sizes of free parameters

    • Bounds, if any (0 for both bounds is unbounded)

12. gulliver passes the specifications to the minimizer.

13. Minimization begins and iterates over the following for each step:

    1. The minimizer uses the specifications to generate a set of parameter values.

    2. The minimizer asks gulliver for the function value \(-\log(\mathcal{L})\) corresponding to these parameter values.

    3. gulliver gives the parameter values to the parametrization service.

    4. parametrization service updates the current event hypothesis using the new parameter values.

    5. gulliver passes the current event hypothesis to the likelihood service.

    6. likelihood service computes \(+\log(\mathcal{L})\).

    7. gulliver returns \(-\log(\mathcal{L})\) to the minimizer.

    8. If the minimizer wants to use gradients:

       • gulliver asks likelihood service to compute gradient.

       • gulliver asks parametrization service to apply chain rule.

       • gulliver returns also the parameter gradient to the minimizer.

    9. The minimizer uses function values (and gradient) to either:

       • Generate a new set of parameter values.

       • Decide that no minimum can be found (FAIL).

       • Decide that it has found a minimum (SUCCESS).

14. The minimizer returns a I3MinimizerResult object with

    • A boolean that indicates convergence.

    • The parameter values of the best fit.

    • A pointer to an algorithm-specific object with diagnostics.

15. gulliver passes the best fit parameter values to the parametrization service.

16. parametrization service updates the current event hypothesis.

17. gulliver gives the current event hypothesis to the likelihood service; this is the best fit event hypothesis.

18. likelihood service computes the best likelihood.

19. gulliver returns to module:

    • Convergence (boolean)

    • logl = best likelihood

    • rlogl = logl/ndof = reduced likelihood

    • nmini = number of likelihood values computed for the minimizer

    • ndof = \({\rm NDF}\); useful for failed fits, otherwise redundant.

    • Best fit event hypothesis

    • Minimizer-specific diagnostics, if any

    • Likelihood-specific diagnostics, if any

    • Parametrization-specific diagnostics, if any

20. module may or may not repeat all steps for other seeds.

21. module derive other quantities from the gulliver fit results.

22. module stores some or all of the results in the frame.