mlafactory 0.1.2__tar.gz → 0.2.3__tar.gz

{mlafactory-0.1.2 → mlafactory-0.2.3}/MANIFEST.in

@@ -1 +1,2 @@
 recursive-include src/mlafactory/minimal_example *.json
+recursive-include src/mlafactory/examples *.json *.yaml

mlafactory-0.2.3/PKG-INFO

@@ -0,0 +1,247 @@
+Metadata-Version: 2.4
+Name: mlafactory
+Version: 0.2.3
+Summary: Digital Multi-Level Assembly (MLA) manufacturing factory simulation made with SimPy
+Author-email: "Oscar J. Castro-Lopez" <oscar.castro@uni.lu>
+License-Expression: BSD-3-Clause
+Project-URL: Homepage, https://gitlab.com/uniluxembourg/hpc/research/cadom/mla_factory
+Project-URL: Repository, https://gitlab.com/uniluxembourg/hpc/research/cadom/mla_factory
+Project-URL: Documentation, https://gitlab.com/uniluxembourg/hpc/research/cadom/mla_factory
+Project-URL: Issues, https://gitlab.com/uniluxembourg/hpc/research/cadom/mla_factory/-/issues
+Keywords: simulation,manufacturing,factory,MLA,discrete-event simulation,simpy
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: simpy>=4.0
+Requires-Dist: numpy>=1.23.2
+Requires-Dist: pandas>=1.5
+Requires-Dist: pyyaml>=6.0.1
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Provides-Extra: dev
+Requires-Dist: mlafactory[test]; extra == "dev"
+Requires-Dist: ruff==0.15.6; extra == "dev"
+Dynamic: license-file
+
+# mlafactory
+
+[![PyPI version](https://badge.fury.io/py/mlafactory.svg)](https://badge.fury.io/py/mlafactory)
+[![License: BSD-3](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+
+`mlafactory` is an open-source discrete-event simulation framework for modeling **Multi-Level Assembly (MLA)** manufacturing systems. Built on top of [SimPy](https://simpy.readthedocs.io/), it enables flexible simulation of factories with dynamic inventory management, heterogeneous machine pools, stochastic order arrivals, and configurable production and replenishment policies.
+
+The framework is designed for **research, experimentation, and reproducible evaluation** of manufacturing strategies.
+
+---
+
+## Features
+
+- **Multi-level bill of materials (BOM)** — recursive assembly of products from sub-components and raw materials
+- **Heterogeneous machine pools** — multiple machine types with configurable setup times, cycle times, and costs
+- **Dynamic inventory management** — min/max stock policies with async waiting and automatic replenishment
+- **Stochastic order arrivals** — fixed, random, spread, or distribution-based inter-order intervals
+- **Configurable replenishment** — per-component reorder delays for raw materials
+- **Multiple inventory initialization strategies** — zero, min, max, or random initial stock levels
+- **Rich reporting** — production service levels, machine utilization, and inventory summaries exported as CSV
+- **CLI and Python API** — run simulations without writing code or integrate programmatically
+- **YAML / JSON configuration** — fully reproducible experiments via configuration files
+
+---
+
+## Requirements
+
+- Python 3.11+
+- SimPy >= 4.0
+- NumPy
+- pandas
+- PyYAML
+
+---
+
+## Installation
+
+
+```bash
+pip install mlafactory
+```
+
+Install from source:
+
+```bash
+git clone https://gitlab.com/uniluxembourg/hpc/research/cadom/mla_factory.git
+cd mla_factory
+pip install -e .
+```
+
+---
+
+## Quick Start
+
+### Command Line
+
+The CLI uses the bundled example configuration when no input options are
+provided. Print a summary with:
+
+```bash
+mlafactory --print-summary
+```
+
+Run a custom YAML or JSON configuration:
+
+```bash
+mlafactory --factory-config my_factory.yml --print-summary
+```
+
+### Python API
+
+```python
+from mlafactory import FactoryRunner
+
+runner = FactoryRunner.from_config("my_factory.yml")
+result = runner.run()
+
+print(result.fulfillment_ratio)
+print(result.production)  # pandas DataFrame, including a TOTAL row
+
+# Score a run directly. "production" aliases total "produced_qty".
+score = runner.run_objective("fulfillment_ratio")
+```
+
+To configure a runner in Python, create a `FactoryConfig` and `RunOptions`:
+
+```python
+from mlafactory.config.config import FactoryConfig, RunOptions
+from mlafactory import FactoryRunner
+
+# config_data is a mapping with the fields in the sample YAML/JSON file.
+# congid_data must contain 'orders', 'bom', 'initial_inventory', 'machines', 'inventory_policy_bounds', and 'supplier_lead_times'
+config = FactoryConfig.from_dict(config_data)
+options = RunOptions(print_summary=True)
+runner = FactoryRunner(config, options)
+result = runner.run()
+```
+
+The full sample configurations are [`min_example.yaml`](src/mlafactory/examples/min_example.yaml) and [`min_example.json`](src/mlafactory/examples/min_example.json).
+
+---
+
+## Documentation
+
+Additional documentation is available in [`docs/`](docs/):
+
+| File | Description |
+|---|---|
+| [`docs/cli.md`](docs/cli.md) | Additional command-line usage notes |
+| [`docs/simulation_model.md`](docs/simulation_model.md) | Simulation architecture and event flow |
+---
+
+## Configuration
+
+Use one YAML or JSON configuration file with these top-level sections:
+
+- `orders`: mapping of order IDs to product quantities
+- `bom`: products and components, each with a machine `type` and nested `bom`
+- `machines`: machine names, types, setup/cycle times, and optional costs
+- `supplier_lead_times`: raw material reorder delays
+- `inventory_policy_bounds`: `min` and `max` stock limits for every BOM or
+  supplier item
+- `initial_inventory`: optional explicit starting stock
+- Optional run settings include `factory_name`, `months`, `hours_per_month`,
+  `seed`, `inventory_strategy`, `order_mode`, and `order_mode_params`
+
+For complete, valid examples, see [`min_example.yaml`](src/mlafactory/examples/min_example.yaml)
+or [`min_example.json`](src/mlafactory/examples/min_example.json). Machine setup
+and cycle times are expressed in minutes; the simulation duration and reorder
+delays use simulation-time hours.
+
+Order interval modes are `fixed`, `random`, `spread`, and `distribution`.
+Distribution mode supports `poisson` and `normal`. The configured seed controls
+random initial inventory and stochastic order intervals.
+
+To export CSV reports, set `export_reports: true` in the configuration or pass
+`--export-reports`; choose the destination with `output_dir` or `--output-dir`.
+The CLI options `--print-summary`, `--debug-logs`, and `--export-reports` enable
+their respective outputs.
+
+---
+
+## Project Structure
+
+```
+mlafactory/
+├── src/mlafactory/
+│   ├── cli.py                  # command-line entry point
+│   ├── runner.py               # public simulation orchestrator
+│   ├── config/                 # configuration, validation, and reporting
+│   ├── examples/               # bundled YAML/JSON configurations
+│   ├── optimization/           # stock-policy optimization adapter
+│   ├── scenario/               # initial inventory and order scheduling
+│   └── sim/                    # SimPy simulation entities
+├── docs/
+├── tests/
+└── README.md
+```
+
+---
+
+## Running Tests
+
+```bash
+pip install -e ".[test]"
+python -m pytest
+```
+
+---
+
+## License
+
+BSD 3-Clause License. See [LICENSE](LICENSE) for details.
+
+---
+
+## Citation
+
+To be completed.
+<!--
+If you use mlafactory in your research, please cite:
+
+```bibtex
+@article{mlafactory2025,
+  title   = {mlafactory: A Discrete-Event Simulation Framework for Multi-Level Assembly Systems},
+  author  = {Your Name},
+  journal = {Journal of Open Source Software},
+  year    = {2025},
+  doi     = {10.xxxx/joss.xxxxx}
+}
+```
+-->
+---
+
+## Authors
+
+Developer and maintainer:
+
+**Oscar J. Castro-Lopez**: 
+Research Associate, University of Luxembourg
+
+Contributors:
+
+- **Pierrick Pochelu**  DevOps, LuxProvide
+- **Georgios Kafanas**  Infrastructure and Architecture Engineer, University of Luxembourg
+
+Contributions welcome — please open an issue or pull request on GitLab.
+
+## Acknowledgements
+
+This project was created with the support of the Luxembourg National Research Fund (FNR) under project 17941664. Supported by the Ministry of Economy (MECO) under project 17941664.

mlafactory-0.2.3/README.md

@@ -0,0 +1,212 @@
+# mlafactory
+
+[![PyPI version](https://badge.fury.io/py/mlafactory.svg)](https://badge.fury.io/py/mlafactory)
+[![License: BSD-3](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+
+`mlafactory` is an open-source discrete-event simulation framework for modeling **Multi-Level Assembly (MLA)** manufacturing systems. Built on top of [SimPy](https://simpy.readthedocs.io/), it enables flexible simulation of factories with dynamic inventory management, heterogeneous machine pools, stochastic order arrivals, and configurable production and replenishment policies.
+
+The framework is designed for **research, experimentation, and reproducible evaluation** of manufacturing strategies.
+
+---
+
+## Features
+
+- **Multi-level bill of materials (BOM)** — recursive assembly of products from sub-components and raw materials
+- **Heterogeneous machine pools** — multiple machine types with configurable setup times, cycle times, and costs
+- **Dynamic inventory management** — min/max stock policies with async waiting and automatic replenishment
+- **Stochastic order arrivals** — fixed, random, spread, or distribution-based inter-order intervals
+- **Configurable replenishment** — per-component reorder delays for raw materials
+- **Multiple inventory initialization strategies** — zero, min, max, or random initial stock levels
+- **Rich reporting** — production service levels, machine utilization, and inventory summaries exported as CSV
+- **CLI and Python API** — run simulations without writing code or integrate programmatically
+- **YAML / JSON configuration** — fully reproducible experiments via configuration files
+
+---
+
+## Requirements
+
+- Python 3.11+
+- SimPy >= 4.0
+- NumPy
+- pandas
+- PyYAML
+
+---
+
+## Installation
+
+
+```bash
+pip install mlafactory
+```
+
+Install from source:
+
+```bash
+git clone https://gitlab.com/uniluxembourg/hpc/research/cadom/mla_factory.git
+cd mla_factory
+pip install -e .
+```
+
+---
+
+## Quick Start
+
+### Command Line
+
+The CLI uses the bundled example configuration when no input options are
+provided. Print a summary with:
+
+```bash
+mlafactory --print-summary
+```
+
+Run a custom YAML or JSON configuration:
+
+```bash
+mlafactory --factory-config my_factory.yml --print-summary
+```
+
+### Python API
+
+```python
+from mlafactory import FactoryRunner
+
+runner = FactoryRunner.from_config("my_factory.yml")
+result = runner.run()
+
+print(result.fulfillment_ratio)
+print(result.production)  # pandas DataFrame, including a TOTAL row
+
+# Score a run directly. "production" aliases total "produced_qty".
+score = runner.run_objective("fulfillment_ratio")
+```
+
+To configure a runner in Python, create a `FactoryConfig` and `RunOptions`:
+
+```python
+from mlafactory.config.config import FactoryConfig, RunOptions
+from mlafactory import FactoryRunner
+
+# config_data is a mapping with the fields in the sample YAML/JSON file.
+# congid_data must contain 'orders', 'bom', 'initial_inventory', 'machines', 'inventory_policy_bounds', and 'supplier_lead_times'
+config = FactoryConfig.from_dict(config_data)
+options = RunOptions(print_summary=True)
+runner = FactoryRunner(config, options)
+result = runner.run()
+```
+
+The full sample configurations are [`min_example.yaml`](src/mlafactory/examples/min_example.yaml) and [`min_example.json`](src/mlafactory/examples/min_example.json).
+
+---
+
+## Documentation
+
+Additional documentation is available in [`docs/`](docs/):
+
+| File | Description |
+|---|---|
+| [`docs/cli.md`](docs/cli.md) | Additional command-line usage notes |
+| [`docs/simulation_model.md`](docs/simulation_model.md) | Simulation architecture and event flow |
+---
+
+## Configuration
+
+Use one YAML or JSON configuration file with these top-level sections:
+
+- `orders`: mapping of order IDs to product quantities
+- `bom`: products and components, each with a machine `type` and nested `bom`
+- `machines`: machine names, types, setup/cycle times, and optional costs
+- `supplier_lead_times`: raw material reorder delays
+- `inventory_policy_bounds`: `min` and `max` stock limits for every BOM or
+  supplier item
+- `initial_inventory`: optional explicit starting stock
+- Optional run settings include `factory_name`, `months`, `hours_per_month`,
+  `seed`, `inventory_strategy`, `order_mode`, and `order_mode_params`
+
+For complete, valid examples, see [`min_example.yaml`](src/mlafactory/examples/min_example.yaml)
+or [`min_example.json`](src/mlafactory/examples/min_example.json). Machine setup
+and cycle times are expressed in minutes; the simulation duration and reorder
+delays use simulation-time hours.
+
+Order interval modes are `fixed`, `random`, `spread`, and `distribution`.
+Distribution mode supports `poisson` and `normal`. The configured seed controls
+random initial inventory and stochastic order intervals.
+
+To export CSV reports, set `export_reports: true` in the configuration or pass
+`--export-reports`; choose the destination with `output_dir` or `--output-dir`.
+The CLI options `--print-summary`, `--debug-logs`, and `--export-reports` enable
+their respective outputs.
+
+---
+
+## Project Structure
+
+```
+mlafactory/
+├── src/mlafactory/
+│   ├── cli.py                  # command-line entry point
+│   ├── runner.py               # public simulation orchestrator
+│   ├── config/                 # configuration, validation, and reporting
+│   ├── examples/               # bundled YAML/JSON configurations
+│   ├── optimization/           # stock-policy optimization adapter
+│   ├── scenario/               # initial inventory and order scheduling
+│   └── sim/                    # SimPy simulation entities
+├── docs/
+├── tests/
+└── README.md
+```
+
+---
+
+## Running Tests
+
+```bash
+pip install -e ".[test]"
+python -m pytest
+```
+
+---
+
+## License
+
+BSD 3-Clause License. See [LICENSE](LICENSE) for details.
+
+---
+
+## Citation
+
+To be completed.
+<!--
+If you use mlafactory in your research, please cite:
+
+```bibtex
+@article{mlafactory2025,
+  title   = {mlafactory: A Discrete-Event Simulation Framework for Multi-Level Assembly Systems},
+  author  = {Your Name},
+  journal = {Journal of Open Source Software},
+  year    = {2025},
+  doi     = {10.xxxx/joss.xxxxx}
+}
+```
+-->
+---
+
+## Authors
+
+Developer and maintainer:
+
+**Oscar J. Castro-Lopez**: 
+Research Associate, University of Luxembourg
+
+Contributors:
+
+- **Pierrick Pochelu**  DevOps, LuxProvide
+- **Georgios Kafanas**  Infrastructure and Architecture Engineer, University of Luxembourg
+
+Contributions welcome — please open an issue or pull request on GitLab.
+
+## Acknowledgements
+
+This project was created with the support of the Luxembourg National Research Fund (FNR) under project 17941664. Supported by the Ministry of Economy (MECO) under project 17941664.

mlafactory-0.2.3/pyproject.toml

@@ -0,0 +1,86 @@
+[build-system]
+requires = ["setuptools>=77.0.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mlafactory"
+version = "0.2.3"
+description = "Digital Multi-Level Assembly (MLA) manufacturing factory simulation made with SimPy"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "BSD-3-Clause"
+license-files = ["LICENSE"]
+authors = [
+    {name = "Oscar J. Castro-Lopez", email = "oscar.castro@uni.lu" },
+]
+keywords = [
+  "simulation", "manufacturing", "factory", "MLA",
+  "discrete-event simulation", "simpy",
+]
+
+
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Operating System :: OS Independent",
+  "Intended Audience :: Science/Research",
+  "Topic :: Scientific/Engineering",
+]
+ 
+# Lower bounds are PLACEHOLDERS: the `test-lowest` CI job installs exactly these
+# versions on the oldest Python. Raise each one until that job is green.
+dependencies = [
+  "simpy>=4.0",
+  "numpy>=1.23.2",
+  "pandas>=1.5",
+  "pyyaml>=6.0.1",
+]
+
+[project.optional-dependencies]
+test = ["pytest>=7", "pytest-cov"]
+dev = ["mlafactory[test]", "ruff==0.15.6"]
+
+
+[project.scripts]
+mlafactory = "mlafactory.cli:main"
+
+[project.urls]
+Homepage = "https://gitlab.com/uniluxembourg/hpc/research/cadom/mla_factory"
+Repository = "https://gitlab.com/uniluxembourg/hpc/research/cadom/mla_factory"
+Documentation = "https://gitlab.com/uniluxembourg/hpc/research/cadom/mla_factory"
+Issues = "https://gitlab.com/uniluxembourg/hpc/research/cadom/mla_factory/-/issues"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+"mlafactory" = [
+  "examples/*.json",
+  "examples/*.yaml",
+  "examples/individual_files/*.json",
+  "minimal_example/*.json",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra"
+ 
+[tool.coverage.run]
+source = ["mlafactory"]
+branch = true
+ 
+[tool.ruff]
+target-version = "py311"   # flags syntax that would break on the oldest supported Python
+src = ["src"]
+ 
+[tool.ruff.lint]
+select = ["E", "F", "I", "B"]
+ 

mlafactory-0.2.3/src/mlafactory/__init__.py

@@ -0,0 +1,5 @@
+"""Public package interface for mlafactory."""
+
+from .runner import FactoryRunner
+
+__all__ = ["FactoryRunner"]

mlafactory-0.2.3/src/mlafactory/cli.py

@@ -0,0 +1,108 @@
+"""Command-line entry point for running a factory simulation.
+
+Precedence of values: command line > config file > defaults.
+Only options explicitly typed on the command line override file values.
+"""
+
+import sys
+from typing import Any
+
+from mlafactory.config.arguments import (
+    MODULE_FILE_OPTIONS,
+    get_args,
+    get_default_input_folder,
+)
+from mlafactory.config.config import (
+    FactoryConfig,
+    RunOptions,
+    load_config_file,
+)
+from mlafactory.config.files import InputValidationError, load_json_inputs
+from mlafactory.runner import FactoryRunner
+
+# Mapping of CLI flag names to internal OrderScheduleParams field names
+ORDER_PARAM_KEYS = {
+    "fixed_interval_hours",
+    "random_interval_range",
+    "dist_type",
+    "poisson_lambda",
+    "normal_mean_std",
+}
+
+
+def process_order_schedule_params(cli_dict: dict[str, Any]) -> dict[str, Any]:
+    """Extract flat order schedule CLI parameters into a nested dict."""
+    order_params = {}
+    for key in ORDER_PARAM_KEYS:
+        if key in cli_dict:
+            order_params[key] = cli_dict.pop(key)
+    if order_params:
+        cli_dict["order_mode_params"] = order_params
+    return cli_dict
+
+
+def build_runner(cli_overrides: dict[str, Any]) -> FactoryRunner:
+    """Construct FactoryRunner by combining config files, inputs, and CLI overrides."""
+    # Extract order schedule CLI flags into nested order_mode_params
+    cli_overrides = process_order_schedule_params(cli_overrides)
+
+    config_file = cli_overrides.pop("factory_config", None)
+
+    if config_file:
+        # Load base configuration from file
+        file_data = load_config_file(config_file)
+
+        # Merge nested order_mode_params if both file and CLI overrides exist
+        if "order_mode_params" in cli_overrides and "order_mode_params" in file_data:
+            merged_order_params = {
+                **file_data["order_mode_params"],
+                **cli_overrides["order_mode_params"],
+            }
+            cli_overrides["order_mode_params"] = merged_order_params
+
+        if cli_overrides:
+            _announce(config_file, cli_overrides)
+
+        # CLI overrides take precedence over config file
+        data = {**file_data, **cli_overrides}
+    else:
+        # Load inputs from directory
+        input_folder = cli_overrides.pop("input_folder", get_default_input_folder())
+        inputs = load_json_inputs(input_folder, cli_overrides, MODULE_FILE_OPTIONS)
+
+        # Combine JSON folder inputs with explicit CLI overrides
+        data = {**inputs, **cli_overrides}
+
+    # Instantiate dataclasses cleanly
+    factory_config = FactoryConfig.from_dict(data)
+    run_options = RunOptions.from_dict(data)
+
+    return FactoryRunner(factory_config, run_options)
+
+
+def _announce(config_file: str, overrides: dict[str, Any]) -> None:
+    """Notify user of CLI overrides taking precedence over configuration file."""
+    shown = ", ".join(f"{key}={value}" for key, value in overrides.items())
+    print(
+        f"mlafactory: using {config_file}; command-line overrides applied: {shown}",
+        file=sys.stderr,
+    )
+
+
+def main(argv=None) -> int:
+    """Run the factory simulation from CLI arguments or a config file."""
+    cli_overrides = {}
+    try:
+        cli_overrides = get_args(argv)
+        runner = build_runner(cli_overrides)
+        runner.run()
+    except (InputValidationError, FileNotFoundError, ValueError) as error:
+        if cli_overrides.get("debug_logs"):
+            raise
+        print(f"mlafactory: error: {error}", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())