maritime-choke 0.1.0__tar.gz

maritime_choke-0.1.0/LICENSE

@@ -0,0 +1,25 @@
+MIT License
+
+Copyright (c) 2026 Fathimath S. Vemmarath and Vipin P. Veetil
+
+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.
+
+Note: This licence covers the source code only. The underlying economic data
+(GTAP, OECD ICIO) are governed by their own licences and are not distributed
+with this software.

maritime_choke-0.1.0/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.4
+Name: maritime-choke
+Version: 0.1.0
+Summary: Interactive model of macroeconomic risk from maritime-chokepoint trade disruptions
+Author: Fathimath S. Vemmarath
+Author-email: "Vipin P. Veetil" <vipin.veetil@gmail.com>
+License: MIT
+Project-URL: Homepage, https://bitbucket.org/VipinVeetil/chokepoints
+Project-URL: Source, https://bitbucket.org/VipinVeetil/chokepoints
+Keywords: production networks,input-output,maritime,chokepoints,trade disruption,systemic risk,economics,supply chains
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering
+Classifier: Framework :: Flask
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.23
+Requires-Dist: scipy>=1.10
+Requires-Dist: matplotlib>=3.6
+Requires-Dist: flask>=2.2
+Requires-Dist: platformdirs>=2.6
+Requires-Dist: certifi>=2022.0.0
+Provides-Extra: dev
+Requires-Dist: pyshp>=2.3; extra == "dev"
+Requires-Dist: pandas>=1.5; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# maritime-choke
+
+An interactive model of the macroeconomic risk from **maritime-chokepoint trade
+disruptions**. Close any set of the world's 12 major shipping chokepoints, pick a
+`(τ, ρ, δ)` calibration, solve a short-run production-network model forward, and
+explore where the value-added loss falls — on an interactive world heat map, by
+country, and by sector — all in a local browser GUI.
+
+Based on *Macroeconomic Risks from Maritime Trade Disruptions* (Vemmarath &
+Veetil). Source & data: https://bitbucket.org/VipinVeetil/chokepoints
+
+## Install
+
+```bash
+pip install maritime-choke
+```
+
+## Get the data (one-time)
+
+The solver needs a model cache (~180 MB) that isn't shipped in the wheel:
+
+```bash
+maritime-choke fetch-data          # downloads and installs it
+```
+
+(You can also point at a local copy: `maritime-choke fetch-data --from-local /path/to/model_cache_2019`.)
+
+## Run
+
+```bash
+maritime-choke run                 # opens the GUI at http://127.0.0.1:5057
+```
+
+Pick chokepoints, set the calibration, hit **Run scenario**. Results are written
+to a per-user folder (see `maritime-choke where`) and shown in the page:
+world value-added loss, a relatable "scale of the loss" comparison, the world
+heat map (recolour by any of 50 sectors), and per-country / per-sector drill-downs.
+
+## Commands
+
+| command | what it does |
+|---|---|
+| `maritime-choke run` | launch the GUI (`--port`, `--no-browser`) |
+| `maritime-choke fetch-data` | download/install the model cache (`--url`, `--from-local`, `--force`) |
+| `maritime-choke pack-data <dir>` | pack a local cache into a `.tar.xz` for hosting |
+| `maritime-choke where` | show data / cache / run-output locations |
+| `maritime-choke build-data` | how to rebuild the cache from GTAP + OECD ICIO |
+
+Data locations can be overridden with `MARITIME_CHOKE_DATA` (cache root) and
+`MARITIME_CHOKE_RUNS` (run outputs). The download URL can be set with
+`MARITIME_CHOKE_DATA_URL`.
+
+## Data & licensing
+
+The model cache is derived from OECD ICIO (freely downloadable) and the licensed
+**GTAP 10** data base. The raw GTAP data is *not* redistributed; if you need to
+rebuild the cache from scratch you must supply your own GTAP licence — see
+`maritime-choke build-data`. The shipped map/comparison assets are built from
+public Natural Earth and World Bank data.
+
+## License
+
+MIT (code). Underlying GTAP and OECD ICIO data are governed by their own terms.

maritime_choke-0.1.0/README.md

@@ -0,0 +1,63 @@
+# maritime-choke
+
+An interactive model of the macroeconomic risk from **maritime-chokepoint trade
+disruptions**. Close any set of the world's 12 major shipping chokepoints, pick a
+`(τ, ρ, δ)` calibration, solve a short-run production-network model forward, and
+explore where the value-added loss falls — on an interactive world heat map, by
+country, and by sector — all in a local browser GUI.
+
+Based on *Macroeconomic Risks from Maritime Trade Disruptions* (Vemmarath &
+Veetil). Source & data: https://bitbucket.org/VipinVeetil/chokepoints
+
+## Install
+
+```bash
+pip install maritime-choke
+```
+
+## Get the data (one-time)
+
+The solver needs a model cache (~180 MB) that isn't shipped in the wheel:
+
+```bash
+maritime-choke fetch-data          # downloads and installs it
+```
+
+(You can also point at a local copy: `maritime-choke fetch-data --from-local /path/to/model_cache_2019`.)
+
+## Run
+
+```bash
+maritime-choke run                 # opens the GUI at http://127.0.0.1:5057
+```
+
+Pick chokepoints, set the calibration, hit **Run scenario**. Results are written
+to a per-user folder (see `maritime-choke where`) and shown in the page:
+world value-added loss, a relatable "scale of the loss" comparison, the world
+heat map (recolour by any of 50 sectors), and per-country / per-sector drill-downs.
+
+## Commands
+
+| command | what it does |
+|---|---|
+| `maritime-choke run` | launch the GUI (`--port`, `--no-browser`) |
+| `maritime-choke fetch-data` | download/install the model cache (`--url`, `--from-local`, `--force`) |
+| `maritime-choke pack-data <dir>` | pack a local cache into a `.tar.xz` for hosting |
+| `maritime-choke where` | show data / cache / run-output locations |
+| `maritime-choke build-data` | how to rebuild the cache from GTAP + OECD ICIO |
+
+Data locations can be overridden with `MARITIME_CHOKE_DATA` (cache root) and
+`MARITIME_CHOKE_RUNS` (run outputs). The download URL can be set with
+`MARITIME_CHOKE_DATA_URL`.
+
+## Data & licensing
+
+The model cache is derived from OECD ICIO (freely downloadable) and the licensed
+**GTAP 10** data base. The raw GTAP data is *not* redistributed; if you need to
+rebuild the cache from scratch you must supply your own GTAP licence — see
+`maritime-choke build-data`. The shipped map/comparison assets are built from
+public Natural Earth and World Bank data.
+
+## License
+
+MIT (code). Underlying GTAP and OECD ICIO data are governed by their own terms.

maritime_choke-0.1.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["setuptools>=64", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "maritime-choke"
+version = "0.1.0"
+description = "Interactive model of macroeconomic risk from maritime-chokepoint trade disruptions"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [
+    { name = "Fathimath S. Vemmarath" },
+    { name = "Vipin P. Veetil", email = "vipin.veetil@gmail.com" },
+]
+keywords = [
+    "production networks", "input-output", "maritime", "chokepoints",
+    "trade disruption", "systemic risk", "economics", "supply chains",
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering",
+    "Framework :: Flask",
+]
+dependencies = [
+    "numpy>=1.23",
+    "scipy>=1.10",
+    "matplotlib>=3.6",
+    "flask>=2.2",
+    "platformdirs>=2.6",
+    "certifi>=2022.0.0",
+]
+
+[project.optional-dependencies]
+# tools to regenerate the shipped static assets / build & publish the package
+dev = ["pyshp>=2.3", "pandas>=1.5", "build", "twine"]
+
+[project.scripts]
+maritime-choke = "maritime_choke.cli:main"
+
+[project.urls]
+Homepage = "https://bitbucket.org/VipinVeetil/chokepoints"
+Source = "https://bitbucket.org/VipinVeetil/chokepoints"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+maritime_choke = ["templates/*.html", "static/*.json"]

maritime_choke-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

maritime_choke-0.1.0/src/maritime_choke/__init__.py

@@ -0,0 +1,21 @@
+"""
+maritime-choke
+==============
+A short-run production-network model of maritime-chokepoint trade disruption,
+with an interactive local web GUI. Close any set of the world's major shipping
+chokepoints, pick a (tau, rho, delta) calibration, solve the model forward, and
+explore where the value-added loss falls on a world heat map and by sector.
+
+Quickstart:
+    maritime-choke fetch-data      # one-time: install the model cache (~180 MB)
+    maritime-choke run             # launch the GUI in your browser
+"""
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+
+def run(port: int | None = None, open_browser: bool = True) -> None:
+    """Launch the GUI (same as `maritime-choke run`)."""
+    from .app import serve
+    serve(port=port, open_browser=open_browser)

maritime_choke-0.1.0/src/maritime_choke/app.py

@@ -0,0 +1,187 @@
+"""
+app.py -- local web GUI for the maritime-chokepoint disruption model.
+
+Run:
+    cd 02_scripts/gui
+    ../../.venv_gui/bin/python app.py           # then open http://127.0.0.1:5000
+
+Pick which chokepoints to close and the (tau, rho, delta) calibration, press
+Run, and the model solves forward. Each run writes a self-contained folder
+under 04_outputs/gui_runs/<run_id>/ (config, summary, per-country CSV, two
+PNG plots) and the headline numbers are shown in the page.
+
+Solves run in a background thread; the page polls /api/progress for the live
+outer-iteration count and h-residual, then renders the results.
+"""
+from __future__ import annotations
+
+import threading
+import time
+import traceback
+from pathlib import Path
+
+from flask import (Flask, jsonify, render_template, request,
+                   send_from_directory, abort)
+
+from . import solver_backend as sb
+
+app = Flask(__name__)
+
+# In-memory registry of runs started this session: run_id -> state dict.
+RUNS: dict[str, dict] = {}
+_LOCK = threading.Lock()
+
+
+def _worker(run_id: str, cfg: dict) -> None:
+    state = RUNS[run_id]
+    try:
+        summary = sb.run_scenario(cfg, progress=state["progress"])
+        state["status"] = "done"
+        state["summary"] = summary
+    except Exception as e:                        # noqa: BLE001
+        state["status"] = "error"
+        state["error"] = f"{e}"
+        state["traceback"] = traceback.format_exc()
+        state["progress"]["phase"] = "error"
+
+
+@app.route("/")
+def index():
+    return render_template(
+        "index.html",
+        chokepoints=sb.chokepoint_labels(),
+        caches=sb.list_caches(),
+        presets=sb.PRESETS,
+        mapmeta=sb.map_metadata(),
+    )
+
+
+@app.route("/api/run", methods=["POST"])
+def api_run():
+    body = request.get_json(force=True)
+    Q = [int(k) for k in body.get("Q", [])]
+    if not Q:
+        return jsonify(error="Select at least one chokepoint to close."), 400
+
+    energy_specific = bool(body.get("energy_specific", True))
+    base_delta = float(body.get("base_delta", 0.10))
+    energy_delta = (float(body.get("energy_delta", 0.45))
+                    if energy_specific else None)
+
+    run_id = body.get("run_id") or f"run_{int(time.time())}"
+    # keep run_id filesystem-safe
+    run_id = "".join(ch for ch in run_id if ch.isalnum() or ch in "-_")[:60]
+
+    cfg = dict(
+        Q=Q,
+        tau=float(body.get("tau", 0.3)),
+        rho=float(body.get("rho", -0.5)),
+        base_delta=base_delta,
+        energy_delta=energy_delta,
+        cache=body.get("cache") or "model_cache_2019",
+        max_outer=int(body.get("max_outer", 600)),
+        run_id=run_id,
+    )
+
+    with _LOCK:
+        # one heavy solve at a time keeps the CPU sane on a laptop
+        busy = any(s["status"] == "running" for s in RUNS.values())
+        if busy:
+            return jsonify(error="A solve is already running; wait for it "
+                                 "to finish."), 409
+        RUNS[run_id] = {
+            "status": "running",
+            "cfg": cfg,
+            "progress": {"phase": "queued", "iter": 0,
+                         "max_iter": cfg["max_outer"], "residual": None,
+                         "elapsed": 0.0},
+            "summary": None,
+            "error": None,
+        }
+    t = threading.Thread(target=_worker, args=(run_id, cfg), daemon=True)
+    t.start()
+    return jsonify(run_id=run_id)
+
+
+@app.route("/api/progress/<run_id>")
+def api_progress(run_id: str):
+    state = RUNS.get(run_id)
+    if state is None:
+        return jsonify(error="unknown run_id"), 404
+    return jsonify(
+        status=state["status"],
+        progress=state["progress"],
+        summary=state["summary"],
+        error=state["error"],
+    )
+
+
+@app.route("/api/runs")
+def api_runs():
+    """List past runs on disk (most recent first)."""
+    import json
+    out = []
+    if sb._runs_dir().exists():
+        for d in sb._runs_dir().iterdir():
+            sfile = d / "summary.json"
+            if sfile.exists():
+                try:
+                    s = json.loads(sfile.read_text())
+                    out.append({
+                        "run_id": s.get("run_id", d.name),
+                        "closed": s.get("closed_chokepoints", []),
+                        "world_lambda_pct": s.get("world_lambda_pct"),
+                        "params": s.get("params", {}),
+                        "mtime": sfile.stat().st_mtime,
+                    })
+                except Exception:                 # noqa: BLE001
+                    pass
+    out.sort(key=lambda r: r["mtime"], reverse=True)
+    return jsonify(runs=out)
+
+
+@app.route("/runs/<run_id>/<path:filename>")
+def serve_run_file(run_id: str, filename: str):
+    run_id = "".join(ch for ch in run_id if ch.isalnum() or ch in "-_")
+    d = sb._runs_dir() / run_id
+    if not d.exists():
+        abort(404)
+    return send_from_directory(d, filename)
+
+
+def _free_port(preferred: int) -> int:
+    """Return `preferred` if free, else an OS-assigned free port."""
+    import socket
+    for cand in (preferred, 0):
+        s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        try:
+            s.bind(("127.0.0.1", cand))
+            return s.getsockname()[1]
+        except OSError:
+            continue
+        finally:
+            s.close()
+    return preferred
+
+
+def serve(port: int | None = None, open_browser: bool = True) -> None:
+    """Launch the local GUI server (used by the `maritime-choke run` command)."""
+    import os
+    if port is None:
+        port = int(os.environ.get("PORT", "5057"))
+    port = _free_port(port)
+    url = f"http://127.0.0.1:{port}"
+    print(f"maritime-choke GUI  ->  {url}")
+    print("Run outputs are written to:", sb._runs_dir())
+    if not sb.list_caches():
+        print("\n[!] No model cache found. Run `maritime-choke fetch-data` first "
+              "(or set MARITIME_CHOKE_DATA to a folder that holds model_cache_2019/).\n")
+    if open_browser:
+        import threading
+        import webbrowser
+        threading.Timer(1.0, lambda: webbrowser.open(url)).start()
+    app.run(host="127.0.0.1", port=port, debug=False, threaded=True)
+
+
+if __name__ == "__main__":
+    serve()

maritime_choke-0.1.0/src/maritime_choke/chokepoint_names.py

@@ -0,0 +1,43 @@
+"""
+chokepoint_names.py
+===================
+Single source of truth for the three chokepoint name forms used across the
+pipeline, in the canonical meta.json order (k = 0..11):
+
+  FULL  : meta["chokepoints"]  -- table row labels, captions
+  CSV   : short keys used as the master-matrix CSV columns and by
+          verification/verify_ras_prose.py (e.g. "Hormuz", "Bab-el-Mandeb")
+  NICE  : compact display labels for figure axes / joint constituents
+          (e.g. "BAM/Aden", "Malacca-Sing.")
+
+Before this module the committed outputs used CSV columns while the committed
+05_figures.py used FULL columns + a FULL->NICE map, so the script could not
+regenerate the committed CSV/figures. All scripts now import these maps so the
+naming is consistent end to end.
+"""
+
+FULL = [
+    "Strait of Hormuz", "Turkish Straits", "Danish Straits", "Suez Canal",
+    "Bab-el-Mandeb", "Strait of Gibraltar", "Strait of Malacca", "Panama Canal",
+    "Taiwan-Luzon Corridor", "Strait of Dover", "Korea Strait", "Kerch Strait",
+]
+CSV = [
+    "Hormuz", "Turkish", "Danish", "Suez", "Bab-el-Mandeb", "Gibraltar",
+    "Malacca", "Panama", "Taiwan-Luzon", "Dover", "Korea", "Kerch",
+]
+NICE = [
+    "Hormuz", "Turkish", "Danish", "Suez", "BAM/Aden", "Gibraltar",
+    "Malacca-Sing.", "Panama", "Taiwan-Luzon", "Dover", "Korea", "Kerch",
+]
+
+assert len(FULL) == len(CSV) == len(NICE) == 12
+
+full_to_csv = dict(zip(FULL, CSV))
+full_to_nice = dict(zip(FULL, NICE))
+csv_to_full = dict(zip(CSV, FULL))
+csv_to_nice = dict(zip(CSV, NICE))
+
+
+def to_csv_columns(full_names):
+    """Map an ordered list of FULL chokepoint names to CSV-short columns."""
+    return [full_to_csv[c] for c in full_names]

maritime_choke-0.1.0/src/maritime_choke/cli.py

@@ -0,0 +1,101 @@
+"""
+cli.py — the `maritime-choke` command.
+
+    maritime-choke run                 launch the interactive GUI (opens a browser)
+    maritime-choke fetch-data          download/install the model cache
+    maritime-choke pack-data <dir>     pack a local cache into an uploadable archive
+    maritime-choke where               show data / cache / run-output locations
+    maritime-choke build-data          how to rebuild the cache from GTAP + OECD ICIO
+"""
+from __future__ import annotations
+
+import argparse
+
+from . import __version__, data
+
+BUILD_HELP = """\
+Rebuild the model cache from raw inputs (for users with their own GTAP licence)
+------------------------------------------------------------------------------
+The cache is derived from OECD ICIO (freely downloadable) and the licensed
+GTAP 10 data base. To rebuild it, use the source repository's pipeline:
+
+  git clone https://bitbucket.org/VipinVeetil/chokepoints
+  # place your GTAP .har files and the OECD ICIO tables under 01_raw_data/
+  cd chokepoints/02_scripts
+  python3 pipeline/00_extract_gtap_har.py
+  python3 pipeline/01_build_extended_table_fast.py --year 2019
+  python3 pipeline/02_build_inputs_k12.py
+
+That writes 03_intermediate/model_cache_2019/. Then install it into
+maritime-choke's data dir:
+
+  maritime-choke fetch-data --from-local <path>/03_intermediate/model_cache_2019
+
+See DATA_AVAILABILITY.md in that repo for the licence notes.
+"""
+
+
+def main(argv=None) -> None:
+    p = argparse.ArgumentParser(
+        prog="maritime-choke",
+        description="Interactive model of macroeconomic risk from "
+                    "maritime-chokepoint trade disruptions.")
+    p.add_argument("--version", action="version",
+                   version=f"maritime-choke {__version__}")
+    sub = p.add_subparsers(dest="cmd")
+
+    pr = sub.add_parser("run", help="launch the interactive GUI")
+    pr.add_argument("--port", type=int, default=None, help="port (default 5057)")
+    pr.add_argument("--no-browser", action="store_true",
+                    help="do not open a browser window")
+
+    pf = sub.add_parser("fetch-data", help="download/install the model cache")
+    pf.add_argument("--url", default=None, help="explicit archive URL")
+    pf.add_argument("--from-local", default=None,
+                    help="a local cache directory or .tar.xz to install instead")
+    pf.add_argument("--name", default=data.DEFAULT_CACHE, help="cache name")
+    pf.add_argument("--force", action="store_true", help="overwrite if present")
+
+    pp = sub.add_parser("pack-data",
+                        help="pack a local cache dir into an uploadable .tar.xz")
+    pp.add_argument("cache_dir", help="path to a model_cache_* directory")
+    pp.add_argument("-o", "--out", default=None, help="output archive path")
+
+    sub.add_parser("where", help="show data / cache / run-output locations")
+    sub.add_parser("build-data", help="how to rebuild the cache from GTAP + ICIO")
+
+    args = p.parse_args(argv)
+
+    if args.cmd == "run":
+        from . import app
+        app.serve(port=args.port, open_browser=not args.no_browser)
+
+    elif args.cmd == "fetch-data":
+        path = data.fetch(url=args.url, name=args.name,
+                          from_local=args.from_local, force=args.force)
+        print("cache ready at:", path)
+
+    elif args.cmd == "pack-data":
+        out = data.pack(args.cache_dir, args.out)
+        mb = out.stat().st_size / (1 << 20)
+        print(f"wrote {out}  ({mb:.0f} MB)")
+        print("Upload this to Zenodo/Release, then set MARITIME_CHOKE_DATA_URL "
+              "(or DATA_URL in data.py) to its download URL.")
+
+    elif args.cmd == "where":
+        print("data dir   :", data.data_dir())
+        print("caches     :", data.caches_dir())
+        print("run outputs:", data.runs_dir())
+        caches = [p.name for p in data.caches_dir().glob("model_cache*")
+                  if data.is_valid_cache(p)] if data.caches_dir().exists() else []
+        print("installed caches:", caches or "(none — run `maritime-choke fetch-data`)")
+
+    elif args.cmd == "build-data":
+        print(BUILD_HELP)
+
+    else:
+        p.print_help()
+
+
+if __name__ == "__main__":
+    main()