Potential Method Apps — User Manual

Overview

This distribution contains five applications for multi-criteria decision making and preference analysis based on the Potential Method:

More detailed instructions for using each of the mentioned applications are given in separate files.

Prerequisites

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, with a clear warning message.

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.

Installation

No installation needed. Unzip the distribution and run the apps directly from the distribution folder.

⚠️ Important: Always run apps from the pm_linux/ (or pm_win\) folder so that config files and data paths are found correctly.

Linux:

cd pm_linux
./compute_potentials --help

Windows (Command Prompt):

cd pm_win
compute_potentials.exe --help

Configuration

Two config files sit in the distribution root:

flow.config

— for compute_potentials and compute_potentials_gui

# flow.config
[paths]
data_input_dir  = data/flow_data
data_output_dir = data/flow_data
rlib_dir        = Rlib
plot_script     = plot.R

choice.config

— for choice and choice_gui

# choice.config — single config for both choice binary and triangle-picker GUI
[paths]
### paths for 'choice' binary
data_input_dir  = data/choice_data
data_output_dir = data/choice_data
rlib_dir        = Rlib
plot_script     = plot.R

### paths for triangle-picker GUI
input_file  = data/choice_data/names.cho
names_file  = data/choice_data/names.txt

Note: table requires no config file — all options are specified via CLI flags and the input file.

Paths can be relative (to the folder you run the app from) or absolute (e.g. /home/john/mydata or C:\Users\john\mydata).

Output Structure

Each app writes its results into a subfolder named after the input file. For example, processing multigraph.dat produces:

flow_data/
├── multigraph.dat
└── multigraph_output/
    ├── multigraph.graph_data.txt
    ├── multigraph.png
    ├── multigraph.svg
    └── multigraph.results

The .graph_data.txt file is read by the R-script plot.R to produce the .svg and .png visualizations. You can customize plot.R for your own publications or presentations.

compute_potentials

Solves a potential problem on a weighted directed graph. Input files use the .dat extension.

Quick Start

Linux:

./compute_potentials -f ./data/flow_data/multigraph.dat -s --show-graph

Windows:

compute_potentials.exe -f .\data\flow_data\multigraph.dat -s --show-graph

Input File Format

[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 = 1.5 ;
# aggregation = average ;
# arcs_norm = 4 ;
# xrange = 1, 10 ;
# log_input = true ;

Format notes: - [nodes] is required. List all node names in nodes_names. - [arcs] is the primary arc section. Additional sections named [arcs-label] (e.g. [arcs-Tommy]) are merged into the same graph — useful for testing multiple arc sets without losing data. - heads and tails use node names, not indices. - [option] settings are optional. Commented-out lines show available options without activating them. - # starts a comment — everything after it on the same line is ignored.

⚠️ Important: Node names in heads and tails must exactly match the names declared in nodes_names. Mismatches produce a clear error message.

Tip: Keep node names short — 1 to 4 characters is ideal.

Tip: A careful user may organize arc sections so that each [arcs-*] section contains arcs with only one head/tail pair. This makes individual relationships easy to read, audit, and modify independently. For example: ```toml [arcs-AB] heads = B ; tails = A ; fvalues = 3 ;

[arcs-BA] heads = A ; tails = B ; fvalues = 2 ; ```

Options

Tip: During repeated testing prefer --draw-graph over --show-graph — the viewer opening on every run becomes disruptive when rapidly changing data.

Output Example

-----------------------------------
Project: Timing.
-----------------------------------
  idx     node  potential   weights
  ---   ------  ---------   -------
    3        C     3.3333    0.7676
    2        B    -0.3333    0.1736
    1        A    -3.0000    0.0589
  inc. 8.43 (deg)
base: 1.5
aggregation: None
  --file: ./data/flow_data/timing_ex.dat

Reading the output: - potential — the raw potential value at each node - weights — normalized weights (sum to 1), the primary ranking result - inc — inconsistency angle in degrees. Lower is better. A value of 0° means perfectly consistent input data.

The footer records all active settings and serves as a reproducibility record — paste the output anywhere and the exact settings are always preserved with it.

Inconsistency Guide

Note: No bound is established for n < 4.

More sophisticated output

The flag --flow-analysis provides two additional pieces of information: Inconsistency by cycles and Ordinal inconsistency. The first gives the sum of weights allong each cycle so that user can see the main source of inconsistency. The seccond compares the signs of given flow and it's projection on the space of consistent flows. For the Timing example it looks like this:

  ----------------------------
    Inconsistency by cycles:
  ----------------------------
                  cycle    sum
  --------------------- ------
                1-2-3-1     -2


  ----------------------------
     Ordinal preference:
  ----------------------------
       flow  projection   sign
  ---------  ----------   ----
       2.00        2.67      +
       3.00        3.67      +
       7.00        6.33      +


  ------------------------------------
   Weak semantic preference violation:
  ------------------------------------

   No weak semantic preference violence detected.

Note. Cycle 0-2-1-0 read as A-C-B-A. i.e. nodes are indexed from 0 (that may chanage soon).

compute_potentials_gui

Graphical interface for compute_potentials. All options are identical to the CLI version.

Linux:

./compute_potentials_gui

Windows:

compute_potentials_gui.exe

The file browser opens the folder specified in data_input_dir in flow.config and shows .dat files only.

choice

Derives weights from ratios and pairwise comparisons. Input files use the .cho extension.

Quick Start

Linux:

./choice -f ./data/choice_data/choice.2-3-5.cho -s

Windows:

choice.exe -f .\data\choice_data\choice.2-3-5.cho -s

Input File Format

name = Choice 2-3-5
A:B = 2:3 ;
B:C:D = 3:5:6 ;
A:D = 2:6 ;

Format notes: - First line is the project name. - Ratios may be pairwise (A:B = 2:3) or multi-way (B:C:D = 3:5:6) and can be freely mixed in the same file. - Each line ends with ;. - Provide enough ratios to keep the graph connected. Redundant ratios are permitted and useful.

Note: Log transformation and sum aggregation are applied internally — the user works only with natural ratios.

Output Example

-----------------------------------
  Project: Choice2-3-5.
  -----------------------------------
    idx     node  potential   weights
    ---   ------  ---------   -------
      1        A    -1.4923    0.1250
      2        B    -0.4923    0.1875
      3        C     0.7675    0.3125
      4        D     1.2172    0.3750
    inc. 0 (deg)
 base: 1.5
 log_input: true
 aggregation: Sum
   --file: data/choice_data/choice.2-3-5.cho

inc. 0° confirms the input ratios are perfectly consistent.

Verification: The file data/flow_data/choice.2-3-5.dat contains the same problem expressed as a graph for compute_potentials. Both apps produce identical results — useful for cross-checking.

Options

Same flags as compute_potentials. See the options table above.

choice_gui

Graphical triangle-picker interface for deriving weights by clicking inside triangles. Each click defines a ratio A:B:C via the barycentric coordinates of the chosen point.

Linux:

./choice_gui

Windows:

choice_gui.exe

Setup

Before running choice_gui, prepare one file in choice_data/:

gui_names.txt — comma-separated list of object names:

X, Y, Z, U

gui_names.cho — will be created by gui with generated ratios which may be used for further calibration and analysis by CLI choice.

Update choice.config to point to your files:

input_file = ./data/choice_data/gui_names.cho
names_file = ./data/choice_data/gui_names.txt

Note: If input_file is not provided in choice.config, choice_gui will automatically generate an input file named gui_names.cho in the current directory.

Workflow

1. Launch choice_gui — it reads node names from gui_names.txt and generates all possible triads automatically.
2. For each triad (A, B, C) a triangle is shown on screen. Click a point inside the triangle to define the ratio A:B:C. The closer to a corner, the higher the preference for that object.
3. Skip any triad you are uncertain about.
4. Press Run when satisfied with the coverage.
5. The GUI writes an output .cho file with one line per triad:

X:Y:Z = 305 : 159 : 537 ;

1. Results are shown on a separate output panel designed for printing.
2. The output file can be edited manually and re-run with choice for further refinement.

Note: Provide enough triads to keep the underlying graph connected. The GUI shows all possible triads — you do not need to complete all of them.

table

Multi-criteria table analysis using the Potential Method. No config file needed — all options are via CLI flags and input file.

Quick Start

Example: Buying a House

A decision maker (DM) wants to buy a house. After initial elimination, four houses remain as candidates. The evaluation criteria are: price (kU), size (m²), investment needed to reach desired condition (kU), and location quality.

A) Input File

The input file is a plain text file with a TOML-like structure divided into sections. The file for this example is house.txt:

[project]
name = House ;

[objects]
criteria = price, size, inv, loc ;  # inv = investment (replaces condition)
subjects = H1, H2, H3, H4 ;

[option]
criteria_weights    = -1, 1, -1, 1 ;
criteria_flow_norm  =  8, 4, 3.2, 4 ;

[exclude]
# criteria = loc ;               # uncomment to exclude location
# cells = (H3,inv):(H1,size) ;  # uncomment to exclude specific cells

[data]
250, 100, 80, 1 ;   # H1
130,  80, 50, 9 ;   # H2
310, 120,  0, 6 ;   # H3
180,  95, 30, 3 ;   # H4

File format notes:

• Each section is introduced by a [section_name] header.
• Values are terminated by ;.
• The # character starts a comment — everything after it on the same line is ignored. Comments may appear at the end of a line or occupy an entire line.
• The order of criteria and subjects in [objects] may be swapped, but the order within each list is significant.

⚠️ Important: The order of criteria in [objects] must match the column order in [data], and the order of subjects must match the row order in [data]. Mismatches are not detected automatically and will produce incorrect results without any warning.

• The [exclude] section allows criteria or individual cells to be excluded from analysis without modifying the data. Commented-out lines show the syntax — uncomment to activate.

Key points: - * denotes missing value in [data] section — handled gracefully by the method (not the case in this example). - Criteria weight sign: +1 higher is better, −1 lower is better. - criteria_flow_norm sets the scale for each criterion — this is where trade-offs between criteria are expressed. - The [exclude] section allows temporary exclusion of criteria, subjects, or individual cells without modifying the data. Uncomment a line to activate the exclusion.

B) Running the Analysis

Linux:

./table -f ./data/table_data/house.txt --by-criteria -s

Windows:

table.exe -f .\data\table_data\house.txt --by-criteria -s

Flags explanation:

Note: During development the app is invoked via cargo run -q -p table --. In a release build this is replaced by the compiled binary ./table. All flags and options remain identical.

Main Options

Flow Normalization

criteria_flow_norm is the most important modeling decision in the table app. It sets the scale for each criterion, allowing criteria measured in different units to be compared meaningfully.

The trade-off between criteria is expressed here — not in the criteria weights. If criteria_weights in the input data are not set, all criteria receive equal weight (1) regardless of their scale. Regardless of that, weights may be normalized using the --weights-normalization flag.

Tip: Start by computing the maximum difference across subjects for each criterion, then set criteria_flow_norm proportionally to reflect the relative importance of each criterion's range.

table_gui

Multi-criteria table analysis using the Potential Method via gui. No config file needed — options are the same as for table.

Quick Start

Linux:

./table_gui or ./bin/table_gui

Windows:

table_gui.exe 

The table_gui application offers a bit more than the CLI version table with an emphasis on the ability to dynamically test input data. As for the aforementioned house selection project, it is possible to exclude a cell from processing by clicking the mouse on that cell, which then turns red. It is also possible to exclude a criterion (column) or subject (row) from processing in the same way.

By pressing the Run button, the results are displayed and printed on the right panel, and on the left panel, the row of criteria weights and the column of subject weights are assigned to the table data. Depending on the Solver mode, the input weights are colored yellow and the calculated weights are colored green.

Saving results is enabled by activating the Save results check box. The path of the output file is printed in green above the results. We provide here a complete printout of the saved results with excluded critaria and cells: