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