TokenFlowMarket

TokenFlowMarket is a Julia/JuMP research package for modeling token-flow markets for geographically distributed AI compute and GenAI services. It provides network-clearing models, multi-period dispatch, extended cost formulations, economic dispatch models, analysis utilities, examples, and a Python dashboard for interactive exploration.

Various GenAI models from CahtGPT, Claude, Gemini have been used to assist in developing the code and examples in this repository.

Features

• Network token-flow clearing with baseline LP, transfer-aware LP, and congestion-aware QP formulations.
• Multi-period token-flow optimization with time-varying demand profiles.
• Extended operating cost models for PUE, accelerators, demand charges, carbon costs, and two-part tariffs.
• Copper-plate economic dispatch models for AI service supply without network constraints.
• Dual, settlement, sensitivity, and market-metric analysis tools.
• Dashboard exports and a Dash/Plotly app for maps, dispatch charts, prices, and scenario comparison.

Repository Layout

src/          Julia package source
examples/     Runnable case studies
test/         Unit and integration tests
data/raw/     Small public input datasets used by examples and tests
scripts/      Data export and utility scripts
dashboard/    Python Dash dashboard
configs/      Configuration files
notebooks/    Exploratory notebooks

Private research notes and draft materials are intentionally excluded from the public release branch.

Requirements

• Julia 1.10 or newer.
• A JuMP-compatible optimizer. The package defaults to Gurobi.Optimizer, but solver selection is exposed through optimizer_factory, so open-source solvers can also be used.
• Python 3.10 or newer for the dashboard.

Julia Setup

From the repository root:

julia --project=. -e 'using Pkg; Pkg.instantiate()'

Run the test suite:

julia --project=. -e 'using Pkg; Pkg.test()'

Run an example:

julia --project=. examples/case_study_5node.jl

Solver Selection

Most model builders and the high-level clear_market interface accept an optimizer_factory keyword. If it is omitted, the current default is Gurobi.Optimizer. To use an open-source solver, install a JuMP/MOI-compatible optimizer and pass it explicitly.

For example, with HiGHS:

using HiGHS
using TokenFlowMarket

sol = clear_market(sc;
    formulation = :baseline_lp,
    optimizer_factory = HiGHS.Optimizer,
)

LP-based formulations, multi-period models, and economic dispatch require a linear optimizer. The congestion-aware QP formulation requires an optimizer with quadratic-program support.

Dashboard

Generate dashboard data:

julia --project=. scripts/export_dashboard_data.jl

Start the Python dashboard:

python3 -m venv dashboard/.venv
source dashboard/.venv/bin/activate
pip install -r dashboard/requirements.txt
cd dashboard
python app.py

Open http://localhost:8050.

Basic Usage

using TokenFlowMarket

sc = build_scenario(
    hub_csv = "data/raw/us_dc_hubs.csv",
    price_csv = "data/raw/eia_state_prices.csv",
    node_ids = [1, 2, 3, 5, 11],
    demand_scale = 35.0,
    name = "us_5node",
)

sol = clear_market(sc; formulation = :baseline_lp)
metrics = compute_metrics(sol, sc)

println(sol.status)
println(metrics["objective_per_hour"])

Citation

If you use this code, please cite:

Shaohui Liu. 2026. Locational Pricing for Generative-AI Services via Token-Flow Market Clearing. In ACM Sustainability Week 2026 (ACM Sustainability Week Companion '26), June 22--25, 2026, Banff, AB, Canada. ACM, New York, NY, USA, 8 pages. https://doi.org/10.1145/3765611.3815064

License

MIT License. See LICENSE.