Adjustment UDF — Least Squares Adjustment for AutoIt

[AspirinJunkie]

Adjustment UDF — Least Squares Adjustment for AutoIt

You have measurements. They don't perfectly agree. You need the best answer.

Least squares adjustment finds the optimal values from redundant, contradictory observations — and tells you exactly how reliable the results are. It's the mathematical foundation behind positioning, navigation, calibration, curve fitting, regression, signal processing, and virtually any domain where measurements meet reality.

This UDF brings that capability to AutoIt with a radically simple interface: describe your model as string formulas, add measurements with their uncertainties, and call _adj_solve(). No matrix algebra, no numerical recipes, no external tools — just your problem and your data.

Underneath, it's a complete adjustment engine powered by OpenBLAS, with nonlinear iterative solvers, variance component estimation, robust estimators, and full statistical diagnostics — the kind of tooling normally reserved for MATLAB or specialized scientific software.

Download: Latest Release on GitHub
GitHub: https://github.com/Sylvan86/autoit-adjustment-udf

Quick Start

#include "Adjustment.au3"
; 5 measurements of a distance — find the best estimate and accuracy

Local $mSystem = _adj_createSystem()

_adj_addObsFunction($mSystem, "M1", "X", 10.02, 1.0)
_adj_addObsFunction($mSystem, "M2", "X",  9.98, 1.0)
_adj_addObsFunction($mSystem, "M3", "X", 10.01, 1.0)
_adj_addObsFunction($mSystem, "M4", "X", 10.03, 1.0)
_adj_addObsFunction($mSystem, "M5", "X",  9.99, 1.0)
_adj_setInitialValue($mSystem, "X", 10.0)

_adj_solve($mSystem)

ConsoleWrite(_adj_displayResults($mSystem))
; Result: X = 10.006 ± 0.009

This is just the simplest case — a mean value. The real strength lies in simultaneously adjusting different measurements with different formulas. For example, determining a point's position from distance and direction measurements, or fitting a curve to data while enforcing constraints.

Feature Overview

For experts — the full scope of the UDF:

Model Types

• OLS / WLS / GLS — Overdetermined system (weighted, generalized with full covariance matrix)
• LSE / WLSE / GLSE — With parameter constraints
• CLS / WCLS / GCLS — Condition adjustment
• GLM / WGLM / GGLM — Gauss-Helmert model (most general form)

Model type detection is automatic based on the input structure.

Solvers and Iteration Methods

• Iteration method: Gauss-Newton, Levenberg-Marquardt (Nielsen damping)
• Linear solver: QR decomposition (DGELSY), Singular Value Decomposition (DGELSD)
• Jacobian matrices: Numerical (Central, Forward, Backward, Ridder, Higham) or analytical
• Scaling: Jacobi equilibration (automatic column scaling)

Statistics and Diagnostics

• Basic statistics: A posteriori variance factor s0², degrees of freedom, vTPv
• Accuracy: Cofactor matrix Qxx, standard deviations (parameters, observations)
• Controllability: Redundancy numbers r_i, cofactor matrices Qvv and Qy
• Model validation: Global test (Chi²)
• Outlier diagnostics: Baarda test (w-statistic), Pope test (tau-statistic), p-values, MDB

Variance Component Estimation (VCE)

Helmert method: Separate variance factors for different observation groups (e.g. distances vs. angles). Iterative until convergence.

Robust Estimation (IRLS)

• L1 (Median) — Breakdown point: 50%
• Huber (c = 1.345) — Breakdown point: ~5%
• Hampel (a = 1.7, b = 3.4, c = 8.5) — Breakdown point: ~25%
• Biweight (Tukey) (c = 4.685) — Breakdown point: 50%
• BIBER (Schweppe) (c = 3.5) — Breakdown point: leverage-dependent
• Modified-M (Koch) (c = 1.5) — Breakdown point: leverage-dependent

Scale parameters: MAD, s0, a priori, user-defined.

Additional Features

• Symbolic formula input as strings — parameters and observations are detected automatically
• Compute-on-demand — statistics are only calculated when requested
• Configurable result display with selectable columns and sections
• Outlier detection and removal (_adj_getOutliers, _adj_removeObs)

Installation

Requirements:

• AutoIt v3.3.16+ (x64)
• OpenBLAS DLL (libopenblas_x64.dll)

Setup:

1. Download: Get the latest release from GitHub Releases
2. Extract: Unpack the files into a directory
3. OpenBLAS: The libopenblas_x64.dll is downloaded automatically on first run, or can be placed manually in the UDF directory
4. Include:

$__g_hBLAS_DLL = DllOpen("libopenblas_x64.dll")
#include "Adjustment.au3"

Documentation

The full documentation is available on GitHub:

• Tutorial — Step-by-step guide, 9 chapters (Beginners)
• Feature Overview — Full capabilities at a glance (Everyone)
• API Reference — All 17 public functions (Developers)
• Configuration — Solver, display, and robust config (Advanced)
• Result Structure — All keys of the result map (Advanced)
• Model Types — OLS to GGLM with mathematics (Experts)
• Solvers — GN, LM, QR, SVD in detail (Experts)
• Statistics — s0, Qxx, global test, Baarda/Pope (Experts)
• Robust Estimation — IRLS, 6 estimators, weight functions (Experts)
• Error Codes — All $ADJ_ERR_* with solutions (Everyone)

Tutorial Chapters

1. Getting Started — What is adjustment?
2. First Network — Trilateration
3. Weighting — Accounting for measurement precision
4. Mixed Observations — Combining distances and angles
5. Constraints — Restrictions and fixed parameters
6. Regression — OLS, orthogonal, Deming, York
7. Covariance Matrix — Correlated measurements
8. Understanding Results — Configuring and interpreting output
9. Robust Estimation — Handling outliers

Download

>>> Download the latest release from GitHub <<<

Source code and issue tracker: https://github.com/Sylvan86/autoit-adjustment-udf
 

Edited March 21 by AspirinJunkie

[AspirinJunkie]

For those of you who (understandably) still find this a bit too abstract, I’ve added another example to the Example folder: InteractiveCircleFit.au3 (it’s in German, but that shouldn’t be too much of a problem)

With this script, the user clicks on any points on the canvas, and the script uses those points to fit a circle that best matches them:

In my opinion, this example is very useful because it allows you to quickly visualize many aspects of adjustment analysis:

- What are observations, and what are parameters?
- What are these "residuals"?
- What do the standard deviations mean?
- What exactly is being "adjusted" here?
- What does "robust adjustment" mean?

Just play around with it (the new release is on GitHub).

Note on authorship: Since I’m not really a visual person and know absolutely nothing about graphics in AutoIt, I relied heavily on Claude for this sample script.
I’m very pleased with the result and glad that Claude fully understood how to use my UDF.

Edited March 25 by AspirinJunkie

[AspirinJunkie]

Adjustment UDF v26.4 — Release Notes

This release ships a complete interactive regression tool as an example, significantly faster robust estimation, and several new diagnostic and statistics features. A number of numerical and code-level bugs have also been fixed.

Download: Release v26.4 on GitHub

Highlight: Interactive Regression

The new example examples/InteractiveRegression.au3 is a complete GUI tool for least-squares curve fitting. It bundles all of the UDF's core capabilities into a single interactive surface — and works as a learning tool: tweak the modes and data, and you can see directly in the plot how error assumptions, weighting, and model choice change the result.

Features:

• Four regression modes: Normal (OLS/WLS), Orthogonal (TLS), Deming, York
• Symbolic formula input with automatic parameter and observation detection (e.g. A * #X + B)
• Editable tables for data and parameters, with Tab/Enter/arrow-key navigation and Excel-compatible multi-cell paste
• Live plot with data points, fitted curve, residual lines, and optional 1σ/2σ confidence band (GDI+)
• Robust estimation with all six M-estimators of the UDF
• CSV import (auto-detect separator and decimal mark) and CSV export with formula metadata (round-trip)
• Prediction with proper σ propagation
• Outlier highlighting based on normalized residuals
• "σ · s₀" button for global variance-factor rescaling of σ inputs
  

Performance: Faster Robust Estimation

Iteratively Reweighted Least Squares (IRLS) dominates runtime on large problems or when many iterations are needed. Several optimizations cut robust-estimation runtime substantially without affecting accuracy:

• Warm-start the Gauss-Newton inner loop between IRLS iterations
• Cap inner GN/LM iterations during re-solves
• Skip pre-VCE state reset in single-pass mode
• Default IRLS convergence tolerance loosened (1e-3 → 1e-2)
• Cascade-init (Huber → redescending) is off by default but still available via cascadeInit
  

New Features

Statistics

• Parameter correlation matrix available on demand
• Condition number of the normal-equations matrix exposed routinely (previously only in the SVD fallback)
• Sanity check tr(R) = f surfaces silently broken redundancy numbers
  

Diagnostics

• Iterative data snooping with soft downweighting (instead of hard outlier removal)
• External reliability (opt-in): minimum detectable bias δ₀ᵢ and parameter effect ∇xᵢ of every undetected outlier
  

Convergence

• Gradient test ‖g(x)‖ < tol is enforced additionally when restrictions are present
• Parameter-correction tolerance scales with parameter magnitude (avoids false convergence for very small parameters)
  

Solver / Robust

• Cascade-init Huber → redescending (MM-estimator) as an optional mode
• Initial Marquardt damping factor lmTau is now configurable
  

Bug Fixes

VCE / Robust

• Statistics are refreshed with the final weights after VCE convergence
• σ̂² is clipped at the MIN_SIGMA2 floor instead of being reset to 1.0
• Active VCE forces the weighted solve path; clipped σ̂² is now correctly reported to the caller as non-convergence
• MAD scale uses the a-priori 1/σᵢ instead of the live whitening vector
• robustParams are auto-filled with defaults when the caller leaves them Null
• __adj_initWeights used to skip weight init for σ=1 + multi-VCE-group → fixed
  

Statistics / Diagnostics

• diag(Qvv) and diag(Qŷ) are floored at 0 before sqrt (previously caused NaN on machine-precision negative values)
• Pope statistic now correctly uses the τ distribution instead of Student-t
• Baarda/Pope p-values are computed in a numerically stable way (no catastrophic cancellation for large w/τ)
  

Solver

• LM convergence test on the GLM/CLS path is now residual-based (r2sum) instead of parameter-based
• Step-size scaling for numerical differentiation smooth-blends across regimes instead of switching hard
  

API

• _adj_setInitialValue now creates missing parameters instead of erroring
• _adj_removeObs resets _prepareRunCount correctly; avoids a crash on the next solve call
  

Code Quality

• Several undeclared locals in AdjustmentStats / AdjustmentDiagnostics that leaked into the ByRef caller scope have been fixed
• Au3Check cleanup across all UDF and example files
  

Compatibility

Fully backward compatible with v26.3.x. No API changes other than additions. Default behavior is unchanged — the performance-related default tweaks affect robust estimation only and remain conservative (see _adj_robustDefaults).

Download

>>> Download release v26.4 from GitHub <<<

Source code and issue tracker: https://github.com/Sylvan86/autoit-adjustment-udf
 

[mLipok]

@water could you take a look here.
Maybe should be added to https://www.autoitscript.com/wiki/User_Defined_Functions
?

[mLipok]

1 hour ago, AspirinJunkie said:

This release ships a complete interactive regression tool as an example, significantly faster robust estimation, and several new diagnostic and statistics features. A number of numerical and code-level bugs have also been fixed.

great job
Thanks

[water]

On 4/30/2026 at 1:16 PM, mLipok said:

@water could you take a look here.
Maybe should be added to https://www.autoitscript.com/wiki/User_Defined_Functions
?

Done 🙂