Block Diagrams with Blockdiag

Preamble

In [1]:
# used to create block diagrams
%reload_ext xdiag_magic
%xdiag_output_format svg

Introduction

You may have noticed that I programmatically generate block diagrams in many of my notebooks, such as the one below.

In [2]:
%%blockdiag
{
    orientation = portrait
    Initialisation -> Evaluation -> "Terminate?" -> Selection -> Variation -> Evaluation
    Initialisation [color = '#ffffcc']
}
blockdiag { orientation = portrait Initialisation -> Evaluation -> "Terminate?" -> Selection -> Variation -> Evaluation Initialisation [color = '#ffffcc'] } InitialisationEvaluationTerminate?SelectionVariation

I achieve this using what appears to be a relatively unknown Jupyter extension called xdiag_magic (by GitHub user kaibaesler) which provides custom magic functions for generating diagrams with blockdiag. Unfortunately, it wasn't a straight-forward conda install ... to get it up and running, but it's still quite easy.

Installation

These instructions assume you already have Jupyter Lab up and running, perhaps through Anaconda.

  1. Clone or Download this repository to your your machine. Make sure to extract it if you download it as a ZIP archive.
  2. Using the command line, navigate to the xidag_magic_extension directory, e.g. using cd.
  3. Once you're inside the directory, make sure you are within the desired environment, e.g. if you're using conda make sure you type conda activate <environment_name>.
  4. Type pip install -r requirements.txt.
  5. Type pip install -e ..

Examples

To test it, launch Jupyter Lab and open or create a notebook. You need to run the following code before generating any diagrams.

In [3]:
%reload_ext xdiag_magic
%xdiag_output_format svg

Then you can visit blockdiag's examples and try running some of their example diagrams to see the output. Your diagram code must appear in a Jupyter Lab Code cell, and be surrounded with the following.

In [ ]:
%%blockdiag
{
    
}

For example:

In [5]:
%%blockdiag
{
    orientation = portrait
    A -> B -> C
}
blockdiag { orientation = portrait A -> B -> C } ABC