Metadata-Version: 2.2
Name: simasm
Version: 0.6.0
Summary: Abstract State Machine Framework for Discrete Event Simulation
Author: Steve Yeo
License: MIT
Project-URL: Homepage, https://simasm-project.github.io/
Project-URL: Documentation, https://simasm-project.github.io/reference/syntax.html/
Project-URL: Repository, https://github.com/SimASM-Project
Project-URL: Issues, https://github.com/SimASM-Project/simasm/issues
Keywords: simulation,discrete-event,state-machine,verification,event-graph,activity-cycle-diagram,devs,abstract-simulator,stutter-equivalence
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Software Development :: Interpreters
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: lark>=1.1.0
Requires-Dist: pydantic>=2.0
Requires-Dist: numpy>=1.20
Requires-Dist: matplotlib<4.0,>=3.7
Requires-Dist: scipy>=1.9
Requires-Dist: sortedcontainers>=2.4
Requires-Dist: pandas>=1.5
Provides-Extra: jupyter
Requires-Dist: ipython>=7.0; extra == "jupyter"
Requires-Dist: matplotlib-inline>=0.1.6; extra == "jupyter"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=4.0; extra == "dev"
Provides-Extra: all
Requires-Dist: simasm[dev,jupyter]; extra == "all"

# SimASM

**Abstract State Machine Framework for Discrete-Event Simulation**

SimASM is a programming language and verification framework that enables:
- Writing discrete-event simulation models using a clean DSL
- Supporting multiple DES formalisms (Event Graph, Activity Cycle Diagram)
- Verifying behavioral equivalence between models via stutter equivalence
- Running experiments with statistics collection and automatic plotting

## Overview

SimASM adopts Abstract State Machines (ASM) as the semantic foundation for DES.
This enables precise translation of DES formalisms into a common formal language,
allowing rigorous verification of behavioral equivalence across formalisms.

**Key Concepts:**
- **Event Graph (EG)**: Event-based formalism using next-event time-advance algorithm
- **Activity Cycle Diagram (ACD)**: Activity-based formalism using three-phase scanning
- **Stutter Equivalence**: Two models are equivalent if they produce the same
  sequence of observable state changes, regardless of internal steps

## Installation

```bash
# From PyPI (recommended)
pip install simasm[jupyter]

# From source (development)
git clone <repo-url>
cd simasm
pip install -e .[jupyter]
```

**Requirements:** Python 3.9+, lark>=1.1.0, pydantic>=2.0, numpy>=1.20,
matplotlib==3.9.2, scipy>=1.9

## Quick Start

### Option 1: Run a Jupyter Notebook
```bash
jupyter notebook notebooks/simasm_demo.ipynb
```

### Option 2: Python API
```python
import simasm

# Register a model
simasm.register_model("mm5_eg", open("simasm/input/models/mm5_eg.simasm").read())

# Run an experiment
result = simasm.run_experiment('''
experiment Test:
    model := "mm5_eg"
    replications: 10
    run_length: 1000.0
endexperiment
''')
```

### Option 3: Command Line
```bash
# Run experiment
python -m simasm.experimenter.cli simasm/input/experiments/littles_law_eg.simasm

# Run verification
python -m simasm.experimenter.cli --verify simasm/input/experiments/mm5_verification.simasm
```

## Repository Structure

```
simasm/
├── notebooks/           # Interactive tutorials and examples
├── simasm/
│   ├── input/
│   │   ├── models/      # Pre-built .simasm model files
│   │   └── experiments/ # Experiment & verification specs
│   └── output/          # Generated results (JSON, CSV, PNG)
├── pyproject.toml
└── README.md
```

## Notebooks Guide

| Notebook | Description | Recommended Order |
|----------|-------------|-------------------|
| `simasm_demo.ipynb` | Interactive intro using Jupyter magic commands | 1 |
| `simasm_python_api_demo.ipynb` | Python API alternative to magics | 1 |
| `eg_littles_law.ipynb` | Event Graph + Little's Law verification | 2 |
| `acd_littles_law.ipynb` | ACD + Little's Law verification | 2 |
| `eg_to_asm_translation.ipynb` | Formal EG→ASM translation algorithm | 3 |
| `acd_to_asm_translation.ipynb` | Formal ACD→ASM translation algorithm | 3 |
| `mm5_verification.ipynb` | Stutter equivalence verification (M/M/5) | 4 |
| `warehouse_verification.ipynb` | Complex 6-station warehouse verification | 5 |
| `warehouse_verification_w_analysis.ipynb` | Extended statistical analysis | 5 |

## Input Files

### Models (`simasm/input/models/`)
| File | Description |
|------|-------------|
| `mm5_eg.simasm` | M/M/5 queue using Event Graph formalism |
| `mm5_acd.simasm` | M/M/5 queue using Activity Cycle Diagram |
| `warehouse_eg.simasm` | 6-station warehouse outbound process (EG) |
| `warehouse_acd.simasm` | 6-station warehouse outbound process (ACD) |

### Experiments (`simasm/input/experiments/`)
| File | Description |
|------|-------------|
| `littles_law_eg.simasm` | Little's Law verification (L = λW) for EG |
| `littles_law_acd.simasm` | Little's Law verification for ACD |
| `mm5_verification.simasm` | Stutter equivalence: EG vs ACD |
| `warehouse_w_stutter_equivalence.simasm` | Warehouse model verification |

## Output Files

Outputs are saved to `simasm/output/` with timestamped directories:

```
simasm/output/
└── 2026-01-19_20-14-21_ExperimentName/
    ├── ExperimentName_results.json   # Statistics
    ├── boxplots.png                  # Box plots
    ├── summary_statistics.png        # Bar charts with CIs
    └── timeseries.png                # Time series traces
```

### JSON Output Structure
```json
{
  "experiment": "LittlesLawEG",
  "metadata": {
    "num_replications": 30,
    "total_wall_time": 7.522,
    "generated_at": "2026-01-19T18:34:06"
  },
  "replications": [
    {
      "id": 1,
      "seed": 12345,
      "final_time": 1000.49,
      "steps_taken": 3239,
      "statistics": {
        "L_system": 2.05,
        "rho_utilization": 0.40
      }
    }
  ]
}
```

## Two DES Formalisms

### Event Graph (EG)
- Event-based: focuses on events and scheduling relationships
- Uses next-event time-advance algorithm
- Events trigger other events with delays and conditions

### Activity Cycle Diagram (ACD)
- Activity-based: focuses on activities and resource flows
- Uses three-phase scanning algorithm (scan → time → execute)
- Activities consume and produce tokens from queues

## Stutter Equivalence Verification

SimASM can verify that two models (e.g., EG and ACD of the same system)
produce identical observable behavior:

```
verification EG_ACD_Equivalence:
    models:
        import EG from "mm5_eg"
        import ACD from "mm5_acd"
    seed: 42
    labels:
        label busy_eq_0 for EG: "service_count(server) == 0"
        label busy_eq_0 for ACD: "servers_busy() == 0"
    check: type=stutter_equivalence, run_length=100.0
endverification
```

## Reproducing Paper Results

SimASM includes a reproducibility module for the SMC paper:

> Yeo, K. S. S., & Li, H. (2025). Semantic Model Complexity for Event Graph
> Discrete-Event Simulation Models via Abstract State Machines. *SIMULTECH 2025*.

### Setup

```bash
git clone https://github.com/SimASM-Project/simasm.git
cd simasm
pip install -e .
```

### Experiment 1: 51-Model LOOCV Validation (Section 5)

```bash
simasm-reproduce loocv
```

Runs the full 51-model benchmark (~5 min). Measures simulation runtimes live
(30 replications each), computes SMC/CC/LOC/KC, and performs leave-one-out
cross-validation on three pools (27 homogeneous, 24 heterogeneous, 51 combined).

### Experiment 2: Warehouse Case Study (Section 6)

```bash
simasm-reproduce warehouse
```

Trains log-log regression on the 51-model pool and predicts runtime for an
industrial warehouse model. Reports absolute percentage errors and 95%
prediction intervals for all four metrics.

### Run Both

```bash
simasm-reproduce all
```

### Expected Output

Runtimes will vary across machines, but the relative rankings (Q², sign test
results) should be consistent with the paper:
- SMC Q² ≈ 0.95 on the combined 51-model pool
- SMC sign test: 51/51 wins vs CC/LOC/KC (p < 0.0001)
- Warehouse: only SMC's 95% prediction interval contains the actual runtime

Use `-v` for verbose per-model output:
```bash
simasm-reproduce loocv -v
```

### Benchmark Models

The 51 models are included in `simasm/models/` (JSON) and `simasm/models_simasm/`
(.simasm translations):
- **27 homogeneous**: tandem, fork-join, feedback × 9 sizes (1–20 stations)
- **24 heterogeneous**: 3 topologies × 2 sizes × 2 IST patterns × 2 IAT levels
- **1 warehouse**: 6-station industrial warehouse (out-of-sample case study)

## Related Work and ASM Frameworks

SimASM builds on the foundation of Abstract State Machines (ASM) introduced by
Gurevich [1, 2]. Several ASM implementations and tools have been developed:

- **ASM Workbench** [3]: Early implementation providing executable ASM specifications
- **ASMETA** [4]: ASM metamodel and toolset for interoperability
- **CoreASM** [5]: Extensible ASM execution engine with microkernel architecture

SimASM applies ASM to discrete-event simulation, following Wagner's foundational
work on ASM-based DES semantics [6]. The stutter equivalence verification is based
on techniques from model checking [7].

### References

1. Gurevich, Y. (1993). Evolving Algebras: An Attempt to Discover Semantics.
   *Bulletin of the EATCS*, 43, 264-284.

2. Gurevich, Y. (2000). Sequential Abstract State Machines Capture Sequential
   Algorithms. *ACM Transactions on Computational Logic*, 1(1), 77-111.

3. Del Castillo, G. (1999). *The ASM Workbench: A Tool Environment for
   Computer-Aided Analysis and Validation of ASM Models*. PhD thesis, University
   of Paderborn.

4. Gargantini, A., Riccobene, E., & Scandurra, P. (2008). A Metamodel-based
   Language and a Simulation Engine for Abstract State Machines. *Journal of
   Universal Computer Science*, 14(12), 1949-1983.

5. Farahbod, R., Gervasi, V., & Glässer, U. (2009). Design and Specification of
   CoreASM: An Extensible ASM Execution Engine. *Fundamenta Informaticae*,
   95(1), 17-54.

6. Wagner, G. (2017). Information and Process Modeling for Simulation.
   In *Enterprise Modeling and Information Systems Architectures*.

7. Baier, C., & Katoen, J.-P. (2008). *Principles of Model Checking*. MIT Press.

## License

MIT License - See LICENSE file

## Links

- Repository: https://github.com/SimASM-Project/simasm
- Issues: https://github.com/SimASM-Project/simasm/issues
