Nearest AMAP(2)-feasible (M2, M3, GAMMA) (matlab/lib/m3a/m3a/amap2/amap2_adjust_gamma.m). More...

#include <cstddef>
#include <vector>
#include "line/api/mam/amap2_assemble.h"
#include "line/api/mam/aph2_adjust.h"
#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/neldermead.h"

Include dependency graph for amap2_adjust_gamma.h:

Classes
struct	line::mam::Amap2AdjustGammaResult< T >
	Result of amap2_adjust_gamma. More...

Namespaces
namespace	line
namespace	line::mam

Functions
template<class T>
bool	line::mam::amap2_gamma_feasible (const T &M1, const T &M2, const T &M3, const T &GAMMA, const T &slack)
	Is (M1, M2, M3, GAMMA) AMAP(2)-feasible?
template<class T>
Amap2AdjustGammaResult< T >	line::mam::amap2_adjust_gamma (const T &M1, const T &M2, const T &M3, const T &GAMMA, const std::vector< T > &weights, int method, int constraints, const T &tol)
	Nearest AMAP(2)-feasible characteristics.
template<class T>
Amap2AdjustGammaResult< T >	line::mam::amap2_adjust_gamma (const T &M1, const T &M2, const T &M3, const T &GAMMA)
	amap2_adjust_gamma with the reference defaults: weights (10,1,10), method 3, constraints 2.
template<class T>
Amap2AdjustGammaResult< T >	line::mam::amap2_adjust_gamma (const T &M1, const T &M2, const T &M3, const T &GAMMA, int method)
	amap2_adjust_gamma with a chosen method and the remaining reference defaults.

Detailed Description

Nearest AMAP(2)-feasible (M2, M3, GAMMA) (matlab/lib/m3a/m3a/amap2/amap2_adjust_gamma.m).

M1 is always feasible on its own, so only the second and third moments and the autocorrelation decay rate GAMMA are adjusted. The reference offers four methods, which trade fidelity between the three characteristics:

1 joint search over (M2, M3, GAMMA) minimizing the weighted relative deviation, subject to the theoretical AMAP(2) feasibility region; 2 M2 forced feasible in closed form, then a search over (M3, GAMMA); 3 (the reference default) strict priority M2 > M3 > GAMMA: apply the closed-form APH(2) adjustment of aph2_adjust to (M2, M3), then clamp GAMMA into the interval that pair admits. No optimizer at all; 4 strict priority M2 > GAMMA > M3: M2 is forced feasible, then M3 is chosen inside its feasible interval to minimize a weighted objective in which GAMMA is always clamped to the interval implied by M3.

The feasibility region and the GAMMA interval are those of Casale, Zhang and Smirni's AMAP(2) characterization, transcribed from the reference's compute_gamma_bounds and nonlcon_theoretical.

ACCEPTANCE CONTRACT (see line/util/auglag.h). Methods 1 and 2 are driven in MATLAB by patternsearch (a direct-search method with a Nelder-Mead search step) and method 4 by PSwarm, a stochastic particle swarm. This port uses the augmented Lagrangian with a simplex inner solver for 1 and 2, and a deterministic multi-start bounded simplex search for 4. None of these reproduce the reference's iterates, and PSwarm in particular is not reproducible even against itself. What is guaranteed and tested is the specification:

the returned triple satisfies the AMAP(2) feasibility conditions, so amap2_fitall_gamma admits at least one solution for it;
an input that is already feasible is returned unchanged by every method (objective zero);
the achieved objective – the reference's own weighted relative deviation – is returned in Amap2AdjustGammaResult::objective so it can be compared against any other optimizer's on the same input.

ON THE constraints ARGUMENT. The reference selects between two constraint sets: constraints = 2 (default) is the theoretical characterization used here, and constraints = 1 replaces it by the indicator "amap2_fit_decay returns something", a zero/one function of x. That indicator is discontinuous, has zero gradient wherever it is defined, and carries no information about the direction of feasibility; it is usable by patternsearch only because a direct-search poll needs no derivative. It is NOT ported: an augmented Lagrangian on a 0/1 constraint degenerates into an unguided penalty. Requesting it raises UnsupportedError rather than silently substituting the theoretical set (which is what the JAR does – it accepts the argument and ignores it).

Gated on transcendental arithmetic: square roots in the bounds and tolerance-driven optimization.

Definition in file amap2_adjust_gamma.h.

Classes

Namespaces

Functions

Detailed Description