Quick Start

Say make depend and then make fast to get an FR executable called realizer

Then try it out with any of the included script files (*.scr) like this:

./realizer < whatever.scr

When the FR runs, it writes an input script called input.scr, so if you just want to change one or a few things, you can rename and edit input.scr and rerun it easily. The order and nature of the prompt questions asked by the FR are answer-driven and input-dependent, so more drastic manual changes to input.scr may not work -- rerun ./realizer without redirected input and answer new questions to regenerate a correct input.scr.

After the FR runs, it makes two output files called landscape.xpm and ties.xpm

You can use the XPM utility sxpm, available on most systems, to view these (xv will also work).

sxpm landscape.xpm

Compiling the Fractal Realizer Code

The Fractal Realizer (FR) code was originally developed using DEC Fortran under ULTRIX (Incredible, huh?).

I have updated the Makefile to work with the Portland Group Fortran 77 compiler under RedHat 7.2 Linux.

Since this is a research code, I assume that users have some facility with compilation and Makefiles. The FR code consists of a visualization portion, written in C, and the FR model itself, written in Fortran. The Fortran portion is a subroutine called by the main C program. The visualization portion is based on the XPM extension to X windows written by Arnaud Le Hors (see below). The XPM extension is already present in (almost) all recent versions of operating systems which include X windows, so it is not necessary to get anything new.

When using non-Portland compilers, change pgf77 in the Makefile to whatever your installation may have. Since the C piece is main, many Fortran compilers need to be given a "nomain" switch, or they get very confused. Because the syntax for this switch varies among compilers, you may have to look up the equivalent switch for your particular compiler. A switch to align common blocks on cache-line boundaries is helpful also.

Another typical two-language compile problem is the number and placement of underscores in the names. Some compilers want "_MAIN_", while others want "_MAIN" or other variants. Since there is no universal solution, you may have to mess with these names manually.

Function prototyping shouldn't be a problem if you use an ANSI-compatible C compiler. We have included a local strdup function, so that shouldn't be a problem either.

It should be possible to get the no-cost GNU g77 compiler to work, but I have not pursued this. If you get g77 to compile this code, or if you modify the Makefile to get other compilers to work, please let me know (hnw@fire.esd.ornl.gov) so that I can incorporate your improvements back into this distribution.

The Makefile also supports compilation of debugging (make debug)and profiling (make prof) objects. The name of the executable is realizer. If you make platform-specific changes to the Makefile, please return it to me so that I can include it in the distribution. Why make others try to duplicate your work?

If you don't understand any of the above, don't worry -- you probably don't have to. JUST TRY IT AND IT WILL PROBABLY WORK.

Terms of Use and Distribution

The FR source code package is distributed under the same terms as the Gnu Copyleft agreement http://www.gnu.org/copyleft/copyleft.html. Copyleft basically says that anyone who redistributes the software, with or without changes, must pass along the freedom to further copy and change it.

There are two additional requests that we make beyond those of the Copyleft agreement: (1) please notify us of improvements made in the code, and allow the improved versions to be distributed here, and (2) work resulting from the use of the Fractal Realizer code should cite the paper listed below and available online here:

Hargrove, W.W., F.M. Hoffman, and P.M. Schwartz. 2002. A fractal landscape realizer for generating synthetic maps. Conservation Ecology 6(1): 2. [online] URL: http://www.consecol.org/vol6/iss1/art2

If you agree to all of the above terms, click here to download the Fractal Realizer distribution package in gzipped tar format.

System Requirements for the Fractal Realizer:

Unix/Linux environment

XPM extension to X windows installed

C compiler

FORTRAN compiler

The XPM X PixMap library, http://www-sop.inria.fr/koala/lehors/xpm.html is used by the Fractal Realizer for visualizing maps of the burn on screen during the simulation. The XPM X PixMap library was written by Arnaud LeHors.

XPixMap (XPM) consists of an ASCII image format and a C library. The format defines how to store color images (X Pixmap) in a portable and powerful way. The library provides a set of functions to store and retrieve images to and from XPM format data, being either files, buffers (files in memory), or data (included files).

While XPM is not an X Consortium standard, it is already a de facto standard. It is used in many applications both commercial and non-commercial. There is a mailing list to talk about XPM. This is xpm-talk@sophia.inria.fr.

You may already have the XPM extension installed on your machine. Several computer manufacturers distribute the XPM library, as contributed software, on the platforms they sell. Several flavors of the LINUX operating system also come with the XPM extension already installed.

Running the Fractal Realizer

The Fractal Realizer has many options, and some of these are mutually exclusive. Simply running the executable begins a cascade of questions from the model which query the user to set up the options for the simulation run. Responses to the questions direct the subsequent questions, changing the way that the option tree is traversed. This verbose interaction mode is a good way to become familiar with the wide array of Fractal Realizer options. After all questions are answered, the simulation begins.

Because answering all of the input questions for each run would be tedious, the Fractal Realizer writes a script file, inpout.scr, containing the input answers from the last run. Thus, the last simulation can be repeated by issuing the command:

realizer < input.scr

To change a few input settings, it is not necessary to wade through all of the input questions again. Instead, simply edit the inpout.scr script file directly, and then rerun the simulation using the modified script file. Mnemonic comments within the script file aid in such editing process.

A number of demonstration .scr script files are included in the distribution, and running these ``canned'' demos is a good way to test the installation, as well as to see the capabilities of the Fractal Realizer. Final landscapes and tie maps can be output in several formats, including XPM and GRASS.

The FR program uses a heap sort to sort the entire map to find the highest probability sites, so execution time will increase rapidly as the size of the map is increased. Execution time also increases with increasing numbers of categories in the map. Because of the midpoint displacement algorithm for generating (pseudo)fractals, the maps must be square, with sides of (2**n)+1. However, the use of constraint masks will permit oddly-shaped and smaller synthetic maps to be generated while still preserving both p and the fractal dimension of each category.

We hope that the FR will prove useful (or at least stimulating) to you. Please be sure to cite our Conservation Ecology paper in all work stemming from the use of the FR, and be sure to let us know of any improvements or suggestions that you may have ...

For additional information contact:

William W. Hargrove

Oak Ridge National Laboratory

Environmental Sciences Division

Building 1507, Room 211

Mail Stop 6407

Oak Ridge, TN 37831-6407

(865) 241-2748

(865) 574-4665 fax

hnw@fire.esd.ornl.gov