mmpp2_fitc_approx.h File Reference

MMPP(2) fitted to counting-process characteristics by optimization (matlab/lib/kpctoolbox/mmpp/mmpp2_fitc_approx.m). More...

#include <cstddef>
#include <vector>
#include "line/api/mam/map_fit_detail.h"
#include "line/api/mam/map_moment.h"
#include "line/api/mam/map_transform.h"
#include "line/num/number.h"
#include "line/util/auglag.h"
#include "line/util/error.h"
#include "line/util/matrix.h"

Include dependency graph for mmpp2_fitc_approx.h:

Go to the source code of this file.

Classes
struct	line::mam::Mmpp2FitcApproxResult< T >
	Result of mmpp2_fitc_approx. More...

Namespaces
namespace	line
namespace	line::mam

Functions
template<class T>
Mmpp2FitcApproxResult< T >	line::mam::mmpp2_fitc_approx (const T &a, const T &bt1, const T &bt2, const T &binf, const T &m3t2, const T &t1, const T &t2, const AugLagOptions< T > &opt)
	Fit an MMPP(2) to counting characteristics.
template<class T>
Mmpp2FitcApproxResult< T >	line::mam::mmpp2_fitc_approx (const T &a, const T &bt1, const T &bt2, const T &binf, const T &m3t2, const T &t1, const T &t2)
	mmpp2_fitc_approx with the default tuning.

Detailed Description

MMPP(2) fitted to counting-process characteristics by optimization (matlab/lib/kpctoolbox/mmpp/mmpp2_fitc_approx.m).

Where mmpp2_fitc.h inverts the Heffes-Lucantoni relations in closed form and therefore fails outright when the requested characteristics are not exactly representable, this routine minimizes the mismatch. The decision variables are the two phase arrival rates l1, l2 and the two switching rates r1, r2 of

D0 = [ -(l1 + r1) r1 ; r2 -(l2 + r2) ], D1 = diag(l1, l2)

and the objective is the sum of squared RELATIVE errors of the five characteristics (rate a, IDC at t1 and t2, IDC at infinity, third central moment of the counts at t2), each computed from the closed forms of the reference rather than from a numerical counting-process evaluation. As in the reference, the characteristics are evaluated on the time scale stretched by factor = a/xa, so the objective is invariant to the rate, and the returned MAP is finally rescaled with map_scale to have rate exactly a.

ACCEPTANCE CONTRACT (see line/util/levmar.h). MATLAB drives this with the problem-based solve, i.e. fmincon interior-point over an automatically differentiated fcn2optimexpr expression; the JAR uses Apache Commons Math BOBYQA. This port uses the augmented Lagrangian of line/util/auglag.h with a Levenberg-Marquardt inner solver, since the objective is literally a sum of squares. None of the three reproduce each other's iterates. What is guaranteed and tested is the specification:

1. the returned (D0, D1) is a valid MAP – row sums zero, non-negative off-diagonals of D0, non-negative D1 – verified with map_isfeasible;
2. its rate is exactly a, by construction (map_scale);
3. the achieved objective, the same sum of squared relative errors the reference minimizes, is returned in Mmpp2FitcApproxResult::objective so it can be compared against any other optimizer's on the same input;
4. when the target characteristics are those of an actual MMPP(2), the objective reaches zero to the stated tolerance and the achieved characteristics, recomputed independently with map_count_var and map_count_moment, reproduce the targets.

The two bound constraints of the reference (l1, l2 >= 1e-6 and r1, r2 >= 0) are passed as inequality rows. Note that the characteristics are undefined at r1 = r2 = 0 and at l1 r2 + l2 r1 = 0, where the expressions divide by zero; no guard is needed, because a step producing a non-finite residual compares false against the incumbent sum of squares and is therefore rejected by the Levenberg-Marquardt loop, which then increases its damping.

REFERENCE DEFECT (matlab/lib/kpctoolbox/mmpp/mmpp2_fitc_approx.m): when t1 == t2 the local xbt2 is never assigned, yet it is used unconditionally two lines later in the expression for xm3t2. Calling the reference with t1 == t2 therefore raises "Unrecognized function or variable 'xbt2'". This port sets xbt2 = xbt1 in that case, which is what the value means, and drops the duplicated IDC residual, matching the JAR. MATLAB was NOT edited.

Gated on transcendental arithmetic: exponentials in the IDC and third-moment expressions, and tolerance-driven optimization.

Definition in file mmpp2_fitc_approx.h.