Installing FUF and SURGE

This page explains how to install the FUF and SURGE text generation system (syntactic realization), with special attention to a Windows platform. It refers to a slightly updated version of FUF 5.4 and SURGE 2.2.

Two Methods: Quick Install / Development Environment

If you want to use SURGE as a black-box tool, without going into details, then follow these instructions:
  1. Download this version of SBCL 1.1.0 (a Windows Commonlisp interpreter/compiler about 10MB).
  2. Download this pre-loaded core image of SBCL that includes FUF 5.4 and SURGE 2.2 preloaded with all test data (about 10MB).
  3. Download the source of FUF and SURGE for reference and inspection (1MB).
  4. Execute the SBCL installer - it will put the binaries for common lisp in a folder like "C:\Program Files\Steel Bank Common Lisp\1.1.0".
  5. Unzip into this folder - it will create a file of 32MB called surge.core.
  6. Create a batch file in your path called surge.cmd with the following content:
    @"C:\Program Files\Steel Bank Common Lisp\1.1.0\sbcl.exe" --core "C:\Program Files\Steel Bank Common Lisp\1.1.0\surge.core"
  7. You can now execute "surge" and interact with FUF and SURGE as described at the end of this document - for example:
    * (in-package "FUG5")
    * (test :item 't1)
  8. If you want to experiment with the smaller test grammars included in "fuf/examples" (gr0...gr10 and ir0...ir10) - you can do:
    * (gsetup1)
    * (isetup1)
    * (test)
If you want a more comfortable development environment, install a minimal CommonLisp environment with Emacs and configure it to load FUF and SURGE by following the insructions below.


  1. Download the SBCL Common Lisp compiler.
  2. If you are on Windows, download the Emacs text editor (which is the best environment to program in Lisp). If you are on MacOS or Linux, Emacs is most probably already installed.
  3. Download the SLIME emacs package.
  4. Download the Quicklisp installation package for CommonLisp into your home directory (the same directory where ~/.emacs is located).
  5. Install quicklisp:
    C:> sbcl --load quicklisp.lisp
    Inside the CommonLisp shell type then:
    * (quicklisp-quickstart:install)
    * (ql:add-to-init-file)
    * (ql:quickload "quicklisp-slime-helper")
  6. Add to your .emacs file the following line:
      (load (expand-file-name "~/quicklisp/slime-helper.el"))

Installing FUF and SURGE

  1. Download FUF.
  2. Extract the files of fuf in a folder such as ~/fuf. It should have the following structure:
    1. doc
    2. examples
    3. src
    4. surge
      1. code
      2. doc
      3. inputs
    Copying the files under your home folder (~/fuf) will make it easy by default for quicklisp to locate the package.
  3. Instruct quicklisp where to find the system definition files to load fuf and dependent modules. Create a file in this folder: ~/.config/common-lisp/source-registry.conf.d with this content:
    	(:tree (:home "fuf"))

Loading and Testing FUF

  1. Start emacs
  2. Start lisp inside emacs: invoke the command "M-x slime" (that is, type "escape x slime enter")
  3. Load FUF: (ql:quickload :fuf54)
  4. Load FUF tests: (ql:quickload :fuf54-test)
  5. Go into the FUF package: (in-package :fug5)

Loading and Testing SURGE

  1. Load SURGE: (ql:quickload :surge22)
  2. Load FUF tests: (ql:quickload :surge22-test)
  3. Go into the FUF package: (in-package :fug5)

Running Specific FUF or SURGE Tests

In general, when you use SURGE, you want to prepare input specifications for sentences. The following process can be used to prepare and test your input specifications:
  1. Create input structures (best is to start from an example similar to one found in "surge/inputs")
  2. The macro "def-test" is used to associate a SURGE input specification (an FD) with the expected sentence. For example:
    (def-test t1
      "This car is expensive."
      ((cat clause)
       (proc ((type ascriptive)
    	  (mode attributive)))        ;; default
       (partic ((carrier ((lex "car")
    		      (cat common)
    		      (distance near)))
    	    (attribute ((lex "expensive")
    			(cat ap)))))))
    Keep your test pairs in a development file and add the line (in-package "FUG5") at the beginning of your file.
  3. To test the interpretation of your input specification, use the "fug5:test" function:
    (fug5:test :item 't1)
  4. If everything works fine, you will see the following input:
    CL-USER> (fug5:test :item 't1)
    FUG5::T1 --> "This car is expensive."
    [Used 88 backtracking points - 19 wrong branches - 8 undos]
    [Used 89 backtracking points - 19 wrong branches - 8 undos]
    1 test run - 1 correct.
  5. If the name of the test you invoke does not exist (no correspond def-test was entered), you will see:
    (fug5:test :item 'd1)
    D1 --> NIL
    [Used 1 backtracking points - 0 wrong branches - 0 undos]
    [Used 1 backtracking points - 0 wrong branches - 0 undos]
    Expected NIL
    Instead  "<fail>"
    1 test run - 0 correct.
    The following tests are incorrect: (D1)
  6. If the input specification is not good, you will see a message similar to this:
    FUG5::T146 --> "The Denver Nuggets surprisingly beat the Celtics."
    [Used 90 backtracking points - 21 wrong branches - 10 undos]
    [Used 110 backtracking points - 37 wrong branches - 14 undos]
    Expected "The Denver Nuggets surprisingly beat the Celtics."
    Instead  "Denver Nuggets surprisingly beat Celtics."
  7. Sometimes, the grammar will get exhausted trying many alternatives without terminating the search process. The test macro limits the search space to up to 1000 backtracking points. When the input you specified is too complex or causes the grammar to search over this limit, you will see the following message:
    FUG5::A4 --> "John takes a book from Mary."
    ;;; Unification stopped after 1001 backtracking points.
    Expected "John takes a book from Mary."
    Instead  "Mary ."
  8. At other times, the input you enter is not compatible with the expectations of SURGE. In this case, you will see:
    FUG5::T97 --> "The person to whom John will give a blue book."
    Expected "The person to whom John will give a blue book."
    Instead  ""

    Debugging your SURGE Input Specifications

    In any case when the input specification fails to produce the sentence you expect, you want to find out the reason for the failure. To get information on the unification process, use the function:
    And to remove the trace info, use:
    This produces lots of information. You can control the verbosity of the trace by using:
    (fug5:trace-level 30)  ;; minimum level of trace detail
    (fug5:trace-level 0)   ;; maximum level of trace detail

    Last modified October 29th 2012