{ "category": "Math and trigonometry functions", "display_name": "SUMXMY2", "entry_kind": "built_in_function", "eval_api": { "method": "POST", "url": "https://handbook.dnacalc.com/api/eval" }, "function_id": "FUNC.SUMXMY2", "implementation_state": { "answer_bank": null, "detail": "Recorded: 6 workbook cells.", "dnacalc_commit": "9e1884369a678158dd82d3d74188daf986995e87", "in_catalogue": true, "state": "matches", "state_label": "Matches every recorded Excel answer", "summary": "Matches all 6 recorded answers", "workbook_corpus": { "cells": 6, "matched": 6 } }, "implementations": [ { "commit": "9e1884369a678158dd82d3d74188daf986995e87", "flavour": "excel-compatibility-candidate", "language": "Rust", "name": "CalcFunc", "own_code": [ "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/catalogue/math.rs#L215-L217" ], "repository": "https://github.com/DnaCalc/DnaCalc", "shared_code": [ "catalogue/math::sum_pairwise", "catalogue/math::numeric_cells" ], "source": "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/catalogue/math.rs#L215-L217", "state": "matches", "suite": null, "summary": "Matches all 6 recorded answers" } ], "json_url": "https://handbook.dnacalc.com/api/functions/FUNC.SUMXMY2.json", "name": "SUMXMY2", "notes": [], "schema": "efh.function-reference/v1", "section_order": [ "what-it-does", "try-it", "quirks", "how-to-implement", "version-differences", "alternatives" ], "sections": { "alternatives": "\n### Relationships\n\n\n- **`SUMX2MY2`** — the near-homograph, and a genuinely different function: subtraction after\n squaring rather than before. That one cancels catastrophically; this one does not. Confusing\n the two is the most likely user error in this corner of the category.\n- **`SUMX2PY2`** — the third member, and the other half of the polarization identity.\n- **`SUMPRODUCT`** — the general member, with the differing documented mismatch code. Note that\n `SUMPRODUCT((x-y)^2)` computes the same value and is what a reader writes when they have not\n found `SUMXMY2`.\n- **`DEVSQ`** — the one-array analogue: `SUMXMY2` against a constant mean is `DEVSQ`.\n- **`STEYX`, `LINEST`, `TREND`, `RSQ`, `FORECAST.LINEAR`** — the regression consumers. Every one\n of them minimizes or reports a quantity of this shape, which is why this function exists.\n- **`SQRT(SUMXMY2(x, y))`** — Euclidean distance, the composition to use for nearest-neighbour\n and clustering work.\n- **Confused with**: `SUMX2MY2`, as above; and with a *mean* squared error, which requires\n dividing by the count and which this function does not do.\n\n\n", "how-to-implement": "\n### Numerical notes\n\n\n`SUMXMY2` is, perhaps surprisingly, the **best conditioned** of the three paired-array\nfunctions, and the reason is a small theorem worth stating.\n\n**The subtraction is usually exact.** Sterbenz's lemma: if `y/2 <= x <= 2y` (same sign, within a\nfactor of two), then `x - y` is computed *exactly* in binary floating point — no rounding at\nall. The regime where a subtraction would normally be feared, near-equal operands, is precisely\nthe regime where it is free of error. And near-equal operands are the normal case for this\nfunction: `x` and `y` are two measurements of the same thing.\n\nSo the term `(x - y)^2` carries, in the common case, exactly one rounding (from the squaring),\nand the relative error of each term is at most one unit of roundoff. Compare `SUMX2MY2`, where\nthe same near-equality destroys the term entirely. **The difference between the two functions is\nnot a matter of degree; it is the difference between an operation that loses no bits and one\nthat can lose all of them.** A reader choosing between the two formulations of \"how far apart\nare these vectors\" should choose this one for that reason alone.\n\n**Underflow of the terms.** For two nearly identical arrays, each difference may be around\n`1e-170`, whose square is subnormal or zero. The sum then reads zero even though the true value\nis a representable positive number. If the caller is using `SUMXMY2` as a convergence test, this\nunderflow is a *silent success signal* — the worst possible failure mode for that use. Scaled\naccumulation (Blue) removes it; so does testing on `SQRT(SUMXMY2(...))`-scale quantities rather\nthan on the squared value.\n\n**What a careful implementation does**: compute the differences first (exactly, in the common\ncase), scale if the differences span a wide range, and accumulate pairwise or with compensation.\nThe Handbook makes no claim about what Excel does.\n\n\n", "quirks": "\n### Result and edge cases\n\n\nReturns `Number`, always non-negative.\n\n- **Length mismatch**: `#N/A`, as documented — not `#VALUE!`. See the family divergence below.\n- **Identical arrays**: exactly zero, and exactly zero is achievable here because each term is\n the square of an exactly-computed difference (see *Numerical notes*).\n- **Zero values are included**, per the documented remark.\n- **Overflow**: a difference near the top of the range squares to overflow, though this requires\n inputs that are themselves enormous — less reachable than for `SUMSQ`, because the difference\n is usually much smaller than the operands.\n- **Underflow**: a very small difference squares to zero. For nearly-equal arrays every term can\n underflow individually while the true sum is representable, which is the mirror image of the\n overflow case and the more likely one in practice.\n- **Empty or all-ignored input**: not documented; zero is the family-consistent answer and the\n Handbook has not checked.\n\n\n### Errors\n\n\n| Error | Condition | Source |\n|---|---|---|\n| `#N/A` | `array_x` and `array_y` do not have the same number of values | Documented by Microsoft |\n| `#VALUE!` | An argument does not resolve to an array or reference of values | Shared call model; not stated on the page |\n| propagated | An error value among the scanned data surfaces as that error | Shared coercion rules and the module's `ReductionFold` |\n\nError values are not named in the documented ignore-list, so their treatment is unstated by the\ndocumentation.\n\n\n", "sources": "\n- Microsoft, \"SUMXMY2 function\" —\n \n (signature, the defining equation, the ignored-values remark including \"cells with the value\n zero are included\", the `#N/A` length-mismatch condition, and the worked example).\n- Microsoft, \"SUMPRODUCT function\" —\n \n (cited for the contrasting `#VALUE!` dimension-mismatch code recorded as a divergence).\n- Higham, *Accuracy and Stability of Numerical Algorithms* — Sterbenz's lemma, cancellation, and\n summation error bounds.\n- Blue, \"A Portable Fortran Program to Find the Euclidean Norm of a Vector\", *ACM TOMS*, 1978 —\n scaled accumulation.\n- Handbook projections `data/functions/FUNC.SUMXMY2.json` (arity exactly 2,\n `error_collapse_profile: ReductionFold`, `numerical_reduction_policy=SequentialLeftFold`,\n `arg_preparation_profile: RefsVisibleInAdapter`) and `data/presence/FUNC.SUMXMY2.json`\n (shared `sumproduct_family` module).\n- Handbook [SUMX2MY2](FUNC.SUMX2MY2.md), [SUMX2PY2](FUNC.SUMX2PY2.md), and\n [Coercion and lifting](../model/02-coercion-and-lifting.md).\n\n", "version-differences": "No comparison between specific Excel builds is recorded here yet. This does not establish that all builds behave alike.", "what-it-does": "\n`SUMXMY2(array_x, array_y)` returns\n\n SUM over i of (x_i - y_i)^2\n\n- **Domain**: two equal-length lists of real numbers. Microsoft documents that arrays with\n different numbers of values give `#N/A`.\n- **Range**: `[0, +infinity)`. Zero exactly when the two arrays agree elementwise.\n- **Interpretation**: the **squared Euclidean distance** between the two vectors,\n `||x - y||^2`. This is the residual sum of squares of regression, the objective function of\n least squares, the numerator of the mean squared error, and the quantity minimized by every\n curve fit in the statistics category. Of the three paired-array functions it is by far the most\n used, and it is the one with a genuine claim to being a primitive rather than a convenience.\n- **Identities**: `SUMXMY2(x, y) = SUMX2PY2(x, y) - 2*SUMPRODUCT(x, y)` (the polarization\n identity); `SUMXMY2(x, y) = SUMSQ(x-y)` if the difference is formed first;\n `SQRT(SUMXMY2(x, y))` is the Euclidean distance.\n- **Metric properties**: `SUMXMY2` is symmetric in its arguments and vanishes only on equality,\n but it is *not* a metric — the triangle inequality holds for its square root, not for it.\n Nothing in the function enforces or checks this; it matters when the result is fed into\n clustering or nearest-neighbour logic that assumes a metric.\n\nMicrosoft's page states the equation as the sum of squared differences and gives a worked\nexample over two seven-element arrays.\n\n\n\n### Arguments\n\n\n| Argument | Meaning | Default |\n|---|---|---|\n| `array_x` | The first array or range of values. Required. | — |\n| `array_y` | The second array or range of values. Required. | — |\n\nThe documented scan rule is the trio's: \"If an array or reference argument contains text,\nlogical values, or empty cells, those values are ignored. However, cells with the value zero are\nincluded.\"\n\n**The pairing gap matters more here than anywhere else in the trio.** For `SUMX2PY2` the pairing\nis mathematically irrelevant; for `SUMX2MY2` it changes the answer; for `SUMXMY2` a\nmis-alignment is *catastrophic*, because the whole point of the function is that `x_i` and `y_i`\nare the same observation measured two ways. If ignoring a text cell in `array_x` compacts that\narray independently, every subsequent pair is shifted by one and the result is the distance\nbetween two vectors that were never meant to be compared — a large, plausible-looking number\nwith no diagnostic. The documentation does not say which reading applies. This is the first\nprobe below and it is the most consequential unstated behaviour on the page.\n\nThe second misunderstood point is the order of operations, encoded in the name: the subtraction\nhappens **before** the squaring. `SUMXMY2` is `sum of (x - y) squared`, not\n`sum of x - (y squared)` and not `sum of (x squared) - (y squared)` — the last of which is\n`SUMX2MY2`, a different function with a nearly identical name.\n\n\n" }, "signature": { "display": "SUMXMY2(array_x, array_y)", "parameters": [ { "description": null, "name": "array_x", "optional": false, "repeats": false }, { "description": null, "name": "array_y", "optional": false, "repeats": false } ], "trailing_repeats": false }, "sources": { "metadata": { "admission": { "label": "implemented", "reason": null }, "arity": { "max": 2, "min": 2 }, "category": "Math and trigonometry functions", "classification": { "arg_preparation_profile": "RefsVisibleInAdapter", "coercion_lift_profile": "Custom", "determinism_class": "Deterministic", "error_collapse_profile": "ReductionFold", "fec_dependency_profile": "RefOnly", "host_interaction_class": "None", "kernel_signature_class": "Custom", "rich_value_usage": "RichBlind", "surface_fec_dependency_profile": "RefOnly", "thread_safety_class": "SafePure", "volatility_class": "NonVolatile" }, "descriptions": { "long": null, "short": "Sum of the squared differences of matching items", "short_source": "dna-calc-own" }, "docs": { "english_description": "Returns the sum of squares of differences of corresponding values in two arrays", "microsoft_url": "https://support.microsoft.com/en-us/office/sumxmy2-function-9d144ac1-4d79-43de-b524-e2ecee23b299" }, "entry_kind": "built_in_function", "localized_family_names": null, "localized_names": [ { "locale": "ar-SA", "name": "SUMXMY2" }, { "locale": "bg-BG", "name": "SUMXMY2" }, { "locale": "cs-CZ", "name": "SUMXMY2" }, { "locale": "da-DK", "name": "SUMXMY2" }, { "locale": "de-DE", "name": "SUMXMY2" }, { "locale": "el-GR", "name": "SUMXMY2" }, { "locale": "en-AU", "name": "SUMXMY2" }, { "locale": "en-GB", "name": "SUMXMY2" }, { "locale": "en-US", "name": "SUMXMY2" }, { "locale": "es-ES", "name": "SUMAXMENOSY2" }, { "locale": "et-EE", "name": "SUMXMY2" }, { "locale": "fi-FI", "name": "EROTUSTEN.NELIÖSUMMA" }, { "locale": "fr-FR", "name": "SOMME.XMY2*" }, { "locale": "he-IL", "name": "SUMXMY2" }, { "locale": "hr-HR", "name": "SUMXMY2" }, { "locale": "hu-HU", "name": "SZUMXBŐLY2" }, { "locale": "id-ID", "name": "SUMXMY2" }, { "locale": "it-IT", "name": "SUMXMY2" }, { "locale": "ja-JP", "name": "SUMXMY2" }, { "locale": "ko-KR", "name": "SUMXMY2" }, { "locale": "lt-LT", "name": "SUMXMY2" }, { "locale": "lv-LV", "name": "SUMXMY2" }, { "locale": "nb-NO", "name": "SUMXMY2" }, { "locale": "nl-NL", "name": "SOM.XMINY.2" }, { "locale": "pl-PL", "name": "SUMA.XMY.2" }, { "locale": "pt-BR", "name": "SUMXMY2" }, { "locale": "pt-PT", "name": "SOMAXMY2" }, { "locale": "ro-RO", "name": "SUMXMY2" }, { "locale": "ru-RU", "name": "СУММКВРАЗН" }, { "locale": "sk-SK", "name": "SUMXMY2" }, { "locale": "sl-SI", "name": "SUMXMY2" }, { "locale": "sr-Latn-RS", "name": "SUMXMY2" }, { "locale": "sv-SE", "name": "SUMMAXMY2" }, { "locale": "th-TH", "name": "SUMXMY2" }, { "locale": "tr-TR", "name": "TOPXEY2 işlevi" }, { "locale": "uk-UA", "name": "SUMXMY2" }, { "locale": "vi-VN", "name": "SUMXMY2" }, { "locale": "zh-CN", "name": "SUMXMY2" }, { "locale": "zh-HK", "name": "SUMXMY2" }, { "locale": "zh-TW", "name": "SUMXMY2" } ], "signature": { "display": "SUMXMY2(array_x, array_y)", "parameters": [ { "description": null, "name": "array_x", "optional": false, "repeats": false }, { "description": null, "name": "array_y", "optional": false, "repeats": false } ], "trailing_repeats": false }, "surface_name": "SUMXMY2", "version_marker": null, "xlcall": { "code": "303", "symbol": "xlfSumxmy2" } }, "microsoft": "https://support.microsoft.com/en-us/office/sumxmy2-function-9d144ac1-4d79-43de-b524-e2ecee23b299" }, "try_it": { "formula": "=SUMXMY2({1;2;3},{2;3;4})" }, "url": "https://handbook.dnacalc.com/functions/SUMXMY2.html", "variants": [], "versions": [] }