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 fromI3GulliverBase
); data member of module
Act I: Configuration¶
tray
configurationservice
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).
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¶
The likelihood service is told to run
SetGeometry
on the G-Framemodule arrives at the P-Frame.
module gives event data (P-frame) to the seed service via
SetEvent(frame)
and asks the seed service how many seeds are available.module starts loop over all available seeds.
module provides seed (
I3EventHypothesis
) and physics frame to gulliver.gulliver gives event data (P-frame) to likelihood; gets the multiplicity \(N_{\rm mult}\).
gulliver gives event data (P-frame) to parametrization; gets number of free parameters \(N_{\rm par}\).
gulliver computes number of degrees of freedom \({\rm NDF} = N_{\rm mult} - N_{\rm par}\).
\({\rm NDF} \leq 0\): gulliver decides that the fit
FAILs
.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.
gulliver gives the seed hypothesis to the parametrization service; this updates the current event hypothesis.
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)
gulliver passes the specifications to the minimizer.
Minimization begins and iterates over the following for each step:
The minimizer uses the specifications to generate a set of parameter values.
The minimizer asks gulliver for the function value \(-\log(\mathcal{L})\) corresponding to these parameter values.
gulliver gives the parameter values to the parametrization service.
parametrization service updates the current event hypothesis using the new parameter values.
gulliver passes the current event hypothesis to the likelihood service.
likelihood service computes \(+\log(\mathcal{L})\).
gulliver returns \(-\log(\mathcal{L})\) to the minimizer.
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.
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
).
The minimizer returns a
I3MinimizerResult
object withA boolean that indicates convergence.
The parameter values of the best fit.
A pointer to an algorithm-specific object with diagnostics.
gulliver passes the best fit parameter values to the parametrization service.
parametrization service updates the current event hypothesis.
gulliver gives the current event hypothesis to the likelihood service; this is the best fit event hypothesis.
likelihood service computes the best likelihood.
gulliver returns to module:
Convergence (boolean)
logl
= best likelihoodrlogl = logl/ndof
= reduced likelihoodnmini
= number of likelihood values computed for the minimizerndof
= \({\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
module may or may not repeat all steps for other seeds.
module derive other quantities from the gulliver fit results.
module stores some or all of the results in the frame.