How to document simulations with parallel processes?

Question

I've been using the SimPy module for Python - that does Discrete Event Simulations. Now, the code has gotten fairly large now and there are quite a few processes occurring in parallel that interact with one another.

How is the best way to show this in terms of documenting? Class hierarchy structures don't adequately capture the interactions between the processes, and almost all auto-generation software gets stuck on the fact that all the code is effectively inheriting from the SimPy module, so a full SimPy documentation is generated for each class :/

I imagine something like UML could be of use, but I'm not too clued up on that. It would need to capture:

• Processes
• Events
• Queues (including Processes waiting for resources...:)
• Resources (like arrays that can be populated/depopulated etc. and have a certain capacity)

So basically, any neat simulation code documenting tools?

Cheers

Answer 1

The UML has state diagram and activitiy diagrams as well as sequence diagrams. Any of these would be appropriate. Usually, a combination of diagrams is required.

One state diagram for each class of objects. http://en.wikipedia.org/wiki/State_diagram

Activity diagrams or sequence diagrams to show specific interactions or collaborations among objects. http://www.agilemodeling.com/artifacts/activityDiagram.htm http://www.ibm.com/developerworks/rational/library/3101.html

A class diagram is also appropriate to show static features of the classes and their relationships. http://en.wikipedia.org/wiki/Class_diagram

The "whole thing" is often difficult to document.

Answer 2

Use a combination of Diagrams and self-written prose.

Imho, you don't need to use UML. If something non-UML transports your message in a clearer/simpler way, use whatever you like.

Also write a short summary with all the basic concepts so that the reader gets a genereal idea what the intention of the system is and what its main components are.

Then write more detailed articles about each component and cross-reference ot other articles.

The article series Writing Great Documentation by Jacob Kaplan-Moss helped me a lot.