PRIMER: The Potential Method
Introduction
This primer introduces the Potential Method (PM) from first principles, starting with a simple story and building toward the mathematical foundation. It is intended to be read before the full design document (DESIGN.md) and before the worked examples.
PM is a ranking method based on a weighted directed graph with nodes as alternatives and arc weights as intensity preferences. It is characterized as a unique method that is invariant when adding a constant cycle to the graph. If you know a little graph theory, you can convince yourself that this is the case.
There are two applications: compute_potentials, a
CLI version, and compute_potentials_gui, and for their
launch the configuration file flow.config is needed. All
options are via CLI flags and input file.
Input data for both applications are in /data/flow_data folder.
A Simple Explanation
Suppose someone is telling a story in which three events occurred. They recall that event E2 happened two periods of time after E1, and that E3 happened three periods after E2. The story continues and new evidence emerges: E3 happened seven periods of time after E1.
The storyteller finds this confusing — and rightly so. Let us see why.
If E3 had happened five periods after E1, the three statements would form a consistent system of equations:
X₂ - X₁ = 2
X₃ - X₂ = 3
X₃ - X₁ = 5This system has a solution, unique up to a constant. Imposing the constraint ∑ Xᵢ = 0 gives a unique canonical solution. For a complete graph there is a convenient closed form:
Xᵢ = Δᵢ / nwhere Δᵢ is the net flow at node i (incoming minus outgoing) and n is the number of nodes.
Consistent case (f = [2, 3, 5], n = 3):
- Δ₁ = 0 - (2 + 5) = -7 → X₁ = -7/3 ≈ -2.333
- Δ₂ = 2 - 3 = -1 → X₂ = -1/3 ≈ -0.333
- Δ₃ = (3 + 5) - 0 = 8 → X₃ = 8/3 ≈ 2.667
Check: ∑ Xᵢ = (-7 - 1 + 8) / 3 = 0 ✓
But the new evidence changes the third equation to:
X₃ - X₁ = 7and the system becomes inconsistent — it has no exact solution. This is exactly the point where the Potential Method begins.
From Story to Graph
PM models the three events as nodes in a directed weighted graph, with three arcs representing the observed time differences:
E1 → E2 (weight 2)
E2 → E3 (weight 3)
E1 → E3 (weight 7)The incidence matrix of this graph is the (m × n) matrix A, where m = 3 arcs and n = 3 nodes:
A =
-1 1 0
0 -1 1
-1 0 1The system of equations can be written compactly as:
A·X = f (1)where f = [2, 3, 7] is the vector of arc weights — called the flow — and the unknown vector X is called the potential.
Since the system is inconsistent, equation (1) has no exact solution. Instead, PM solves the normal equation:
Aᵀ·A·X = Aᵀ·f (2)The Solution
The solution X of equation (2) is unique up to a constant. The constraint ∑ Xᵢ = 0 forces the solution into the natural subspace R(A), giving a unique canonical least squares solution.
Inconsistent case (f = [2, 3, 7], n = 3):
- Δ₁ = 0 - (2 + 7) = -9 → X₁ = -9/3 = -3.000
- Δ₂ = 2 - 3 = -1 → X₂ = -1/3 ≈ -0.333
- Δ₃ = (3 + 7) - 0 = 10 → X₃ = 10/3 ≈ 3.333
Check: ∑ Xᵢ = (-9 - 1 + 10) / 3 = 0 ✓
In general, the rank of A equals n - k, where k is the number of connected components of the underlying graph. On each component the reduced system has a unique solution under the zero-sum constraint.
Note: The constraint ∑ Xᵢ = 0 is more appropriate than grounding one node to zero. Grounding arbitrarily privileges one node; the zero-sum constraint treats all nodes symmetrically and places the solution in the natural subspace R(A).
Inconsistency
The inconsistency of the input data is measured by the angle between the flow vector f and its orthogonal projection onto R(A):
- inc = 0° — perfectly consistent data. f lies exactly in R(A) and the potential solution is exact.
- inc > 0° — inconsistent data. PM finds the least squares solution — the closest consistent approximation to f in R(A).
For the timing example with f = [2, 3, 7]:
inc = 8.43°This is a small angle — the new evidence is not wildly contradictory, just slightly inconsistent with the previous observations. The potential method finds the best possible solution given this mild inconsistency, rather than refusing to compute or silently ignoring it.
The following table gives suggested acceptance levels by number of nodes, from the published reference:
| n (nodes) | α (degrees) |
|-----------|-------------|
| 4 | 5.3 |
| 5 | 9.9 |
| 6 | 12.7 |
| 7 | 14.7 |
| 8 | 16.1 |Reference: Measure of Inconsistency for the Potential Method. In: Torra, V., Narukawa, Y., López, B., Villaret, M. (eds) Modeling Decisions for Artificial Intelligence. MDAI 2012. Lecture Notes in Computer Science, vol 7647. Springer, Berlin, Heidelberg.
Note: For n = 3 nodes there were insufficient statistical arguments to establish a meaningful bound. No suggested level is given for n < 4.
The Timing Example in Software
The timing story maps directly to a timing_ex.dat input
file. Here is the inconsistent case (f = [2, 3, 7]):
[project]
project_name = Timing ;
[nodes]
nodes_names = A, B, C ;
[arcs]
heads = B, C, C ;
tails = A, B, A ;
fvalues = 2, 3, 7 ;
[option]
# base = 2 ;
xrange = 0,5 ;
# aggregation = average ;The lines
# base = 2 ;
# aggregation = average ;are ignored because they are commented. The default value
base = 1.5 is used.
Running the analysis:
./compute_potentials -f ./data/flow_data/timing_ex.dat -s --flow-analysisgives the following output:
-----------------------------------
Project: Timing
-----------------------------------
idx node potential weights
--- ------ --------- -------
3 C 5.0000 0.7676
2 B 2.1053 0.1736
1 A 0.0000 0.0589
inc. 8.43 (deg)
----------------------------
Inconsistency by cycles:
----------------------------
cycle sum
--------------------- ------
2-3-1-2 -2
----------------------------
Ordinal preference:
----------------------------
flow projection sign
--------- ---------- ----
2.00 2.67 +
3.00 3.67 +
7.00 6.33 +
------------------------------------
Semantic preference violation:
------------------------------------
No semantic preference violence detected.
base: 1.5
xrange: 0,5
arcs_norm: none
aggregation: None
--file: data/flow_data/timing_ex.datThe potentials are: - A = 5.0000 = X₁ ✓ - B = 2.1053 = X₂ ✓ - C = 0.0000 = X₃ ✓
And inc = 8.43° show the measure if inconsistency.
For the consistent case (f = [2, 3, 5]), using
--xrange 0,5 to set boundary conditions A = 0, C = 5:
./compute_potentials -f ./data/flow_data/timing_ex.dat -s --xrange 0,5Output:
-----------------------------------
Project: Timing.
-----------------------------------
idx node potential weights
--- ------ --------- -------
3 C 5.0000 0.7003
2 B 2.0000 0.2075
1 A 0.0000 0.0922
inc. 0 (deg)
base: 1.5
xrange: 0,5
aggregation: None
--file: ./data/flow_data/timing_ex.datinc = 0° confirms perfect consistency. The potentials recover the exact solution: A = 0, B = 2, C = 5.
There are three more sections in flow_analysis:
Inconsistency by cycles
Ordinal preference
Semantic preference violationEach of them we shall comment at the end of this document.
Multigraph Example
If you compute:
./compute_potentials -f ./data/flow_data/multigraph.dat -s --show-graphyou will obtain a graph image
which is saved in the directory multigraph_output
alongside with the file multigraph.dat.
In the legend, nodes are ranked from higher to lower node weight value. The colors and size of the node follow such ranking.
The solid lines are the arcs of the generating tree, and the dashed lines are the chords of that tree. There is a one-to-one correspondence between chords and cycles. The number next to the arc of the tree and the chord is the weight of that arc (the intensity of the preference), and the number in parentheses next to the chord is the sum of the weights of the arcs along the corresponding cycle (the inconsistency of the cycle).
The command ./compute_potentials with flag:
--flow-analysis will produce the full inconsistency
analysis:
-----------------------------------
Project: Multigraph
-----------------------------------
idx node potential weights
--- ------ --------- -------
1 A 0.8176 0.2751
2 B 1.6783 0.3899
3 C -3.4037 0.0497
4 D 0.9078 0.2853
inc. 65.91 (deg)
----------------------------
Inconsistency by cycles:
----------------------------
cycle sum
--------------------- ------
3-2-4-3 2
2-4-2 15
2-1-3-4-2 8
2-3-4-2 15
1-2-4-3-1 9
1-2-4-3-1 13
3-2-4-3 -1
2-1-3-4-2 -2
4-2-4 -5
1-3-1 17
----------------------------
Ordinal preference:
----------------------------
flow projection sign
--------- ---------- ----
1.00 -0.86 -
2.00 0.77 +
3.00 4.31 +
4.00 -4.22 -
5.00 -5.08 -
6.00 0.86 +
7.00 0.77 +
8.00 -0.77 -
9.00 5.08 +
10.00 0.86 +
11.00 -0.86 -
12.00 5.08 +
13.00 4.22 +
------------------------------------
Weak semantic preference violation:
------------------------------------
i j f-diff p-diff
--- --- ------ --------------
1 4 -3 3.3606557377
1 5 -4 4.2213114754
2 4 -2 4.9918032787
2 5 -3 5.8524590164
2 8 -6 1.5409836066
2 11 -9 1.631147541
3 4 -1 8.5327868852
3 5 -2 9.393442623
3 6 -3 3.4508196721
3 7 -4 3.5409836066
3 8 -5 5.0819672131
3 10 -7 3.4508196721
3 11 -8 5.1721311475
3 13 -10 0.0901639344
4 5 -1 0.8606557377
6 7 -1 0.0901639344
6 8 -2 1.631147541
6 11 -5 1.7213114754
7 8 -1 1.5409836066
7 11 -4 1.631147541
8 11 -3 0.0901639344
9 10 -1 4.2213114754
9 11 -2 5.9426229508
9 13 -4 0.8606557377
10 11 -1 1.7213114754
12 13 -1 0.8606557377
base: 1.5
arcs_norm: none
aggregation: None
--file: data/flow_data/multigraph.datIn the Inconsistency by cycles section of the output you
will recognize the numbers along the chords (dashed lines on the graph).
In the Ordinal inconsistency section of the output the sign
of flow component (preference intensity) and difference of the potential
between the head and the tail of the corresponding arc (projection)are
compared. If the signs match, the potential preserves the preference,
otherwise the preference inversion occurs.
Semantic preference
MACBETH (Measuring Attractiveness by a Categorical Based Evaluation
Technique), developed by Carlos A. Bana e Costa and Jean-Claude
Vansnick, utilizes semantic judgements to allow decision-makers to
express preferences qualitatively rather than through direct numerical
values. We borrowed the termin semantic preference from
their article.
The potential method does not use categorical values and qualitative
preferences at all. The intensity of preference between two alternatives
is the only and primary information that the user needs to evaluate as a
non-negative real number. We denote by F_ij the intensity
of preference i >= j, also denoted as
(i <- j). If F_ij = 0, this means that the
alternatives are considered equivalent.
We are searching for a value function X on the set of
alternatives which satisfies two conditions (S denotes the
set of alternatives):
Condition 1. (ordinal condition)
For all i,j from S: i <- j iff X(i) >= X(j) Condition 2. (weak semantic condition)
F_ij >= F_uv implies X(i) - X(j) >= X(u) - X(v)
Strong semantic condition is
Condition 2a. (strong semantic condition)
F_ij > F_uv implies X(i) - X(j) > X(u) - X(v),
and it is easier to satisfy it than
weak semantic condition.
No violation of weak semantic preference means that
X is measurable value function.
How to recognize strong semantic condition?
In the following output, you may recognize a violation of the weak semantic condition, but not the violation of the strong one.
------------------------------------
Weak semantic preference violation:
------------------------------------
i j f-diff p-diff
--- --- ------- -------
1 2 0.0000 -0.3333
1 6 0.0000 0.3333
2 6 0.0000 0.6667
3 9 0.0000 -1.0000
3 15 0.0000 -0.3333
4 10 0.0000 -1.0000
5 7 0.0000 -0.6667
5 8 0.0000 -1.0000
7 8 0.0000 -0.3333
9 12 0.0000 1.0000
9 15 0.0000 0.6667
11 14 0.0000 -0.3333
12 15 0.0000 -0.3333Prerequisites
All apps run without any additional software. R is an
optional bonus that enables graph visualization output
(.svg and .png). If R is not installed, all
analysis results are still computed and printed normally — only the
graph drawing is skipped.
Optional: Install R for graph visualization
Download and install R from: https://www.r-project.org/ or eventualy RStudio form https://posit.co/download/rstudio-desktop.
Then install the required R libraries:
From RStudio (or equivalent):
install.packages(c('dplyr', 'igraph', 'readr', 'stringr', 'RColorBrewer'))A suggestion: Try to install one by one library if something went wrong.
Mathematical Foundation
The timing example introduces the core concept. The following worked examples in TABLE_APP.md build on this foundation:
- Buying a House — practical MCDM with flow normalization, criteria weights, missing data, and stability analysis.
- Missing Data Showcase — mathematical demonstration of harmonic interpolation: the method exactly recovers a complete sequence of perfect squares from observations split alternately across two criteria with extreme missing data.
For the full mathematical foundation — the discrete Laplace equation, the Sobolev space analogy, — see the Mathematical Showcase section of the TABLE_APP document.