Poietic Tool

Command-line tool for manipulating and exploring Poietic Models, with support for Stock and Flow simulation.

See also: Full documentation with all the commands.

Installation

Available platforms: MacOS 14 (and later), Linux

To install the poietic command-line tool, run the following command in the project's top-level directory:

./install

The tool will be installed in the Swift Package Manager's' ~/.swiftpm/bin directory. Make sure you have the directory in your PATH, if you do not, then add the following to the end of your ~/.zshrc or ~/.bashrc file:

export PATH=~/.swiftpm/bin:$PATH

Recommended (optional): Graphviz for visualising the design graph and Gnuplot for charts. The tool can generate output for both.

On MacOS with Homebrew:

brew install graphviz gnuplot

Examples

The examples are located in the Examples repository. Follow instructions how to run them in the documentation contained within the repository.

Tool Overview

Detailed documentation can be found here: Command Line Tool documentation.

Command summary:

• new: Create an empty design.
• info: Get information about the design
• list: List design content objects.
• show: Describe an object.
• edit: Edit an object or a selection of objects.
  • set: Set an attribute value
  • undo: Undo last change
  • redo: Redo undone change
  • add: Create a new node
  • connect: Create a new connection (edge) between two nodes
  • remove: Remove an object – a node or a connection
  • auto-parameters: Automatically connect parameter nodes: connect required, disconnect unused
  • layout: Lay out objects
  • align: Align objects on canvas
• import: Import a frame into the design.
• run: Run the simulation and generate output
• write-dot: Write a Graphviz DOT file.
• metamodel: Describe the metamodel (supports: text, markdown and HTML output)
• create-library Create a library of multiple models.

Experimental commands:

• experimental-export-svg: Export design as a SVG diagram. Requires pictograms from poietic-assets

Use --help with a desired command to learn more.

Developer's note: At the moment of writing this, I know how to include resources with a command-line tool in a Swift package. That is why the SVG feature is "experimental".

Pseudo-REPL

Think of this tool as ed but for data represented as a graph. At least for now.

The tool is designed in a way that it is by itself interactive for a single-user. For interactivity in a shell, set the POIETIC_DESIGN environment variable to point to a file where the design is stored.

Example session, creates a simple bank account model:

poietic new
poietic info

poietic edit add Stock name=account formula=100
poietic edit add Auxiliary name=rate formula=0.02
poietic edit add FlowRate name=interest formula="account * rate"
poietic edit connect Flow interest account
poietic edit connect Parameter rate interest
poietic edit connect Parameter account interest
poietic info

poietic list formulas

Run the simulation:

poietic run

Make some mistakes:

poietic edit add Stock name=unwanted formula=0
poietic list formulas

poietic edit undo

poietic list formulas

If you have Graphviz installed, then you can run the following and then open the diagram.png image:

poietic write-dot --output diagram.dot -l name 
dot -Tpng -odiagram.png diagram.dot

Discover more design possibilities by exploring the metamodel in a HTML file:

poietic metamodel -f html > metamodel.html

The above command will create a metamodel.html file with full description of currently available metamodel for the given design.

Features

• Preserved history – Editing is non-destructive, can be reversed using undo and redo commands.
• Exports to different formats:
  • Graphviz dot files
  • CSV
  • Charts to Gnuplot
• Stock, Flow, Auxiliary, Graphical function and more kinds of nodes. See Metamodel.
• Arithmetic expressions with built-in functions. See Formulas.

See Also

• Formulas
• Metamodel

Underlying packages:

• Poietic Core: repository, documentation
• Poietic Flows: repository, documentation

Author

Stefan Urbanek