SMSL: State Machine Serialization Language

SMSL is a data language designed specifically for serializing finite state machines. It provides a clean and intuitive syntax for defining state machines, with support for multiple common data formats.

Features

• State Machine Serialization: Read and serialize finite state machines from/to string-based data formats
• Multiple Format Support: Works with SMSL, JSON, and YAML formats
• Graph Integration: Built-in integration with graph data structures, enabling any graph algorithm for your needs
• Visualization Tools: Visualize your state machines using NetworkX and matplotlib
• Path Finding: Find shortest paths between states in your state machine

Installation

pip install pysmsl

Usage

Basic Usage

import smsl

# Load a state machine from a file
sm = smsl.smslStateMachine('examples/hanoi.json')

# Access the state machine
state_branch = sm.state_machine[0]

# Find the shortest path between two states
from smsl_state import smslState
path = state_branch.shortest_path(
    smslState('State_aaa'),
    smslState('State_ccc')
)

# Get the operations (edges) along that path
edge_path = state_branch.shortest_edge_path(
    smslState('State_aaa'),
    smslState('State_ccc')
)

# Visualize the state machine
state_branch.plot_sb()

State Machine Definition Formats

SMSL Format

// SMSL format example
{
    # NAME: SB1
    # INITIAL: State000
    # NUM_FACTS: 3
    # SUB_SBS: (SB2: 0)

    State000: [Operation000 -> State100],

    State100: [
        Operation100A -> State110,
        Operation100B -> State111
    ],
        
    State110: [
        Operation110A -> State100,
        Operation110B -> State111
    ],

    State111: [ ]
}

JSON Format

{
    "SB1": {
        "HEADER": {
            "INITIAL": "State000",
            "NUM_FACTS": 3,
            "SUB_SBS": {
                "SB2": 0 
            }
        },
        "State000": {
            "Operation000": "State100"
        },
        "State100": {
            "Operation100A": "State110",
            "Operation100B": "State111"
        },
        "State110": {
            "Operation110A": "State100",
            "Operation110B": "State111"
        },
        "State111": { }
    }
}

YAML Format

SB1: [
  HEADER: [
    INITIAL: State000,
    NUM_FACTS: 3,
    SUB_SBS: [
      SB2: 0
    ]
  ],
  State000: [
    Operation000: State100
  ],
  State100: [
    Operation100A: State110,
    Operation100B: State111
  ],
  State110: [
    Operation110A: State100,
    Operation110B: State111
  ],
  State111: [ ]
]

Examples

The repository includes several examples:

• examples/example.smsl, examples/example.json, examples/example.yaml: Simple state machine examples in different formats
• examples/hanoi.json: A state machine for solving the Tower of Hanoi puzzle

Tutorials

Tower of Hanoi

The repository includes a complete example of using SMSL to solve the Tower of Hanoi puzzle:

• tutorials/hanoi/hanoi_vtk_sim/: A VTK simulation of the Tower of Hanoi
• tutorials/hanoi/hanoi_robot/: A robot implementation for playing Tower of Hanoi

To run the VTK simulation:

cd tutorials/hanoi/hanoi_vtk_sim
python hanoi_vtk_sim.py

Design Philosophy

SMSL is designed with the following goals in mind:

1. Simplicity: Easy to read and write state machine definitions
2. Flexibility: Support for multiple data formats (SMSL, JSON, YAML)
3. Extensibility: Integration with graph algorithms for advanced state machine analysis
4. Visualization: Tools for visualizing and understanding state machines

Dependencies

• Python 3.6+
• networkx
• matplotlib
• pyyaml

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Citation

If you use SMSL in your research, please consider citing the following papers:

@article{liu2024roadmap,
  title={A Roadmap Towards Automated and Regulated Robotic Systems},
  author={Liu, Yihao and Armand, Mehran},
  journal={arXiv preprint arXiv:2403.14049},
  year={2024}
}

@article{liu2023toward,
  title={Toward Process Controlled Medical Robotic System},
  author={Liu, Yihao and Kheradmand, Amir and Armand, Mehran},
  journal={arXiv preprint arXiv:2308.05809},
  year={2023}
}