{ "category": "Math and trigonometry functions", "display_name": "SUMX2PY2", "entry_kind": "built_in_function", "eval_api": { "method": "POST", "url": "https://handbook.dnacalc.com/api/eval" }, "function_id": "FUNC.SUMX2PY2", "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#L212-L214" ], "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#L212-L214", "state": "matches", "suite": null, "summary": "Matches all 6 recorded answers" } ], "json_url": "https://handbook.dnacalc.com/api/functions/FUNC.SUMX2PY2.json", "name": "SUMX2PY2", "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- **`SUMSQ`** — `SUMX2PY2(x, y) = SUMSQ(x) + SUMSQ(y)`, exactly. Since `SUMSQ` is variadic and\n accepts both ranges in one call, `SUMSQ(x, y)` computes the same mathematical quantity with a\n different (and looser) length requirement. The two differ only in the structural check and in\n the summation order.\n- **`SUMX2MY2`** — the same construction with a minus. That one cancels; this one cannot. If you\n only read one paragraph of the trio's numerical notes, read `SUMX2MY2`'s.\n- **`SUMXMY2`** — the sum of squared differences; related to this function by\n `SUMXMY2 = SUMX2PY2 - 2*SUMPRODUCT(x, y)`.\n- **`SUMPRODUCT`** — the general member, with the differing documented mismatch code.\n- **`SQRT(SUMX2PY2(x, y))`** — the Euclidean norm of the concatenated vectors, and the idiom to\n reach for given that Excel has no norm function.\n- **Confused with**: `SUMX2MY2` and `SUMXMY2`, whose names differ only in the placement of a\n letter. A useful reading rule: everything before the final `2` describes the expression; the\n trailing `2` means \"squared\". `SUMX2PY2` is `x²+y²`; `SUMXMY2` is `(x−y)²`.\n\n\n", "how-to-implement": "\n### Numerical notes\n\n\nThis is the placid member of the trio. There is **no cancellation** — every term is\nnon-negative, so the running sum is monotone and the relative error of the result is bounded by\nthe accumulated rounding of the additions. Everything difficult about `SUMX2PY2` is about\n*range*, not about *accuracy*.\n\n**1. Dynamic range is the whole problem.** Squaring doubles the exponent, so a set of inputs\nspanning the ordinary working range produces squares spanning twice that, and the two ends of\nthat span behave badly:\n\n- Above the square root of the largest double, a term overflows on its own.\n- Below roughly the fourth root of the smallest normal, a term underflows to zero, silently\n discarding a contribution.\n\nThe remedy is the standard scaled accumulation from Blue's TOMS algorithm and the LAPACK\n`dnrm2` line: find the largest magnitude `m` over both arrays, accumulate `SUM (v/m)^2`, and\nmultiply by `m^2` at the end. Blue's three-accumulator refinement handles data that spans the\nwhole range in a single pass. This removes both bands exactly, and it costs one extra pass or a\nrunning maximum. Nothing in the interface tells you whether it is done, and probe 3 below is the\nway to find out.\n\n**3. Squaring is exact in the significand, inexact in the result.** `x*x` carries one rounding,\nwhich is the minimum possible. There is no accuracy to be gained by a cleverer squaring; the\ngains are all in the scaling and the summation order.\n\n**4. What a careful implementation does**: scale by the global maximum magnitude, accumulate\npairwise or with compensation, unscale once. Where the data is well inside the normal range the\nresult is indistinguishable from the naive one, which is why this function looks easy — the\ndifference only appears at the ends, and it appears as the difference between an answer and an\nerror.\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- **Zero values are included**, per the documented remark.\n- **Overflow.** The characteristic edge. The squares carry twice the exponent range of the\n inputs, so a single term overflows once `|x|` passes roughly the square root of the largest\n double — even though a scaled computation would return a finite answer. Because all terms are\n positive, overflow is monotone and irreversible: once the accumulator saturates there is no\n later term that can bring it back.\n- **Underflow.** Symmetrically, values below about `1e-160` square to subnormals and then to\n zero, so a vector of small entries can return exactly zero when the true sum of squares is a\n representable positive number.\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` have a different 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\nThe documented ignore-list names text, logicals and empty cells; error values are not mentioned,\nso their treatment is unstated by the documentation.\n\n\n", "sources": "\n- Microsoft, \"SUMX2PY2 function\" —\n \n (signature, the defining equation, the ignored-values remark including \"cells with the value\n zero are included\", and the `#N/A` length-mismatch condition).\n- Microsoft, \"SUMPRODUCT function\" —\n \n (cited for the contrasting `#VALUE!` dimension-mismatch code recorded as a divergence).\n- Blue, \"A Portable Fortran Program to Find the Euclidean Norm of a Vector\", *ACM TOMS*, 1978;\n the LAPACK `dnrm2` lineage — scaled accumulation.\n- Higham, *Accuracy and Stability of Numerical Algorithms* — summation error bounds for\n non-negative terms.\n- Handbook projections `data/functions/FUNC.SUMX2PY2.json` (arity exactly 2,\n `error_collapse_profile: ReductionFold`, `numerical_reduction_policy=SequentialLeftFold`,\n `arg_preparation_profile: RefsVisibleInAdapter`) and `data/presence/FUNC.SUMX2PY2.json`\n (shared `sumproduct_family` module).\n- Handbook [SUMSQ](FUNC.SUMSQ.md), [SUMX2MY2](FUNC.SUMX2MY2.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`SUMX2PY2(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**: `[0, +infinity)`. Every term is non-negative, so the sum is monotone in every\n input's magnitude and is zero only when all contributing values are zero.\n- **Interpretation**: `SUMX2PY2(x, y) = ||x||^2 + ||y||^2` — the total squared Euclidean norm of\n the two vectors taken together. Equivalently it is `SUMSQ` applied to the concatenation of the\n two arrays, which is the cleanest way to think about it: **the pairing does not actually\n matter to the answer.** Addition is commutative and every term enters positively, so any\n re-pairing of the same multiset of values gives the same mathematical result. That property is\n unique to this member of the trio and it has a practical consequence noted below.\n- **Identities**: `SUMX2PY2(x, y) = SUMSQ(x) + SUMSQ(y)`;\n `SUMX2PY2(x, y) = SUMXMY2(x, y) + 2*SUMPRODUCT(x, y)`, which is the polarization identity and\n the reason this function turns up in regression bookkeeping.\n\nMicrosoft's page states the equation as the sum of `x^2 + y^2` over corresponding values.\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: \"If an array or reference argument contains text, logical values, or\nempty cells, those values are ignored; however, cells with the value zero are included.\"\n\nBecause the pairing is mathematically irrelevant here, the ambiguity that matters for\n`SUMX2MY2` and `SUMXMY2` — whether ignoring a value in one array also drops its partner — has a\n*visible* consequence for this function too, but of a different kind. If ignoring is pairwise,\na text cell in `array_x` silently removes a perfectly good number from `array_y` as well, and\nthe total drops by that number's square. If ignoring is independent, the total keeps it. The\ndocumentation does not say which, and the two readings give different numbers. It is the first\nprobe below.\n\nThe other commonly misunderstood point is the length check: the function requires equal counts\neven though the answer would be well defined for unequal ones. The requirement is structural,\nnot mathematical.\n\n\n" }, "signature": { "display": "SUMX2PY2(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 plus y squared over matching items", "short_source": "dna-calc-own" }, "docs": { "english_description": "Returns the sum of the sum of squares of corresponding values in two arrays", "microsoft_url": "https://support.microsoft.com/en-us/office/sumx2py2-function-826b60b4-0aa2-4e5e-81d2-be704d3d786f" }, "entry_kind": "built_in_function", "localized_family_names": null, "localized_names": [ { "locale": "ar-SA", "name": "SUMX2PY2" }, { "locale": "bg-BG", "name": "SUMX2PY2" }, { "locale": "cs-CZ", "name": "SUMX2PY2" }, { "locale": "da-DK", "name": "SUMX2PY2" }, { "locale": "de-DE", "name": "SUMX2PY2" }, { "locale": "el-GR", "name": "SUMX2PY2" }, { "locale": "en-AU", "name": "SUMX2PY2" }, { "locale": "en-GB", "name": "SUMX2PY2" }, { "locale": "en-US", "name": "SUMX2PY2" }, { "locale": "es-ES", "name": "SUMAX2MASY2" }, { "locale": "et-EE", "name": "SUMX2PY2" }, { "locale": "fi-FI", "name": "NELIÖSUMMIEN.SUMMA" }, { "locale": "fr-FR", "name": "SOMME.X2PY2*" }, { "locale": "he-IL", "name": "SUMX2PY2" }, { "locale": "hr-HR", "name": "SUMX2PY2" }, { "locale": "hu-HU", "name": "SZUMX2MEGY2" }, { "locale": "id-ID", "name": "SUMX2PY2" }, { "locale": "it-IT", "name": "SUMX2PY2" }, { "locale": "ja-JP", "name": "SUMX2PY2" }, { "locale": "ko-KR", "name": "SUMX2PY2" }, { "locale": "lt-LT", "name": "SUMX2PY2" }, { "locale": "lv-LV", "name": "SUMX2PY2" }, { "locale": "nb-NO", "name": "SUMX2PY2" }, { "locale": "nl-NL", "name": "SOM.X2PLUSY2" }, { "locale": "pl-PL", "name": "SUMA.X2.P.Y2" }, { "locale": "pt-BR", "name": "SUMX2PY2" }, { "locale": "pt-PT", "name": "SOMAX2SY2" }, { "locale": "ro-RO", "name": "SUMX2PY2" }, { "locale": "ru-RU", "name": "СУММСУММКВ" }, { "locale": "sk-SK", "name": "SUMX2PY2" }, { "locale": "sl-SI", "name": "SUMX2PY2" }, { "locale": "sr-Latn-RS", "name": "SUMX2PY2" }, { "locale": "sv-SE", "name": "SUMMAX2PY2" }, { "locale": "th-TH", "name": "SUMX2PY2" }, { "locale": "tr-TR", "name": "TOPX2AY2 işlevi" }, { "locale": "uk-UA", "name": "SUMX2PY2" }, { "locale": "vi-VN", "name": "SUMX2PY2" }, { "locale": "zh-CN", "name": "SUMX2PY2" }, { "locale": "zh-HK", "name": "SUMX2PY2" }, { "locale": "zh-TW", "name": "SUMX2PY2" } ], "signature": { "display": "SUMX2PY2(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": "SUMX2PY2", "version_marker": null, "xlcall": { "code": "305", "symbol": "xlfSumx2py2" } }, "microsoft": "https://support.microsoft.com/en-us/office/sumx2py2-function-826b60b4-0aa2-4e5e-81d2-be704d3d786f" }, "try_it": { "formula": "=SUMX2PY2({1;2;3},{2;3;4})" }, "url": "https://handbook.dnacalc.com/functions/SUMX2PY2.html", "variants": [], "versions": [] }