simple-logistics 0.1.0__py3-none-any.whl

simple_logistics/__init__.py

@@ -0,0 +1,17 @@
+from .logistics import (
+    InvalidAdjacencyMatrixError,
+    CapacityExceededError,
+    TransportNetwork,
+    Package,
+    Vehicle,
+    FleetManager,
+)
+
+__all__ = [
+    "InvalidAdjacencyMatrixError",
+    "CapacityExceededError",
+    "TransportNetwork",
+    "Package",
+    "Vehicle",
+    "FleetManager",
+]

simple_logistics/logistics.py

@@ -0,0 +1,754 @@
+import numpy as np
+import pandas as pd
+from datetime import datetime
+
+
+class InvalidAdjacencyMatrixError(Exception):
+    """Custom exception for errors in the adjacency matrix."""
+    def __init__(self, message: str):
+        super().__init__(f"Adjacency Matrix Error: {message}")
+
+
+class CapacityExceededError(Exception):
+    """Raised when a route sheet assigns more load than allowed to a vehicle."""
+    def __init__(self, vehicle_id: str, reason: str):
+        super().__init__(f"Capacity error in vehicle '{vehicle_id}': {reason}")
+
+
+class TransportNetwork:
+    def __init__(self):
+        self.graph = {}
+
+    def load_matrix_csv(self, csv_path: str):
+        """Loads the adjacency matrix from a CSV file using Pandas."""
+        self.graph = {}
+        try:
+            df = pd.read_csv(csv_path, index_col=0)
+        except FileNotFoundError:
+            raise InvalidAdjacencyMatrixError(f"The file '{csv_path}' does not exist.")
+        except Exception as e:
+            raise InvalidAdjacencyMatrixError(f"Could not read the CSV file. Detail: {e}")
+
+        # Validate matrix structure and values
+        # A. Check that it is not empty
+        if df.empty:
+            raise InvalidAdjacencyMatrixError("The CSV file is empty.")
+
+        # B. Validate that columns and indices are valid string names and not raw numbers
+        for col in df.columns:
+            if not isinstance(col, str) or col.isdigit():
+                raise InvalidAdjacencyMatrixError(f"Column header '{col}' is not a valid name.")
+
+        for idx in df.index:
+            if not isinstance(idx, str) or idx.isdigit():
+                raise InvalidAdjacencyMatrixError(f"Row name '{idx}' is not a valid name.")
+
+        # C. Check that it is an N x N square matrix
+        if df.shape[0] != df.shape[1]:
+            raise InvalidAdjacencyMatrixError(
+                f"The matrix is not square ({df.shape[0]} rows x {df.shape[1]} columns)."
+            )
+
+        # D. Check that row and column names match exactly
+        if list(df.index) != list(df.columns):
+            raise InvalidAdjacencyMatrixError(
+                "Row and column names must be identical and in the exact same order."
+            )
+
+        # E. Check that there are no null values (NaN)
+        if df.isnull().values.any():
+            raise InvalidAdjacencyMatrixError("The matrix contains empty or null cells.")
+
+        # F. Check that all matrix data are numeric
+        if not np.issubdtype(df.values.dtype, np.number):
+            raise InvalidAdjacencyMatrixError("The matrix contains non-numeric values.")
+
+        # G. Check that there are no negative distances
+        if (df.values < 0).any():
+            raise InvalidAdjacencyMatrixError("Negative distances exist in the matrix.")
+
+        # H. Check that the main diagonal contains only zeros (0)
+        diagonal = np.diag(df.values)
+        if not np.all(diagonal == 0):
+            raise InvalidAdjacencyMatrixError("The main diagonal must be 0 (distance from a node to itself).")
+
+        # Convert the matrix into an adjacency dictionary:
+        # {"origin1": {"destination1": distance, "destination2": distance}, ...}
+        for origin in df.index:
+            origin_str = str(origin).strip()
+            self.graph[origin_str] = {}
+            for destination in df.columns:
+                destination_str = str(destination).strip()
+                distance = float(df.loc[origin, destination])
+
+                if distance > 0 and origin_str != destination_str:
+                    self.graph[origin_str][destination_str] = distance
+
+    def calculate_optimal_route(self, origin: str, destination: str):
+        """Calculates the shortest path using Dijkstra's algorithm."""
+        if origin not in self.graph or destination not in self.graph:
+            raise ValueError("Origin or destination does not exist in the route matrix.")
+
+        # 1. Track distances and unvisited nodes
+        distances = {node: float('inf') for node in self.graph}
+        distances[origin] = 0
+        predecessors = {}
+        unvisited = set(self.graph.keys())
+
+        while unvisited:
+            # Find the unvisited node with the smallest accumulated distance
+            current_node = min(unvisited, key=lambda node: distances[node])
+
+            # Stop search if shortest distance is infinity or destination is reached
+            if distances[current_node] == float('inf') or current_node == destination:
+                break
+
+            unvisited.remove(current_node)
+
+            # Update distances of direct neighbors
+            for neighbor, weight in self.graph[current_node].items():
+                if neighbor in unvisited:
+                    new_distance = distances[current_node] + weight
+                    if new_distance < distances[neighbor]:
+                        distances[neighbor] = new_distance
+                        predecessors[neighbor] = current_node
+
+        # 2. Reconstruct the route from destination back to origin
+        path = []
+        current = destination
+        while current in predecessors:
+            path.insert(0, current)
+            current = predecessors[current]
+
+        if path or origin == destination:
+            path.insert(0, origin)
+
+        # Return path (list of stops) and distances[destination] (total accumulated distance)
+        return path, distances[destination]
+
+
+class Package:
+    def __init__(self, package_id: str, customer_id: str, weight_kg: float, volume_m3: float,
+                 origin: str, destination: str, eta: str, actual_time: str = None):
+        self.package_id = package_id
+        self.customer_id = customer_id
+        self.weight_kg = weight_kg
+        self.volume_m3 = volume_m3
+        self.origin = origin
+        self.destination = destination
+        self.eta = eta
+        self.actual_time = actual_time
+        self.status = "pending"
+        self.deviation_minutes = None
+        self.co2_emissions_kg = 0.0
+
+    def update_status(self):
+        """Compares actual_time with eta ('HH:MM' format) accounting for midnight crossings."""
+        if not self.actual_time:
+            self.status = "pending"
+            self.deviation_minutes = None
+            return
+
+        time_format = "%H:%M"
+        t_actual = datetime.strptime(self.actual_time.strip(), time_format)
+        t_eta = datetime.strptime(self.eta.strip(), time_format)
+
+        diff_min = (t_actual - t_eta).total_seconds() / 60.0
+        # Midnight crossing adjustment (+/- 12-hour window)
+        if diff_min < -720:
+            diff_min += 1440
+        elif diff_min > 720:
+            diff_min -= 1440
+
+        self.deviation_minutes = round(diff_min, 1)
+        self.status = "delivered" if self.deviation_minutes <= 0 else "delayed"
+
+    def to_dict(self):
+        return {
+            "package_id": self.package_id,
+            "customer_id": self.customer_id,
+            "origin": self.origin,
+            "destination": self.destination,
+            "weight_kg": self.weight_kg,
+            "volume_m3": self.volume_m3,
+            "eta": self.eta,
+            "actual_time": self.actual_time,
+            "deviation_minutes": self.deviation_minutes,
+            "status": self.status,
+            "co2_emissions_kg": self.co2_emissions_kg
+        }
+
+
+class Vehicle:
+    # Standard emission factors in kg of CO2 per liter of fuel consumed
+    CO2_EMISSION_FACTORS = {
+        "diesel": 2.68,
+        "gasoline": 2.31,
+        "hybrid": 1.85,
+        "lpg": 1.66,
+        "electric": 0.0
+    }
+
+    def __init__(self, vehicle_id: str, engine_type: str, weight_capacity_kg: float,
+                 volume_capacity_m3: float, theoretical_consumption_km_l: float,
+                 driver: str = None):
+        self.vehicle_id = vehicle_id.strip()
+        self.engine_type = engine_type.lower().strip()
+        self.weight_capacity_kg = weight_capacity_kg
+        self.volume_capacity_m3 = volume_capacity_m3
+        self.theoretical_consumption_km_l = theoretical_consumption_km_l
+        self.driver = driver.strip() if driver else f"Driver-{self.vehicle_id}"
+        self.packages = []
+        self.route_km_traveled = 0.0
+        self.actual_fuel_l = None
+
+    @property
+    def current_weight_kg(self):
+        return sum(p.weight_kg for p in self.packages)
+
+    @property
+    def current_volume_m3(self):
+        return sum(p.volume_m3 for p in self.packages)
+
+    @property
+    def actual_consumption_km_l(self):
+        """Calculates actual efficiency in km/liter if actual_fuel_l has been recorded."""
+        if self.actual_fuel_l and self.actual_fuel_l > 0 and self.route_km_traveled > 0:
+            return round(self.route_km_traveled / self.actual_fuel_l, 2)
+        return None
+
+    def can_load(self, package: Package):
+        valid_weight = (self.current_weight_kg + package.weight_kg) <= self.weight_capacity_kg
+        valid_volume = (self.current_volume_m3 + package.volume_m3) <= self.volume_capacity_m3
+        return valid_weight and valid_volume
+
+    def load_package(self, package: Package):
+        if self.can_load(package):
+            self.packages.append(package)
+            return True
+        return False
+
+    def calculate_co2_emissions(self, km_traveled: float) -> float:
+        """Calculates kg of CO2 emitted based on distance, theoretical consumption, and engine type."""
+        if self.theoretical_consumption_km_l <= 0 or km_traveled <= 0:
+            return 0.0
+
+        # Normalize accents in case accented strings are passed
+        engine_norm = (
+            self.engine_type
+            .replace("á", "a")
+            .replace("é", "e")
+            .replace("í", "i")
+            .replace("ó", "o")
+            .replace("ú", "u")
+        )
+
+        liters_consumed = km_traveled / self.theoretical_consumption_km_l
+        emission_factor = self.CO2_EMISSION_FACTORS.get(engine_norm, 2.50)
+        return round(liters_consumed * emission_factor, 2)
+
+    def to_dict(self):
+        return {
+            "vehicle_id": self.vehicle_id,
+            "driver": self.driver,
+            "engine_type": self.engine_type,
+            "current_weight_kg": self.current_weight_kg,
+            "weight_capacity_kg": self.weight_capacity_kg,
+            "current_volume_m3": self.current_volume_m3,
+            "volume_capacity_m3": self.volume_capacity_m3,
+            "theoretical_consumption_km_l": self.theoretical_consumption_km_l,
+            "actual_fuel_l": self.actual_fuel_l,
+            "actual_consumption_km_l": self.actual_consumption_km_l,
+            "num_packages": len(self.packages)
+        }
+
+
+class FleetManager:
+    def __init__(self, transport_network: TransportNetwork):
+        """
+        Main fleet orchestrator.
+        Receives the previously loaded TransportNetwork instance.
+        """
+        self.network = transport_network
+        self.vehicles = {}  # Dictionary: {vehicle_id: Vehicle_object}
+        self._simulation_executed = False
+
+    def add_vehicle(self, vehicle: Vehicle):
+        """Registers a Vehicle object in the manager."""
+        self.vehicles[vehicle.vehicle_id] = vehicle
+
+    def load_and_validate_route_sheet(self, deliveries_csv_path: str) -> pd.DataFrame:
+        """
+        Loads the daily deliveries CSV and validates that packages do not exceed
+        the weight and volume limits of their assigned vehicles.
+        """
+        try:
+            df_deliveries = pd.read_csv(deliveries_csv_path)
+        except FileNotFoundError:
+            raise FileNotFoundError(f"Route sheet file not found: '{deliveries_csv_path}'")
+
+        # Verify required columns are present
+        required_columns = [
+            "package_id", "customer_id", "weight_kg", "volume_m3",
+            "origin", "destination", "eta", "vehicle_id"
+        ]
+        for col in required_columns:
+            if col not in df_deliveries.columns:
+                raise ValueError(f"Missing required column '{col}' in the route sheet.")
+
+        # Reset vehicle loads and route metrics for the new simulation
+        for v in self.vehicles.values():
+            v.packages = []
+            v.route_km_traveled = 0.0
+            v.actual_fuel_l = None
+        self._simulation_executed = False
+
+        # Process row by row
+        for idx, row in df_deliveries.iterrows():
+            for col in required_columns:
+                if pd.isnull(row[col]):
+                    raise ValueError(f"Row {idx + 2} contains a null value in required column '{col}'.")
+
+            pkg_id = str(row["package_id"]).strip()
+            v_id = str(row["vehicle_id"]).strip()
+
+            if v_id not in self.vehicles:
+                raise ValueError(f"Vehicle '{v_id}' assigned in the CSV is not registered in the fleet.")
+
+            weight = float(row["weight_kg"])
+            volume = float(row["volume_m3"])
+            if weight <= 0 or volume <= 0:
+                raise ValueError(f"Package '{pkg_id}' must have weight_kg and volume_m3 greater than 0.")
+
+            vehicle = self.vehicles[v_id]
+
+            # If CSV includes optional 'driver' column, update driver name on vehicle
+            if "driver" in row and pd.notnull(row["driver"]):
+                vehicle.driver = str(row["driver"]).strip()
+
+            # If CSV includes optional 'actual_fuel_l' column, validate consistency and record
+            if "actual_fuel_l" in row and pd.notnull(row["actual_fuel_l"]):
+                liters = float(row["actual_fuel_l"])
+                if liters <= 0:
+                    raise ValueError(f"The value of 'actual_fuel_l' for '{v_id}' must be greater than 0.")
+                if vehicle.actual_fuel_l is not None and not np.isclose(vehicle.actual_fuel_l, liters):
+                    raise ValueError(
+                        f"Conflicting values of 'actual_fuel_l' for vehicle '{v_id}' "
+                        f"({vehicle.actual_fuel_l} vs {liters})."
+                    )
+                vehicle.actual_fuel_l = liters
+
+            origin = str(row["origin"]).strip()
+            destination = str(row["destination"]).strip()
+
+            if origin not in self.network.graph or destination not in self.network.graph:
+                raise ValueError(
+                    f"Origin '{origin}' or destination '{destination}' for package '{pkg_id}' does not exist in the network."
+                )
+
+            actual_time = str(row["actual_time"]).strip() if "actual_time" in row and pd.notnull(row["actual_time"]) else None
+
+            package = Package(
+                package_id=pkg_id,
+                customer_id=str(row["customer_id"]).strip(),
+                weight_kg=weight,
+                volume_m3=volume,
+                origin=origin,
+                destination=destination,
+                eta=str(row["eta"]).strip(),
+                actual_time=actual_time
+            )
+
+            success = vehicle.load_package(package)
+
+            if not success:
+                raise CapacityExceededError(
+                    vehicle_id=vehicle.vehicle_id,
+                    reason=f"Package '{package.package_id}' exceeds weight or volume capacity."
+                )
+
+        print("Route sheet validated successfully: All packages comply with weight and volume limits.")
+        return df_deliveries
+
+    def generate_operations_report(self) -> pd.DataFrame:
+        """Calculates routes, distances, estimated/actual consumption, CO2 emissions, and punctuality per vehicle."""
+        results = []
+
+        for vehicle in self.vehicles.values():
+            if not vehicle.packages:
+                continue
+
+            total_route = []
+            total_km = 0.0
+            current_point = vehicle.packages[0].origin
+
+            for package in vehicle.packages:
+                package_leg_km = 0.0
+
+                # 1. Travel to the package origin if the vehicle is at another node
+                if current_point != package.origin:
+                    pickup_leg, pickup_km = self.network.calculate_optimal_route(current_point, package.origin)
+                    if pickup_km == float('inf'):
+                        raise ValueError(f"No possible route exists between '{current_point}' and '{package.origin}'.")
+                    package_leg_km += pickup_km
+                    total_route.extend(pickup_leg[1:] if total_route else pickup_leg)
+
+                # 2. Deliver the package from its origin to its destination
+                delivery_leg, delivery_km = self.network.calculate_optimal_route(package.origin, package.destination)
+                if delivery_km == float('inf'):
+                    raise ValueError(f"No possible route exists between '{package.origin}' and '{package.destination}'.")
+
+                package_leg_km += delivery_km
+                total_km += package_leg_km
+                total_route.extend(delivery_leg[1:] if total_route else delivery_leg)
+                current_point = package.destination
+
+                # 3. Update punctuality and total service emissions (pickup + delivery)
+                package.update_status()
+                package.co2_emissions_kg = vehicle.calculate_co2_emissions(package_leg_km)
+
+            vehicle.route_km_traveled = total_km
+            estimated_consumption = round(total_km / vehicle.theoretical_consumption_km_l, 2) if vehicle.theoretical_consumption_km_l > 0 else 0.0
+            total_emissions = vehicle.calculate_co2_emissions(total_km)
+
+            # Actual efficiency metrics if actual fuel data is available
+            actual_km_l = vehicle.actual_consumption_km_l
+            if actual_km_l is not None and vehicle.theoretical_consumption_km_l > 0:
+                efficiency_dev = round(((actual_km_l - vehicle.theoretical_consumption_km_l) / vehicle.theoretical_consumption_km_l) * 100, 2)
+            else:
+                efficiency_dev = None
+
+            completed = [p for p in vehicle.packages if p.status != "pending"]
+            on_time = sum(1 for p in completed if p.status == "delivered")
+            delays = sum(1 for p in completed if p.status == "delayed")
+            punctuality_score = round((on_time / len(completed)) * 100, 2) if completed else None
+
+            results.append({
+                "vehicle_id": vehicle.vehicle_id,
+                "driver": vehicle.driver,
+                "engine": vehicle.engine_type,
+                "route_taken": " -> ".join(total_route),
+                "total_km": total_km,
+                "estimated_consumption_l": estimated_consumption,
+                "actual_fuel_l": vehicle.actual_fuel_l,
+                "actual_consumption_km_l": actual_km_l,
+                "efficiency_deviation_pct": efficiency_dev,
+                "co2_emissions_kg": total_emissions,
+                "total_packages": len(vehicle.packages),
+                "delayed_packages": delays,
+                "punctuality_score": punctuality_score
+            })
+
+        self._simulation_executed = True
+        return pd.DataFrame(results)
+
+    def generate_fuel_efficiency_report(
+        self,
+        consumption_csv_path: str = None,
+        inefficiency_threshold_pct: float = 15.0
+    ) -> pd.DataFrame:
+        """
+        Analyzes deviations between actual (km/l) and theoretical fuel efficiency using Pandas
+        to detect inefficient driving.
+
+        - If `consumption_csv_path` is passed, reads a CSV with required columns:
+          ['vehicle_id', 'actual_fuel_l'] and optional ['actual_km'].
+        - If no CSV is passed, uses the data loaded in the vehicles after simulation.
+        """
+        output_columns = [
+            "vehicle_id", "driver", "engine", "km_traveled",
+            "theoretical_consumption_km_l", "actual_consumption_km_l",
+            "deviation_km_l", "deviation_pct",
+            "theoretical_liters", "actual_fuel_l", "extra_liters",
+            "inefficient_driving", "diagnosis"
+        ]
+
+        # Ensure route distances are calculated if there are packages pending simulation
+        if not self._simulation_executed and any(v.packages for v in self.vehicles.values()):
+            self.generate_operations_report()
+
+        # Build base DataFrame of the registered fleet
+        fleet_data = [
+            {
+                "vehicle_id": v.vehicle_id,
+                "driver": v.driver,
+                "engine": v.engine_type,
+                "theoretical_consumption_km_l": v.theoretical_consumption_km_l,
+                "route_km": v.route_km_traveled,
+                "loaded_liters": v.actual_fuel_l
+            }
+            for v in self.vehicles.values()
+        ]
+        if not fleet_data:
+            return pd.DataFrame(columns=output_columns)
+
+        df_fleet = pd.DataFrame(fleet_data)
+
+        if consumption_csv_path is not None:
+            try:
+                df_consumption = pd.read_csv(consumption_csv_path)
+            except FileNotFoundError:
+                raise FileNotFoundError(f"Fuel consumption file not found: '{consumption_csv_path}'")
+
+            for col in ["vehicle_id", "actual_fuel_l"]:
+                if col not in df_consumption.columns:
+                    raise ValueError(f"Missing required column '{col}' in the fuel consumption CSV.")
+
+            df_consumption["vehicle_id"] = df_consumption["vehicle_id"].astype(str).str.strip()
+            unregistered = set(df_consumption["vehicle_id"]) - set(self.vehicles.keys())
+            if unregistered:
+                raise ValueError(f"Vehicles not registered in the fleet: {', '.join(sorted(unregistered))}")
+
+            if (df_consumption["actual_fuel_l"] <= 0).any():
+                raise ValueError("All values of 'actual_fuel_l' must be greater than 0.")
+
+            # Group in case there are multiple refuelings for the same vehicle, preserving NaN if actual_km is missing
+            agg_dict = {"actual_fuel_l": "sum"}
+            if "actual_km" in df_consumption.columns:
+                df_consumption["actual_km"] = pd.to_numeric(df_consumption["actual_km"], errors="coerce")
+                agg_dict["actual_km"] = lambda s: s.sum(min_count=1)
+
+            df_agg = df_consumption.groupby("vehicle_id", as_index=False).agg(agg_dict)
+            df = pd.merge(df_fleet, df_agg, on="vehicle_id", how="inner")
+
+            if "actual_km" in df.columns:
+                df["km_traveled"] = df["actual_km"].fillna(df["route_km"])
+            else:
+                df["km_traveled"] = df["route_km"]
+        else:
+            df = df_fleet[df_fleet["loaded_liters"].notnull() & (df_fleet["route_km"] > 0)].copy()
+            if df.empty:
+                return pd.DataFrame(columns=output_columns)
+            df["km_traveled"] = df["route_km"]
+            df["actual_fuel_l"] = df["loaded_liters"].astype(float)
+
+        df = df[(df["km_traveled"] > 0) & (df["theoretical_consumption_km_l"] > 0)].copy()
+        if df.empty:
+            return pd.DataFrame(columns=output_columns)
+
+        # Vectorized calculations with Pandas
+        df["actual_consumption_km_l"] = (df["km_traveled"] / df["actual_fuel_l"]).round(2)
+        df["deviation_km_l"] = (df["actual_consumption_km_l"] - df["theoretical_consumption_km_l"]).round(2)
+        df["deviation_pct"] = ((df["deviation_km_l"] / df["theoretical_consumption_km_l"]) * 100).round(2)
+
+        df["theoretical_liters"] = (df["km_traveled"] / df["theoretical_consumption_km_l"]).round(2)
+        df["actual_fuel_l"] = df["actual_fuel_l"].round(2)
+        df["extra_liters"] = (df["actual_fuel_l"] - df["theoretical_liters"]).round(2)
+
+        # Actual efficiency lower than theoretical by more than `inefficiency_threshold_pct` indicates inefficient driving
+        df["inefficient_driving"] = df["deviation_pct"] < -abs(inefficiency_threshold_pct)
+        df["diagnosis"] = np.where(
+            df["inefficient_driving"],
+            "Inefficient driving",
+            np.where(df["deviation_pct"] > 5.0, "Efficient driving", "Normal consumption")
+        )
+
+        return df[output_columns]
+
+    def generate_punctuality_report(self) -> pd.DataFrame:
+        """
+        Evaluates each driver's punctuality by comparing actual_time vs eta
+        and calculates their quality score (0 to 100).
+        """
+        driver_data = {}
+
+        for vehicle in self.vehicles.values():
+            if not vehicle.packages:
+                continue
+
+            driver = vehicle.driver
+            if driver not in driver_data:
+                driver_data[driver] = {
+                    "vehicles": [],
+                    "packages": []
+                }
+
+            driver_data[driver]["vehicles"].append(vehicle.vehicle_id)
+
+            for package in vehicle.packages:
+                package.update_status()
+                driver_data[driver]["packages"].append(package)
+
+        results = []
+        for driver, info in driver_data.items():
+            packages = info["packages"]
+            completed = [p for p in packages if p.status != "pending"]
+            on_time = sum(1 for p in completed if p.status == "delivered")
+            delayed = sum(1 for p in completed if p.status == "delayed")
+            pending = sum(1 for p in packages if p.status == "pending")
+
+            deviations = [p.deviation_minutes for p in completed if p.deviation_minutes is not None]
+            avg_deviation = round(sum(deviations) / len(deviations), 1) if deviations else None
+            positive_delays = [d for d in deviations if d > 0]
+            max_delay = round(max(positive_delays), 1) if positive_delays else 0.0
+
+            if completed:
+                score = round((on_time / len(completed)) * 100, 2)
+                if score >= 95:
+                    rating = "Excellent"
+                elif score >= 80:
+                    rating = "Good"
+                elif score >= 60:
+                    rating = "Needs Improvement"
+                else:
+                    rating = "Critical"
+            else:
+                score = None
+                rating = "No deliveries"
+
+            results.append({
+                "driver": driver,
+                "vehicles": ", ".join(info["vehicles"]),
+                "assigned_packages": len(packages),
+                "delivered_on_time": on_time,
+                "delayed": delayed,
+                "pending": pending,
+                "avg_deviation_min": avg_deviation,
+                "max_delay_min": max_delay,
+                "punctuality_score": score,
+                "rating": rating
+            })
+
+        return pd.DataFrame(results)
+
+    def generate_package_co2_report(self) -> pd.DataFrame:
+        """Returns a DataFrame with the carbon footprint broken down by delivered package."""
+        if not self._simulation_executed and any(v.packages for v in self.vehicles.values()):
+            self.generate_operations_report()
+
+        records = []
+        for vehicle in self.vehicles.values():
+            for p in vehicle.packages:
+                records.append({
+                    "package_id": p.package_id,
+                    "customer_id": p.customer_id,
+                    "vehicle_id": vehicle.vehicle_id,
+                    "driver": vehicle.driver,
+                    "engine": vehicle.engine_type,
+                    "origin": p.origin,
+                    "destination": p.destination,
+                    "eta": p.eta,
+                    "actual_time": p.actual_time,
+                    "deviation_minutes": p.deviation_minutes,
+                    "status": p.status,
+                    "co2_emissions_kg": p.co2_emissions_kg
+                })
+        return pd.DataFrame(records)
+
+    def generate_customer_co2_report(self) -> pd.DataFrame:
+        """Groups and sums total CO2 emissions per customer."""
+        df_packages = self.generate_package_co2_report()
+        if df_packages.empty:
+            return pd.DataFrame(columns=["customer_id", "total_packages", "total_co2_emissions_kg"])
+
+        return (
+            df_packages.groupby("customer_id", as_index=False)
+            .agg(
+                total_packages=("package_id", "count"),
+                total_co2_emissions_kg=("co2_emissions_kg", "sum")
+            )
+            .round({"total_co2_emissions_kg": 2})
+        )
+
+    def generate_vehicle_manifest(self, vehicle_id: str) -> pd.DataFrame:
+        """
+        Builds a structured stop-by-stop load manifest for a specific vehicle,
+        ready to be viewed by the driver on their mobile device.
+        """
+        if vehicle_id not in self.vehicles:
+            raise ValueError(f"Vehicle '{vehicle_id}' is not registered in the fleet.")
+
+        vehicle = self.vehicles[vehicle_id]
+        if not vehicle.packages:
+            raise ValueError(f"Vehicle '{vehicle_id}' has no assigned packages.")
+
+        rows = []
+        current_point = vehicle.packages[0].origin
+
+        for order, package in enumerate(vehicle.packages, start=1):
+            package.update_status()
+
+            full_leg = []
+            leg_km = 0.0
+            requires_transfer = False
+
+            if current_point != package.origin:
+                pickup_leg, pickup_km = self.network.calculate_optimal_route(current_point, package.origin)
+                if pickup_km == float('inf'):
+                    raise ValueError(f"No possible route exists between '{current_point}' and '{package.origin}'.")
+                full_leg.extend(pickup_leg)
+                leg_km += pickup_km
+                requires_transfer = True
+
+            delivery_leg, delivery_km = self.network.calculate_optimal_route(package.origin, package.destination)
+            if delivery_km == float('inf'):
+                raise ValueError(f"No possible route exists between '{package.origin}' and '{package.destination}'.")
+
+            full_leg.extend(delivery_leg[1:] if full_leg else delivery_leg)
+            leg_km += delivery_km
+            current_point = package.destination
+
+            operation_type = (
+                f"Transfer from {full_leg[0]} + Pickup and Delivery"
+                if requires_transfer
+                else "Pickup and Delivery"
+            )
+
+            rows.append({
+                "stop_order": order,
+                "vehicle_id": vehicle.vehicle_id,
+                "driver": vehicle.driver,
+                "package_id": package.package_id,
+                "customer_id": package.customer_id,
+                "operation_type": operation_type,
+                "origin": package.origin,
+                "destination": package.destination,
+                "navigation_route": " -> ".join(full_leg),
+                "leg_distance_km": round(leg_km, 2),
+                "weight_kg": package.weight_kg,
+                "volume_m3": package.volume_m3,
+                "eta": package.eta,
+                "status": package.status,
+                "delivered_check": "[ ]",
+                "driver_notes": ""
+            })
+
+        return pd.DataFrame(rows)
+
+    def export_load_manifest(self, vehicle_id: str = None, filename: str = None) -> dict:
+        """
+        Generates and exports one or more Load Manifest CSV files directly
+        in the current directory, ready for the driver's mobile device.
+
+        - If `vehicle_id` is specified:
+            * Saves `<filename>` if provided, or `manifest_<vehicle_id>.csv` in the current directory.
+        - If `vehicle_id` is None:
+            * Exports an individual CSV (`manifest_<vehicle_id>.csv`) for each vehicle with assigned cargo.
+
+        Returns a dictionary {vehicle_id: generated_csv_filename}.
+        """
+        generated_files = {}
+
+        if vehicle_id is not None:
+            df_manifest = self.generate_vehicle_manifest(vehicle_id)
+            if filename:
+                clean_name = filename.strip()
+                final_file = clean_name if clean_name.lower().endswith(".csv") else f"{clean_name}.csv"
+            else:
+                final_file = f"manifest_{vehicle_id}.csv"
+
+            df_manifest.to_csv(final_file, index=False, encoding="utf-8-sig")
+            generated_files[vehicle_id] = final_file
+            return generated_files
+
+        active_vehicles = [v for v in self.vehicles.values() if v.packages]
+        if not active_vehicles:
+            raise ValueError("No vehicles with assigned packages available to export load manifests.")
+
+        for vehicle in active_vehicles:
+            df_manifest = self.generate_vehicle_manifest(vehicle.vehicle_id)
+            final_file = f"manifest_{vehicle.vehicle_id}.csv"
+            df_manifest.to_csv(final_file, index=False, encoding="utf-8-sig")
+            generated_files[vehicle.vehicle_id] = final_file
+
+        return generated_files

simple_logistics-0.1.0.dist-info/METADATA

@@ -0,0 +1,158 @@
+Metadata-Version: 2.4
+Name: simple_logistics
+Version: 0.1.0
+Summary: Library for management of vehicles and packages
+Author-email: Beñat Monje <benat.monje@alumni.mondragon.edu>, Txaber Ajangiz <txaber.ajangiz@alumni.mondragon.edu>
+License: MIT
+Keywords: logistics,vehicles,routes
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: pandas>=2.0.0
+Dynamic: license-file
+
+# Simple Logistics
+
+A Python library for transport fleet logistics management. Model distribution networks via adjacency matrices, compute optimal routes using Dijkstra's algorithm, validate vehicle load limits, and generate operational analytics.
+
+## Features
+
+* **Transport Network (`TransportNetwork`):** Strict loading and validation of CSV adjacency matrices and shortest-path calculation.
+* **Fleet & Load Control (`FleetManager`, `Vehicle`, `Package`):** Automated route sheet validation enforcing maximum weight and volume capacities per vehicle.
+* **Logistics Analytics (`FleetManager`):**
+  * Fuel efficiency evaluation (actual vs. theoretical consumption).
+  * Delivery punctuality measurement (ETA vs. actual delivery time) and vehicle/driver quality scoring.
+  * Carbon footprint ($\text{CO}_2$) reporting grouped by package, customer, or route.
+  * Structured CSV load manifest export ready for driver mobile devices.
+
+## Installation
+
+```bash
+pip install simple_logistics
+```
+
+## Quick Start
+
+```python
+from simple_logistics import (
+    TransportNetwork,
+    Vehicle,
+    FleetManager,
+)
+
+## Input CSV Schemas
+
+### 1. Adjacency Matrix (`network.csv`)
+A square matrix where row and column headers match in exact order, distances are non-negative, and the main diagonal is `0`:
+
+```csv
+,Hub_A,Hub_B,Client_1
+Hub_A,0,12.5,30.0
+Hub_B,12.5,0,15.0
+Client_1,30.0,15.0,0
+```
+
+### 2. Daily Route Sheet (`deliveries.csv`)
+- **Required columns**: `package_id`, `customer_id`, `weight_kg`, `volume_m3`, `origin`, `destination`, `eta`, `vehicle_id`
+- **Optional columns**: `driver`, `actual_time`, `actual_fuel_l`
+
+```csv
+package_id,customer_id,weight_kg,volume_m3,origin,destination,eta,vehicle_id,actual_time,actual_fuel_l
+PKG-001,CUST-10,120.5,1.2,Hub_A,Hub_B,09:30,TRUCK-01,09:20,4.2
+PKG-002,CUST-11,85.0,0.8,Hub_B,Client_1,10:45,TRUCK-01,10:55,4.2
+PKG-003,CUST-10,40.0,0.5,Hub_A,Client_1,11:00,VAN-02,10:50,
+```
+
+### 3. External Fuel Logs (`fuel_logs.csv`, optional)
+- **Required columns**: `vehicle_id`, `actual_fuel_l`
+- **Optional column**: `actual_km`
+
+## Quick Start Example
+
+```python
+from fleet_route_engine import (
+    TransportNetwork,
+    Vehicle,
+    FleetManager,
+    CapacityExceededError,
+    InvalidAdjacencyMatrixError,
+)
+
+# 1. Load and validate the transport network
+network = TransportNetwork()
+try:
+    network.load_matrix_csv("network.csv")
+except InvalidAdjacencyMatrixError as e:
+    print(f"Network error: {e}")
+    raise
+
+# Optional: Query a single shortest path directly
+route, distance_km = network.calculate_optimal_route("Hub_A", "Client_1")
+print(f"Optimal route: {' -> '.join(route)} ({distance_km} km)")
+
+# 2. Initialize the fleet manager and register vehicles
+manager = FleetManager(network)
+
+manager.add_vehicle(
+    Vehicle(
+        vehicle_id="TRUCK-01",
+        engine_type="diesel",
+        weight_capacity_kg=1500.0,
+        volume_capacity_m3=12.0,
+        theoretical_consumption_km_l=10.5,
+        driver="Alex Rivera",
+    )
+)
+
+manager.add_vehicle(
+    Vehicle(
+        vehicle_id="VAN-02",
+        engine_type="electric",
+        weight_capacity_kg=800.0,
+        volume_capacity_m3=6.5,
+        theoretical_consumption_km_l=6.0,
+        driver="Sam Taylor",
+    )
+)
+
+# 3. Load and validate the daily route sheet
+try:
+    manager.load_and_validate_route_sheet("deliveries.csv")
+except CapacityExceededError as e:
+    print(f"Load validation failed: {e}")
+    raise
+
+# 4. Generate analytical reports (returned as Pandas DataFrames)
+ops_report = manager.generate_operations_report()
+print("\n--- Operations Report ---")
+print(ops_report)
+
+fuel_report = manager.generate_fuel_efficiency_report(inefficiency_threshold_pct=15.0)
+print("\n--- Fuel Efficiency Report ---")
+print(fuel_report)
+
+punctuality_report = manager.generate_punctuality_report()
+print("\n--- Driver Punctuality Report ---")
+print(punctuality_report)
+
+customer_co2_report = manager.generate_customer_co2_report()
+print("\n--- CO2 Emissions by Customer ---")
+print(customer_co2_report)
+
+# 5. Export stop-by-stop load manifests for drivers
+exported_files = manager.export_load_manifest()
+print("\nGenerated manifests:", exported_files)
+```
+## Requirements
+
+* Python >= 3.9
+* `numpy`
+* `pandas`
+
+## License
+
+MIT

simple_logistics-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+simple_logistics/__init__.py,sha256=b56Dk6dwNZgbfaz6_sT3Dk-ERLMVvNfJx59Sex7vxLI,321
+simple_logistics/logistics.py,sha256=1j-wafSPABnfYp3Jl1KvrB8jW4gwGj9f7UyqdMaeBB4,33235
+simple_logistics-0.1.0.dist-info/licenses/LICENSE,sha256=K9ubANS_GxRR_00SKXCCus_uMaoz31S66iW-A0LWZIc,1105
+simple_logistics-0.1.0.dist-info/METADATA,sha256=ws-l3WZL_YFgF9e2nOQapczSlDdEhjT1ktUQ8hTrjoE,4978
+simple_logistics-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+simple_logistics-0.1.0.dist-info/top_level.txt,sha256=wtIMdbOUB-XXfA89SsSP7cVuLl3O5gsoebeWvq_Xu50,17
+simple_logistics-0.1.0.dist-info/RECORD,,

simple_logistics-0.1.0.dist-info/WHEEL

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

simple_logistics-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Txaber Ajangiz , Beñat Monje
+
+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.

simple_logistics-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+simple_logistics