Metadata-Version: 2.4
Name: mlafactory
Version: 0.1.1
Summary: Digital Multi-Level Assembly (MLA) manufacturing factory simulation made with SimPy
Author-email: "Oscar J. Castro-Lopez" <oscar.castro@uni.lu>
Maintainer-email: Pierrick Pochelu <pierrick.pochelu@gmail.com>, Georgios Kafanas <georgios.kafanas@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
Keywords: simulation,manufacturing,factory,MLA
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: simpy
Requires-Dist: pandas
Requires-Dist: numpy
Requires-Dist: pyyaml
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.9+](https://img.shields.io/badge/python-3.9+-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.9+
- SimPy >= 4.0
- pandas
- PyYAML

---

## Installation

<!-- To be completed
```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

`mlafactory` ships with a built-in bike factory example:

```bash
mlafactory --show-output
```

To run with a custom configuration file:

```bash
mlafactory --factory-config my_factory.yml --show-output
```

### Python API

```python
from mlafactory.FactoryRunner import FactoryRunner

# Load from a configuration file
simulator = FactoryRunner.from_config("my_factory.yml")
result = simulator.run()

# Or configure programmatically
simulator = FactoryRunner(
    factory_name="BikeFactory",
    bom=bom,
    initial_inventory=initial_inventory,
    reorder_delays=reorder_delays,
    product_demand=product_demand,
    machines=machines,
    stock_limits=stock_limits,
    months=12,
    hours_per_month=160,
    inventory_strategy="max",
    show_output=True,
    export_reports=True,
    output_dir="output/",
)
result = simulator.run()
```

### Expected Output

```
Elapsed real time: 0.02940058708190918
Total simulated time: 1920 hours
======================================== Production Results ========================================
        product  demand  fulfilled  inventory  production  fulfillment_ratio  production_ratio
0      RoadBike      52         26          6          32           0.500000          0.615385
1  MountainBike      65         57          6          63           0.876923          0.969231
2  ElectricBike      63         28          3          31           0.444444          0.492063
3         TOTAL     180        111         15         126           0.616667          0.692226
======================================== Machines Summary ========================================
     type  name  setup_time  cycle_time  n_setups  n_cycles  setup_cost  cycle_cost  tt_setup   tt_build      tt_idle
0    bike  bk01         1.0        25.0        13        32           0         0.0  0.216667  13.333333  1906.450000
1    bike  bk02         2.0        20.0        13        32           0         0.0  0.433333  10.666667  1908.900000
2    bike  bk03         3.0        19.0        14        31           0         0.0  0.700000   9.816667  1909.483333
3    bike  bk04         4.0        17.0        14        31           0         0.0  0.933333   8.783333  1910.283333
4   frame  fr01         2.0        15.0         3        43           0         0.0  0.100000  10.750000  1909.150000
5   frame  fr02         3.0        12.0         2        39           0         0.0  0.100000   7.800000  1912.100000
6   frame  fr03         3.0        13.0         3        39           0         0.0  0.150000   8.450000  1911.400000
7   frame  fr04         4.0        14.0         2        53           0         0.0  0.133333  12.366667  1907.500000
8   wheel  wl01         3.0         8.0        29        43           0         0.0  1.450000   5.733333  1912.816667
9   wheel  wl02        10.0         5.0        29        43           0         0.0  4.833333   3.583333  1911.583333
10  wheel  wl03         1.0        10.0         4        42           0         0.0  0.066667   7.000000  1912.933333
11  wheel  wl04         2.0         7.0         4        42           0         0.0  0.133333   4.900000  1914.966667
12  wheel  wl05         9.0         6.0         4        42           0         0.0  0.600000   4.200000  1915.200000
13  wheel  wl06         3.0         5.0         4        42           0         0.0  0.200000   3.500000  1916.300000
======================================== Inventory Summary ========================================
                item  initial  consumed  final  n_reorders
0       MountainBike      0.0      57.0    6.0         NaN
1           RoadBike      0.0      26.0    6.0         NaN
2       ElectricBike      0.0      28.0    3.0         NaN
3            wheel_a      0.0     126.0    1.0         NaN
4            wheel_b      0.0     126.0    1.0         NaN
5            frame_a      0.0      97.0   27.0         NaN
6            frame_b      0.0      32.0   18.0         NaN
7              pedal     10.0     258.0   16.0        22.0
8          crank_arm      5.0     129.0   13.0        22.0
9   front_derailleur      4.0     129.0   12.0        22.0
10             chain      3.0     129.0   12.0        22.0
11       chain_rings      2.0     129.0   12.0        22.0
12       rear_brakes      1.0     129.0   12.0        22.0
13            cogset      2.0     129.0   12.0        22.0
14   rear_derailleur      3.0     129.0   12.0        22.0
15            spokes     25.0    6350.0   10.0       127.0
16               hub      1.0     256.0   17.0        24.0
17               rim      1.0     256.0   17.0        24.0
18              tire      1.0     256.0   17.0        24.0
19             valve      1.0     256.0   17.0        24.0
20          top_tube      1.0     174.0   14.0        10.0
21         down_tube      1.0     174.0   14.0        10.0
22         seat_tube      1.0     174.0   14.0        10.0
23         seat_stay      1.0     174.0   14.0        10.0
24        chain_stay      1.0     174.0   14.0        10.0
25             paint      3.0     261.0   10.0        12.0
```

---

## Documentation

Full documentation is available in the [`docs/`](docs/) directory:

| File | Description |
|---|---|
| [`docs/cli.md`](docs/cli.md) | Command-line interface reference |
| [`docs/simulation_model.md`](docs/simulation_model.md) | Simulation architecture and event flow |
---

## Minimal Configuration Example

```yaml
factory_name: "BikeFactory"
months: 12
hours_per_month: 160
show_output: true

product_demand:
  "order_01":
    MountainBike: 10

bom:
  MountainBike:
    type: bike
    bom:
      frame_a: { type: frame, qty: 1 }
      wheel_a: { type: wheel, qty: 2 }
      pedal:   { type: raw,   qty: 2 }

  frame_a:
    type: frame
    bom:
      tubes:    { type: raw, qty: 1 }
      seat_stay:   { type: raw, qty: 1 }
      chain_stay:  { type: raw, qty: 1 }
      paint:       { type: raw, qty: 1.5 }

  wheel_a:
    type: wheel
    bom:
      spokes: { type: raw, qty: 15 }
      hub:    { type: raw, qty: 1 }
      rim:    { type: raw, qty: 1 }
      tire:   { type: raw, qty: 1 }
      valve:  { type: raw, qty: 1 }

reorder_delays:
  pedal: { reorder_delay: 10 }
  tubes: { reorder_delay: 10 }
  seat_stay: { reorder_delay: 10 }
  chain_stay: { reorder_delay: 10 }
  paint: { reorder_delay: 10 }
  spokes: { reorder_delay: 15 }
  hub: { reorder_delay: 10 }
  rim: { reorder_delay: 10 }
  tire: { reorder_delay: 10 }
  valve: { reorder_delay: 10 }

initial_inventory:
  MountainBike: 0

stock_limits:
  MountainBike: { min: 5, max: 20 }
  frame_a:      { min: 5, max: 15 }
  wheel_a:      { min: 5, max: 20 }
  pedal:        { min: 10, max: 30 }
  spokes: { min: 30, max: 60 }
  hub: { min: 10, max: 20 }
  rim: { min: 10, max: 20 }
  tire: { min: 10, max: 20 }
  valve: { min: 10, max: 20 }
  tubes: { min: 10, max: 25 }
  seat_stay: { min: 10, max: 25 }
  chain_stay: { min: 10, max: 25 }
  paint: { min: 10, max: 25 }


machines:
  - { name: bk01, type: bike,  setup_time: 5,  cycle_time: 20 }
  - { name: fr01, type: frame, setup_time: 3,  cycle_time: 15 }
  - { name: wl01, type: wheel, setup_time: 2,  cycle_time: 8  }
```

---

## Project Structure

```
mla_factory/
├── src/mlafactory
│   ├── Inventory.py          # Inventory management and async waiting
│   ├── Machine.py            # Machine production process
│   ├── MachineDispatcher.py  # Task routing and machine pool management
│   ├── FactorySimulator.py   # Core factory coordination
│   ├── FactoryRunner.py      # Orchestrator: validation, run, reporting
│   ├── aux_files.py          # I/O utilities and custom exceptions
│   ├── aux_intervals.py      # Order interval generation
│   ├── aux_reports.py        # Result collection and export
│   └── minimal_example/      # Built-in bike factory example
├── docs/
├── tests/
└── README.md
```

---

## Running Tests

```bash
pip install pytest
pytest tests/
```

---

## 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.
