sverify-polars 0.8.0__tar.gz

sverify_polars-0.8.0/.gitignore

@@ -0,0 +1,27 @@
+/.lake
+/core/.lake
+/analysis/.lake
+/engines/.lake
+/float-bounds/.lake
+/python/.venv
+.hypothesis/
+.pytest_cache/
+__pycache__/
+/python/src/sverify/_bin/
+/python/build/
+/python/dist/
+/python/wheelhouse/
+__marimo__/
+# Great Docs build output (`poe docs`)
+/python/great-docs/
+/python/.great-docs*/
+# The site's generated pages (`poe docs_pages`, python/scripts/docs_pages.py)
+/python/examples/
+/python/semantics/
+/python/design/
+/python/ledgers/
+
+# Coverage data (`poe test-cov`, #750).
+.coverage
+.coverage.*
+coverage.json

sverify_polars-0.8.0/LICENSE

@@ -0,0 +1,373 @@
+Mozilla Public License Version 2.0
+==================================
+
+1. Definitions
+--------------
+
+1.1. "Contributor"
+    means each individual or legal entity that creates, contributes to
+    the creation of, or owns Covered Software.
+
+1.2. "Contributor Version"
+    means the combination of the Contributions of others (if any) used
+    by a Contributor and that particular Contributor's Contribution.
+
+1.3. "Contribution"
+    means Covered Software of a particular Contributor.
+
+1.4. "Covered Software"
+    means Source Code Form to which the initial Contributor has attached
+    the notice in Exhibit A, the Executable Form of such Source Code
+    Form, and Modifications of such Source Code Form, in each case
+    including portions thereof.
+
+1.5. "Incompatible With Secondary Licenses"
+    means
+
+    (a) that the initial Contributor has attached the notice described
+        in Exhibit B to the Covered Software; or
+
+    (b) that the Covered Software was made available under the terms of
+        version 1.1 or earlier of the License, but not also under the
+        terms of a Secondary License.
+
+1.6. "Executable Form"
+    means any form of the work other than Source Code Form.
+
+1.7. "Larger Work"
+    means a work that combines Covered Software with other material, in
+    a separate file or files, that is not Covered Software.
+
+1.8. "License"
+    means this document.
+
+1.9. "Licensable"
+    means having the right to grant, to the maximum extent possible,
+    whether at the time of the initial grant or subsequently, any and
+    all of the rights conveyed by this License.
+
+1.10. "Modifications"
+    means any of the following:
+
+    (a) any file in Source Code Form that results from an addition to,
+        deletion from, or modification of the contents of Covered
+        Software; or
+
+    (b) any new file in Source Code Form that contains any Covered
+        Software.
+
+1.11. "Patent Claims" of a Contributor
+    means any patent claim(s), including without limitation, method,
+    process, and apparatus claims, in any patent Licensable by such
+    Contributor that would be infringed, but for the grant of the
+    License, by the making, using, selling, offering for sale, having
+    made, import, or transfer of either its Contributions or its
+    Contributor Version.
+
+1.12. "Secondary License"
+    means either the GNU General Public License, Version 2.0, the GNU
+    Lesser General Public License, Version 2.1, the GNU Affero General
+    Public License, Version 3.0, or any later versions of those
+    licenses.
+
+1.13. "Source Code Form"
+    means the form of the work preferred for making modifications.
+
+1.14. "You" (or "Your")
+    means an individual or a legal entity exercising rights under this
+    License. For legal entities, "You" includes any entity that
+    controls, is controlled by, or is under common control with You. For
+    purposes of this definition, "control" means (a) the power, direct
+    or indirect, to cause the direction or management of such entity,
+    whether by contract or otherwise, or (b) ownership of more than
+    fifty percent (50%) of the outstanding shares or beneficial
+    ownership of such entity.
+
+2. License Grants and Conditions
+--------------------------------
+
+2.1. Grants
+
+Each Contributor hereby grants You a world-wide, royalty-free,
+non-exclusive license:
+
+(a) under intellectual property rights (other than patent or trademark)
+    Licensable by such Contributor to use, reproduce, make available,
+    modify, display, perform, distribute, and otherwise exploit its
+    Contributions, either on an unmodified basis, with Modifications, or
+    as part of a Larger Work; and
+
+(b) under Patent Claims of such Contributor to make, use, sell, offer
+    for sale, have made, import, and otherwise transfer either its
+    Contributions or its Contributor Version.
+
+2.2. Effective Date
+
+The licenses granted in Section 2.1 with respect to any Contribution
+become effective for each Contribution on the date the Contributor first
+distributes such Contribution.
+
+2.3. Limitations on Grant Scope
+
+The licenses granted in this Section 2 are the only rights granted under
+this License. No additional rights or licenses will be implied from the
+distribution or licensing of Covered Software under this License.
+Notwithstanding Section 2.1(b) above, no patent license is granted by a
+Contributor:
+
+(a) for any code that a Contributor has removed from Covered Software;
+    or
+
+(b) for infringements caused by: (i) Your and any other third party's
+    modifications of Covered Software, or (ii) the combination of its
+    Contributions with other software (except as part of its Contributor
+    Version); or
+
+(c) under Patent Claims infringed by Covered Software in the absence of
+    its Contributions.
+
+This License does not grant any rights in the trademarks, service marks,
+or logos of any Contributor (except as may be necessary to comply with
+the notice requirements in Section 3.4).
+
+2.4. Subsequent Licenses
+
+No Contributor makes additional grants as a result of Your choice to
+distribute the Covered Software under a subsequent version of this
+License (see Section 10.2) or under the terms of a Secondary License (if
+permitted under the terms of Section 3.3).
+
+2.5. Representation
+
+Each Contributor represents that the Contributor believes its
+Contributions are its original creation(s) or it has sufficient rights
+to grant the rights to its Contributions conveyed by this License.
+
+2.6. Fair Use
+
+This License is not intended to limit any rights You have under
+applicable copyright doctrines of fair use, fair dealing, or other
+equivalents.
+
+2.7. Conditions
+
+Sections 3.1, 3.2, 3.3, and 3.4 are conditions of the licenses granted
+in Section 2.1.
+
+3. Responsibilities
+-------------------
+
+3.1. Distribution of Source Form
+
+All distribution of Covered Software in Source Code Form, including any
+Modifications that You create or to which You contribute, must be under
+the terms of this License. You must inform recipients that the Source
+Code Form of the Covered Software is governed by the terms of this
+License, and how they can obtain a copy of this License. You may not
+attempt to alter or restrict the recipients' rights in the Source Code
+Form.
+
+3.2. Distribution of Executable Form
+
+If You distribute Covered Software in Executable Form then:
+
+(a) such Covered Software must also be made available in Source Code
+    Form, as described in Section 3.1, and You must inform recipients of
+    the Executable Form how they can obtain a copy of such Source Code
+    Form by reasonable means in a timely manner, at a charge no more
+    than the cost of distribution to the recipient; and
+
+(b) You may distribute such Executable Form under the terms of this
+    License, or sublicense it under different terms, provided that the
+    license for the Executable Form does not attempt to limit or alter
+    the recipients' rights in the Source Code Form under this License.
+
+3.3. Distribution of a Larger Work
+
+You may create and distribute a Larger Work under terms of Your choice,
+provided that You also comply with the requirements of this License for
+the Covered Software. If the Larger Work is a combination of Covered
+Software with a work governed by one or more Secondary Licenses, and the
+Covered Software is not Incompatible With Secondary Licenses, this
+License permits You to additionally distribute such Covered Software
+under the terms of such Secondary License(s), so that the recipient of
+the Larger Work may, at their option, further distribute the Covered
+Software under the terms of either this License or such Secondary
+License(s).
+
+3.4. Notices
+
+You may not remove or alter the substance of any license notices
+(including copyright notices, patent notices, disclaimers of warranty,
+or limitations of liability) contained within the Source Code Form of
+the Covered Software, except that You may alter any license notices to
+the extent required to remedy known factual inaccuracies.
+
+3.5. Application of Additional Terms
+
+You may choose to offer, and to charge a fee for, warranty, support,
+indemnity or liability obligations to one or more recipients of Covered
+Software. However, You may do so only on Your own behalf, and not on
+behalf of any Contributor. You must make it absolutely clear that any
+such warranty, support, indemnity, or liability obligation is offered by
+You alone, and You hereby agree to indemnify every Contributor for any
+liability incurred by such Contributor as a result of warranty, support,
+indemnity or liability terms You offer. You may include additional
+disclaimers of warranty and limitations of liability specific to any
+jurisdiction.
+
+4. Inability to Comply Due to Statute or Regulation
+---------------------------------------------------
+
+If it is impossible for You to comply with any of the terms of this
+License with respect to some or all of the Covered Software due to
+statute, judicial order, or regulation then You must: (a) comply with
+the terms of this License to the maximum extent possible; and (b)
+describe the limitations and the code they affect. Such description must
+be placed in a text file included with all distributions of the Covered
+Software under this License. Except to the extent prohibited by statute
+or regulation, such description must be sufficiently detailed for a
+recipient of ordinary skill to be able to understand it.
+
+5. Termination
+--------------
+
+5.1. The rights granted under this License will terminate automatically
+if You fail to comply with any of its terms. However, if You become
+compliant, then the rights granted under this License from a particular
+Contributor are reinstated (a) provisionally, unless and until such
+Contributor explicitly and finally terminates Your grants, and (b) on an
+ongoing basis, if such Contributor fails to notify You of the
+non-compliance by some reasonable means prior to 60 days after You have
+come back into compliance. Moreover, Your grants from a particular
+Contributor are reinstated on an ongoing basis if such Contributor
+notifies You of the non-compliance by some reasonable means, this is the
+first time You have received notice of non-compliance with this License
+from such Contributor, and You become compliant prior to 30 days after
+Your receipt of the notice.
+
+5.2. If You initiate litigation against any entity by asserting a patent
+infringement claim (excluding declaratory judgment actions,
+counter-claims, and cross-claims) alleging that a Contributor Version
+directly or indirectly infringes any patent, then the rights granted to
+You by any and all Contributors for the Covered Software under Section
+2.1 of this License shall terminate.
+
+5.3. In the event of termination under Sections 5.1 or 5.2 above, all
+end user license agreements (excluding distributors and resellers) which
+have been validly granted by You or Your distributors under this License
+prior to termination shall survive termination.
+
+************************************************************************
+*                                                                      *
+*  6. Disclaimer of Warranty                                           *
+*  -------------------------                                           *
+*                                                                      *
+*  Covered Software is provided under this License on an "as is"       *
+*  basis, without warranty of any kind, either expressed, implied, or  *
+*  statutory, including, without limitation, warranties that the       *
+*  Covered Software is free of defects, merchantable, fit for a        *
+*  particular purpose or non-infringing. The entire risk as to the     *
+*  quality and performance of the Covered Software is with You.        *
+*  Should any Covered Software prove defective in any respect, You     *
+*  (not any Contributor) assume the cost of any necessary servicing,   *
+*  repair, or correction. This disclaimer of warranty constitutes an   *
+*  essential part of this License. No use of any Covered Software is   *
+*  authorized under this License except under this disclaimer.         *
+*                                                                      *
+************************************************************************
+
+************************************************************************
+*                                                                      *
+*  7. Limitation of Liability                                          *
+*  --------------------------                                          *
+*                                                                      *
+*  Under no circumstances and under no legal theory, whether tort      *
+*  (including negligence), contract, or otherwise, shall any           *
+*  Contributor, or anyone who distributes Covered Software as          *
+*  permitted above, be liable to You for any direct, indirect,         *
+*  special, incidental, or consequential damages of any character      *
+*  including, without limitation, damages for lost profits, loss of    *
+*  goodwill, work stoppage, computer failure or malfunction, or any    *
+*  and all other commercial damages or losses, even if such party      *
+*  shall have been informed of the possibility of such damages. This   *
+*  limitation of liability shall not apply to liability for death or   *
+*  personal injury resulting from such party's negligence to the       *
+*  extent applicable law prohibits such limitation. Some               *
+*  jurisdictions do not allow the exclusion or limitation of           *
+*  incidental or consequential damages, so this exclusion and          *
+*  limitation may not apply to You.                                    *
+*                                                                      *
+************************************************************************
+
+8. Litigation
+-------------
+
+Any litigation relating to this License may be brought only in the
+courts of a jurisdiction where the defendant maintains its principal
+place of business and such litigation shall be governed by laws of that
+jurisdiction, without reference to its conflict-of-law provisions.
+Nothing in this Section shall prevent a party's ability to bring
+cross-claims or counter-claims.
+
+9. Miscellaneous
+----------------
+
+This License represents the complete agreement concerning the subject
+matter hereof. If any provision of this License is held to be
+unenforceable, such provision shall be reformed only to the extent
+necessary to make it enforceable. Any law or regulation which provides
+that the language of a contract shall be construed against the drafter
+shall not be used to construe this License against a Contributor.
+
+10. Versions of the License
+---------------------------
+
+10.1. New Versions
+
+Mozilla Foundation is the license steward. Except as provided in Section
+10.3, no one other than the license steward has the right to modify or
+publish new versions of this License. Each version will be given a
+distinguishing version number.
+
+10.2. Effect of New Versions
+
+You may distribute the Covered Software under the terms of the version
+of the License under which You originally received the Covered Software,
+or under the terms of any subsequent version published by the license
+steward.
+
+10.3. Modified Versions
+
+If you create software not governed by this License, and you want to
+create a new license for such software, you may create and use a
+modified version of this License if you rename the license and remove
+any references to the name of the license steward (except to note that
+such modified license differs from this License).
+
+10.4. Distributing Source Code Form that is Incompatible With Secondary
+Licenses
+
+If You choose to distribute Source Code Form that is Incompatible With
+Secondary Licenses under the terms of this version of the License, the
+notice described in Exhibit B of this License must be attached.
+
+Exhibit A - Source Code Form License Notice
+-------------------------------------------
+
+  This Source Code Form is subject to the terms of the Mozilla Public
+  License, v. 2.0. If a copy of the MPL was not distributed with this
+  file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+If it is not possible or desirable to put the notice in a particular
+file, then You may include the notice in a location (such as a LICENSE
+file in a relevant directory) where a recipient would be likely to look
+for such a notice.
+
+You may add additional accurate notices of copyright ownership.
+
+Exhibit B - "Incompatible With Secondary Licenses" Notice
+---------------------------------------------------------
+
+  This Source Code Form is "Incompatible With Secondary Licenses", as
+  defined by the Mozilla Public License, v. 2.0.

sverify_polars-0.8.0/PKG-INFO

@@ -0,0 +1,41 @@
+Metadata-Version: 2.5
+Name: sverify-polars
+Version: 0.8.0
+Summary: Polars as an engine of sverify: plans verified in Lean, run as Polars lazy frames
+Project-URL: Source, https://github.com/AlexanderNenninger/substrait-lean/tree/main/engines/polars
+Project-URL: Issues, https://github.com/AlexanderNenninger/substrait-lean/issues
+License-Expression: MPL-2.0
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: sverify==0.8.0
+Provides-Extra: run
+Requires-Dist: numpy>=2.5.4; extra == 'run'
+Requires-Dist: polars>=2.1.0; extra == 'run'
+Description-Content-Type: text/markdown
+
+# sverify-polars
+
+> Sverify-polars is a working prototype, and so is sverify, which it extends.
+> Their proofs and code still need a human audit before anyone relies on their
+> results.
+
+Polars as an engine of [sverify](https://github.com/AlexanderNenninger/substrait-lean):
+a plan verified in Lean runs as a Polars lazy frame on Polars's streaming
+engine, with a shim where Polars differs from the reference. Install it with
+`pip install sverify[polars]`, which brings Polars and NumPy (`sverify-polars[run]`);
+`sverify-polars` alone carries the plugin and the facts, for verifying under
+`semantics="polars"` without Polars. sverify finds it through its
+`ProfilePlugin` in the entry-point group `sverify.profiles`.
+
+The directory holds the whole engine package:
+
+- `src/sverify_polars/`: the plugin (`PLUGIN`), the translation to lazy
+  frames (`engine`) and the shims (`shims`);
+- `facts/`: what Polars does at each of the core's options, the evidence
+  for `Profile.polars` ([facts/README.md](facts/README.md));
+- `probes/`: the probes' recordings the facts cite;
+- `tests/`: its tests, which run in sverify's test session
+  (`python/pyproject.toml`'s `testpaths`).
+
+Its Lean half, the profile and its shims, is in the root Lean package for now
+(`SubstraitLean/PolarsProfile.lean`, `PolarsShims.lean`).

sverify_polars-0.8.0/README.md

@@ -0,0 +1,26 @@
+# sverify-polars
+
+> Sverify-polars is a working prototype, and so is sverify, which it extends.
+> Their proofs and code still need a human audit before anyone relies on their
+> results.
+
+Polars as an engine of [sverify](https://github.com/AlexanderNenninger/substrait-lean):
+a plan verified in Lean runs as a Polars lazy frame on Polars's streaming
+engine, with a shim where Polars differs from the reference. Install it with
+`pip install sverify[polars]`, which brings Polars and NumPy (`sverify-polars[run]`);
+`sverify-polars` alone carries the plugin and the facts, for verifying under
+`semantics="polars"` without Polars. sverify finds it through its
+`ProfilePlugin` in the entry-point group `sverify.profiles`.
+
+The directory holds the whole engine package:
+
+- `src/sverify_polars/`: the plugin (`PLUGIN`), the translation to lazy
+  frames (`engine`) and the shims (`shims`);
+- `facts/`: what Polars does at each of the core's options, the evidence
+  for `Profile.polars` ([facts/README.md](facts/README.md));
+- `probes/`: the probes' recordings the facts cite;
+- `tests/`: its tests, which run in sverify's test session
+  (`python/pyproject.toml`'s `testpaths`).
+
+Its Lean half, the profile and its shims, is in the root Lean package for now
+(`SubstraitLean/PolarsProfile.lean`, `PolarsShims.lean`).

sverify_polars-0.8.0/facts/README.md

@@ -0,0 +1,166 @@
+# Polars characterization
+
+What Polars does at each of the core's options
+([core-semantics.md](../../../docs/core-semantics.md)), recorded as facts, one
+JSON document each in [facts/](./), in the format of
+[fact.schema.json](../../../characterization/fact.schema.json) (`python -m sverify_dev.facts` checks
+them). They are the evidence `Profile.polars`
+(`SubstraitLean/PolarsProfile.lean`, the profile
+`verify(semantics="polars")` checks under; [Polars as a
+profile](../../../docs/engine-profiles.md#polars-as-a-profile)) and its row of the
+realizability table are built from.
+
+Polars here is version 2.1.0, the version `python/uv.lock` pins: the Python
+package `polars` 2.1.0 and its Rust crates at tag
+[`py-2.1.0`](https://github.com/pola-rs/polars/tree/py-2.1.0) (commit
+`7f902bd3`). The facts' `engine_version` is `py-2.1.0`. What is probed is
+Polars's expression API (`pl.col(...)`, `DataFrame.select`, `group_by`,
+`sort`, `join`), which `sverify_polars.engine` writes plans to; Polars's
+SQL interface (`pl.SQLContext`) is out of scope.
+
+Each fact names the items of the characterization checklist
+([areas.json](../../../characterization/areas.json)) it settles; `python -m sverify_dev.facts
+--coverage polars` lists them, and the items no fact settles yet.
+
+## How the facts are judged
+
+The facts are judged as every engine's are
+([../README.md](../../../characterization/README.md#how-the-facts-are-judged)). A fact's `status` is `open` where Polars differs from the reference
+and the profile has not decided how to bridge it, and `no-finding` where
+Polars gives the reference natively.
+
+## The probes
+
+`python -m sverify_dev.probe_polars` (`python/tools/sverify_dev/probe_polars.py`)
+writes [probes.json](../probes/probes.json), which `engines/polars/tests/test_probe_polars.py` checks is
+current. It holds two kinds of entry:
+
+- A probe runs a Polars expression on edge cases (0, ±1, ±2, 3, ±7, the
+  bounds of each integer width; 0.5, ±2.5, 7, 1e308, ±inf, NaN; NULL), one
+  row at a time, and compares each row with Lean's outcome of the Substrait
+  call under each candidate value of its option (`substrait-check
+  --outcomes`), as `sverify_dev.probe` does for DuckDB. `matching` lists the
+  candidates that agree on every row; `candidates` gives, for each, the
+  number of rows that differ and up to four of them.
+- An observation is a short Polars program whose result no single Substrait
+  call describes (a sort, a grouping, a cast that fails, a date), with its
+  `observed` result.
+
+Facts cite both by their `construct`. Rerun after a Polars or model change:
+
+```bash
+cd python && uv run python -m sverify_dev.probe_polars --write
+```
+
+The probes ran on macOS arm64. The elementary functions are Rust's `f64`
+functions, which call the platform's libm, and the sign of a NaN that
+arithmetic creates is the platform's, so no observation depends on either.
+
+## The Polars diff, as a table
+
+How Polars 2.1.0 compares with the reference, option by option. "Native"
+means Polars's own expression gives the reference result.
+
+| Function (types) | Option | Reference | Polars | Fact |
+|---|---|---|---|---|
+| `add` `subtract` `multiply` `negate` (`i8`…`i64`) | `overflow` | `ERROR` | `SILENT`, at the column's width; `**` too | [int-arith](polars-int-arith.json) |
+| `abs` (`i8`…`i64`) | `overflow` | `ERROR` | `abs(MIN)` is `MIN` | [int-abs](polars-int-abs.json) |
+| `divide` (`i8`…`i64`) | rounding | truncate | `//` floors; no truncating division in the Python API | [int-divide](polars-int-divide.json) |
+| | `on_division_by_zero` | `ERROR` | `NULL` | |
+| | `overflow` (`MIN / -1`) | `ERROR` | wraps to `MIN` | |
+| `modulus` (`i8`…`i64`) | `division_type` | `TRUNCATE` | `FLOOR` | [int-modulus](polars-int-modulus.json) |
+| | `on_division_by_zero` | `ERROR` | `NULL` | |
+| | `MIN % -1` | 0 | 0, native | |
+| `/` on integers | | an integer `divide` | a `Float64` division; a literal divisor takes the reciprocal, as below | [int-true-divide](polars-int-true-divide.json) |
+| `shift_left`, `shift_right` | range (ST-1) | drop bits, raise outside `[0, 63]` | no shift expressions | [int-shift](polars-int-shift.json) |
+| `sum` (`i8`…`i64`) | `overflow` | `ERROR`, at the input's type | `i8`, `i16` widen to `i64`; `i32`, `i64` wrap | [sum-int](polars-sum-int.json) |
+| `sum` (all) | no values | NULL | 0 (Substrait's `sum0`) | sum-int, [sum-float](polars-sum-float.json) |
+| `avg` (integers) | `avg_int_result` | the declared type | `Float64` | [avg-int](polars-avg-int.json) |
+| `add` `subtract` `multiply` (`fp64`) | `nan_creation` | raise | NaN (IEEE) | [double-arith](polars-double-arith.json) |
+| `divide` (`fp64`) | `on_division_by_zero` | `ERROR` | `IEEE`; `±inf / ±inf` is NaN | [double-divide](polars-double-divide.json) |
+| `divide`, `modulus` by a literal (`fp32`, `fp64`) | `rounding`, `nan_creation` | one rounding; no NaN from finite operands | `x · (1 / c)`: an ulp off, NaN or inf for a subnormal `c`, `49.0 % 49.0` is 49.0; on streaming per morsel, so it depends on the thread count ([PL-3](../../../upstream/bugs/PL-3.json)) | [double-scalar-divisor](polars-double-scalar-divisor.json) |
+| `modulus` (`fp64`) | | truncated (`fmod`), zero divisor raises | `x - y·floor(x / y)`: floor sign, NaN for `x % 0` and finite `x % ±inf` ([PL-1](../../../upstream/bugs/PL-1.json)) | [double-modulus](polars-double-modulus.json) |
+| `sqrt`, logs, `asin`, `acos`, `power`, trig of ±inf | `on_domain_error` | `ERROR` | `NAN` | [math-domain](polars-math-domain.json) |
+| `ln`, `log10`, `log2` | `on_log_zero` | `ERROR` | `MINUS_INFINITY` | math-domain |
+| `log10`, `log2` | last bits | the platform's `log10`, `log2` | `ln(x) / ln(b)`, an ulp off at times; on `Float32` the natural `log()` too ([PL-4](../../../upstream/bugs/PL-4.json)) | [log-base](polars-log-base.json) |
+| `atan2` | `atan2(0, 0)` | raise | 0 | [atan2](polars-atan2.json) |
+| `round` | `rounding` | `TIE_AWAY_FROM_ZERO` | `TIE_TO_EVEN` by default; native with `mode='half_away_from_zero'` | [round](polars-round.json) |
+| `round` to `d` digits | | `TIE_AWAY_FROM_ZERO`, `d < 0` allowed | `op(x · 10ᵈ) / 10ᵈ`; `d < 0` refused by the API | [round-digits](polars-round-digits.json) |
+| `floor`, `ceil`, `exp`, `atan` | | | native | round, math-domain |
+| doubles | `zero_sign` | `ONE_ZERO` | two zeros in arithmetic; a `±0.0` literal gives -0.0 for `-0.0 + 0.0`, per morsel on streaming | [zero-sign-streaming](polars-zero-sign-streaming.json) |
+| doubles | `nan_kind` | `ONE_NAN` | the sign survives | [nan-sign](polars-nan-sign.json) |
+| `sum`, `avg`, `variance`, `std_dev` over ±inf | `nan_creation`, `stat_degenerate` | raise | NaN | [nonfinite-aggregates](polars-nonfinite-aggregates.json) |
+| `sum`, `avg` (`fp64`) | `sum_order` | any order, within #85's bound | streaming: pairwise per morsel, in turn when grouped, varying between runs; in memory: pairwise, Kahan when grouped | [sum-float-streaming](polars-sum-float-streaming.json), [mean-float-streaming](polars-mean-float-streaming.json) |
+| `variance`, `std_dev`, `covar_*`, `corr` | `stat_algo`, `stat_degenerate` | generic properties; NULL for `corr` of one pair | two-pass blocks or Welford by path; NaN for degenerate `corr`; `Decimal` raises on streaming ([PL-5](../../../upstream/bugs/PL-5.json)) | [var-std-streaming](polars-var-std-streaming.json), [cov](polars-cov.json), [corr](polars-corr.json) |
+| `quantile_disc`, `quantile_cont`, `median` | `quantile_interp` | a value of the input; any double between neighbours | `nearest` by default; `linear` for `median` | [quantile](polars-quantile.json) |
+| decimals | result type | the YAML's (`multiply`: s₁ + s₂) | `Decimal(38, max(s₁, s₂))` | [decimal-arith](polars-decimal-arith.json) |
+| | `decimal_rescale` | `TIE_AWAY_FROM_ZERO` | `TIE_TO_EVEN` ([ST-8](../../../upstream/bugs/ST-8.json)) | |
+
+### NULLs, NaN and order
+
+| Function (types) | Option | Reference | Polars | Fact |
+|---|---|---|---|---|
+| `equal`, grouping, `DISTINCT`, joins (`fp64`) | `nan_equality` | `NAN_IS_NAN` | native | [nan-equality](polars-nan-equality.json) |
+| `lt`, sorts, `rank`, `median` (`fp64`) | `nan_order` | `GREATEST` | native | [nan-order](polars-nan-order.json) |
+| `max`, `greatest`, `arg_max` (`fp64`) | `nan_order` | `GREATEST`: `max(1, NaN)` is NaN | NaN skipped unless all NaN; `nan_max` native | [min-max-nan](polars-min-max-nan.json) |
+| `equal`, sorts, grouping (`fp64`) | `zero_sign` | `ONE_ZERO` | one zero; a group key keeps the zero seen first | [zero-order](polars-zero-order.json) |
+| sort key | `null_order` | as the key states; `NULLS_LAST` for `UNSPECIFIED` | `NULLS_FIRST` by default in both directions; native with `nulls_last` | [null-order](polars-null-order.json) |
+| sort, `fetch` | `tie_order` | any order | stable with `maintain_order`; on streaming unstable above 32 MiB without it | [sort-stability-streaming](polars-sort-stability-streaming.json) |
+| strings, booleans | order | code points; `false < true` | native | [string-order](polars-string-order.json) |
+| `aggregate` keys, joins | NULL keys | one group; `=` skips NULL | native (`nulls_equal` for `IS NOT DISTINCT FROM`) | [null-keys](polars-null-keys.json) |
+| `and`, `or`, `not`, `bool_and`, `bool_or` | | Kleene; aggregates skip NULLs | native | [kleene](polars-kleene.json) |
+| `count`, aggregates of no values | | `count` skips NULLs; NULL | native, but `sum` is 0 | [count-empty](polars-count-empty.json) |
+| `first`, `last`, `arg_min`, `arg_max` | `tie_pick` | any row | the first (last) in input order, deterministic | [first-last](polars-first-last.json), [arg-min-max](polars-arg-min-max.json) |
+| `string_agg`, `array_agg` | `tie_order` | any order | input order; `str.join` skips NULLs | first-last |
+| `mode` | `tie_pick` | one value of the tie | every mode, as a list | [mode](polars-mode.json) |
+| `rank`, `dense_rank`, `row_number` | | SQL's; NULLs ranked | `rank('min')`, `'dense'`, `'ordinal'`; NULL's rank is NULL; no `ntile`, `percent_rank`, `cume_dist` | [rank](polars-rank.json) |
+| `lag`, `first_value`, windowed sums | `tie_order` | the window's order | `.over` in input order | [window-values](polars-window-values.json) |
+| `i64` vs `fp64` comparison | | a cast first | compares as `Float64` | [int-float-compare](polars-int-float-compare.json) |
+
+### Strings, dates and casts
+
+| Function (types) | Option | Reference | Polars | Fact |
+|---|---|---|---|---|
+| `substring` | `negative_start` | `WRAP_FROM_END`, 1-based | `str.slice`, 0-based, `WRAP_FROM_END` | [substring](polars-substring.json) |
+| `strpos` | | 1-based characters, 0 when absent | `str.find`: 0-based bytes, NULL when absent | [strpos](polars-strpos.json) |
+| `upper`, `lower` | `char_set` | `UTF8` (Rust's mappings) | native | [case](polars-case.json) |
+| `character_length` | | code points | native | [length](polars-length.json) |
+| `reverse` | | code points | grapheme clusters | [reverse](polars-reverse.json) |
+| `btrim` | | spaces | `strip_chars(' ')` native; `strip_chars()` trims all whitespace | [trim](polars-trim.json) |
+| `str_concat` | `null_handling` | `ACCEPT_NULLS` | native; `ignore_nulls=True` for `IGNORE_NULLS` | [concat](polars-concat.json) |
+| `starts_with`, `ends_with`, `replace` | `case_sensitivity` | `CASE_SENSITIVE` | native | [match-functions](polars-match-functions.json) |
+| `regexp_extract`, `regexp_replace` | | RE2; `''` without a match | Rust `regex`; NULL without a match; `$1` replacements | [regex](polars-regex.json) |
+| `levenshtein`, `md5`, `sha256`, `repeat`, `ascii`, `like`, `ilike` | | defined | no expression | [string-functions-missing](polars-string-functions-missing.json) |
+| date arithmetic | `date_range` | raise outside 0001 … 9999 | computes past them; huge day counts panic ([PL-2](../../../upstream/bugs/PL-2.json)) | [date-range](polars-date-range.json) |
+| date + months | | the month's last day where shorter | native | [month-arith](polars-month-arith.json) |
+| timestamps | precision | microseconds | `Datetime('us')` | [timestamp-unit](polars-timestamp-unit.json) |
+| `date_part`, `date_trunc` | | ISO weeks, floor before 1970 | native | [date-parts](polars-date-parts.json) |
+| `strftime` | | opaque | chrono's specifiers | [strftime](polars-strftime.json) |
+| `TIME ± INTERVAL`, time zones, invalid dates | `time_interval_months` | refused | refused or raises | [temporal-errors](polars-temporal-errors.json) |
+| `cast` `fp64` → integer | `float_to_int` | `TRUNCATE` | native | [cast-double-to-int](polars-cast-double-to-int.json) |
+| `cast` (numbers) | `cast_failure` | as stated | `strict=True` throws, `strict=False` returns NULL; `wrap_numerical` wraps integers, saturates doubles | [cast-int](polars-cast-int.json), cast-double-to-int |
+| `cast` `i64` → `fp64`, `fp64` → `fp32` | | nearest | native | [cast-to-double](polars-cast-to-double.json) |
+| `cast` from and to strings | | the reference's rules | strict parsing; shortest round-trip text; no text to bool or date | [cast-string](polars-cast-string.json) |
+
+### Lists, set operations, frontend and I/O
+
+| Function (types) | Option | Reference | Polars | Fact |
+|---|---|---|---|---|
+| `ORDER BY` of lists, `<` of lists | `list_null_order` | NULL in `<`, `GREATEST` in sorts | `LEAST` in sorts; `<`, `min`, `max` of lists raise | [list-order](polars-list-order.json) |
+| `list_extract` | indexing | 1-based | `list.get`: 0-based, negative from the end, raises out of range | [list-index](polars-list-index.json) |
+| `=` on lists and structs | | structural, NULLs equal | native | [nested-equality](polars-nested-equality.json) |
+| `UNNEST` | NULL and empty lists | no row | a NULL row for a NULL list, none for an empty one; native with `keep_nulls=False` | [explode](polars-explode.json) |
+| `UNION`, `INTERSECT`, `EXCEPT` | | NULLs equal | `concat`, `unique`, semi/anti joins with `nulls_equal=True` | [set-operations](polars-set-operations.json) |
+| sort key | `clustered` | equal keys adjacent | a sort | [clustered](polars-clustered.json) |
+| `substring` | `substring_range` | raise outside 32 bits | computes; a negative length raises | [substring-range](polars-substring-range.json) |
+| `fp32` arithmetic | | refused (#417) | native single precision; literals take `Float32` | [fp32](polars-fp32.json) |
+| types | implicit casts, literals, names | explicit in the plan | wider type; literals adopt the column's; `Int32` literals | [implicit-casts](polars-implicit-casts.json), [literal-types](polars-literal-types.json), [type-names](polars-type-names.json) |
+| I/O | formats, object stores, catalogs | outside the plan | Parquet, CSV, IPC, NDJSON, Delta, Iceberg; `storage_options`; `pl.Catalog` | [io](polars-io.json) |
+
+### Execution
+
+| Construct | Option | Reference | Polars | Fact |
+|---|---|---|---|---|
+| `CASE` (`when/then`) | `evaluation_order` | a branch sees only its rows | an elementwise branch is masked on both engines; other branches run on every row | [exec-when-eager](polars-exec-when-eager.json) |
+| a subexpression shared by two branches | `evaluation_order` | a branch sees only its rows | CSE hoists it onto every row, so a guarded strict cast raises ([PL-6](../../../upstream/bugs/PL-6.json)) | [exec-cse-hoist](polars-exec-cse-hoist.json) |
+| stacked filters | `evaluation_order` | a filter's condition sees the rows below it | predicate pushdown merges them; `str.to_integer` raises on removed rows ([PL-7](../../../upstream/bugs/PL-7.json)); sverify turns pushdown off | [exec-predicate-pushdown](polars-exec-predicate-pushdown.json) |