.. _library_schulze_ranker:

schulze_ranker

Schulze pairwise preference ranker. It builds the direct pairwise strength graph from aggregated matchups and applies the Schulze strongest-path dynamic program to derive the final pairwise preference relation.

The library implements the ranker_protocol defined in the ranking_protocols library. It provides predicates for learning a ranker from pairwise preferences, using it to order candidate items, and exporting it as a list of predicate clauses or to a file.

Datasets are represented as objects implementing the pairwise_ranking_dataset_protocol protocol from the ranking_protocols library. See the test_datasets directory for examples. The current implementation requires a well-formed connected pairwise dataset so that all ranked items remain comparable in the aggregated matchup graph.

API documentation

Open the `../../apis/library_index.html#schulze_ranker <../../apis/library_index.html#schulze_ranker>`__ link in a web browser.

Loading

To load this library, load the loader.lgt file:

::

| ?- logtalk_load(schulze_ranker(loader)).

Testing

To test this library predicates, load the tester.lgt file:

::

| ?- logtalk_load(schulze_ranker(tester)).

Features

• Pairwise Preference Learning: Learns one deterministic score per item from aggregated pairwise outcomes.
• Schulze Strongest Paths: Computes the final ranking relation using the Schulze strongest-path dynamic program over aggregated head-to-head data.
• Configurable Direct Edge Semantics: Supports both winning-votes and victory-margins victory-strength modes. The victory_strength/1 option selects whether direct edges use winning votes or victory margins before strongest-path propagation.
• Strongest-Path Access: Exposes the labeled strongest-path relation for ordered item pairs using the strongest_paths/2 predicate.
• Deterministic Ranking: Orders candidate items by final Schulze relation win counts with deterministic tie-breaking.
• Tie-breaking: Items tied in the final Schulze relation receive the same learned score, and ranking ties are then broken deterministically using the standard term order of the item identifiers.
• Strict Dataset Validation: Rejects duplicate items, undeclared items, self-preferences, non-positive weights, and disconnected comparison graphs.
• Training Diagnostics: Learned rankers include dataset summary metadata and the effective victory-strength mode.
• Ranker Export: Learned rankers can be exported as self-contained terms.

Options

The following options can be passed to the learn/3 predicate:

• victory_strength(winning_votes): Use the winning side's aggregated vote total as the direct edge strength.
• victory_strength(margins): Use the victory margin as the direct edge strength.

  The default is victory_strength(winning_votes).

Strongest paths

The strongest_paths/2 predicate returns the learned strongest-path matrix as an ordered list of path(Item1, Item2, Strength) terms for all ordered pairs of distinct learned items.

This predicate complements scores/2 and rank/3 without changing their semantics. The scores/2 predicate still returns the number of opponents that each item beats in the final Schulze relation, while strongest_paths/2 exposes the underlying pairwise path strengths used to derive that relation.

Diagnostics syntax

The diagnostics/2 predicate returns a list of metadata terms with the form:

::

[ model(schulze_ranker), options(Options), strongest_paths(StrongestPaths), dataset_summary(DatasetSummary) ]

Ranker representation

The learned ranker is represented by a compound term of the form:

::

schulze_ranker(Items, Scores, Diagnostics)

Where:

• Items: List of ranked items.
• Scores: List of Item-Score pairs.
• Diagnostics: List of metadata terms, including the effective victory_strength/1 option, the labeled strongest paths, and the dataset summary.