From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from firstgate.proxmox.com (firstgate.proxmox.com [212.224.123.68]) by lore.proxmox.com (Postfix) with ESMTPS id 8AFF61FF13E for ; Fri, 06 Mar 2026 09:21:11 +0100 (CET) Received: from firstgate.proxmox.com (localhost [127.0.0.1]) by firstgate.proxmox.com (Proxmox) with ESMTP id 08C4E1A597; Fri, 6 Mar 2026 09:22:18 +0100 (CET) From: Dominik Rusovac To: pve-devel@lists.proxmox.com Subject: [RFC proxmox] resource-scheduling: add module-level docs Date: Fri, 6 Mar 2026 09:22:09 +0100 Message-ID: <20260306082209.34858-1-d.rusovac@proxmox.com> X-Mailer: git-send-email 2.47.3 MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Bm-Milter-Handled: 55990f41-d878-4baa-be0a-ee34c49e34d2 X-Bm-Transport-Timestamp: 1772785305336 X-SPAM-LEVEL: Spam detection results: 0 AWL 0.208 Adjusted score from AWL reputation of From: address BAYES_00 -1.9 Bayes spam probability is 0 to 1% DMARC_MISSING 0.1 Missing DMARC policy KAM_DMARC_STATUS 0.01 Test Rule for DKIM or SPF Failure with Strict Alignment PROLO_LEO1 0.1 Meta Catches all Leo drug variations so far RCVD_IN_MSPIKE_H2 0.001 Average reputation (+2) SPF_HELO_NONE 0.001 SPF: HELO does not publish an SPF Record SPF_PASS -0.001 SPF: sender matches SPF record Message-ID-Hash: 5EXROGOJ4QHD2N2CIDZFYBL2KJLJMSSN X-Message-ID-Hash: 5EXROGOJ4QHD2N2CIDZFYBL2KJLJMSSN X-MailFrom: d.rusovac@proxmox.com X-Mailman-Rule-Misses: dmarc-mitigation; no-senders; approved; loop; banned-address; emergency; member-moderation; nonmember-moderation; administrivia; implicit-dest; max-recipients; max-size; news-moderation; no-subject; digests; suspicious-header X-Mailman-Version: 3.3.10 Precedence: list List-Id: Proxmox VE development discussion List-Help: List-Owner: List-Post: List-Subscribe: List-Unsubscribe: Describe TOPSIS algorithm and static resource scheduling. Signed-off-by: Dominik Rusovac --- 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(xs: &[f64; N], ys: &[f64; N]) -> [f64; N] { -- 2.47.3