St. Mary's Project
Python Emacs Lisp
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
examples
ssa
.travis.yml
LICENSE
README.org
complex-grapher-example.py
example.py
odin.org
odin.py
requirements.txt
ssa.org
test.gml
test.py
test_graph-generator.py

README.org

SSA-Tool: Working with Self-Stabilizing Algorithms in Python

https://travis-ci.org/vermiculus/ssa-tool.svg

Never mind the above; I haven’t been able to set it up correctly yet. Needing to tangle the file makes it a little complicated. The master branch contains all of the tangled code for the project. Travis CI will be using the master branch.

This is a set of tools for the representation, creation, and evaluation of self-stabilizing algorithms.

I will add more content here soon, but please do see the documentation for the project in src/ssa.org. It is a literate program written with Org-Babel using the Emacs text editor.

Introduction

Directory Structure

The project is set up as a traditional Python module:

./
  setup.py
  ssa.py
  tests/
    __init__.py
    core_tests.py
    creation_tests.py
    simulation_tests.py

Setup

try:
    from setuptools import setup
except ImportError:
    from distutils.core import setup

config = {
    'description': 'A utility for the creation and evaluation of self-stabilizing algorithms',
    'author': 'Sean Allred',
    'url': 'http://github.com/vermiculus/ssa-tool',
    'download_url': 'http://github.com/vermiculus/ssa-tool',
    'author_email': 'seallred@smcm.edu',
    'version': '0.1',
    'install_requires': ['networkx'],
    'packages': ['ssa'],
    'scripts': [],
    'name': 'ssa',
}

setup(**config)

Example

# code example

Installing

Tangling

#!/usr/bin/env emacs --script

(ignore-errors
  (let ((old-dir default-directory))
    (cd "~/.emacs.d")
    (normal-top-level-add-subdirs-to-load-path)
    (cd old-dir)))

(setq python-indent-guess-indent-offset nil)

; (package-install 'org)

(require 'org)
(require 'ob)
(require 'ob-tangle)

;; http://www.emacswiki.org/emacs/ElispCookbook
(defun string/ends-with (s ending)
      "return non-nil if string S ends with ENDING."
      (cond ((>= (length s) (length ending))
             (let ((elength (length ending)))
               (string= (substring s (- 0 elength)) ending)))
            (t nil)))

;; http://turingmachine.org/bl/2013-05-29-recursively-listing-directories-in-elisp.html
(defun directory-files-recursive (directory match maxdepth ignore)
  "List files in DIRECTORY and in its sub-directories.  Return
   files that match the regular expression MATCH but ignore files
   and directories that match IGNORE (IGNORE is tested before
   MATCH).  Recurse only to depth MAXDEPTH.  If zero or negative,
   then do not recurse"
  (let* ((files-list '())
         (current-directory-list
          (directory-files directory t)))
    ;; while we are in the current directory
     (while current-directory-list
       (let ((f (car current-directory-list)))
         (cond 
          ((and
           ignore ;; make sure it is not nil
           (string-match ignore f))
           ; ignore
            nil)
          ((and
            (file-regular-p f)
            (file-readable-p f)
            (string-match match f))
          (setq files-list (cons f files-list)))
          ((and
           (file-directory-p f)
           (file-readable-p f)
           (not (string-equal ".." (substring f -2)))
           (not (string-equal "." (substring f -1)))
           (> maxdepth 0))
           ;; recurse only if necessary
           (setq files-list (append files-list (directory-files-recursive f match (- maxdepth -1) ignore)))
           (setq files-list (cons f files-list)))
          (t)))
       (setq current-directory-list (cdr current-directory-list)))
       files-list))

(if nil
    (delq nil
          (mapcar
           (lambda (file-path)
             (if (string/ends-with file-path "org")
                 (org-babel-tangle-file (message file-path))))
           (directory-files-recursive "." "" 10 "\\(build\\|dist\\)")))
  (mapcar 'org-babel-tangle-file
          (split-string (shell-command-to-string "find . -name '*.org' -type f"))))

pip Install

try:
    from setuptools import setup
except ImportError:
    from distutils.core import setup

config = {
    'description': 'A utility for the creation and evaluation of self-stabilizing algorithms',
    'author': 'Sean Allred',
    'url': 'http://github.com/vermiculus/ssa-tool',
    'download_url': 'http://github.com/vermiculus/ssa-tool',
    'author_email': 'seallred@smcm.edu',
    'version': '0.1',
    'install_requires': ['networkx', 'pygame'],
    'packages': ['ssa'],
    'scripts': [],
    'name': 'ssa',
}

setup(**config)

Makefile

PREBUILT_EMACS="https://dl.dropboxusercontent.com/u/17471132/emacs/emacs-24.3__Ubuntu-12.04-LTS.tgz"

documentation:
        $(info No prepared documentation yet)
        $(info See src/ssa.org)
        $(info $(HOME))

bootstrap:
        sed -n '/:shebang/,/#+END_SRC/p' README.org \
          | tail -n +2 \
          | sed '$$ d' > tangle.el

tangle: bootstrap
        emacs --script tangle.el

install: tangle
        python setup.py install

install-clean:
        rm -rf ssa.egg-info
        rm -rf build
        rm -rf dist

clean:
        rm -f tangle.el temp
        find . -name '*.py'  -type f -exec rm -rf {} \;
        find . -name '*.pyc' -type f -exec rm -rf {} \;
        find . -name '*~'    -type f -exec rm -rf {} \;

check:
        $(info At least one test pops open a window with quick, discontinuous movement.)
        $(info If this kind of thing bothers you (e.g. epileptic), do not look at this test.)
        $(info At any rate, these tests are designed to be unattended.)
        $(info Press enter to confirm that you have read this message, or Ctrl-C out.)
        @read response
        $(MAKE) _check

_check:
        cd ssa && nosetests --verbose

travis-dependencies:
        $(MAKE) _travis-emacs24-build
        $(MAKE) _travis-emacs24-install
        emacs --version

_travis-emacs24-build:
        $(info Downloading emacs 24)
        wget -O emacs.tgz $(PREBUILT_EMACS)
        $(info Unzipping)
        tar -zxf emacs.tgz

_travis-emacs24-install:
        $(info Installing)
        cd emacs-24.3 && make install

Executable

#!/usr/bin/env sh
# -*- mode: sh -*-

python3 ssa-tool.py "$@"

Notes

Dijkstra 1974

A self-stabilizing network is seen as a graph of state machines. Each privilege is realized as a transition from the current state to another state. The state of the graph is passed as input to this state machine. When the input graph matches some predicate, this privilege is set—there is some transition out of this state. This is why the choice of predicate to act upon is arbitrary: you can only move to one other state!

When every node of the graph is in an accepting state with no set predicates, then the graph has stabilized.

privilege

  • we consider graphs of finite state machines
  • privileges are boolean functions of the FSM’s state and the states of its neighbors
  • when these functions are true, the privilege is ‘present’

system state

  • each legitimate state must have at least one privilege present
    • even if the action is ‘do nothing’
  • in each legitimate state, every possible action will maintain legitimacy
  • each privilege must be present in at least one legitimate state
  • for any given pair of legitimate states, there exists a transformation between them

self-stabilization

regardless of the initial state and regardless of the privilege selected each time for the next move, at least one privilege will always be present and the system is guaranteed to find itself in a legitimate state after a finite number of moves.