bloomr 0.1.1__py3-none-any.whl

bloomr/__init__.py

@@ -0,0 +1,51 @@
+"""
+Bloomr: Memory-efficient Chinese Postman Problem solver.
+
+Bloomr is a modern Python package for solving the Chinese Postman Problem (CPP)
+on road networks. It uses a high-performance Rust backend with the blossom algorithm
+for efficient perfect matching.
+
+The package provides a simple, pythonic API for:
+- Downloading road networks from OpenStreetMap via OSMnx
+- Computing optimal routes that traverse every road segment at least once
+- Generating GPS-compatible GPX files for navigation
+
+Basic Usage:
+    >>> from bloomr import solve_cpp
+    >>>
+    >>> # Solve CPP for a region
+    >>> result = solve_cpp("Jersey, Channel Islands")
+    >>> print(result.summary())
+    >>>
+    >>> # Access the GPX route file
+    >>> print(f"GPX route: {result.gpx_path}")
+
+Advanced Usage:
+    >>> from bloomr import download_graph, solve_cpp
+    >>>
+    >>> # Download and cache a graph
+    >>> graph_path = download_graph("San Francisco, California")
+    >>>
+    >>> # Solve using the cached graph
+    >>> result = solve_cpp(graphml_path=graph_path)
+"""
+
+from .download import download_graph, sanitize_filename
+from .solver import CPPResult, solve_cpp
+
+__version__ = "0.1.1"
+
+__all__ = [
+    "solve_cpp",
+    "download_graph",
+    "sanitize_filename",
+    "CPPResult",
+]
+
+# Visualization is optional - only import if dependencies are available
+try:
+    from .visualize import plot_route_map  # noqa: F401
+
+    __all__.append("plot_route_map")
+except ImportError:
+    pass

bloomr/download.py

@@ -0,0 +1,120 @@
+"""
+Graph downloading functionality using OSMnx.
+
+This module provides functions to download road network data from OpenStreetMap
+and save it as GraphML files for use with the Bloomr CPP solver.
+"""
+
+from pathlib import Path
+from typing import Optional, Union
+
+try:
+    import osmnx as ox
+except ImportError as e:
+    raise ImportError(
+        "OSMnx is required for downloading graphs. " "Install with: pip install bloomr"
+    ) from e
+
+
+def sanitize_filename(name: str) -> str:
+    """
+    Convert a place name to a valid filename.
+
+    Args:
+        name: Place name (e.g., "Jersey, Channel Islands")
+
+    Returns:
+        Sanitized filename (e.g., "jersey_channel_islands")
+    """
+    return name.lower().replace(" ", "_").replace(",", "").replace("/", "_")
+
+
+def download_graph(
+    place: str,
+    *,
+    output_dir: Optional[Union[Path, str]] = None,
+    network_type: str = "drive_service",
+    simplify: bool = False,
+    force: bool = False,
+) -> Path:
+    """
+    Download road network from OpenStreetMap and save as GraphML.
+
+    This function downloads a road network for a specified place using OSMnx,
+    adds edge speeds and travel times, and saves it as a GraphML file that
+    can be used with the Bloomr CPP solver.
+
+    Args:
+        place: OSMnx place query (e.g., "Jersey, Channel Islands",
+               "San Francisco, California")
+        output_dir: Output directory for GraphML file. Defaults to "graphml_data"
+        network_type: Type of network to download. Options:
+                     - "drive": Car-navigable roads
+                     - "drive_service": Drive + service roads (default)
+                     - "walk": Walkable paths
+                     - "bike": Bikeable paths
+                     - "all": All streets and paths
+        simplify: Whether to simplify the graph by merging nodes and removing
+                 interstitial nodes. Default False.
+        force: Force re-download even if file exists. Default False.
+
+    Returns:
+        Path to the saved GraphML file
+
+    Raises:
+        ValueError: If the place cannot be found or network_type is invalid
+        RuntimeError: If the download or save operation fails
+
+    Example:
+        >>> from bloomr import download_graph
+        >>> graph_path = download_graph("Jersey, Channel Islands")
+        >>> print(graph_path)
+        graphml_data/jersey_channel_islands.graphml
+    """
+    # Set default output directory
+    if output_dir is None:
+        output_dir = Path("graphml_data")
+    else:
+        output_dir = Path(output_dir)
+
+    # Create output directory
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    # Generate filename
+    filename = sanitize_filename(place)
+    graphml_path = output_dir / f"{filename}.graphml"
+
+    # Check if file exists
+    if graphml_path.exists() and not force:
+        print(f"GraphML file already exists: {graphml_path}")
+        print("Use force=True to re-download")
+        return graphml_path
+
+    # Configure OSMnx
+    ox.settings.use_cache = True
+    ox.settings.log_console = False
+
+    print(f"Downloading road network for: {place}")
+    print(f"Network type: {network_type}")
+    print("This may take several minutes for large regions...")
+
+    try:
+        # Download graph from OpenStreetMap
+        G = ox.graph_from_place(place, network_type=network_type, simplify=simplify)
+
+        print(f"Downloaded: {len(G.nodes)} nodes, {len(G.edges)} edges")
+
+        # Add speeds and travel times to edges
+        print("Adding edge speeds and travel times...")
+        G = ox.add_edge_speeds(G)
+        G = ox.add_edge_travel_times(G)
+
+        # Save to GraphML format
+        print(f"Saving to: {graphml_path}")
+        ox.save_graphml(G, filepath=graphml_path)
+
+        print(f"Successfully saved GraphML file: {graphml_path}")
+        return graphml_path
+
+    except Exception as e:
+        raise RuntimeError(f"Failed to download or save graph: {e}") from e

bloomr/solver.py

@@ -0,0 +1,375 @@
+"""
+Chinese Postman Problem solver using Rust blossom algorithm.
+
+This module provides the main solver function that interfaces with the Rust
+backend implementation of the blossom algorithm for efficient perfect matching.
+"""
+
+import json
+import platform
+import subprocess
+import sys
+from pathlib import Path
+from typing import Optional, Union
+
+from .download import download_graph, sanitize_filename
+
+
+def _get_platform_suffix() -> str:
+    """
+    Get the platform-specific suffix for the Rust binary.
+
+    Returns:
+        Platform suffix like 'linux-x86_64', 'macos-aarch64', etc.
+
+    Raises:
+        RuntimeError: If the platform is not supported
+    """
+    system = platform.system().lower()
+    machine = platform.machine().lower()
+
+    # Normalize machine architecture
+    if machine in ("x86_64", "amd64"):
+        arch = "x86_64"
+    elif machine in ("arm64", "aarch64"):
+        arch = "aarch64"
+    else:
+        raise RuntimeError(f"Unsupported architecture: {machine}")
+
+    # Map to platform suffixes
+    if system == "linux":
+        return f"linux-{arch}"
+    elif system == "darwin":
+        return f"macos-{arch}"
+    elif system == "windows":
+        return f"windows-{arch}"
+    else:
+        raise RuntimeError(f"Unsupported platform: {system}")
+
+
+def _find_rust_binary() -> Path:
+    """
+    Find the Rust binary in either the packaged location or development location.
+
+    Tries in order:
+    1. Packaged binary in bloomr/bin/ (platform-specific)
+    2. Development release build in bloomr-rust/target/release/
+    3. Development debug build in bloomr-rust/target/debug/
+
+    Returns:
+        Path to the Rust binary
+
+    Raises:
+        RuntimeError: If binary cannot be found
+    """
+    package_dir = Path(__file__).parent
+    project_root = package_dir.parent
+
+    # Try packaged binary first
+    try:
+        platform_suffix = _get_platform_suffix()
+        binary_name = f"bloomr-rust-{platform_suffix}"
+        if sys.platform == "win32":
+            binary_name += ".exe"
+
+        packaged_binary = package_dir / "bin" / binary_name
+        if packaged_binary.exists():
+            return packaged_binary
+    except RuntimeError:
+        # Platform not supported for packaged binary, fall through to dev builds
+        pass
+
+    # Try development builds
+    binary_name = "bloomr-rust.exe" if sys.platform == "win32" else "bloomr-rust"
+
+    # Try release build
+    dev_release_binary = project_root / "bloomr-rust" / "target" / "release" / binary_name
+    if dev_release_binary.exists():
+        return dev_release_binary
+
+    # Try debug build
+    dev_debug_binary = project_root / "bloomr-rust" / "target" / "debug" / binary_name
+    if dev_debug_binary.exists():
+        return dev_debug_binary
+
+    raise RuntimeError("Rust binary not found in any expected location")
+
+
+class CPPResult:
+    """
+    Results from solving the Chinese Postman Problem.
+
+    Attributes:
+        graphml_path: Path to the input GraphML file
+        gpx_path: Path to the generated GPX route file
+        metrics_path: Path to the metrics JSON file
+        map_path: Path to the route visualization PNG (if generated)
+        metrics: Dictionary containing solution metrics
+        region: Region name
+    """
+
+    def __init__(
+        self,
+        graphml_path: Path,
+        gpx_path: Path,
+        metrics_path: Path,
+        metrics: dict,
+        region: str,
+        map_path: Optional[Path] = None,
+    ):
+        self.graphml_path = graphml_path
+        self.gpx_path = gpx_path
+        self.metrics_path = metrics_path
+        self.map_path = map_path
+        self.metrics = metrics
+        self.region = region
+
+    def __repr__(self) -> str:
+        return (
+            f"CPPResult(region='{self.region}', "
+            f"distance={self.metrics.get('total_circuit_distance_km', 0):.2f}km, "
+            f"efficiency={self.metrics.get('distance_efficiency', 0):.4f})"
+        )
+
+    def summary(self) -> str:
+        """
+        Get a formatted summary of the solution.
+
+        Returns:
+            Multi-line string with key metrics
+        """
+        m = self.metrics
+        map_line = f"  Map:                       {self.map_path}\n" if self.map_path else ""
+
+        unique_segments = m.get("unique_road_segments", 0)
+        base_edges = m.get("base_graph_edges", 0)
+        circuit_edges = m.get("circuit_length", 0)
+        bidirectional = m.get("bidirectional_edge_pairs", 0)
+        oneway = m.get("one_way_edges", 0)
+
+        orig_dist = m.get("total_original_distance_km", 0)
+        circuit_dist = m.get("total_circuit_distance_km", 0)
+        extra_dist = circuit_dist - orig_dist
+        actual_dup = m.get("duplication_ratio", 0)
+
+        dist_eff = m.get("distance_efficiency", 0)
+        time_eff = m.get("time_efficiency", 0)
+        deadhead = m.get("deadhead_percentage", 0)
+
+        return f"""
+Bloomr CPP Solution (Mixed CPP) for {self.region}
+{'='*70}
+
+GRAPH STRUCTURE:
+  Unique road segments:      {unique_segments}
+    - Bidirectional (two-way): {bidirectional}
+    - One-way:                 {oneway}
+  Base graph edges:          {base_edges}
+    (bidirectional edges stored in both directions for Mixed CPP)
+
+SOLUTION METRICS:
+  Duplication ratio: {actual_dup:.4f}
+    - How many times each road is traversed on average
+    - Ratio: circuit_edges / unique_segments
+    - {circuit_edges} / {unique_segments} = {actual_dup:.4f}
+
+  Total original distance: {orig_dist:.2f} km (all roads once)
+  Total circuit distance:  {circuit_dist:.2f} km (actual route)
+  Extra distance needed:   {extra_dist:.2f} km ({deadhead:.1f}%)
+
+  Distance efficiency: {dist_eff * 100:.1f}%
+  Time efficiency:     {time_eff * 100:.1f}%
+
+OUTPUT FILES:
+  GPX route:                 {self.gpx_path}
+  Metrics:                   {self.metrics_path}
+{map_line}{'='*70}
+"""
+
+
+def solve_cpp(
+    place: Optional[str] = None,
+    *,
+    graphml_path: Optional[Union[Path, str]] = None,
+    output_dir: Optional[Union[Path, str]] = None,
+    network_type: str = "drive_service",
+    simplify: bool = False,
+    method: str = "blossom",
+    verbose: bool = False,
+    visualize: bool = True,
+) -> CPPResult:
+    """
+    Solve the Chinese Postman Problem for a road network.
+
+    This function finds an optimal route that traverses every road segment at least once,
+    using the Rust implementation for efficient perfect matching.
+
+    You can either:
+    1. Provide a place name, and the graph will be downloaded automatically
+    2. Provide a path to an existing GraphML file
+
+    Args:
+        place: OSMnx place query (e.g., "Jersey, Channel Islands").
+               If provided, the graph will be downloaded automatically.
+        graphml_path: Path to an existing GraphML file from OSMnx.
+                     If provided, this takes precedence over place.
+        output_dir: Output directory for solution files (GPX, metrics).
+                   Defaults to "solutions/<region_name>"
+        network_type: Type of network to download if place is provided.
+                     Options: "drive", "drive_service", "walk", "bike", "all"
+        simplify: Whether to simplify the downloaded graph. Only used if place is provided.
+        method: Graph balancing algorithm to use.
+               Only "blossom" is supported: Optimal O(n³) algorithm using Edmonds' blossom
+               algorithm for minimum weight perfect matching.
+        verbose: Enable verbose logging from the Rust solver
+        visualize: Whether to generate a map visualization PNG.
+                  Requires matplotlib and contextily (install with: pip install 'bloomr[viz]')
+
+    Returns:
+        CPPResult object containing paths to output files and solution metrics
+
+    Raises:
+        ValueError: If neither place nor graphml_path is provided, or if both are provided
+        FileNotFoundError: If graphml_path is provided but doesn't exist
+        RuntimeError: If the Rust solver fails
+
+    Examples:
+        >>> from bloomr import solve_cpp
+        >>>
+        >>> # Solve for a place (downloads graph automatically)
+        >>> result = solve_cpp("Jersey, Channel Islands")
+        >>> print(result.summary())
+        >>>
+        >>> # Solve for an existing GraphML file
+        >>> result = solve_cpp(graphml_path="my_graph.graphml")
+        >>> print(f"Route saved to: {result.gpx_path}")
+    """
+    # Validate inputs
+    if place is None and graphml_path is None:
+        raise ValueError("Either 'place' or 'graphml_path' must be provided")
+
+    if place is not None and graphml_path is not None:
+        raise ValueError("Provide either 'place' or 'graphml_path', not both")
+
+    # Validate method
+    if method != "blossom":
+        raise ValueError(f"Invalid method '{method}'. Only 'blossom' is supported")
+
+    # Determine region name
+    if place is not None:
+        region = sanitize_filename(place)
+        # Download graph
+        print(f"Downloading graph for: {place}")
+        graphml_path = download_graph(
+            place,
+            network_type=network_type,
+            simplify=simplify,
+        )
+    else:
+        assert graphml_path is not None  # Type narrowing for mypy
+        graphml_path = Path(graphml_path)
+        if not graphml_path.exists():
+            raise FileNotFoundError(f"GraphML file not found: {graphml_path}")
+        region = graphml_path.stem
+
+    # Set default output directory
+    if output_dir is None:
+        output_dir = Path("solutions") / region
+    else:
+        output_dir = Path(output_dir)
+
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    # Find Rust binary
+    rust_binary = _find_rust_binary()
+
+    if not rust_binary.exists():
+        raise RuntimeError(
+            "Rust binary not found. Please ensure bloomr is installed correctly.\n"
+            "If you're developing locally, build it first:\n"
+            "  cd bloomr-rust\n"
+            "  cargo build --release"
+        )
+
+    # Prepare command
+    cmd = [
+        str(rust_binary),
+        "--graphml",
+        str(graphml_path),
+        "--output-dir",
+        str(output_dir),
+        "--region",
+        region,
+        "--method",
+        method,
+    ]
+
+    if verbose:
+        cmd.append("--verbose")
+
+    # Run Rust solver
+    print("Running Bloomr CPP solver...")
+    print(f"Using graph: {graphml_path}")
+    print(f"Output directory: {output_dir}")
+    print()  # Blank line before Rust output
+
+    try:
+        # Run without capturing output so progress bars show in real-time
+        subprocess.run(
+            cmd,
+            check=True,
+        )
+
+    except subprocess.CalledProcessError as e:
+        raise RuntimeError(f"Rust solver failed with exit code {e.returncode}") from e
+
+    # Load results
+    gpx_path = output_dir / f"{region}_cpp_route.gpx"
+    metrics_path = output_dir / f"{region}_metrics.json"
+
+    if not gpx_path.exists():
+        raise RuntimeError(f"Expected GPX file not found: {gpx_path}")
+
+    if not metrics_path.exists():
+        raise RuntimeError(f"Expected metrics file not found: {metrics_path}")
+
+    # Load metrics
+    with open(metrics_path, "r") as f:
+        metrics = json.load(f)
+
+    # Generate visualization if requested
+    map_path = None
+    if visualize:
+        try:
+            from .visualize import plot_route_map
+
+            map_path = output_dir / f"{region}_route_map.png"
+            print("\nGenerating route visualization...")
+            plot_route_map(
+                graphml_path=graphml_path,
+                gpx_path=gpx_path,
+                output_path=map_path,
+            )
+        except ImportError:
+            print(
+                "\nWarning: Could not generate visualization. "
+                "Install visualization dependencies with:\n"
+                "  pip install 'bloomr[viz]'"
+            )
+        except Exception as e:
+            print(f"\nWarning: Could not generate visualization: {e}")
+
+    # Create result object
+    cpp_result = CPPResult(
+        graphml_path=graphml_path,
+        gpx_path=gpx_path,
+        metrics_path=metrics_path,
+        metrics=metrics,
+        region=region,
+        map_path=map_path,
+    )
+
+    print("\nSolution completed successfully!")
+    print(cpp_result.summary())
+
+    return cpp_result

bloomr/visualize.py

@@ -0,0 +1,239 @@
+"""
+Visualization utilities for CPP solutions.
+
+This module provides functions to visualize CPP routes on maps.
+"""
+
+import xml.etree.ElementTree as ET
+from pathlib import Path
+from typing import List, Tuple
+
+import networkx as nx
+
+
+def plot_route_map(
+    graphml_path: Path,
+    gpx_path: Path,
+    output_path: Path,
+    *,
+    figsize: Tuple[int, int] = (15, 15),
+    show_basemap: bool = True,
+    route_color: str = "#FF0000",
+    route_alpha: float = 0.6,
+    route_width: float = 1.5,
+    network_color: str = "#CCCCCC",
+    network_alpha: float = 0.3,
+    network_width: float = 0.5,
+    dpi: int = 150,
+) -> Path:
+    """
+    Create a map visualization of the CPP route.
+
+    This function reads the GraphML road network and GPX route file,
+    then creates a visualization showing the route overlaid on the road network
+    with an optional basemap.
+
+    Args:
+        graphml_path: Path to the GraphML file containing the road network
+        gpx_path: Path to the GPX file containing the route
+        output_path: Path where the PNG image will be saved
+        figsize: Figure size in inches (width, height)
+        show_basemap: Whether to show a basemap (requires contextily)
+        route_color: Color for the route line
+        route_alpha: Transparency of the route line (0-1)
+        route_width: Width of the route line
+        network_color: Color for the underlying road network
+        network_alpha: Transparency of the road network (0-1)
+        network_width: Width of the road network lines
+        dpi: Dots per inch for the output image
+
+    Returns:
+        Path to the saved PNG file
+
+    Raises:
+        ImportError: If required visualization dependencies are not installed
+        FileNotFoundError: If input files don't exist
+
+    Examples:
+        >>> from bloomr.visualize import plot_route_map
+        >>> from pathlib import Path
+        >>>
+        >>> plot_route_map(
+        ...     graphml_path=Path("graphml_data/jersey.graphml"),
+        ...     gpx_path=Path("solutions/jersey/jersey_cpp_route.gpx"),
+        ...     output_path=Path("solutions/jersey/jersey_route_map.png"),
+        ... )
+    """
+    try:
+        import matplotlib.patches as mpatches
+        import matplotlib.pyplot as plt
+    except ImportError as e:
+        raise ImportError(
+            "Visualization requires matplotlib. Install with:\n" "  pip install 'bloomr[viz]'"
+        ) from e
+
+    if show_basemap:
+        try:
+            import contextily as ctx
+        except ImportError as e:
+            raise ImportError(
+                "Basemap visualization requires contextily. Install with:\n"
+                "  pip install 'bloomr[viz]'"
+            ) from e
+
+    # Verify input files exist
+    if not graphml_path.exists():
+        raise FileNotFoundError(f"GraphML file not found: {graphml_path}")
+    if not gpx_path.exists():
+        raise FileNotFoundError(f"GPX file not found: {gpx_path}")
+
+    # Load the road network
+    print(f"Loading road network from {graphml_path.name}...")
+    G = nx.read_graphml(graphml_path)
+
+    # Extract coordinates from the graph
+    node_positions = {}
+    for node, data in G.nodes(data=True):
+        try:
+            lon = float(data.get("x", data.get("d4", 0)))
+            lat = float(data.get("y", data.get("d3", 0)))
+            node_positions[node] = (lon, lat)
+        except (ValueError, TypeError):
+            continue
+
+    # Parse GPX file to get route coordinates
+    print(f"Loading route from {gpx_path.name}...")
+    route_coords = _parse_gpx(gpx_path)
+
+    if not route_coords:
+        raise ValueError(f"No route coordinates found in GPX file: {gpx_path}")
+
+    print(f"Creating visualization with {len(route_coords)} route points...")
+
+    # Create figure
+    fig, ax = plt.subplots(figsize=figsize, dpi=dpi)
+
+    # Plot road network edges
+    for u, v in G.edges():
+        if u in node_positions and v in node_positions:
+            x_coords = [node_positions[u][0], node_positions[v][0]]
+            y_coords = [node_positions[u][1], node_positions[v][1]]
+            ax.plot(
+                x_coords,
+                y_coords,
+                color=network_color,
+                alpha=network_alpha,
+                linewidth=network_width,
+                zorder=1,
+            )
+
+    # Plot route
+    route_lons = [coord[0] for coord in route_coords]
+    route_lats = [coord[1] for coord in route_coords]
+    ax.plot(
+        route_lons,
+        route_lats,
+        color=route_color,
+        alpha=route_alpha,
+        linewidth=route_width,
+        zorder=2,
+        label="CPP Route",
+    )
+
+    # Mark start/end points
+    if route_coords:
+        start = route_coords[0]
+        end = route_coords[-1]
+        ax.plot(start[0], start[1], "go", markersize=10, zorder=3, label="Start")
+        ax.plot(end[0], end[1], "rs", markersize=10, zorder=3, label="End")
+
+    # Add basemap if requested
+    if show_basemap:
+        try:
+            print("Adding basemap (this may take a moment)...")
+            ctx.add_basemap(
+                ax,
+                crs="EPSG:4326",
+                source=ctx.providers.CartoDB.Positron,
+                attribution=False,
+            )
+        except Exception as e:
+            print(f"Warning: Could not add basemap: {e}")
+            print("Continuing without basemap...")
+
+    # Set labels and title
+    ax.set_xlabel("Longitude", fontsize=12)
+    ax.set_ylabel("Latitude", fontsize=12)
+    ax.set_title("Chinese Postman Problem Solution", fontsize=16, fontweight="bold")
+
+    # Add legend
+    legend_elements = [
+        mpatches.Patch(color=route_color, alpha=route_alpha, label="CPP Route"),
+        mpatches.Patch(color=network_color, alpha=network_alpha, label="Road Network"),
+        plt.Line2D(
+            [0], [0], marker="o", color="w", markerfacecolor="g", markersize=8, label="Start"
+        ),
+        plt.Line2D([0], [0], marker="s", color="w", markerfacecolor="r", markersize=8, label="End"),
+    ]
+    ax.legend(handles=legend_elements, loc="upper right", fontsize=10)
+
+    # Adjust layout and save
+    plt.tight_layout()
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    print(f"Saving map to {output_path}...")
+    plt.savefig(output_path, dpi=dpi, bbox_inches="tight")
+    plt.close()
+
+    print(f"Map saved successfully: {output_path}")
+    return output_path
+
+
+def _parse_gpx(gpx_path: Path) -> List[Tuple[float, float]]:
+    """
+    Parse GPX file and extract route coordinates.
+
+    Args:
+        gpx_path: Path to GPX file
+
+    Returns:
+        List of (lon, lat) tuples
+    """
+    # GPX files are generated by our own Rust backend, not untrusted external sources
+    tree = ET.parse(gpx_path)  # nosec B314
+    root = tree.getroot()
+
+    # GPX namespace
+    ns = {"gpx": "http://www.topografix.com/GPX/1/1"}
+
+    coords = []
+
+    # Try to find track points
+    for trkpt in root.findall(".//gpx:trkpt", ns):
+        lat_str = trkpt.get("lat")
+        lon_str = trkpt.get("lon")
+        if lat_str is not None and lon_str is not None:
+            lat = float(lat_str)
+            lon = float(lon_str)
+            coords.append((lon, lat))
+
+    # If no track points, try route points
+    if not coords:
+        for rtept in root.findall(".//gpx:rtept", ns):
+            lat_str = rtept.get("lat")
+            lon_str = rtept.get("lon")
+            if lat_str is not None and lon_str is not None:
+                lat = float(lat_str)
+                lon = float(lon_str)
+                coords.append((lon, lat))
+
+    # If still no points, try waypoints
+    if not coords:
+        for wpt in root.findall(".//gpx:wpt", ns):
+            lat_str = wpt.get("lat")
+            lon_str = wpt.get("lon")
+            if lat_str is not None and lon_str is not None:
+                lat = float(lat_str)
+                lon = float(lon_str)
+                coords.append((lon, lat))
+
+    return coords

bloomr-0.1.1.dist-info/METADATA

@@ -0,0 +1,187 @@
+Metadata-Version: 2.4
+Name: bloomr
+Version: 0.1.1
+Summary: Memory-efficient Chinese Postman Problem solver using Rust blossom algorithm
+Author-email: Nathaniel Hey <gnathoi@nat.je>
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/gnathoi/bloomr
+Project-URL: Documentation, https://github.com/gnathoi/bloomr#readme
+Project-URL: Repository, https://github.com/gnathoi/bloomr
+Project-URL: Issues, https://github.com/gnathoi/bloomr/issues
+Keywords: chinese-postman,graph-algorithms,routing,osmnx,blossom-algorithm,eulerian-circuit
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Rust
+Classifier: Topic :: Scientific/Engineering :: GIS
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: osmnx>=1.9.0
+Requires-Dist: networkx>=3.0
+Provides-Extra: viz
+Requires-Dist: matplotlib>=3.5.0; extra == "viz"
+Requires-Dist: contextily>=1.3.0; extra == "viz"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: black>=23.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Dynamic: license-file
+
+# Bloomr
+
+[![CI](https://github.com/gnathoi/bloomr/actions/workflows/ci.yml/badge.svg)](https://github.com/gnathoi/bloomr/actions/workflows/ci.yml)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+[![PyPI version](https://img.shields.io/pypi/v/bloomr.svg)](https://pypi.org/project/bloomr/)
+[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![Made with Rust](https://img.shields.io/badge/Made%20with-Rust-orange.svg)](https://www.rust-lang.org/)
+
+A Python package for solving the Mixed Chinese Postman Problem on road networks with a high-performance Rust backend.
+
+## What is the Mixed Chinese Postman Problem?
+
+The Chinese Postman Problem asks: what is the shortest route that traverses every edge in a graph at least once? This is useful for planning routes that need to, for example, survey every road in an area as efficiently as possible.
+
+The Mixed CPP extends this to real-world road networks where:
+
+- Some streets are bidirectional (two-way streets that can be traversed in either direction)
+- Some streets are directed (one-way streets with mandatory direction)
+
+Finding optimal routes in mixed networks is more complex than the classical all-directed or all-undirected versions of the problem. Bloomr solves this using Edmonds' blossom algorithm for efficient minimum-weight perfect matching.
+
+## What Bloomr Does
+
+Bloomr downloads real road network data from OpenStreetMap, identifies one-way and two-way streets, computes an optimal route that covers every street at least once, and outputs the solution as a GPX file for GPS navigation.
+
+The package uses a Python API for ease of use and a Rust backend for computational performance. The Rust implementation uses the blossom algorithm to find perfect matchings that minimize the total distance of repeated streets.
+
+## Installation
+
+```bash
+pip install bloomr
+```
+
+## Python API
+
+The API provides two main functions:
+
+### Solve CPP for a location
+
+```python
+from bloomr import solve_cpp
+
+# Download road network and solve CPP
+result = solve_cpp("Jersey, Channel Islands")
+
+# View solution summary
+print(result.summary())
+
+# Access result files
+print(f"Route saved to: {result.gpx_path}")
+print(f"Metrics: {result.metrics}")
+```
+
+### Download a graph separately
+
+```python
+from bloomr import download_graph
+
+# Download and cache a road network
+graph_path = download_graph("San Francisco, California")
+
+# Solve using the cached graph
+result = solve_cpp(graphml_path=graph_path)
+```
+
+## API Reference
+
+### solve_cpp()
+
+```python
+solve_cpp(
+    place: Optional[str] = None,
+    *,
+    graphml_path: Optional[Path] = None,
+    output_dir: Optional[Path] = None,
+    network_type: str = "drive_service",
+    simplify: bool = False,
+    method: str = "blossom",
+    verbose: bool = False,
+    visualize: bool = True
+)
+```
+
+Solve the Chinese Postman Problem for a road network.
+
+Arguments:
+
+- `place`: Location name for OSMnx (e.g., "Jersey, Channel Islands")
+- `graphml_path`: Path to existing GraphML file (alternative to place)
+- `output_dir`: Directory for output files (default: "solutions/{region}")
+- `network_type`: Type of road network - "drive", "drive_service", "walk", "bike", or "all"
+- `simplify`: Whether to simplify the graph topology
+- `method`: Graph balancing algorithm - "blossom" (optimal, default)
+- `verbose`: Print detailed progress information
+- `visualize`: Generate a route visualization map
+
+Returns a `CPPResult` object containing:
+
+- `graphml_path`: Input graph file
+- `gpx_path`: Output GPX route file
+- `metrics_path`: JSON file with solution metrics
+- `metrics`: Dictionary of solution metrics
+- `region`: Region name
+- `map_path`: Path to visualization (if generated)
+
+### download_graph()
+
+```python
+download_graph(
+    place: str,
+    *,
+    output_dir: Optional[Path] = None,
+    network_type: str = "drive_service",
+    simplify: bool = False,
+    force: bool = False
+) -> Path
+```
+
+Download a road network from OpenStreetMap and save as GraphML.
+
+Arguments:
+
+- `place`: Location name for OSMnx
+- `output_dir`: Directory for GraphML file (default: "graphml_data")
+- `network_type`: Type of road network
+- `simplify`: Whether to simplify the graph topology
+- `force`: Force re-download even if cached
+
+Returns the path to the saved GraphML file.
+
+## Solution Metrics
+
+Each solution includes comprehensive metrics:
+
+- `unique_road_segments`: Total number of distinct streets
+- `bidirectional_edge_pairs`: Number of two-way streets
+- `one_way_edges`: Number of one-way streets
+- `duplication_ratio`: Average times each street is traversed
+- `total_original_distance_km`: Total length of all streets (traversed once)
+- `total_circuit_distance_km`: Actual route distance
+- `distance_efficiency`: Ratio of original to circuit distance
+- `deadhead_percentage`: Percentage of route that repeats streets
+
+## Output Files
+
+All outputs are stored in `solutions/{region_name}/`:
+
+- `{region}_cpp_route.gpx`: GPS route file for navigation
+- `{region}_metrics.json`: Detailed solution metrics
+
+Graphs are cached in `graphml_data/` to avoid re-downloading.

bloomr-0.1.1.dist-info/RECORD

@@ -0,0 +1,13 @@
+bloomr/__init__.py,sha256=Y1VohmfGPdw0v7mHAG-0-6FliOWY5h-tBnqs-T8AZ38,1463
+bloomr/download.py,sha256=fZA1SJ0BTg9iwtA8lErLSm2Rep-m4aiCa2gdCSoMHLw,3920
+bloomr/solver.py,sha256=FRi7UnZGUjwe7If_2OOLCZQaGGUBymHDKt57jw6osMY,12180
+bloomr/visualize.py,sha256=02G9wg2xwloKQUNlTplFza8O0ASZgTBv927EAgioEic,7874
+bloomr/bin/bloomr-rust-linux-x86_64,sha256=Mhr_lRkgcLZpI9xOqMYBYUKuZR7siCZC6_nYgu5-FLM,1636288
+bloomr/bin/bloomr-rust-macos-aarch64,sha256=MK5ugHRdYN98MwT50lFzhEd9HuLQZgR07Ski6oakiyA,1388128
+bloomr/bin/bloomr-rust-macos-x86_64,sha256=lHgs1Z-nzY9EU6NsIZl0zq8NU4TkzyDBCgn5DgPHsUY,1481368
+bloomr/bin/bloomr-rust-windows-x86_64.exe,sha256=fMwEBUpaXe5uG7jE_v2Y3vPeRaqb77H_xIsjxyQLLrc,1349120
+bloomr-0.1.1.dist-info/licenses/LICENSE,sha256=6kwgzDLrIVTZSRWSydWtFbAetQRjIqDhls-AqwA3Wes,11341
+bloomr-0.1.1.dist-info/METADATA,sha256=9__lg6SNSzpVlVnZ8eS5lup819ckoMJJkP9Y3h1D_mk,6682
+bloomr-0.1.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+bloomr-0.1.1.dist-info/top_level.txt,sha256=sL9zHoV1EwZQxZZouGQ2hUQMNl-a0QABft1-XKWdl94,7
+bloomr-0.1.1.dist-info/RECORD,,

bloomr-0.1.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

bloomr-0.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Support. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2025 Nathaniel Hey
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

bloomr-0.1.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+bloomr