SEC.Models.EdmOptimizer

SEC.Models.EdmOptimizer.py

optimize_edm_xr_decomposition(decomposition, init_params, **kwargs)

Optimize the EDM decomposition.

Parameters:

• decomposition (Decomposition) – The decomposition to optimize.

• init_params (array-like) – The initial parameters for the EDM components.

• kwargs (dict) –

  Additional parameters for the optimization process.

  position_anchor_scalefloat, optional

  Scale factor for the soft position constraint that keeps each EDM component centroid near its EGH peak frame. Default 1e-5. Increase to enforce tighter position anchoring.

  e_boundstuple or None, optional

  Lower and upper bounds for the porosity parameter e (index 4 of each component’s 7-parameter vector). Default (0.0, 1.0). Pass None to disable bounds on e (not recommended).

  shared_ebool, optional

  If True, treat e as a single shared column parameter across all components instead of fitting it independently per component. This enforces the physical constraint that the interstitial porosity e = Vm/(Vm+Vs) is a column property, not a molecule-size-dependent property. K_SEC (= a) then carries all molecule-size information. Default False.

  shared_columnbool, optional

  If True, enforce the full constrained-EDM parameterisation where t0, u, e, Dz are shared column parameters and only a (K_SEC), b, and cinj are per-component.

  This is the recommended mode for K_SEC identification. With over-parameterised (free) EDM, the optimiser can absorb peak position into t0/u and leave a near zero for all components, making Spearman(Rg, a) meaningless. With constrained EDM, peak positions are explained solely by a-differences, yielding Spearman(Rg, a) = -1.000 for well-separated SEC data.

  Parameter vector layout:

  [t0_sh, u_sh, e_sh, Dz_sh,
   a_0, b_0, cinj_0,
   a_1, b_1, cinj_1, ...]
  

  Default bounds applied when shared_column=True: - e_bounds → (0.2, 0.85) (physical SEC total-porosity range) - cinj_min → 0.05 (prevents component collapse to zero)

  These defaults can be overridden via: - e_bounds kwarg (same meaning as the top-level kwarg) - cinj_min kwarg

  Default True. Pass False to use unconstrained (free) EDM, which is deprecated and will be removed in a future release.

  suppress_positive_b_warningbool, optional

  If True, suppress the UserWarning that is issued when any fitted b parameter is positive. In SEC, b > 0 (Langmuir adsorption) is physically unusual — right-tailing is normally kinetic (b = 0). A positive b may indicate secondary adsorption, overloading, or the model compensating for kinetic tailing with the wrong mechanism. Default False.

Returns:

new_xr_ccurves – The optimized EDM component curves.

Return type:

list of EdmComponentCurve

refine_edm_per_component(edm_ccurves, x, y, **kwargs)

Lighter second XR pass: fix shared column, refine per-component (a, b, cinj).

This is the EDM analog of SDM’s UV pass (which fixes XR and only refines mapping + UV scales). The shared column parameters (t0, u, e, Dz) are extracted from the already-optimised edm_ccurves and held fixed. Only the per-component (a, b, cinj) parameters are free.

This split is physically motivated: - Shared column (t0, u, e, Dz): column geometry, determined by the first full

pass and not expected to improve from further unconstrained refinement.

• Per-component (a = K_SEC, b, cinj): molecule-specific, benefit from refinement once the column baseline is stable.

Parameters:

• edm_ccurves (list of EdmComponentCurve) – Output of a previous optimize_edm_xr_decomposition() call. All curves must share the same (t0, u, e, Dz) (i.e. the result of a shared_column=True run).

• x (array-like) – Elution frame positions (same as used in the first pass).

• y (array-like) – XR integrated intensity (same as used in the first pass).

• kwargs (dict) –

  cinj_minfloat, optional

  Lower bound for cinj. Default 0.05.

  b_maxfloat, optional

  Global override for the b upper bound. When omitted (default), the automatic strategy is used:

  • n_comp < 4: per-component ceiling at the Pass-1 b value. b can decrease (toward physical values) but not increase. Legitimate b > 0 from 2/3-component Pass-1 results is preserved.

  • n_comp >= 4: min(b_pass1_i, 0.0) per component. High-component-count systems tend to drift to large positive b (EDM overflow territory); forcing b ≤ 0 resets the optimizer into the physically correct linear-SEC basin.

  Pass an explicit float to override for all components (e.g. 0.0 to force the physical regime regardless of component count).

  position_anchor_scalefloat, optional

  Scale for soft centroid-to-EGH-peak penalty. Default 1e-5.

  suppress_positive_b_warningbool, optional

  Suppress the b > 0 UserWarning. Default False.

  debug : bool, optional

Returns:

refined_ccurves

Return type:

list of EdmComponentCurve