jupedsim-network 0.1.0__tar.gz

jupedsim_network-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,66 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+      - run: uv run pytest
+
+  docs:
+    runs-on: ubuntu-latest
+    env:
+      HUGO_VERSION: 0.144.0
+    steps:
+      - name: Install Hugo CLI
+        run: |
+          wget -O ${{ runner.temp }}/hugo.deb https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb \
+          && sudo dpkg -i ${{ runner.temp }}/hugo.deb
+      - uses: actions/setup-go@v5
+        with:
+          go-version: "1.22"
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # full history for enableGitInfo (last-updated dates)
+      - uses: astral-sh/setup-uv@v6
+      # The figures are not in git: regenerate them from the current code,
+      # so the site never shows a figure the code can no longer produce.
+      - name: Generate figures
+        run: |
+          uv run --group docs python scripts/figures/make_figures.py
+          uv run --group docs python scripts/figures/make_gifs.py
+      - name: Build with Hugo
+        env:
+          HUGO_ENVIRONMENT: production
+        working-directory: site
+        run: hugo --minify --panicOnWarning
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site/public
+
+  deploy:
+    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+    needs: [test, docs]
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

jupedsim_network-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.egg-info/
+.venv/
+build/
+dist/
+.pytest_cache/
+.ruff_cache/
+site/public/
+site/resources/
+.hugo_build.lock
+site/static/images/network/

jupedsim_network-0.1.0/LICENSE

@@ -0,0 +1,14 @@
+License:
+========
+jupedsim-network is free software: you can redistribute it and/or modify
+it under the terms of the GNU Lesser General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+any later version.
+
+jupedsim-network is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU Lesser General Public License
+along with jupedsim-network. If not, see <http://www.gnu.org/licenses/>.

jupedsim_network-0.1.0/PKG-INFO

@@ -0,0 +1,66 @@
+Metadata-Version: 2.5
+Name: jupedsim-network
+Version: 0.1.0
+Summary: Coarse network egress model for fast evacuation-time estimates, companion to JuPedSim
+Project-URL: Documentation, https://pedestriandynamics.org/jupedsim-network/
+Project-URL: Source, https://github.com/PedestrianDynamics/jupedsim-network
+Project-URL: JuPedSim, https://www.jupedsim.org
+License-Expression: LGPL-3.0-or-later
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.26
+Description-Content-Type: text/markdown
+
+# jupedsim-network
+
+A coarse network egress model for fast estimates of evacuation times
+(pre-movement plus movement). Rooms, corridors and stair flights are
+nodes with an area; doors and stair entries are links with a flow
+capacity. Agents move
+through the graph by relations adapted from the SFPE hydraulic model. A run of a
+ten-storey building takes about 0.1 s, so scenarios can be sampled many
+times.
+
+The package is a companion to [JuPedSim](https://www.jupedsim.org): use
+the network model to screen scenarios and find critical cases, and the
+microscopic models of JuPedSim to check geometry details. It depends only
+on NumPy.
+
+The model is a prototype. It is verified against hand calculations but
+not validated against experiments, and it is not intended for
+regulatory or design use; see the
+[limitations](https://pedestriandynamics.org/jupedsim-network/docs/limitations/).
+
+## Install
+
+Python 3.10 or later:
+
+```
+pip install git+https://github.com/PedestrianDynamics/jupedsim-network
+```
+
+## Development
+
+```
+uv sync
+uv run pytest
+uv run ruff check . && uv run ruff format --check .
+```
+
+The documentation is a [Hugo](https://gohugo.io) site with the
+[Hextra](https://imfing.github.io/hextra/) theme in `site/`. Hugo
+(extended) and Go are needed to build it:
+
+```
+uv run --group docs python scripts/figures/make_figures.py
+uv run --group docs python scripts/figures/make_gifs.py
+cd site && hugo server
+```
+
+The figures and animations are not stored in git. The two scripts write
+them to `site/static/images/network/` (about 2 minutes); CI runs them
+before every build.
+
+## License
+
+LGPL-3.0-or-later, as JuPedSim.

jupedsim_network-0.1.0/README.md

@@ -0,0 +1,53 @@
+# jupedsim-network
+
+A coarse network egress model for fast estimates of evacuation times
+(pre-movement plus movement). Rooms, corridors and stair flights are
+nodes with an area; doors and stair entries are links with a flow
+capacity. Agents move
+through the graph by relations adapted from the SFPE hydraulic model. A run of a
+ten-storey building takes about 0.1 s, so scenarios can be sampled many
+times.
+
+The package is a companion to [JuPedSim](https://www.jupedsim.org): use
+the network model to screen scenarios and find critical cases, and the
+microscopic models of JuPedSim to check geometry details. It depends only
+on NumPy.
+
+The model is a prototype. It is verified against hand calculations but
+not validated against experiments, and it is not intended for
+regulatory or design use; see the
+[limitations](https://pedestriandynamics.org/jupedsim-network/docs/limitations/).
+
+## Install
+
+Python 3.10 or later:
+
+```
+pip install git+https://github.com/PedestrianDynamics/jupedsim-network
+```
+
+## Development
+
+```
+uv sync
+uv run pytest
+uv run ruff check . && uv run ruff format --check .
+```
+
+The documentation is a [Hugo](https://gohugo.io) site with the
+[Hextra](https://imfing.github.io/hextra/) theme in `site/`. Hugo
+(extended) and Go are needed to build it:
+
+```
+uv run --group docs python scripts/figures/make_figures.py
+uv run --group docs python scripts/figures/make_gifs.py
+cd site && hugo server
+```
+
+The figures and animations are not stored in git. The two scripts write
+them to `site/static/images/network/` (about 2 minutes); CI runs them
+before every build.
+
+## License
+
+LGPL-3.0-or-later, as JuPedSim.

jupedsim_network-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "jupedsim-network"
+version = "0.1.0"
+description = "Coarse network egress model for fast evacuation-time estimates, companion to JuPedSim"
+readme = "README.md"
+license = "LGPL-3.0-or-later"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+dependencies = ["numpy>=1.26"]
+
+[project.urls]
+Documentation = "https://pedestriandynamics.org/jupedsim-network/"
+Source = "https://github.com/PedestrianDynamics/jupedsim-network"
+JuPedSim = "https://www.jupedsim.org"
+
+[dependency-groups]
+dev = ["pytest>=8", "ruff>=0.6"]
+docs = ["matplotlib==3.10.8"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/jupedsim_network"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 80
+indent-width = 4
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N"]
+ignore = ["E501"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"

jupedsim_network-0.1.0/scripts/figures/make_figures.py

@@ -0,0 +1,442 @@
+"""Static figures for the network model documentation.
+
+Writes PNGs to ``site/static/images/network`` or to the directory given as
+the first argument. ``jupedsim_network`` must be importable::
+
+    uv run --group docs python scripts/figures/make_figures.py
+    uv run --group docs python scripts/figures/make_gifs.py
+"""
+
+import sys
+from pathlib import Path
+
+import matplotlib
+
+matplotlib.use("Agg")
+import matplotlib.pyplot as plt
+import numpy as np
+from matplotlib.patches import Circle, FancyArrowPatch, FancyBboxPatch
+from scenarios import building, building_populations, merge_corridor
+
+from jupedsim_network import (
+    LogNormal,
+    Network,
+    NetworkSimulation,
+    Population,
+    hydraulic,
+)
+
+ROOT = Path(__file__).resolve().parents[2]
+DEFAULT_OUT = ROOT / "site" / "static" / "images" / "network"
+PAL = ["#90c1c6", "#72a5b4", "#58849f", "#446485", "#324465", "#1f253f"]
+RED = "#bd0c0c"
+ORANGE = "#fc8d59"
+GREY = "dimgrey"
+
+
+def style():
+    plt.rcParams.update(
+        {
+            "font.family": "DejaVu Sans",
+            "font.size": 10,
+            "axes.spines.top": False,
+            "axes.spines.right": False,
+            "axes.spines.left": False,
+            "axes.spines.bottom": False,
+            "axes.grid": False,
+            "axes.labelcolor": "#333333",
+            "axes.titlesize": 11,
+            "axes.titleweight": "semibold",
+            "xtick.major.size": 0,
+            "ytick.major.size": 0,
+            "xtick.color": GREY,
+            "ytick.color": GREY,
+            "legend.frameon": True,
+            "legend.facecolor": "white",
+            "legend.framealpha": 0.8,
+            "legend.edgecolor": "lightgrey",
+            "legend.labelcolor": GREY,
+            "savefig.dpi": 150,
+            "savefig.bbox": "tight",
+        }
+    )
+
+
+def frame(*axes):
+    for ax in axes:
+        ax.patch.set_edgecolor("lightgrey")
+        ax.patch.set_linewidth(0.8)
+        ax.grid(alpha=0.4, linewidth=0.6)
+
+
+def box(ax, xy, w, h, text, color):
+    patch = FancyBboxPatch(
+        xy,
+        w,
+        h,
+        boxstyle="round,pad=0.02,rounding_size=0.08",
+        fc=color,
+        ec="#324465",
+        lw=1.0,
+    )
+    ax.add_patch(patch)
+    ax.text(
+        xy[0] + w / 2,
+        xy[1] + h / 2,
+        text,
+        ha="center",
+        va="center",
+        fontsize=9,
+        color="#1f253f",
+    )
+
+
+def arrow(ax, a, b, text=None, offset=(0, 0.12)):
+    ax.add_patch(
+        FancyArrowPatch(
+            a, b, arrowstyle="-|>", mutation_scale=12, color="#446485", lw=1.4
+        )
+    )
+    if text:
+        mid = ((a[0] + b[0]) / 2 + offset[0], (a[1] + b[1]) / 2 + offset[1])
+        ax.text(*mid, text, ha="center", va="bottom", fontsize=8, color=GREY)
+
+
+def schematic(out):
+    fig, ax = plt.subplots(figsize=(10, 3.6))
+    box(ax, (0.0, 1.6), 2.2, 1.1, "", "#e8f1f2")
+    ax.text(
+        1.1,
+        2.48,
+        "room a, area $A_a$",
+        ha="center",
+        fontsize=9,
+        color="#1f253f",
+    )
+    box(ax, (0.0, 0.0), 2.2, 1.1, "room b\narea $A_b$", "#e8f1f2")
+    box(ax, (3.6, 0.8), 1.8, 1.1, "corridor\narea $A_c$", "#e8f1f2")
+    box(ax, (6.8, 0.8), 1.8, 1.1, "stair flight\n$k(R,T)$, area", "#d5e5ea")
+    box(ax, (9.8, 0.8), 1.4, 1.1, "safe", "#e9f4e4")
+    arrow(ax, (2.2, 2.15), (3.6, 1.55), "door, $w_a$")
+    arrow(ax, (2.2, 0.55), (3.6, 1.15), "door, $w_b$", offset=(0, -0.35))
+    arrow(ax, (5.4, 1.35), (6.8, 1.35), "stair entry")
+    arrow(ax, (8.6, 1.35), (9.8, 1.35), "door")
+    for x in range(5):
+        ax.add_patch(Circle((1.75 - 0.18 * x, 2.15), 0.06, color=RED))
+    ax.annotate(
+        "",
+        xy=(0.15, 1.92),
+        xytext=(2.05, 1.92),
+        arrowprops=dict(arrowstyle="<->", color=GREY, lw=0.8),
+    )
+    ax.text(
+        1.1,
+        1.7,
+        "link length $L$ (walked in source)",
+        ha="center",
+        fontsize=7.5,
+        color=GREY,
+    )
+    ax.text(
+        1.0, 2.15, "queue →", fontsize=7.5, color=RED, ha="right", va="center"
+    )
+    ax.text(
+        5.6,
+        -0.25,
+        r"link capacity $C = F_s\,(w - 2b)$   ·   node density "
+        r"$D = \sum_i a_i / A$",
+        ha="center",
+        fontsize=9,
+        color=GREY,
+    )
+    ax.set_xlim(-0.2, 11.4)
+    ax.set_ylim(-0.5, 2.9)
+    ax.set_aspect("equal")
+    ax.axis("off")
+    fig.savefig(out / "schematic.png")
+    plt.close(fig)
+
+
+def mark_densities(ax, marks):
+    top = ax.get_ylim()[1] * 0.98
+    for x, text in marks:
+        ax.axvline(x, color="lightgrey", lw=0.8, zorder=0)
+        ax.text(
+            x,
+            top,
+            text,
+            fontsize=7.5,
+            color=GREY,
+            ha="center",
+            va="top",
+            bbox=dict(fc="white", ec="none", pad=1),
+        )
+
+
+def fundamental(out):
+    d = np.linspace(0, hydraulic.JAM_DENSITY, 400)
+    k_level = hydraulic.LEVEL_SPEED_CONSTANT
+    k_stair = hydraulic.stair_speed_constant(0.18, 0.28)
+    fig, axes = plt.subplots(1, 3, figsize=(13, 3.8))
+    for k, label, color in [
+        (k_level, "level, k = 1.40 m/s", PAL[3]),
+        (k_stair, "stair 18/28 cm, k = 1.08 m/s", ORANGE),
+    ]:
+        s = hydraulic.speed(d, k)
+        axes[0].plot(d, s, color=color, lw=2, label=label)
+        axes[1].plot(d, s * d, color=color, lw=2, label=label)
+    marks = [
+        (hydraulic.MIN_DENSITY, "0.54"),
+        (hydraulic.PEAK_FLOW_DENSITY, "1.88"),
+        (2.75, "2.75"),
+        (hydraulic.JAM_DENSITY, "3.76"),
+    ]
+    for ax in axes[:2]:
+        mark_densities(ax, marks)
+    axes[0].set(
+        xlabel="density D (1/m²)",
+        ylabel="speed S (m/s)",
+        title="(a) speed, S = k (1 − 0.266 D)",
+    )
+    axes[1].set(
+        xlabel="density D (1/m²)",
+        ylabel="specific flow S·D (1/m/s)",
+        title="(b) specific flow",
+    )
+    axes[0].legend(loc="lower left", fontsize=8)
+    phi = np.clip((2.75 - d) / (2.75 - hydraulic.PEAK_FLOW_DENSITY), 0, 1)
+    axes[2].plot(d, phi, color=PAL[4], lw=2, label="supply reduction on")
+    axes[2].plot(
+        d,
+        np.where(d < 2.75, 1, 0),
+        color=RED,
+        lw=1.2,
+        ls="--",
+        label="hard limit only",
+    )
+    axes[2].set(
+        xlabel="density of receiving node D (1/m²)",
+        ylabel="accepted share of inflow φ",
+        title="(c) supply factor",
+        xlim=(0, hydraulic.JAM_DENSITY),
+    )
+    axes[2].legend(loc="lower left", fontsize=8)
+    axes[2].annotate(
+        "$D_{peak}$",
+        (1.88, 1.0),
+        (1.2, 0.7),
+        color=GREY,
+        arrowprops=dict(arrowstyle="-", color=GREY, lw=0.6),
+    )
+    axes[2].annotate(
+        "$D_{max}$",
+        (2.75, 0.0),
+        (3.0, 0.35),
+        color=GREY,
+        arrowprops=dict(arrowstyle="-", color=GREY, lw=0.6),
+    )
+    frame(*axes)
+    fig.tight_layout()
+    fig.savefig(out / "fundamental_diagram.png")
+    plt.close(fig)
+
+
+def door_and_merge(out):
+    fig, axes = plt.subplots(1, 2, figsize=(11, 4))
+    net = Network()
+    net.add_room("room", area=40.0)
+    net.add_safe("exit")
+    net.connect("room", "exit", width=1.0, specific_flow=1.33)
+    r = NetworkSimulation(net, [Population("room", 100, speed=1.0)]).run(1)
+    exits = np.sort(r.exit_times)
+    axes[0].step(
+        exits,
+        np.arange(1, 101),
+        where="post",
+        color=PAL[3],
+        lw=2,
+        label="network model, Δt = 0.5 s",
+    )
+    t = np.linspace(0, 99 / (1.33 * 0.7), 50)
+    axes[0].plot(
+        t,
+        1 + 1.33 * 0.7 * t,
+        color=RED,
+        ls="--",
+        lw=1.2,
+        label="model convention 1 + C t",
+    )
+    t = np.linspace(0, 100 / (1.33 * 0.7), 50)
+    axes[0].plot(
+        t,
+        1.33 * 0.7 * t,
+        color=ORANGE,
+        ls=":",
+        lw=1.6,
+        label="SFPE hand calculation C t",
+    )
+    axes[0].set(
+        xlabel="time (s)",
+        ylabel="agents through door",
+        title="(a) IMO test 4 geometry: 100 agents, 1 m door",
+    )
+    axes[0].text(
+        60,
+        12,
+        f"last agent: {r.evacuation_time:.1f} s\n"
+        f"(N − 1)/C = {99 / 0.931:.1f} s\n"
+        f"N/C = {100 / 0.931:.1f} s",
+        color=GREY,
+        fontsize=9,
+    )
+    axes[0].legend(loc="upper left", fontsize=8)
+
+    pops = [Population("a", 300), Population("b", 300)]
+    r = NetworkSimulation(merge_corridor(), pops, t_max=150.0).run(seed=2)
+    for name, color, w, ls in [
+        ("a->corridor", PAL[2], 1, "-"),
+        ("b->corridor", ORANGE, 3, "--"),
+    ]:
+        flow = r.link_flow[:, r.link_names.index(name)]
+        axes[1].plot(
+            r.times,
+            np.cumsum(flow),
+            color=color,
+            ls=ls,
+            lw=2,
+            label=f"{name.split('-')[0]}  (merge weight {w})",
+        )
+    axes[1].set(
+        xlabel="time (s)",
+        ylabel="agents into corridor",
+        title="(b) merging into a full corridor, weights 1 : 3",
+    )
+    axes[1].legend(loc="upper left", fontsize=8)
+    frame(*axes)
+    fig.tight_layout()
+    fig.savefig(out / "door_and_merge.png")
+    plt.close(fig)
+
+
+def rset_quantiles(max_density, supply_reduction, runs):
+    sim = NetworkSimulation(
+        building(stairs=("A",)),
+        building_populations(),
+        max_density=max_density,
+        supply_reduction=supply_reduction,
+    )
+    times = sim.run_many(runs, seed=1).evacuation_times
+    return np.quantile(times, [0.05, 0.5, 0.95])
+
+
+def density_sweep(out, runs=30):
+    limits = np.array([2.0, 2.25, 2.5, 2.75, 3.0, 3.25, 3.5, 3.7])
+    fig, ax = plt.subplots(figsize=(7, 4.2))
+    for on, color, label, marker in [
+        (True, PAL[3], "supply reduction on", "o"),
+        (False, RED, "hard limit only", "s"),
+    ]:
+        q = np.array([rset_quantiles(m, on, runs) for m in limits])
+        ax.fill_between(limits, q[:, 0], q[:, 2], color=color, alpha=0.15)
+        ax.plot(limits, q[:, 1], color=color, marker=marker, lw=2, label=label)
+    ax.set(
+        xlabel="max_density (1/m²)",
+        ylabel="evacuation time (s), median and 5–95 %",
+        title="10 floors × 60 agents, one stair",
+    )
+    ax.legend(loc="upper left", fontsize=8)
+    frame(ax)
+    fig.savefig(out / "max_density_sweep.png")
+    plt.close(fig)
+
+
+def route_tie(out):
+    cases = [
+        (
+            "two stairs, nearest exit (tie → one stair)",
+            building(),
+            building_populations(),
+            RED,
+            "-",
+        ),
+        (
+            "two stairs, targets split 50/50",
+            building(),
+            building_populations(split="AB"),
+            PAL[3],
+            "--",
+        ),
+        (
+            "one stair",
+            building(stairs=("A",)),
+            building_populations(),
+            GREY,
+            ":",
+        ),
+    ]
+    fig, ax = plt.subplots(figsize=(7, 4.2))
+    for label, net, pops, color, ls in cases:
+        r = NetworkSimulation(net, pops).run(seed=1)
+        e = np.sort(r.exit_times)
+        ax.step(
+            e,
+            np.arange(1, len(e) + 1),
+            where="post",
+            color=color,
+            ls=ls,
+            lw=2,
+            label=f"{label}: {r.evacuation_time:.1f} s",
+        )
+    ax.set(
+        xlabel="time (s)",
+        ylabel="agents evacuated",
+        title="Equal-distance exits are not split",
+    )
+    ax.legend(loc="lower right", fontsize=8)
+    frame(ax)
+    fig.savefig(out / "route_tie.png")
+    plt.close(fig)
+
+
+def monte_carlo(out, runs=300):
+    pre = LogNormal(120.0, 60.0, upper=600.0)
+    pops = building_populations(pre=pre, split="AB")
+    mc = NetworkSimulation(building(), pops).run_many(runs, seed=11)
+    t = mc.complete
+    fig, ax = plt.subplots(figsize=(7, 4.2))
+    ax.hist(t, bins=30, color=PAL[2], edgecolor="white")
+    for q, ls in [(0.5, "--"), (0.95, "-")]:
+        v = mc.quantile(q)
+        ax.axvline(v, color=RED, ls=ls, lw=1.2)
+        ax.text(
+            v,
+            ax.get_ylim()[1] * 0.95,
+            f" {int(q * 100)} %: {v:.0f} s",
+            color=RED,
+            fontsize=8.5,
+            va="top",
+        )
+    ax.set(
+        xlabel="evacuation time (s)",
+        ylabel="runs",
+        title=f"{runs} runs, pre-movement LogNormal(120 s, 60 s)",
+    )
+    ax.grid(alpha=0.4, axis="y")
+    fig.savefig(out / "monte_carlo.png")
+    plt.close(fig)
+
+
+def main():
+    out = Path(sys.argv[1]) if len(sys.argv) > 1 else DEFAULT_OUT
+    out.mkdir(parents=True, exist_ok=True)
+    style()
+    schematic(out)
+    fundamental(out)
+    door_and_merge(out)
+    density_sweep(out)
+    route_tie(out)
+    monte_carlo(out)
+
+
+if __name__ == "__main__":
+    main()