Metadata-Version: 2.2
Name: simasm
Version: 0.1.0
Summary: Abstract State Machine Framework for Discrete Event Simulation
Author: Steve
License: MIT
Project-URL: Homepage, https://github.com/stevenaeola/simasm
Project-URL: Documentation, https://github.com/stevenaeola/simasm#readme
Project-URL: Repository, https://github.com/stevenaeola/simasm
Project-URL: Issues, https://github.com/stevenaeola/simasm/issues
Keywords: simulation,discrete-event,state-machine,verification,event-graph,activity-cycle-diagram,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
Provides-Extra: jupyter
Requires-Dist: ipython>=7.0; 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 Python package for modeling, simulating, and verifying discrete event systems using Abstract State Machines (ASM) as a common semantic foundation.

## Features

- **DSL for Simulation Models**: Write discrete event simulation models in a clean, readable syntax
- **Multiple Formalisms**: Support for Event Graph and Activity Cycle Diagram modeling styles
- **Stutter Equivalence Verification**: Formally verify that two models produce equivalent observable behavior
- **Jupyter Integration**: Interactive modeling with `%%simasm` magic commands
- **Statistics Collection**: Built-in support for time-average, utilization, and count statistics

## Installation

```bash
pip install simasm
```

For Jupyter support:
```bash
pip install simasm[jupyter]
```

## Quick Start

### In Jupyter/Colab

```python
import simasm  # Auto-registers %%simasm magic
```

Define a model:
```
%%simasm model --name mm1_queue
domain Event
domain Load

var sim_clocktime: Real
var queue: List<Load>

// ... model definition
```

Run an experiment:
```
%%simasm experiment
experiment MyExperiment:
    model := "mm1_queue"

    replication:
        count: 10
        warm_up_time: 100.0
        run_length: 1000.0
    endreplication

    statistics:
        stat AvgQueueLength: time_average
            expression: "lib.length(queue)"
        endstat
    endstatistics
endexperiment
```

### From Python

```python
from simasm.experimenter.engine import ExperimenterEngine

# Run an experiment
engine = ExperimenterEngine("experiments/my_experiment.simasm")
result = engine.run()

print(f"Average queue length: {result['L_queue']}")
```

## Model Syntax

SimASM uses a domain-specific language for defining simulation models:

```simasm
// Domain declarations
domain Load
domain Server

// Constants and variables
const server: Server
var sim_clocktime: Real
var queue: List<Load>

// Random stream variables
var interarrival_time: rnd.exponential(1.25) as "arrivals"
var service_time: rnd.exponential(1.0) as "service"

// Rules
rule arrive() =
    let load = new Load
    lib.add(queue, load)
    // Schedule next arrival
endrule

// Main rule
main rule main =
    if sim_clocktime < sim_end_time then
        run_routine()
    endif
endrule

// Initial state
init:
    sim_clocktime := 0.0
    queue := []
endinit
```

## Verification

SimASM can verify stutter equivalence between two models:

```
%%simasm verify
verification EG_vs_ACD:
    models:
        import EG from "event_graph_model.simasm"
        import ACD from "acd_model.simasm"
    endmodels

    seed: 42

    labels:
        label queue_empty for EG: "queue_count() == 0"
        label queue_empty for ACD: "queue_count() == 0"
    endlabels

    observables:
        observable queue_empty:
            EG -> queue_empty
            ACD -> queue_empty
        endobservable
    endobservables

    check:
        type: stutter_equivalence
        run_length: 1000.0
    endcheck
endverification
```

## Documentation

- [Full Documentation](https://github.com/yourusername/simasm)
- [Examples](https://github.com/yourusername/simasm/tree/main/examples)

## License

MIT License - see [LICENSE](LICENSE) for details.

## Citation

If you use SimASM in your research, please cite:

```bibtex
@software{simasm,
  title = {SimASM: Abstract State Machine Framework for Discrete Event Simulation},
  author = {Steve},
  year = {2024},
  url = {https://github.com/yourusername/simasm}
}
```
