FalcomChain Documentation

FalcomChain is a Python library for hierarchical capacitated facility location and districting via MCMC: it partitions a geographic region into contiguous, demand-balanced districts, places facilities from a candidate set, and — instead of returning one brittle “optimum” — samples an ensemble of near-optimal plans you can interrogate for robust boundaries, essential facilities, and capacity utilization.

FalcomChain’s spanning-tree ReCom-style proposal architecture builds on GerryChain (MGGG Redistricting Lab), extended to hierarchical, capacitated problems with two-level facility assignment.

The FalCom family

Three companion libraries cover the full workflow. This documentation covers all three: FalcomTravel and FalcomPlot each have a dedicated page here rather than separate doc sites.

Library	Role in the pipeline	Documented in
FalcomTravel	Geodata → travel-time matrix (r5r, OSMnx, Dijkstra, Euclidean backends)	Travel Times with FalcomTravel
FalcomChain (this library)	Travel times + graph → MCMC ensemble of districting plans	everything else
FalcomPlot	Ensemble → plots, diagnostics, animations, interactive maps	Visualization with FalcomPlot

How the documentation is organized

Each page has one specific goal, stated at the top. The groups below follow the order of a real project: understand the method, prepare your inputs, run chains, analyze the output.

Start here

• Getting Started
• Algorithm Overview

Prepare your inputs

• Working with GeoDataFrames
• Travel Times with FalcomTravel
• Candidate Feasibility

Run the chain

• Running a FalCom Chain
• Level-2 (Super-) Facilities
• Optimization Methods
• Fixed Superdistricts

Analyze the ensemble

• Ensemble Analysis
• Visualization with FalcomPlot

Case study

• Case Study: Working with Real Data

Tutorials

• Quickstart: First Chain on a Synthetic Grid

Project

• Reproducibility
• Contributing

Reference

• Graph Attribute Schema
• FalcomChain API

Indices

• Index

• Module Index

• Search Page