Metadata-Version: 2.4
Name: pgmst
Version: 0.2.0
Summary: Physics-informed graph embedding (SGCN) and multi-objective MST zoning (PGNN + MST).
Project-URL: Homepage, https://github.com/UrbanGISer/PGMST
Project-URL: Documentation, https://github.com/UrbanGISer/PGMST#readme
Project-URL: Repository, https://github.com/UrbanGISer/PGMST
Project-URL: Issues, https://github.com/UrbanGISer/PGMST/issues
Author: PGMST contributors
License: MIT License
        
        Copyright (c) 2025 PGMST contributors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: MST,OD-matrix,community-detection,graph-neural-network,spatial,zoning
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: GIS
Requires-Python: >=3.10
Requires-Dist: geopandas>=0.14
Requires-Dist: libpysal>=4.8
Requires-Dist: networkx>=3.0
Requires-Dist: numpy>=1.24
Requires-Dist: pandas>=2.0
Requires-Dist: scipy>=1.10
Requires-Dist: torch-geometric>=2.4
Requires-Dist: torch>=2.0
Provides-Extra: dev
Requires-Dist: build>=1.0; extra == 'dev'
Requires-Dist: hatch>=1.7; extra == 'dev'
Requires-Dist: twine>=5.0; extra == 'dev'
Description-Content-Type: text/markdown

# PGMST

**P**hysics-informed **G**raph embedding + **M**ulti-objective **ST** (MST-based) regionalization.

Two-stage API:

1. **`pgmst.pgnn.PGNN`** — packaged **SGCN** pipeline (half-life OD weights + spatial glue on contiguity edges). `embed()` appends **`Emb_X` / `Emb_Y`** to your zone table.
2. **`pgmst.mst.MST`** — build an MST on the **spatial adjacency** graph with edge costs from **embedding distance**, then **modularity- and constraint-driven** partitioning (population / hospital / custom caps, minimum localization index).

Optional: GCN-style embedding via `pgmst.physics_graph` + PyTorch Geometric (see example notebook).

## Install

```bash
pip install pgmst
```

For a development editable install from a clone:

```bash
pip install -e ".[dev]"
```

## Quick start

```python
from pgmst import PGNN, MST

coords_emb = PGNN(
    coords_df,
    df_flow,
    id_column="ZoneID",
    w=df_adj,
    k_hops=5,
    w_adj_percentile=75.0,
    coordxy="XCoord,YCoord",
).embed()

pr = MST(
    coords_emb,
    df_flow,
    id_column="ZoneID",
    emb=("Emb_X", "Emb_Y"),
    w=df_adj,
    constraints=[("POPU", "min", 10_000), ("POPU", "max", 500_000), ("hosp", "min", 1)],
    min_local_index=0.3,
).partition()

print(pr.modularity)
print(pr.cluster.head())
```

## Example notebook

After installation, the Florida demo notebook is shipped inside the package:

- **`pgmst/examples/PGMST_Florida_demo.ipynb`**

You can copy it to your working directory or open it from `site-packages/pgmst/examples/`.  
The notebook expects OD/adjacency/shapefile paths: point `REPO` at a checkout of **GNNGeoCommunity** (or your own data) where `data/OD_All_Flows30K.csv`, `data/FLAdjUpdate.csv`, and `data/Florida_2011.zip` live.

## PyPI release

See **[docs/PYPI.md](docs/PYPI.md)** for local builds (`python -m build` / `twine`) and **GitHub Actions** publishing (Trusted Publisher on PyPI).

## Requirements

Python 3.10+, PyTorch, PyTorch Geometric, GeoPandas, NetworkX, SciPy, pandas, NumPy. Queen/Rook contiguity needs **libpysal**.

## License

MIT — see [LICENSE](LICENSE).
