feat: Add `RoundMode` (half even; half away from zero) and fix inconsistent rounding between float and decimal #21883

Julian-J-S · 2025-03-21T11:30:46Z

fix #21800 (though as @orlp mentioned there are theoretically more round modes to add)

Current Problem ⚠️

current round expression has no mode and is inconsistent
- Decimal: uses "half to even"
- Float: uses "half away from zero"

PR Solution 🍀

implement missing round modes
- Decimal: implement "half away from zero"
- Float: implement "half to even"
set "half to even" as default for float & decimal

Example

df = pl.DataFrame(
    {
        "f64": [-3.5, -2.5, -1.5, -0.5, 0.5, 1.5, 2.5, 3.5],
        "d": ["-3.5", "-2.5", "-1.5", "-0.5", "0.5", "1.5", "2.5", "3.5"],
    },
    schema={
        "f64": pl.Float64,
        "d": pl.Decimal(scale=1),
    },
)

df.with_columns(
    pl.all().round().name.suffix("_default"),
    pl.all().round(mode="half_away_from_zero").name.suffix("_away_from_zero"),
    pl.all().round(mode="half_to_even").name.suffix("_to_even"),
)

shape: (8, 8)
┌──────┬──────────────┬─────────────┬──────────────┬────────────────────┬──────────────────┬─────────────┬──────────────┐
│ f64  ┆ d            ┆ f64_default ┆ d_default    ┆ f64_away_from_zero ┆ d_away_from_zero ┆ f64_to_even ┆ d_to_even    │
│ ---  ┆ ---          ┆ ---         ┆ ---          ┆ ---                ┆ ---              ┆ ---         ┆ ---          │
│ f64  ┆ decimal[*,1] ┆ f64         ┆ decimal[*,1] ┆ f64                ┆ decimal[*,1]     ┆ f64         ┆ decimal[*,1] │
╞══════╪══════════════╪═════════════╪══════════════╪════════════════════╪══════════════════╪═════════════╪══════════════╡
│ -3.5 ┆ -3.5         ┆ -4.0        ┆ -4.0         ┆ -4.0               ┆ -4.0             ┆ -4.0        ┆ -4.0         │
│ -2.5 ┆ -2.5         ┆ -2.0        ┆ -2.0         ┆ -3.0               ┆ -3.0             ┆ -2.0        ┆ -2.0         │
│ -1.5 ┆ -1.5         ┆ -2.0        ┆ -2.0         ┆ -2.0               ┆ -2.0             ┆ -2.0        ┆ -2.0         │
│ -0.5 ┆ -0.5         ┆ -0.0        ┆ 0.0          ┆ -1.0               ┆ -1.0             ┆ -0.0        ┆ 0.0          │
│ 0.5  ┆ 0.5          ┆ 0.0         ┆ 0.0          ┆ 1.0                ┆ 1.0              ┆ 0.0         ┆ 0.0          │
│ 1.5  ┆ 1.5          ┆ 2.0         ┆ 2.0          ┆ 2.0                ┆ 2.0              ┆ 2.0         ┆ 2.0          │
│ 2.5  ┆ 2.5          ┆ 2.0         ┆ 2.0          ┆ 3.0                ┆ 3.0              ┆ 2.0         ┆ 2.0          │
│ 3.5  ┆ 3.5          ┆ 4.0         ┆ 4.0          ┆ 4.0                ┆ 4.0              ┆ 4.0         ┆ 4.0          │
└──────┴──────────────┴─────────────┴──────────────┴────────────────────┴──────────────────┴─────────────┴──────────────┘

Open

I will just quote @orlp:

Thus I'd suggest the following names (and their half_ cousins):
to_even, to nearest even (default),
to_zero, to 0,
away_from_zero, away from 0 to +inf for positive, -inf for negative,
ceil, to +inf,
floor, to -inf,
stochastic, as explained earlier.

IMO having consistent rounding across types and the two most used round modes will already be a great benefit and cover 99% of use-cases.
We can implement the other modes in the future if time and demand is there.

…istent rounding between float and decimal

codecov · 2025-03-21T11:43:02Z

Codecov Report

Attention: Patch coverage is 54.83871% with 42 lines in your changes missing coverage. Please review.

Project coverage is 80.91%. Comparing base (0f53539) to head (bd039bb).
Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
crates/polars-ops/src/series/ops/round.rs	53.70%	25 Missing ⚠️
.../polars-python/src/lazyframe/visitor/expr_nodes.rs	0.00%	12 Missing ⚠️
crates/polars-python/src/conversion/mod.rs	50.00%	5 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #21883      +/-   ##
==========================================
- Coverage   80.92%   80.91%   -0.02%     
==========================================
  Files        1624     1624              
  Lines      234643   234694      +51     
  Branches     2693     2693              
==========================================
+ Hits       189878   189893      +15     
- Misses      44133    44169      +36     
  Partials      632      632

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

orlp · 2025-03-21T11:55:57Z

I think we need to do another pass over the names. I think half_away_from_zero is a bit too wordy, and I also just realized my usage of 'up' and 'down' conflicts with both Python and Java.

Can we discuss that in the issue? Also, please don't make me catch API changes in the review, please just stick with what the issue suggests or discuss changes in the issue first.

Julian-J-S · 2025-03-28T06:33:25Z

@orlp as discussed I adjusted the names and implemented

half_to_even (was missing for f32/f64)
half_away_from_zero (was missing for Decimal)
set half_to_even as default for both

please have a look 🤓

wence- · 2025-03-31T11:54:17Z

crates/polars-python/src/lazyframe/visitor/expr_nodes.rs

+                    match mode {
+                        RoundMode::HalfToEven => "half_to_even",
+                        RoundMode::HalfAwayFromZero => "half_away_from_zero",
+                    },


Since the enum is annotated with strum, we can just use:

Into::<&str>::into(mode)

here, I think.

Could you please bump the minor IR version in visit.rs (in the impl of NodeTraverser).

wence- · 2025-03-31T11:54:37Z

crates/polars-python/src/lazyframe/visitor/expr_nodes.rs

+#[pyclass(name = "RoundMode")]
+pub struct PyRoundMode {
+    inner: RoundMode,
+}
+
+#[pymethods]
+impl PyRoundMode {
+    #[getter]
+    fn kind(&self) -> &str {
+        self.inner.into()
+    }
+}
+


Then there is no need for these.

orlp · 2025-03-31T12:05:12Z

crates/polars-ops/src/series/ops/round.rs

+                    } else {
+                        // Note we do the computation on f64 floats to not lose precision
+                        // when the computation is done, we cast to f32
+                        let multiplier = 10.0.pow(decimals as f64);


You can use powi without casting the exponent. This applies to the other spots too.

orlp · 2025-03-31T12:10:14Z

crates/polars-ops/src/series/ops/round.rs

-                .apply_values(|v| {
-                    // We use rounding=ROUND_HALF_EVEN
+            let res = match mode {
+                RoundMode::HalfToEven => ca.apply_values(|v| {
                    let rem = v % multiplier;
                    let is_v_floor_even = ((v - rem) / multiplier) % 2 == 0;


Can you please avoid the extra division by doing a modulo with 2 * multiplier and some extra logic? i128 division/modulo is very very expensive.

feat: Add RoundMode (half even; half away from zero) and fix incons…

067e2f7

…istent rounding between float and decimal

Julian-J-S requested review from ritchie46, c-peters, alexander-beedie, MarcoGorelli, reswqa, wence- and orlp as code owners March 21, 2025 11:30

github-actions bot added enhancement New feature or an improvement of an existing feature python Related to Python Polars rust Related to Rust Polars labels Mar 21, 2025

make clippy happy

bd039bb

adjust round mode names

36c0bed

Julian-J-S mentioned this pull request Mar 28, 2025

float and decimal have different round behavior (round up; half even) #20033

Closed

orlp self-assigned this Mar 31, 2025

wence- reviewed Mar 31, 2025

View reviewed changes

orlp reviewed Mar 31, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: Add `RoundMode` (half even; half away from zero) and fix inconsistent rounding between float and decimal #21883

feat: Add `RoundMode` (half even; half away from zero) and fix inconsistent rounding between float and decimal #21883

Julian-J-S commented Mar 21, 2025 •

edited

Loading

codecov bot commented Mar 21, 2025 •

edited

Loading

orlp commented Mar 21, 2025 •

edited

Loading

Julian-J-S commented Mar 28, 2025

wence- Mar 31, 2025

wence- Mar 31, 2025

wence- Mar 31, 2025

orlp Mar 31, 2025 •

edited

Loading

orlp Mar 31, 2025 •

edited

Loading

feat: Add RoundMode (half even; half away from zero) and fix inconsistent rounding between float and decimal #21883

Are you sure you want to change the base?

feat: Add RoundMode (half even; half away from zero) and fix inconsistent rounding between float and decimal #21883

Conversation

Julian-J-S commented Mar 21, 2025 • edited Loading

Current Problem ⚠️

PR Solution 🍀

Example

Open

codecov bot commented Mar 21, 2025 • edited Loading

Codecov Report

orlp commented Mar 21, 2025 • edited Loading

Julian-J-S commented Mar 28, 2025

wence- Mar 31, 2025

Choose a reason for hiding this comment

wence- Mar 31, 2025

Choose a reason for hiding this comment

wence- Mar 31, 2025

Choose a reason for hiding this comment

orlp Mar 31, 2025 • edited Loading

Choose a reason for hiding this comment

orlp Mar 31, 2025 • edited Loading

Choose a reason for hiding this comment

feat: Add `RoundMode` (half even; half away from zero) and fix inconsistent rounding between float and decimal #21883

feat: Add `RoundMode` (half even; half away from zero) and fix inconsistent rounding between float and decimal #21883

Julian-J-S commented Mar 21, 2025 •

edited

Loading

codecov bot commented Mar 21, 2025 •

edited

Loading

orlp commented Mar 21, 2025 •

edited

Loading

orlp Mar 31, 2025 •

edited

Loading

orlp Mar 31, 2025 •

edited

Loading