penrose: A system that automatically visualize mathematics

[ library, mit, program, unclassified ] [ Propose Tags ]

[Skip to Readme]
Versions [RSS] [faq],,,, (info)
Change log
Dependencies ad (==4.3.*), aeson (==1.2.*), base (==4.9.*), containers (==0.5.*), gloss (==1.11.*), megaparsec (==5.3.*), old-time (==1.1.*), random (==1.1.*), text (==1.2.*), websockets (==0.11.*) [details]
License MIT
Author team-penrose
Home page
Uploaded by wodeni at 2017-07-08T23:39:42Z
Distributions NixOS:
Executables penrose
Downloads 1893 total (21 in the last 30 days)
Rating (no votes yet) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Hackage Matrix CI
Docs not available [build log]
All reported builds failed as of 2017-07-09 [all 3 reports]


Maintainer's Corner

For package maintainers and hackage trustees


Readme for penrose-

[back to package description]


We're building a prototype for set theory. Not ready for contributions or public use yet, but hopefully will be after this summer! See for more information.


Install any relevant packages: cabal install $PACKAGE_NAME (though I'm told the Haskell community has moved on to the better stack package manager).

To compile both: ghc Runtime.hs

To just compile Compiler: ghc Compiler.hs

To use: ./Runtime <filename>.sub <filename>.sty

User interface:

  • You can click and drag the objects, including labels. The optimization will pause while dragging and re-layout when the mouse is lifted. The object on top is semi-arbitrary, decided by the order of the objects in the internal list.
  • Pressing the R key will resample the configuration.
  • Pressing the A key will turn autostep (automatically stepping the optimization) on or off.
  • Pressing the S key will step the optimization by one step if autostep is off. It won't do anything if autostep is on.

Examples of existing pairs:

  • twosets.sub settheory.sty
  • continuousmap1.sub continuousmap1.sty (system doesn't currently handle this)


src contains the compiler and runtime.

src/GC-slides contains slides from weekly group meetings.

src/gifs and src/pictures contain GIFs and pictures documenting new features in the system.

Other directories in the root contain documentation and old parts of the system.

More information

I use the following library to handle the graphics, animation, and user input: gloss.

Functionality of the current code:

  • gradient-descent-based layout
  • with backtracking line search
  • for set theory with points, sets, and certain constraints on points and sets
  • with very simple objective functions provided (e.g. centering)
  • where the layout is animated and interactive (v. useful for debugging)

Some limitations:

  • line search sometimes doesn't terminate
  • need a better debugging interface for optimization, e.g. live parameter tuning


  • stepsPerSecond: number of simulation steps for gloss to take for each second of real time
  • picWidth, picHeight: canvas dimensions
  • stepFlag: turns stepping the simulation on and off for debugging (no stepping = objects don't move)
  • clampFlag: turns clamping gradient values on and off for debugging
  • debug: turns on/off the debug print functions
  • constraintFlag: turns constraint satisfaction on/off (currently off because we're doing unconstrained optimization)
  • Default ambient objective functions are specified in ambientObjFns, and analogously for ambientConstrFns.
  • Default objective functions are specified in genObjsAndFns.
  • btls: turn on/off the backtracking line search for debugging (off = use a fixed timestep specified in the code)
  • alpha and beta: parameters for the backtracking line search (see code for a more detailed description)
  • stopEps: stopping condition sensitivity for gradient descent. Stop when magnitude of gradient is less than stopEps.


  • Use the flags above.
  • I also use ghci, the Haskell REPL. To load the file, do :l filename.hs. To import a library, paste in the normal import statement. To declare something, start with a let statement, e.g. let x = 5.
  • For printing internal values, I use the Debug.Trace library.


  • Compiler parses the Substance and Style programs and combines their abstract syntax trees into Layout (the intermediate layout representation).
  • Runtime calls Compiler on the input files, and transforms the data in Layout to Opt (the representations used by the optimization code).
  • Runtime imports Compiler as a module.

Usage for old code

Compile: ghc settheory.hs

Create SVG: ./settheory -w 500 -h 500 -o set.svg (The parameters are the width and height of the rendered picture.)

Open SVG: chrome set.svg