Ridgerunner is a program for tightening knots created by Jason Cantarella, Eric Rawdon, and Michael Piatek. The software depends on many of the other programs on this site: unless you’ve already installed plCurve, octrope, and [tsnnls] as well as argtable2, you should use the ‘metapackage’ rrplusdeps below. Installing povray as well as the GNU Scientific Library and Geomview will make your life easier, but they aren’t strictly neccessary.

We used the software to create the tables of tight knots in Knot Tightening By Constrained Gradient Descent and The Shapes of Tight Composite Knots (see Papers) and the movies at Ridgerunner Movies, so it’s fairly battle-tested by now. Actual crashes (segfaults) are quite uncommon, though the software can get to a point where the linear algebra becomes so degenerate that it can go no further. A helpful hint when starting out is to avoid configurations which have a lot of self contact in their starting position, or a lot of symmetry. For instance, a Hopf link formed from two round circles will kill ridgerunner instantly because there are too many initial self-contacts.

The latest data files produced by ridgerunner for tight knots and links are freely available in the subversion repository at http://www.jasoncantarella/TightKnot2. The current best files for knots and links are in the “best” directory.

Brief Introduction

The full list of command-line arguments for ridgerunner is somewhat intimidating. If you just type ridgerunner (after a successful install), you’ll get a lot of possible arguments. Luckily, very few are needed to start tightening some knots. A simple session with ridgerunner looks like this.

jason:ridgerunner> ridgerunner ./data/3.1.vect -a –StopSteps=1000
Ridgerunner 2.0.0
svn version 340:341M
Built Feb 21 2012, 11:00:20.
plCurve Version: 5.0.5
Octrope Version: 1.5
tsnnls Version: 2.3.3
Seeded from dev/random with seed 288502481.
Loaded 1 component, 47 vertex plCurve from ./data/3.1.vect.
Saved copy of ./data/3.1.vect to ./3.1.rr/3.1.vect.
Curve has thickness 1.54794. Scaling to thickness 0.501.
Scaled curve has thickness 0.501.
Autoscale selftest ok.
Rerez’d, autoscaled, eq’d file written to ./3.1.rr/3.1.atstart.vect.
Overstep tolerance: 0.000100 of thickness 0.500000 (0.499950) minminrad: 0.49997500
ridgerunner: Curses screen display disabled, using stdout.
Define CURSES_DISPLAY to enable better screen display.
ridgerunner: Starting run. Will stop if
step number >= 1000
residual < 0
ropelength decrease over last 20 steps < -1000.

1 Rop: 36.68996343890 Str: 0 MRstruts: 0 Thi: 0.5000015
2 Rop: 36.68999769764 Str: 1 MRstruts: 0 Thi: 0.5000000
3 Rop: 36.66687647726 Str: 1 MRstruts: 0 Thi: 0.4999996
4 Rop: 36.66685032902 Str: 2 MRstruts: 0 Thi: 0.4999996
5 Rop: 36.08036840390 Str: 8 MRstruts: 0 Thi: 0.4949835
6 Rop: 36.07859929174 Str: 2 MRstruts: 0 Thi: 0.4999999
7 Rop: 36.00000909104 Str: 3 MRstruts: 0 Thi: 0.4999891

994 Rop: 33.19041815788 Str: 56 MRstruts: 0 Thi: 0.4999897
995 Rop: 33.19041102220 Str: 56 MRstruts: 0 Thi: 0.4999896
996 Rop: 33.19039909288 Str: 56 MRstruts: 0 Thi: 0.4999894
997 Rop: 33.19039412711 Str: 56 MRstruts: 0 Thi: 0.4999894
998 Rop: 33.19008824082 Str: 43 MRstruts: 0 Thi: 0.4999893
999 Rop: 33.19003077760 Str: 53 MRstruts: 0 Thi: 0.4999893
1000 Rop: 33.19001902293 Str: 55 MRstruts: 0 Thi: 0.4999893
ridgerunner: run complete. Terminated because
ridgerunner: reached maximum number of steps (1000).
tube (vecttools 1.1) compiled Feb 21 2012 16:21:05
tube: Wrote 1733 vertex, 3466 face tube.
ridgerunner: Run complete.

We used three options here: -a or autoscale, which scales the knot to thickness 1 before starting the minimization, –StopSteps=1000, which set the number of steps to 1000, and ./data/3.1.vect, which was the name of the input curve. As you can see, this shrinks the trefoil knot in /data (there’s a complete knot table in there for you to play with) by about 3 units of ropelength. The results appear in a subdirectory of wherever you ran ridgerunner from. If you ran knot.vect, the results will be in knot.rr.

jason:ridgerunner> cd 3.1.rr/
jason:3.1.rr> ls
3.1.atstart.vect 3.1.final.tube.off 3.1.log logfiles/ vectfiles/
3.1.final.struts 3.1.final.vect 3.1.vect snapshots/

The results are not particularly dramatic. On the left, we see 3.1.atstart.vect (with a tube around it), which is always a copy of the VECT file that you submitted to ridgerunner, and on the right we see 3.1.final.vect (with a tube around it), which is the final output of ridgerunner (assuming that the run completed normally).

3.1.atstart.tube ->    3.1.final.tube

Still, if you can do this, you can (in principle) do anything in knot tightening.

You can use multiple stopping criteria together. For instance, in production work, we usually used

ridgerunner -a myfile.vect –StopRes=0.01 –StopTime=2880 –StopSteps=500000

which stops when the residual of the file is 0.01 (that is, the elastic force on the knot is 99% balanced by tube contacts), or when two days (2880 minutes) have passed, or when 500,000 steps have been taken, whichever comes first.

Advanced Options

Many of the advanced options are mostly useful for debugging or historical reasons, but several are worth discussing.

-l, –Lambda=<double> minimum radius of curvature for unit rope

If you are studying stiff rope, with radius of curvature bounded below, you can set the minimum radius of curvature of the rope with this option. Note that the rope has diameter 1 in ridgerunner, so the default setting for lambda is 0.5 (fully flexible rope).

–MangleMode instead of trying to reduce length, try to change configuration
–MangleSteps=<#steps> switch mangling algorithm after this many steps

This is still experimental, but is currently useful enough to document. MangleMode will not try to shrink the knot, but instead turns it inside out by flowing around a randomly selected torus whose center is near the center of mass of the polygon. This is often very effective in finding different local minima for a given knot type.

–EqOn automatically equilateralizes when max/min edge > 3
–EqMultiplier=<scalar> increase to make ‘equilateralization force’ stronger
–EqForceOn turn on equilateralization force during the run (can interfere with stepper)

One of these options should always be chosen during a long run. The difference between them is that EqForceOn will attempt to maintain a perfectly equilateral polygon during the entire run by adding a penalty function which makes non-equilateral edges undesirable. This can interfere with the stepper, and slows down convergence of the run. On the other hand, EqOn monitors the run and essentially rediscretizes the polygon and restarts from the new configuration whenever the longest edge is more than 3 times the length of the shortest edge. This does not look good in a movie, but is more effective during minimization.

–SnapshotInterval=<n> save a complete snapshot of computation every n steps

This is basically a debugging option. In myfile.rr/snapshots, ridgerunner will store everything about your run every n steps. This can be very useful for debugging, but can also take up a lot of disk space. Setting SnapshotInterval to 100000 or so will essentially turn off snapshots.

–Symmetry=Z/pZ,D2 rotation/reflection symmetry group (around z-axis) to enforce on curve

Ridgerunner will enforce a rotational symmetry (around the z axis) or a reflection symmetry (over the x-y plane) on curves during a run. The curves must be carefully generated so that as polygons, vertex-by-vertex they have the desired symmetry in the input configuration. Ridgerunner will then maintain this symmetry during the run.

–Display=ropelength/strutcount/thickness name of logfile to display on screen during run

In the directory myfile.rr/logfiles, ridgerunner will store logs of various quantities that might be of interest during a run. Everything from the variance of edgelength (edgelengthvariance) to the memory used by ridgerunner (memused) is logged. You can display these logs as the program runs by adding –Display=<logfilename> to the command line. The most commonly used of these options is –Display=residual, since the residual is usually a stopping criterion.

How to make a tightening movie

Ridgerunner can be used to make movies of the tightening process, as well as generate final tight configurations. Unless the


command line argument is given, myfile.rr/vectfiles will contain a collection of intermediate VECT files showing the curve as it appeared at various step numbers in the computation. Ridgerunner ships with a PERL script called povanimate which will convert these to rendered PNG files automatically using Tube and Povsnap, but there are some gotchas which you should be aware of.

First, povanimate requires Term::ProgressBar. No problem! Type

sudo cpan
install Term::ProgressBar

and watch the fun until the build completes, then exit cpan. (If this was your first time, congratulations! You’ve just updated your installation of Perl.)

Second, you have to actually have [vecttools], povrayutils and plsurf (available on this page) installed, as well as povray itself, in order to use this script.

You must invoke povanimate from the myfile.rr/vectfiles directory as it’s not smart enough to go spelunking for vectfiles to use outside the directory that you run it from. As the script runs, you should see something like:

jason:vectfiles> povanimate
Animating directory of 444 files
Will create 444 frames to reach desired 20 second time.
Tubing files…
Files: 100% [===================================================]D 0h00m11s
Orienting the entire collection of surfaces (could take some time)
Rendering the frames
100% [==========================================================]D 0h50m20s
Now generating spin frames…
(nothing to do)

when you’re done, you’ll see a new directory called myfile.rr/movie which contains povray rendered snapshots of the individual frames in your run. The vectfiles are thinned out, if needed, to produce about 20 seconds of video at 24 fps. There’s a command-line option for povanimate to change the length of the movie if you want it faster or slower. You can process the resulting directory of still images into video however you want. Personally, I like QuickTime Pro, but there are plenty of other options (eg. on Linux platforms), and a sneaky way to do it is to use Mathematica to import the stills and export them as an animation if you don’t want to pay for QuickTime Pro.


If you want the absolute latest, you can always get it from the subversion repository at http://www.jasoncantarella.com/ridgerunner/. The ridgerunner plus dependencies has an open subversion repository at http://www.jasoncantarella.com/rrplusdeps/. Note that you’ll need the GNU autotools in order to compile from the repository and also that building rrplusdeps from the repo is not for the faint of heart since you’ll have to check out the individual packages plCurve, octrope, tsnnls, vecttools, plsurf and povrayutils into your working copy in order for the build to complete.

  1. Ridgerunner plus dependencies. This is the preferred installation for Ridgerunner, updated August 2013 to include the latest versions of the libraries which ridgerunner depends on and with some bugfixes. It includes all of the (nonstandard) dependencies. There are still dependencies that you’ll need to install manually:
    1. LAPACK and BLAS, and lapack-devel and blas-devel to get the headers you’ll need for compilation.
    2. argtable2, which is available as a standard package on most Linux builds
    3. gsl, the GNU Scientific Library, which is also a standard package in most Linux builds
    4. A version of the ncurses library, using a package such as ncurses-devel.
    5. PovRay, if this is still possible on your system (we’re working to replace this dependency)
  2. Ridgerunner 2.0 build (just ridgerunner. This is the right package if you’ve already installed everything else separately.)
  3. plsurf 1.0 build (surface library used for moviemaking)
  4. povrayutils 0.9 build (utility library used for moviemaking)

Development Roadmap

Ridgerunner is a mature piece of software which is essentially complete. Piotr Pieranski and Sylwek Przybyl have (private) software which operates at much higher resolutions than ridgerunner, and is the preferred path forward for very detailed images of specific tight knots and links. For most scientific purposes, the ridgerunner tightenings should be sufficient. We will continue to complete the table of tight knots and links with composite link data as it becomes available. Development is currently restricted to bugfixes.