mlafactory 0.1.0__py3-none-any.whl

mlafactory/FactoryRunner.py

@@ -0,0 +1,411 @@
+"""
+mlafactory Simulation Framework
+
+This project implements a discrete-event simulation framework for modeling
+multi-level assembly (MLA) manufacturing systems using the SimPy library.
+
+Modules in this project simulate:
+- Order processing and dynamic production scheduling
+- Inventory management with configurable stock thresholds
+- Machine operations and resource planning
+- Multi-level component dependencies using bill of materials (BOM)
+- Automated report generation and performance analysis
+
+Developed by: Oscar J. Castro-Lopez
+Affiliation: University of Luxembourg
+"""
+
+import json
+import logging
+import random
+import time
+from pathlib import Path
+from typing import Dict, List, Union
+
+import pandas as pd
+import simpy
+import yaml
+from mlafactory.aux_files import InputValidationError
+from mlafactory.aux_intervals import generate_wait_intervals
+from mlafactory.aux_reports import collect_results, save_reports_to_folder
+from mlafactory.FactorySimulator import FactorySimulator
+
+
+def setup_logging(debug_mode, factory_name):
+    """Configures logging based on debug flag."""
+    if debug_mode:
+        logging.basicConfig(
+            level=logging.DEBUG,
+            format="%(levelname)s: %(message)s",
+            filename=f"{factory_name}.log",
+            filemode="w",  # 'w' overwrites
+            encoding="utf-8",
+        )
+    else:
+        logging.basicConfig(
+            level=logging.INFO,
+            format="%(levelname)s: %(message)s",
+            handlers=[logging.StreamHandler()],  # Log to console only
+        )
+
+
+class FactoryRunner:
+    """
+    Orchestrator class for running a multi-level assembly (MLA)
+    factory simulation.
+
+    This class configures the simulation environment, validates inputs,
+    triggers, production scheduling, and collects/report results.
+
+    Args:
+        factory_name: str
+            Name of the factory.
+        product_demand: dict
+            Demand per order ID, mapping to products and quantities.
+        bom: dict
+            Bill of materials structure.
+        initial_inventory: dict
+            Initial inventory levels for all components.
+        machines: list
+            List of machines with their capabilities and specs.
+        stock_limits: dict
+            Min/max stock level limits for each component.
+        reorder_delays: dict
+            Metadata for raw materials.
+        inventory_strategy: str
+            Strategy to initialize inventory of raw material. Default 'max'.
+        inventory_seed: int
+            Random seed in case the strategy of initialize inventory is random.
+            Default 42.
+        months: int
+            Simulation duration in months (default: 12).
+        hours_per_month: int
+            Work hours per month (default: 160).
+        order_mode: str
+            How orders are spaced ("fixed", "random", etc.).
+        order_mode_params: dict
+            Parameters controlling order spacing.
+        show_output: bool
+            Whether to print results to console.
+        show_debug: bool
+            Enable debug logging.
+        export_reports: bool
+            Save reports to disk after simulation.
+        output_dir: str
+            Output folder for saving reports.
+        waiting_intervals: List[int], Optional
+            Precomputed wait intervals (optional).
+    """
+
+    def __init__(
+        self,
+        factory_name: str,
+        product_demand: Dict,
+        bom: Dict,
+        initial_inventory: Dict,
+        machines: List,
+        stock_limits: Dict,
+        reorder_delays: Dict,
+        inventory_strategy: str = "max",
+        inventory_seed: int = 42,
+        months: int = 12,
+        hours_per_month: int = 160,
+        order_mode: str = "fixed",
+        order_mode_params: Union[Dict, None] = None,
+        show_output: bool = False,
+        show_debug: bool = False,
+        export_reports: bool = False,
+        output_dir: str = "output/",
+        waiting_intervals: Union[List, None] = None,
+    ):
+        # Simulation config
+        self.factory_name = factory_name
+        self.product_demand = product_demand
+        self.bom = bom
+        self.initial_inventory = initial_inventory
+        self.machines = machines
+        self.stock_limits = stock_limits
+        self.reorder_delays = reorder_delays
+        self.inventory_strategy = inventory_strategy
+        self.inventory_seed = inventory_seed
+        self.order_mode = order_mode
+        self.order_mode_params = order_mode_params or {"interval": 1}
+        self.simulation_time = months * hours_per_month
+        self.months = months
+        self.hours_per_month = hours_per_month
+
+        # Logging and output options
+        self.show_output = show_output
+        self.show_debug = show_debug
+        self.export_reports = export_reports
+        self.output_dir = output_dir
+
+        self.env = simpy.Environment()
+        self.waiting_intervals = waiting_intervals
+
+        self._setup_logging()
+
+    def _setup_logging(self):
+        """Configure logging for this simulation run."""
+        setup_logging(self.show_debug, self.factory_name)
+
+    def _generate_waiting_intervals(self):
+        """Generate order wait intervals based on configured
+        mode and parameters."""
+        return generate_wait_intervals(
+            n_orders=len(self.product_demand),
+            mode=self.order_mode,
+            params=self.order_mode_params,
+            simulation_time=self.simulation_time,
+        )
+
+    def _validate_raw_materials(self):
+        for product, details in self.bom.items():
+            for comp, comp_details in details.get("bom", {}).items():
+                if (
+                    comp_details.get("type") == "raw"
+                    and comp not in self.reorder_delays
+                ):
+                    msg = (
+                        f"Raw component '{comp}' used in '{product}' "
+                        "is missing in component_info."
+                    )
+                    logging.error(msg)
+                    raise InputValidationError(msg)
+
+    def _validate_demand_products(self):
+        bom_products = set(self.bom)
+        for order_id, order_items in self.product_demand.items():
+            for product in order_items:
+                if product not in bom_products:
+                    msg = (
+                        f"Product '{product}' in order '{order_id}' "
+                        "is not defined in BOM."
+                    )
+                    logging.error(msg)
+                    raise InputValidationError(msg)
+
+    def _validate_stock_limits(self):
+        bom_products = set(self.bom)
+        missing_limits = [
+            item
+            for item in bom_products | set(self.reorder_delays)
+            if item not in self.stock_limits
+        ]
+        if missing_limits:
+            for item in missing_limits:
+                logging.error("Missing stock_limits entry for '%s'.", item)
+            raise InputValidationError(
+                "Stock limits missing for one or more components."
+            )
+
+    def _initialize_inventory(self):
+        rng = random.Random(self.inventory_seed)
+        for product, details in self.bom.items():
+            self._set_initial_inventory(product, 0)
+            for comp, comp_details in details.get("bom", {}).items():
+                initial_value = self._get_initial_value(comp, comp_details, rng)
+                self._set_initial_inventory(comp, initial_value)
+
+    def _get_initial_value(self, comp, comp_details, rng):
+        if comp_details.get("type") != "raw":
+            return 0
+        strategy = self.inventory_strategy
+        limits = self.stock_limits[comp]
+        if strategy == "max":
+            return limits["max"]
+        if strategy == "min":
+            return limits["min"]
+        if strategy == "random":
+            return rng.randint(limits["min"], limits["max"])
+        if strategy == "zero":
+            return 0
+
+    def _set_initial_inventory(self, item, value):
+        self.initial_inventory.setdefault(item, value)
+        logging.debug(
+            "Inventory initialized: %s = %s", item, self.initial_inventory[item]
+        )
+
+    def _check_min_stock_constraints(self):
+        for product, details in self.bom.items():
+            components = details.get("bom", {})
+            for comp_key, comp_val in components.items():
+                required_qty = comp_val["qty"]
+                min_stock = self.stock_limits[comp_key]["min"]
+                if required_qty > min_stock:
+                    logging.warning(
+                        "Component '%s': min stock (%s) is less than required "
+                        "in BOM for '%s' (%s). Simulation may get stuck if "
+                        "stock is depleted.",
+                        comp_key,
+                        min_stock,
+                        product,
+                        required_qty,
+                    )
+
+    def _validate_bom_machines(self):
+        """
+        Validate that the machines are able to build
+        the products specified in the BOM,
+        Raises:
+            InputValidationError: If a type of machine is missing.
+        """
+        machine_types = set()
+        for machine in self.machines:
+            machine_types.add(machine["type"])
+
+        bom_set = set()
+        for _, product_val in self.bom.items():
+            bom_set.add(product_val["type"])
+
+        difference = bom_set - machine_types
+        if len(difference) > 0:
+            msg = f"There are no machines for the products: {difference}."
+            logging.error(msg)
+            raise InputValidationError(msg)
+
+    def _start_production(
+        self,
+        factory: FactorySimulator,
+    ):
+        """
+        Start the production process by adding orders at specified intervals.
+        """
+        for wait, (key, val) in zip(self.wait_intervals, self.product_demand.items()):
+            yield self.env.timeout(wait)
+            products = val
+            for product_type, quantity in products.items():
+                factory.add_order(key, product_type, quantity)
+
+    def prepare_and_validate(self):
+        """
+        Validate all major inputs before running the simulation.
+        Ensures consistency across BOM, inventory, demand, and
+        component metadata.
+        Raises:
+            InputValidationError: If any input validation check fails.
+        """
+        self._validate_bom_machines()
+        self._validate_raw_materials()
+        self._validate_demand_products()
+        self._validate_stock_limits()
+        self._initialize_inventory()
+        self._check_min_stock_constraints()
+        logging.debug("All input validations passed.")
+
+    def run(self) -> Dict:
+        """
+        Execute the simulation and return collected results.
+        Returns:
+            dict: Summary statistics including production, inventory, and
+            machine usage.
+        """
+        self.env = simpy.Environment()  # reset for re-runs
+        self.prepare_and_validate()
+
+        self.wait_intervals = (
+            self.waiting_intervals or self._generate_waiting_intervals()
+        )
+
+        factory = FactorySimulator(
+            self.env,
+            self.factory_name,
+            self.machines,
+            self.initial_inventory,
+            self.reorder_delays,
+            self.bom,
+            self.stock_limits,
+        )
+
+        # Start process
+        self.env.process(self._start_production(factory))
+
+        # Run environment
+        start_time = time.time()
+        self.env.run(until=self.simulation_time)
+        elapsed = time.time() - start_time
+        logging.debug("Elapsed real-world time: %s seconds", f"{elapsed:.2f}")
+
+        # Add the last time to the machines
+        for _, machine_dict in factory.machines.items():
+            for machine in machine_dict["machines"]:
+                last_task, _, _ = machine.current_task
+                machine.task_durations[last_task] += (
+                    self.simulation_time - machine.last_start
+                )
+
+        # Collect results
+        (production_summary, machines_summary, inventory_summary) = collect_results(
+            factory, self.product_demand
+        )
+
+        if self.show_output or self.export_reports:
+            production_df = pd.DataFrame(production_summary)
+            machines_df = pd.DataFrame(machines_summary)
+            inventory_df = pd.DataFrame(inventory_summary).T.reset_index()
+            inventory_df = inventory_df.rename(columns={"index": "item"})
+            self._show_output(elapsed, production_df, machines_df, inventory_df)
+            self._export_reports(factory, production_df, machines_df, inventory_df)
+
+        return {
+            "simulation_time": self.simulation_time,
+            "real_simulation_time": elapsed,
+            "production": production_summary,
+            "machines": machines_summary,
+            "inventory": inventory_summary,
+        }
+
+    def _show_output(self, elapsed, production_df, machines_df, inventory_df):
+        """Prints simulation results to console."""
+        if self.show_output:
+            print(f"Elapsed real time: {elapsed}")
+            print(f"Total simulated time: {self.simulation_time} hours")
+            print("=" * 40, "Production Results", "=" * 40)
+            print(production_df)
+            print("=" * 40, "Machines Summary", "=" * 40)
+            print(machines_df)
+            print("=" * 40, "Inventory Summary", "=" * 40)
+            print(inventory_df)
+
+    def _export_reports(self, factory, production_df, machines_df, inventory_df):
+        """Save simulation reports to disk."""
+        if self.export_reports:
+            save_reports_to_folder(
+                factory,
+                self.factory_name,
+                self.output_dir,
+                production_df,
+                machines_df,
+                inventory_df,
+            )
+
+    @classmethod
+    def from_config(cls, path: str) -> "FactoryRunner":
+        """
+        Load configuration from a JSON or YAML file and create a FactoryRunner
+        instance.
+
+        Args:
+            path: Path to a JSON or YAML configuration file.
+
+        Returns:
+            FactoryRunner instance.
+        """
+        config_path = Path(path)
+        if not config_path.exists():
+            raise FileNotFoundError(f"Config file not found: {config_path}")
+
+        # Detect file type
+        if config_path.suffix in [".yaml", ".yml"]:
+            with open(config_path, "r", encoding="utf-8") as f:
+                config = yaml.safe_load(f)
+        elif config_path.suffix == ".json":
+            with open(config_path, "r", encoding="utf-8") as f:
+                config = json.load(f)
+        else:
+            raise ValueError(f"Unsupported config format: {config_path.suffix}")
+
+        # Optional: validate required keys or normalize config here
+
+        return cls(**config)