Ridgerunner

From JasonCantarellaWebpage

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.

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/
  jason:3.1.rr>

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).

->

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

  --NoOutputFiles

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.

Downloads

Ridgerunner plus dependencies
- This is the preferred installation for Ridgerunner, updated March 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:
  - LAPACK and BLAS, and lapack-devel and blas-devel to get the headers you'll need for compilation.
  - argtable2, which is available as a standard package on most Linux builds
  - gsl, the GNU Scientific Library, which is also a standard package in most Linux builds
  - A version of the ncurses library, using a package such as ncurses-devel.
  - PovRay, if this is still possible on your system (we're working to replace this dependency)
Ridgerunner 2.0 build (just ridgerunner. This is the right package if you've already installed everything else separately.)
plsurf 1.0 build (surface library used for moviemaking)
povrayutils 0.9 build (utility library used for moviemaking)

Navigation