The Lone TeXnician
==================

This is a Mars Rover controller written in (La)TeX.  It also includes
a bit of Perl because TeX has no socket libraries.

---

1. Wrapper interface

There is a 100-line Perl wrapper (called texsocket) that deals with
the networking.  It basically operates by opening up the TCP/IP socket
along with a two- way pipe to a TeX process.  The wrapper keeps the
incoming messages from the server buffered until TeX asks for them by
printing "WANT" and then blocking until it gets a line of text from
STDIN.  Likewise, to send a message to the server, TeX prints "HERE:"
followed by the message, and the Perl wrapper simply passes that
along.

The other major responsibility of the Perl wrapper is to keep time for
TeX.  Since TeX does not have its own internal clock (indeed, there is
a "\time" macro that gives the time up to the minute, but it is fixed
at the beginning of the job, so even if it were well-enough resolved,
it wouldn't help).  We do this by adding an extra signal "t <time> ;"
analogous to the rest, which the TeX can then interpret to keep an
internal clock about 10x more accurately than the telemetry packets
provide, and also that is robust under fluctuating latency.  The wrapper
is also in charge of restarting TeX should it run into an error, and
then re-initializing it with the original init message.

---

2. The TeX code

I broke up the code into several separate files, roughly divided based
on the functionality.  But since TeX has just a single namespace, it
doesn't actually provide any true modularity.  The files are as follows:

 main.tex - the main driver: it just includes all the other files, checks
            if we're running LaTeX (and if so, provides the necessary
	    commands) and then starts the main loop running.
 comm.tex - this is where I defined the communication/interface routines.
 go.tex   - this is the brain, where the program does all its thinking.
 math.tex - defines macros for multiplication, division, sqrt, and
            length of 2d vectors (pythag).  TeX doesn't actually provide
	    a way to multiply or divide two non-integers.
 trig.tex - defines sin, cos, atan, and a macro to normalize an angle to
            be between +/-180.  Again, since these aren't built-in, I
	    opted for a piecewise quadratic approximation that does a
	    pretty decent job (good enough for government work, at least).
 vars.tex - allocates all my (obnoxiously) global variables.
 param.tex- defines a few parameters that I didn't want to hard-code.
            I never quite cleaned it up, so they're not all used.
 active.tex-this deals with active characters and is how I parse the
            signals.  But it's important to sequester it because otherwise
            everything will be contaminated with wrong catcodes.
 pict.tex - this includes extra features for LaTeX to draw a picture of
            the map as we're rolling along.  It doesn't quite work right
            because some numbers are escaping onto the page somewhere.
            To use pdfLaTeX, pass texsocket the '-l' option and you should
	    get out a PDF file in the working directory.  There's also
	    an extra page at the end that would take more time than it's
	    worth to get rid of.

---

3. Logic

My basic logic is a two-state machine.  At any time the rover is
either running toward home (state R), or swerving out of the way of an
obstacle (state S).  In R, we just keep turning toward the origin, and
regulate the speed to be cos(theta), where theta is the angle between
the direction of travel and the origin.  If we find a rock/crater in
front of us (the distance threshold is a configurable (in param.tex)
multiple of the maximum speed.  I don't work out braking times to
figure out a more optimal solution), then we go into swerving mode.
This actually has two sub-modes.  The first sub-mode is where we turn
the rover until it's no longer in danger of intersection (with a 20%
padding for safety).  At this point, we just drive straight until we
pass the obstacle on our right or left.  This prevents us from turning
right back into the same rock over and over again.  This logic was
sufficient to get about 80% completion rate on the provided sample
maps, as well as on most roasonable random maps.  Certainly, the
contest organizers will have designed much more challenging maps
with much smarter martians, and in these later rounds, my program
likely won't stand much of a chance.

---

4. Known Limitations

 - Martians are ignored.  They didn't really do anything on the sample
   server.

 - Overflow errors are very possible.  TeX uses only fixed-point numbers
   internally.  I store all fractional quantities as dimension registers,
   with the conversion 1pt -> 1m, or 1m/s, or 1degree/s, etc.  But the
   largest dimension TeX can deal with is a few thousand pt, so anything
   bigger than a couple kilometers will cause my program to barf, rather
   instantly.  An alternative would have been to use a smaller conversion,
   since we don't need 5 decimals of accuracy, but this makes all the rest
   of the math more difficult (and slower), since TeX always reports its
   dimensions in pt.

 - Native TeX has very low memory limitations.  The version I packaged
   is beefed up some, but can still probably run out.

 - The program sometimes has a hard time recognizing when it's supposed
   to quit.  This is mostly only in the case of the visualization window,
   however.

 - There's a short pause at the beginning of the first trial.

---

5. Why TeX?

Because I can.  I hope you enjoy looking at it as much as I enjoyed
writing it.

---

6. Acknowledgments

The multiplication, division, and square root routines are not my own.
The first two were posted to usenet by Donald Arseneau over a decade ago
and I stole them wholesale.  The latter was written by a classmate of
mine for a TeX macro package to typeset CD labels with circular text.