From 2212909dcdf5c4f1f74975152c73a6fef685dddd Mon Sep 17 00:00:00 2001
From: Niklas Fiekas <niklas.fiekas@sartorius.com>
Date: Sat, 2 Nov 2024 13:05:39 +0100
Subject: [PATCH] more docs and better outputs

---
 README.md                             | 21 ++++++++++++++++++++-
 research/src/bin/replay_encounters.rs |  6 +++---
 src/lib.rs                            | 13 ++++++++-----
 3 files changed, 31 insertions(+), 9 deletions(-)

diff --git a/README.md b/README.md
index aa4a90c..a5918a9 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,26 @@
 liglicko2
 =========
 
-Lichess-flavored Glicko-2 rating system.
+Lichess-flavored Glicko-2 rating system with fractional rating periods and
+instant rating updates.
+
+This does not (yet) exactly match the Lichess implementation.
+Instead, it's a proof of concept for potential improvements and parameter
+tweaks.
+
+See <http://glicko.net/glicko/glicko2.pdf> for a description of the
+original Glicko-2 rating system. The following changes have been made:
+
+- Optimized default parameters based on Lichess data. Optimal parameters
+  depend on the application, so this will not be ideal for all use cases.
+- All rating components are clamped to specific ranges, so that even
+  pathological scenarios cannot cause degenerate results.
+- Glicko-2 updates ratings in bulk in discrete *rating periods*. Lichess
+  instead updates pairs of ratings, so that ratings can be immediately
+  updated after each game.
+- Lichess keeps the time decay of rating deviations, but generalizes it
+  to work with fractional rating periods.
+- Allows considering an inherent advantage for the first player in a game.
 
 Documentation
 -------------
diff --git a/research/src/bin/replay_encounters.rs b/research/src/bin/replay_encounters.rs
index a4e45b1..f0f4c1d 100644
--- a/research/src/bin/replay_encounters.rs
+++ b/research/src/bin/replay_encounters.rs
@@ -376,7 +376,7 @@ fn write_report<W: Write>(
     for experiment in experiments.iter() {
         writeln!(
             writer,
-            "{},{},{},{},{},{},{}",
+            "{},{},{},{},{},{},{:.5}",
             f64::from(experiment.rating_system.min_deviation()),
             f64::from(experiment.rating_system.max_deviation()),
             f64::from(experiment.rating_system.default_volatility()),
@@ -410,7 +410,7 @@ fn write_report<W: Write>(
         {
             writeln!(
                 writer,
-                "# Sample {:?} rating of {}: {} (rd: {}, vola: {})",
+                "# Sample {:?} rating of {}: {:.1} (rd: {:.3}, vola: {:.5})",
                 speed,
                 name,
                 f64::from(rating.rating),
@@ -432,7 +432,7 @@ fn write_report<W: Write>(
         let avg = best_experiment.estimate_avg_rating(speed);
         writeln!(
             writer,
-            "# Estimated {speed:?} distribution: p1 {p1:.1}, p10 {p10:.1}, median {median:.1}, p90 {p90:.1}, p99 {p99:.1}, avg {avg:.1}",
+            "# Estimated {speed:?} distribution: p1={p1:.1} p10={p10:.1} p50={median:.1} p90={p90:.1} p99={p99:.1}, avg={avg:.1}",
         )?;
     }
     writeln!(writer, "# ---")?;
diff --git a/src/lib.rs b/src/lib.rs
index 5baa7f2..1ff85bd 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,9 +1,12 @@
-//! Implementation of the Lichess-flavored Glicko-2 rating system.
+//! Lichess-flavored Glicko-2 rating system system with fractional rating
+//! periods and instant rating updates.
 //!
-//! See <http://glicko.net/glicko/glicko2.pdf> for a description of the
-//! original Glicko-2 rating system.
+//! This does not (yet) exactly match the Lichess implementation.
+//! Instead, it's a proof of concept for potential improvements and parameter
+//! tweaks.
 //!
-//! Lichess has made some modifications:
+//! See <http://glicko.net/glicko/glicko2.pdf> for a description of the
+//! original Glicko-2 rating system. The following changes have been made:
 //!
 //! - Optimized default parameters based on Lichess data. Optimal parameters
 //!   depend on the application, so this will not be ideal for all use cases.
@@ -14,7 +17,7 @@
 //!   updated after each game.
 //! - Lichess keeps the time decay of rating deviations, but generalizes it
 //!   to work with fractional rating periods.
-//! - Lichess may consider an inherent advantage for the first player in a game.
+//! - Allows considering an inherent advantage for the first player in a game.
 //!
 //! # Errors
 //!