aph2_adjust_opt.h File Reference

Optimization-based APH(2) moment adjustment: the 'opt_param' and 'opt_char' methods of matlab/lib/m3a/m3a/aph2/aph2_adjust.m. More...

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

Include dependency graph for aph2_adjust_opt.h:

Go to the source code of this file.

Classes
struct	line::mam::Aph2AdjustOptResult< T >
	Result of an optimization-based APH(2) moment adjustment. More...

Namespaces
namespace	line
namespace	line::mam

Functions
template<class T>
Aph2AdjustOptResult< T >	line::mam::aph2_adjust_opt_param (const T &M1, const T &M2, const T &M3, const T &feastol, const T &degentol)
	aph2_adjust, method 'opt_param': adjust (M2, M3) by searching the APH(2) parameter space with M1 matched exactly.
template<class T>
Aph2AdjustOptResult< T >	line::mam::aph2_adjust_opt_param (const T &M1, const T &M2, const T &M3)
	aph2_adjust_opt_param with the MATLAB defaults feastol = 1e-6, degentol = 1e-8.
template<class T>
Aph2AdjustOptResult< T >	line::mam::aph2_adjust_opt_char (const T &M1, const T &M2, const T &M3, const T &postol, const T &degen)
	aph2_adjust, method 'opt_char': adjust (M2, M3) by searching the moment space subject to APH(2) invertibility.
template<class T>
Aph2AdjustOptResult< T >	line::mam::aph2_adjust_opt_char (const T &M1, const T &M2, const T &M3)
	aph2_adjust_opt_char with the MATLAB default postol = 1e-6 and degen = 1e-10.

Detailed Description

Optimization-based APH(2) moment adjustment: the 'opt_param' and 'opt_char' methods of matlab/lib/m3a/m3a/aph2/aph2_adjust.m.

Both find (M2a, M3a) close to a requested (M2, M3), holding M1 fixed, such that an APH(2) with those three moments exists. They differ in the space they search:

opt_param searches the PARAMETER space. The decision variables are the second phase mean l2 and the branching probability r1, with l1 = M1 - l2 r1 chosen so that the first moment is matched exactly; (M2a, M3a) are then whatever that APH(2) has. Any point of the feasible box is a valid APH(2), so the answer is feasible by construction. opt_char searches the CHARACTERISTIC space. The decision variables are (M2a, M3a) directly and feasibility is imposed as nonlinear constraints: the closed-form inversion aph2_fit1 / aph2_fit2 must produce a non-negative discriminant, non-negative phase means and a probability in [0, 1]. The reference solves the two inversions as separate problems and keeps whichever gives the smaller adjustment; so does this port. The closed-form Telek-Heindl bounds are imposed as three further rows, which are redundant in exact arithmetic but close a gap in the inversion form that an optimizer otherwise exploits; see aph2_moment_bounds_rows for the reproduction.

ACCEPTANCE CONTRACT (see line/util/auglag.h). MATLAB drives both with fmincon (active-set) or, in the '_gads' variants, with GlobalSearch. This port uses the augmented Lagrangian of line/util/auglag.h with the least-squares inner solver, which is a different algorithm: the iterates do not match and, on a problem with several local minima, the local minimum need not be the same one. What is guaranteed and tested is the specification:

1. the returned (M1, M2a, M3a) admits an APH(2), i.e. it satisfies the Telek-Heindl bounds that aph2_adjust's 'simple' method enforces;
2. when the requested (M2, M3) is already APH(2)-feasible, the returned pair reproduces it to the stated tolerance (objective ~ 0);
3. the achieved objective ||(M2a, M3a) - (M2, M3)||, the exact objective the reference minimizes, is returned in Aph2AdjustOptResult::objective so it can be compared against any other optimizer's on the same input.

NOT PORTED: 'opt_param_gads' and 'opt_char_gads'. They are the same two problems handed to GlobalSearch, whose answer depends on a randomly seeded multi-start; a deterministic multi-start would be a different algorithm again and would not reproduce them, so they are deliberately absent rather than approximated. Since both problems are smooth with a small feasible region, the single-start solve here reaches the same objective on every input exercised in tests/test_mam_fit_optim.cpp.

REFERENCE DEFECT (matlab/lib/m3a/m3a/aph2/aph2_adjust.m, 'opt_char'): the constraint functions nonlcon1 and nonlcon2 read tmp0, which is assigned only inside the sibling nested functions aph2_fit1 / aph2_fit2 and is therefore not in their scope. Calling aph2_adjust(M1, M2, M3, 'opt_char') raises "Unrecognized function or variable 'tmp0'" before any optimization happens, so the reference's opt_char has never run. This port recomputes tmp0 in the constraint, which is the evident intent (it is the discriminant of the inversion, and c(1) = -tmp0 asks for it to be non-negative). MATLAB was NOT edited.

Gated on transcendental arithmetic: the optimizers stop on tolerances, and the inversion takes a square root.

Definition in file aph2_adjust_opt.h.