RT(1)

NAME
remrt - network distributed (remote) ray-trace dispatcher

SYNOPSIS
remrt [ options ... ] model.g objects ...

DESCRIPTION
remrt is intended to be an entirely plug-compatible replacement for the rt(1) program. While rt can operate on more than one processor of a shared memory MIMD style multi-processor, it can not spread the work out across the network. remrt and its companion program rtsrv(1) implement a libpkg(3)-based protocol for distributing the task of ray-traced rendering out to an arbitrary number of processors on the network. Those processors can be from an arbitrary mix of vendors, with differing instruction sets and data representations, operating at widely different speeds.

remrt provides two levels of fault-tolerance in its distributed computation. First, any rtsrv processor which fails (or whose network link fails) will have its work reassigned automaticly by remrt to other processors, so that the failure of that processor does not hold up the progress of the computation. On a regular interval remrt attempts to restart computation on failed processors marked ``active'', so that when failed systems become available again they are put back to work. Second, remrt offers a form of ``checkpoint-restart'' by carefully writing all received pixel data immediately to disk. If the machine running remrt should fail, when remrt is restarted, it will determine what work remains to be done and restart all the rtsrv processes on the remote machines.

remrt takes exactly the same set of command line arguments as rt(1). For a full discussion of those options, consult the rt(1) manual page. From within mged(1) the remrt program can be run from the current mged view by giving the mged command
     rrt remrt -M -s###
where ``###'' is the image resolution desired.

remrt depends on the Berkeley rsh (1) remote shell command and the user's corresponding ``.rhosts'' file to automaticly initiate remote computation.

remrt requires a control file called ``.remrtrc'' which specifies a few essential parameters of the server machines (network hosts) that are to participate in the distributed computation. The ``.remrtrc'' file contains a list of normal remrt commands which are to be executed before distributed processing is to begin. This can be useful for establishing a variety of user-specific defaults. However, the most important command to provide is a ``host'' command to describe each of the remote hosts that will (or may) participate in the distributed computation. Here is a sample ``.remrt'' file:

host wolf	passive cd /tmp/cad/.remrt.4d
host voyage	always cd /tmp/cad/.remrt.4d
host whiz	hacknight convert /tmp

The first argument to the ``host'' command is the name of the server machine. It will be converted to a fully qualified name by calling gethostbyname(3) and gethostbyaddr(3).

The second argument to the ``host'' command describes ``when'' this machine should be used.

always
    says that whenever this host is not participating in the computation, repeated attempts should be made (every 5 minutes) to start an rtsrv process on that machine. This option is most useful for machines where the system administrator and/or owner of the machine won't mind your using the machine at any time. (Note that rtsrv runs at the lowest priority by default, so this isn't too terribly uncivilized. But be polite and ask first.)

night
    indicates that the machine should only be used during the night and on weekends. Night extends from 1800 through 0000 to 0800. Saturday and Sunday are considered to be in night time for the entire day.

hacknight
    indicates that the machine is owned by a late-night ``hacker'', and can be used while that hacker is likely to be asleep. Hacking tends to run from 1300 through 0000 to 0400, so hacknight is the time period from 0400 to 1300.

passive
    indicates that remrt should never attempt to initiate an rtsrv process on this machine, but if the user should happen to start rtsrv manually on the machine and direct it to join the computational fray, then the necessary information will be available.

If an unlisted machine should join the fray, it will be added
    with a ``when'' value of passive and a ``where'' value of convert. When an rtsrv passes from night into day, it is automaticly terminated by remrt at the appointed time.

The third argument to the ``host'' command is the ``where'' parameter, which indicates where the BRL-CAD ``.g'' file (and any related texture maps) can be found.

cd  indicates that the rtsrv program should change directory cd(2) to the indicated directory path, and should just read the data files in that directory as rt normally would. This can be used to specify NFS or RFS mounted remote directories, or static copies of the binary database file(s) needed to perform the ray-tracing. This is the most efficient way of operating rtsrv, but it also requires some manual preparation on the part of the user to install all the required files in the designated location.

convert
    indicates that remrt should send across an ASCII machine-independent version of the ``.g'' database file using the command:
        asc2g < file.g | rsh host 'cd directory; g2asc > file.g'
    before starting up the rtsrv program in that same directory. This relieves the user of the burden of setting up the ``.g'' database file, but suffers from several drawbacks. First, the transmission of a large database can take a noticeable amount of time. Second, should the server host go down and then re-join the fray, the database will be sent again, because remrt has no easy way to tell if the previous ``.g'' file is still intact after the crash/restart. Third, remrt has no way to tell what auxiliary files might be needed for this ``.g'' file, and thus can not send them automaticly. If the ``.g'' file references height field, extruded bit-map, or volumetric solids, the associated data files will not be present on a convert mode server. The same applies for texture map and bump map files.

remrt uses several different strategies for optimizing the dispatching of work. These can be controlled by the ``allocate'' command. If the -I (interactive) flag is given or ``allocate frame'' has been specified, then the work allocation method is a ``free for all'', allocating work from one frame at a time to all servers as they become ready for more. This maximizes the CPU overhead for prepping (because all CPUs will prep all frames), but it also provides the shortest wall-clock time to getting the first frame finished. This mode is recommended for demonstrations, and other situations where people are sitting around waiting for results to appear on the screen.

If the ``allocate load'' command has been given, then new servers will not be assigned to a given frame unless there is at least enough work remaining on that frame to require 10 percent of that server's measured performance capacity. Otherwise the server is started on a subsequent frame.

If the ``allocate movie'' command is given, then each server is allocated a whole frame to do. This minimizes the CPU time spent in the overhead of prepping the frame, and tends to maximize overall throughput, at the price of making you wait a long time for the first frame to finish. This mode is best used when crunching out large numbers of frames for an animation. (See also the scriptsort(1) command for a clever power-of-two script rearrangement technique first proposed by Jim Blinn).

The output can be stored either in a file, or sent to the current framebuffer, the same as with rt(1).

When remrt is run without command line arguments, it enters an interactive mode. In this mode, the current framebuffer can be assigned and released, frames can be added to the list of pending work, and many other control and status commands can be used.

Normally remrt runs in a batch mode, taking all its information from the command line, the script file on stdin, and the ``.remrtrc'' file. If you wish to issue an interactive-style command to remrt while it is running in batch mode, this can be accomplished by giving an extra argument to rtsrv, which will simply pass on the command and exit. For example:
    rtsrv server_host 4446 status
would send the command ``status'' to the remrt process running on the machine called ``server_host'' and listening at port 4446. 4446 is the port used by the first copy of remrt running on a machine. If a second copy of remrt is started while the first one continues to run, it will be assigned port 4447. One is added to the port number repeatedly until an available port is found. Normally you do not need to worry about which port is being used, unless you wish to send commands there directly. The netstat(1) command can sometimes be useful to track down which ports are being used.

SEE ALSO
rtsrv(1), rt(1), scriptsort(1), brlcad(1), mged(1), lgt(1), pix-fb(1), rtray(1), rtpp(1), librt(3), ray(5V), pix(5).

DIAGNOSTICS
Numerous error conditions are possible. Descriptive messages are printed on standard error.

COPYRIGHT
This software is Copyright (c) 1985-2012 United States Government as represented by the U.S. Army Research Laboratory. All rights reserved.

SEE ALSO
M. Muuss, ``Workstations, Networking, Distributed Graphics, and Parallel Processing'', in ``Computer Graphics Techniques: Theory and Practice'', ed: Rogers & Earnshaw, Springer Verlag, New York, pages 409-472.

BUGS
Most deficiencies observed while using the remrt program are usually with the rt(1) program, with which it shares a substantial amount of common code, or with the librt(3) library. If a frame fails to render properly, try processing it on a single machine using rt(1) to determine if the problem is in the ray-tracing side of things, or the distributed computation side of things.

BUG REPORTS
Reports of bugs or problems should be submitted via electronic mail to <devs@brlcad.org>.