{ "category": "Math and trigonometry functions", "display_name": "SUMX2MY2", "entry_kind": "built_in_function", "eval_api": { "method": "POST", "url": "https://handbook.dnacalc.com/api/eval" }, "function_id": "FUNC.SUMX2MY2", "implementation_state": { "answer_bank": null, "detail": "Recorded: 7 workbook cells.", "dnacalc_commit": "9e1884369a678158dd82d3d74188daf986995e87", "in_catalogue": true, "state": "matches", "state_label": "Matches every recorded Excel answer", "summary": "Matches all 7 recorded answers", "workbook_corpus": { "cells": 7, "matched": 7 } }, "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#L209-L211" ], "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#L209-L211", "state": "matches", "suite": null, "summary": "Matches all 7 recorded answers" } ], "json_url": "https://handbook.dnacalc.com/api/functions/FUNC.SUMX2MY2.json", "name": "SUMX2MY2", "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- **`SUMX2PY2`** — the same construction with a plus. Numerically it is the easy one, because\n the terms cannot cancel.\n- **`SUMXMY2`** — the sum of squared differences. Note the algebra:\n `SUMXMY2 = SUMX2PY2 - 2*SUMPRODUCT(x, y)`, and `SUMX2MY2 = SUMPRODUCT(x-y, x+y)`. The three\n functions plus `SUMPRODUCT` span the same quadratic forms in different arrangements.\n- **`SUMPRODUCT`** — the general member, and the one whose documented mismatch error code\n differs (see above). `SUMX2MY2(x, y)` and `SUMPRODUCT((x-y), (x+y))` are the same mathematical\n value by two routes and are the basis for the accuracy comparison below.\n- **`SUMSQ`** — `SUMX2MY2(x, y) = SUMSQ(x) - SUMSQ(y)`, which is the *worst* way to compute it\n and is exactly the composition this function should save you from.\n- **`F.TEST` and the variance-ratio statistics** — the consumers of a difference of sums of\n squares.\n- **Confused with**: `SUMXMY2`, constantly. The names differ by the position of a single letter\n and the functions differ by which operation is inside the square. `SUMX2MY2` is\n \"sum of (x-squared minus y-squared)\"; `SUMXMY2` is \"sum of (x minus y), squared\".\n\n\n", "how-to-implement": "\n### Numerical notes\n\n\n**This is a cancellation function.** When `x_i` and `y_i` are close, `x_i^2` and `y_i^2` are\ncloser still in relative terms, and their difference loses roughly as many significant bits as\nthe two values share. In the extreme — `x` and `y` agreeing to within a few ULP — the computed\ndifference of squares can be entirely rounding error. Since the natural use of this function is\nto compare two vectors of similar magnitude, **the cancellation case is the intended case, not a\npathological one.**\n\n**The remedy is one line of algebra.** Evaluate each term as\n\n (x_i - y_i) * (x_i + y_i)\n\nrather than as `x_i*x_i - y_i*y_i`. This is not a heuristic; it is provably better:\n\n- `x - y` is computed exactly whenever `y/2 <= x <= 2y` (Sterbenz's lemma), which covers exactly\n the near-cancellation regime that destroys the naive form. The subtraction that loses\n information in the naive formula loses none in the rewritten one, because it happens *before*\n the squaring rather than after.\n- `x + y` is a well-conditioned sum for same-sign data and carries at most one rounding.\n- The product then carries at most one more rounding. The rewritten term has a small relative\n error where the naive term has an unbounded one.\n\nThe rewrite also improves the **overflow** picture: `x^2` overflows for `|x|` above roughly the\nsquare root of the largest double, while `(x-y)(x+y)` overflows only when the answer itself is\nnear the top of the range. There is a whole band of inputs on which the naive form fails and the\nrewritten form returns the right answer.\n\nKahan's work on difference-of-products (and the `fma`-based two-product technique that goes with\nit) is the general treatment; the difference of squares is its simplest instance.\n\n**What a careful implementation does**: rewrite each term as `(x-y)(x+y)`, accumulate pairwise\nor with compensation, and — if the input range is wide — scale. The result will differ from a\nnaive implementation, and that difference is largest exactly where users care most. The Handbook\nmakes no claim about which form Excel uses; probe 2 below settles it.\n\n\n", "quirks": "\n### Result and edge cases\n\n\nReturns `Number`.\n\n- **Length mismatch**: `#N/A`, as documented. Note the code: `#N/A`, not `#VALUE!`.\n- **Empty pairs / all values ignored**: not documented. Zero is the family-consistent answer;\n the Handbook has not checked.\n- **Zero values are included**, per the documented remark, which matters because a zero\n contributes nothing to the sum but does occupy a pairing slot.\n- **Overflow**: the squares carry twice the exponent range of the inputs, so a term can overflow\n even where the mathematical result is small. This is `SUMSQ`'s hazard, inherited.\n- **Cancellation**: the defining hazard of this surface. Discussed below.\n\n\n### Errors\n\n\n| Error | Condition | Source |\n|---|---|---|\n| `#N/A` | `array_x` and `array_y` have a different number of values | Documented by Microsoft |\n| `#VALUE!` | An argument is not an array/reference or does not resolve to 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\nThe documented ignore-list covers text, logicals and empty cells; it does not mention error\nvalues, so their treatment here is unstated by the documentation.\n\n\n", "sources": "\n- Microsoft, \"SUMX2MY2 function\" —\n \n (signature, the defining equation, \"If an array or reference argument contains text, logical\n values, or empty cells, those values are ignored. However, cells with the value zero are\n included\", and the `#N/A` length-mismatch condition).\n- Microsoft, \"SUMPRODUCT function\" —\n \n (cited here for the contrasting `#VALUE!` dimension-mismatch code recorded as a divergence).\n- Higham, *Accuracy and Stability of Numerical Algorithms* — cancellation, Sterbenz's lemma, and\n summation error bounds.\n- Kahan, on accurate difference-of-products evaluation — the general form of the rewrite used\n here.\n- Handbook projections `data/functions/FUNC.SUMX2MY2.json` (arity exactly 2,\n `error_collapse_profile: ReductionFold`, `numerical_reduction_policy=SequentialLeftFold`,\n `arg_preparation_profile: RefsVisibleInAdapter`) and `data/presence/FUNC.SUMX2MY2.json`\n (shared `sumproduct_family` module).\n- Handbook [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`SUMX2MY2(array_x, array_y)` returns\n\n SUM over i of (x_i^2 - y_i^2)\n\n- **Domain**: two equal-length lists of real numbers. Microsoft documents that unequal lengths\n give `#N/A`.\n- **Range**: all reals. Unlike `SUMSQ` and `SUMX2PY2`, this aggregate is signed and can be zero\n for non-zero data — indeed it is zero whenever the two vectors have the same Euclidean norm,\n which is exactly the case a user is most likely to be testing.\n- **The identity that defines the page**: `x^2 - y^2 = (x - y)(x + y)`. Algebraically trivial,\n numerically decisive; see *Numerical notes*.\n- **Interpretation**: `SUMX2MY2(x, y) = ||x||^2 - ||y||^2`, the difference of squared Euclidean\n norms. It appears in energy-difference calculations, in the numerator of certain variance-ratio\n statistics, and in physics worksheets computing `E = m(c^2 - v^2)`-shaped quantities.\n\nMicrosoft's page states the equation as the sum of `x^2 - y^2` over corresponding pairs.\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 commonly misunderstood aspect is **pairing**. The two arrays are matched element by element\nin their natural order, so a row range and a column range of the same length pair up\npositionally, not geometrically. The documentation speaks of \"a different number of values\"\nrather than of shape, which suggests count rather than dimension is what is compared — but it\ndoes not say so explicitly, and the Handbook does not assert it.\n\nThe scan rule is documented: \"If an array or reference argument contains text, logical values,\nor empty cells, those values are ignored. However, cells with the value zero are included.\"\n\n**That remark hides a real question the documentation does not answer.** If a value in\n`array_x` is ignored, is its partner in `array_y` also dropped, or does the pairing shift? Two\nreadings are possible — pairwise exclusion (drop both, keep the alignment) and independent\ncompaction (each array compacts separately, re-pairing surviving elements) — and they give\ndifferent answers on the same data. Nothing on the page settles it. It is the first probe below.\n\n\n" }, "signature": { "display": "SUMX2MY2(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 x squared minus y squared over matching items", "short_source": "dna-calc-own" }, "docs": { "english_description": "Returns the sum of the difference of squares of corresponding values in two arrays", "microsoft_url": "https://support.microsoft.com/en-us/office/sumx2my2-function-9e599cc5-5399-48e9-a5e0-e37812dfa3e9" }, "entry_kind": "built_in_function", "localized_family_names": null, "localized_names": [ { "locale": "ar-SA", "name": "SUMX2MY2" }, { "locale": "bg-BG", "name": "SUMX2MY2" }, { "locale": "cs-CZ", "name": "SUMX2MY2" }, { "locale": "da-DK", "name": "SUMX2MY2" }, { "locale": "de-DE", "name": "SUMX2MY2" }, { "locale": "el-GR", "name": "SUMX2MY2" }, { "locale": "en-AU", "name": "SUMX2MY2" }, { "locale": "en-GB", "name": "SUMX2MY2" }, { "locale": "en-US", "name": "SUMX2MY2" }, { "locale": "es-ES", "name": "SUMAX2MENOSY2" }, { "locale": "et-EE", "name": "SUMX2MY2" }, { "locale": "fi-FI", "name": "NELIÖSUMMIEN.EROTUS" }, { "locale": "fr-FR", "name": "SOMME.X2MY2*" }, { "locale": "he-IL", "name": "SUMX2MY2" }, { "locale": "hr-HR", "name": "SUMX2MY2" }, { "locale": "hu-HU", "name": "SZUMX2BŐLY2" }, { "locale": "id-ID", "name": "SUMX2MY2" }, { "locale": "it-IT", "name": "SUMX2MY2" }, { "locale": "ja-JP", "name": "SUMX2MY2" }, { "locale": "ko-KR", "name": "SUMX2MY2" }, { "locale": "lt-LT", "name": "SUMX2MY2" }, { "locale": "lv-LV", "name": "SUMX2MY2" }, { "locale": "nb-NO", "name": "SUMX2MY2" }, { "locale": "nl-NL", "name": "SOM.X2MINY2" }, { "locale": "pl-PL", "name": "SUMA.X2.M.Y2" }, { "locale": "pt-BR", "name": "SUMX2MY2" }, { "locale": "pt-PT", "name": "SOMAX2DY2" }, { "locale": "ro-RO", "name": "SUMX2MY2" }, { "locale": "ru-RU", "name": "СУММРАЗНКВ" }, { "locale": "sk-SK", "name": "SUMX2MY2" }, { "locale": "sl-SI", "name": "SUMX2MY2" }, { "locale": "sr-Latn-RS", "name": "SUMX2MY2" }, { "locale": "sv-SE", "name": "SUMMAX2MY2" }, { "locale": "th-TH", "name": "SUMX2MY2" }, { "locale": "tr-TR", "name": "TOPX2EY2 işlevi" }, { "locale": "uk-UA", "name": "SUMX2MY2" }, { "locale": "vi-VN", "name": "SUMX2MY2" }, { "locale": "zh-CN", "name": "SUMX2MY2" }, { "locale": "zh-HK", "name": "SUMX2MY2" }, { "locale": "zh-TW", "name": "SUMX2MY2" } ], "signature": { "display": "SUMX2MY2(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": "SUMX2MY2", "version_marker": null, "xlcall": { "code": "304", "symbol": "xlfSumx2my2" } }, "microsoft": "https://support.microsoft.com/en-us/office/sumx2my2-function-9e599cc5-5399-48e9-a5e0-e37812dfa3e9" }, "try_it": { "formula": "=SUMX2MY2({1;2;3},{2;3;4})" }, "url": "https://handbook.dnacalc.com/functions/SUMX2MY2.html", "variants": [], "versions": [] }