[RFC proxmox] resource-scheduling: add module-level docs

[RFC proxmox] resource-scheduling: add module-level docs

[Dominik Rusovac]

Describe TOPSIS algorithm and static resource scheduling.

Signed-off-by: Dominik Rusovac <d.rusovac@proxmox.com>
---
 proxmox-resource-scheduling/src/pve_static.rs | 18 ++++++++++++++++++
 proxmox-resource-scheduling/src/topsis.rs     | 11 +++++++++++
 2 files changed, 29 insertions(+)

diff --git a/proxmox-resource-scheduling/src/pve_static.rs b/proxmox-resource-scheduling/src/pve_static.rs
index b81086dd..38da1d66 100644
--- a/proxmox-resource-scheduling/src/pve_static.rs
+++ b/proxmox-resource-scheduling/src/pve_static.rs
@@ -1,3 +1,21 @@
+//! Models usage of guests and nodes, and allows scoring nodes on which to start a new service via
+//! TOPSIS. For this scoring, each node in turn is considered as if the service was already running
+//! on it.
+//!
+//! CPU and memory usage are used as criteria, with memory being weighted much more, because it's a
+//! truly limited resource. For both, CPU and memory, highest usage among nodes (weighted more, as
+//! ideally no node should be overcommitted) and the [`root mean square`] (average) of usages across all
+//! nodes are considered.
+//!
+//! # Technical Details
+//! - As an alternative to the vector normalization method in the underlying TOPSIS algorithm, which
+//!   can lead to suboptimal decisions, [`min-max normalization`] was evaluated. While promising in
+//!   certain cases, the results were not convincing enough to swap normalization methods.
+//! - To mitigate suboptimal decisions, re-scaling CPU usage was also evaluated. Again promising in
+//!   certain cases, yet overall not convincing enough.
+//!
+//! [`root mean square`]: https://en.wikipedia.org/wiki/Root_mean_square
+//! [`min-max normalization`]: https://en.wikipedia.org/wiki/Feature_scaling
 use anyhow::Error;
 use serde::{Deserialize, Serialize};
 
diff --git a/proxmox-resource-scheduling/src/topsis.rs b/proxmox-resource-scheduling/src/topsis.rs
index 6d078aa6..9aec404c 100644
--- a/proxmox-resource-scheduling/src/topsis.rs
+++ b/proxmox-resource-scheduling/src/topsis.rs
@@ -1,3 +1,14 @@
+//! TOPSIS algorithm to score multi-valued alternatives according to a given set of weighted
+//! criteria.
+//!
+//! # Technical Details
+//! Implements variant of TOPSIS as outlined [`here`], meaning:
+//! - alternatives are being normalized using vector normalization; and
+//! - the score of an alternative corresponds to its similarity to the worst idealized
+//!   alternative[^note].
+//!
+//! [`here`]: https://en.wikipedia.org/wiki/TOPSIS
+//! [^note]: This alternative consists of the worst value for each single criterion among all alternatives.
 use anyhow::{bail, Error};
 
 fn differences<const N: usize>(xs: &[f64; N], ys: &[f64; N]) -> [f64; N] {
-- 
2.47.3