cpigjs

This project contains cpigjs, a program written in JavaScript to draw Conditional Predicate Implication Graphs.

The primary application of cpigjs is visualizing implications among fairness notions for the problem of fairly allocating indivisible items. The fairDiv directory contains data on implications between fairness notions, which cpigjs can use to infer additional implications and draw them as a DAG.

See the paper arXiv:2502.02815 for the motivation behind this project and a more mathematically-formal explanation of what this program does. The paper calls this program 'inference engine' instead of cpigjs.

Introduction

There is a set $Φ$ of predicates on a ground set $Ω$ (i.e., functions from $Ω$ to bool). We say that a predicate $a ∈ Φ$ implies another predicate $b ∈ Φ$ conditioned on set $S ⊆ Ω$ if $a(u) ⟹ b(u) ∀ u ∈ S$.

Given a set of conditional implications, cpigjs infers more of them using transitive closure and then displays them as a Hasse diagram.

This is useful to visualize, e.g., implications between fairness notions in the fair division problem. Here the ground set is the set of all allocations across all fair division instances, and the predicates are fairness notions. Implications are often conditional on, e.g., valuation functions being additive, or the items being goods.

The ground set is generally uncountably large (e.g., in fair division), so we cannot explicitly enumerate its members. Instead, we implicitly define a set family $Σ$ over $Ω$ (i.e., $Σ$ is a subset of the power set of $Ω$), and every implication is conditioned on a set from $Σ$.

For the problem of fairly allocating indivisible items, fairDiv/setFamily.json describes the family $Σ$ and fairDiv/data.json describes the predicates and implications.

Setup

1. Install the project's dependencies (npm install).
2. Run npx tsc to compile the typescript code.

How to Run in the Browser

First, generate an HTML file by running npm run buildWeb.

Then serve this project's root directory (i.e., fairDiv's parent directory) using an HTTP server, and open fairDiv/index.html in your web browser.

How to Run with node

Install Graphviz and ensure that the dot command is available on your command line.

To return all implications for additive valuations over goods when agents have equal entitlements (including open problems), and save the output to goods.pdf, run

node scripts/cli.js --sf fairDiv/setFamily.json -i fairDiv/data.json -c '{"valuation": "additive", "marginal": "nonneg", "eqEnt": true}' -o goods.pdf

To output the sequence of implications from EEF (epistemic envy freeness) to MMS (maximin share) for additive valuations, run

node scripts/cli.js --sf fairDiv/setFamily.json -i fairDiv/data.json -c '{"valuation": "additive"}' --pred EEF MMS

To verify the resolution of a large number of settings (i.e., verify that these settings have very few open problems left), run

node scripts/countOpenProblems.js --sf fairDiv/setFamily.json -i fairDiv/data.json -c fairDiv/almost-resolved-settings.json

To create the figures used in the paper and put them in a directory named output, run

node scripts/cli.js bulk --sf fairDiv/setFamily.json -i fairDiv/data.json -c fairDiv/paper-figures.json -o output

To run unit tests, run npx mocha scripts/test.js.