Monday, December 27, 2010

Where's the "Numerical Recipes in Pseudocode?"

You know the little saw that comes on Swiss Army Knives? It looks awesome and potentially useful; right up to the point that you actually need it. At that point, you realize it's just a toy. Any piece of wood that could actually be sawed with it could easily be snapped with your foot, if not your bare hands, and any piece too substantial won't even be phased. That's exactly what Numerical Recipes in C is. It looks awesome and potentially useful; right up to the point that you actually need it.

I was doing some heavy-duty numerical programming at my last job, so my boss bought me Numerical Recipes in C as a reference. Most of the time I didn't need to use any of the code from the book; I was mostly converting some existing MATLAB code to C. The Numerical Recipes book just kinda sat on my desk, every once in a while I would crack it open and read about a random subject. The chapter about pseudo-random number generators was pretty interesting, but I never really looked to far into the actual code. See, each subject has a few pages of high level explanation followed by a few printed C programs. The explanations were interesting and pretty easy to understand. As I wold find out though, the code was a complete mess.

At some point we needed to add a three dimensional interpolator to our program. My boss and I found a cubic spline interpolator in the book that looked pretty good, so logically he had me use that one instead of bothering a scientist to come up with a new one. It didn't take long for me to figure out that incorporating the Numerical Recipes code wasn't going to be fun. The authors of the book are mathematicians as opposed to programmers, and their coding style definitely shows it. At first glance I noticed that variables aren't given meaningful names; instead they're given two or three letter names that appear random. For their sake I like to assume the names were acronyms for things I've never heard of and weren't mentioned in the book, but the effect is pretty much the same as random. Of course being a hotshot programmer like I like to think I am, I wasn't phased. The next thing I noticed was a cardinal rule of C programming being egregiously violated; the authors used macros to essentially make their own programming language. Memory allocation, deallocation, and basic data types were all defined by macros, and were just different enough from regular C to throw me off. What's worse is that the macros being used were defined in various places throughout the appendix of the book, so about every other line of code required me to search through the appendix to find out what was going on. As if reading source code wasn't already difficult, I now had to keep track of nonsensical variable names, convert their bizarre C-like language to regular C in my head, and constantly flip back and forth between the code and the appendix. Eventually I got all of the code into my program, but the amount of modification I did in the process left my code and their code pretty much unrecognizable from each other. That made debugging really difficult when the code crashed with a weird memory error.

After I spent about an entire work day working through every line of the code, scrapping it and starting over, going through it again and still getting the same memory error, my boss decided to write me a new interpolator in MATLAB himself. I still have no idea what was causing the error. I could have translated the code incorrectly, it could be that I was running the code with a different compiler on a different system, or it could just be a typo in the book. The only thing I know for sure is that if I never see their code again it will be too soon. Anyway, once I got the code from my boss, I translated it into C and got it running in the program in about 45 minutes.

The whole ordeal got me thinking. If I could translate MATLAB code into my C program faster and less error-prone than their botched C code, why did they put the programs in C in the first place? Did they want C programmers to be able to read it? No it can't be that, they went pretty far out of their way to ensure that reading their code was out of the question. Did they use C so that programmers could just copy and pase the code directly into their programs, even without understanding it? Obviously not, the input and output values are non-standard, macro-defined data types, and macros are used egregiously throughout the code. The only way you could copy and paste any of their code and have it run would to also copy and pase an entire appendix of macros and complie them into your entire existing code base (in other words it's out of the question). The only reasonable answer I can come up with is that I'm looking at it all wrong. Mabye I'm simply not the intended audience for this book. Perhaps C programmers working on numerical software were the furthest thing from their mind when the authors were writing a book titled "Numerical Recipes in C." As reasonable as that answer sounds, it raises another, more serious question though. If a C programmer writing numerical software can't get any value out of the book, who can? The explanations in the book are interesting, but not thorough enough to actually be useful to a professional mathematician or programmer, and the code isn't usable in any serious way. You can play around with the preloaded software on their CD, but don't even think about incorporating the code into your software unless you're ready to overhaul your entire code base to accommodate their ridiculous coding conventions. You can attempt to reverse engineer their code like I failed to do, but I'll warn you right now that if your time has any value you're better off getting a mathematician to come up with something from scratch. If you don't have access to any mathematicians, quit your job right now; the only kind of company that would have you write numerical software without any mathematicians on staff is the unsuccessful kind.

With professional programmers and professional mathematicians ruled out, the only possible audience left for this book is non-professionals; reducing the status of this book from tool to toy. Like the swiss army saw before it, it's a toy dressed up as a tool. Moreover, it's a toy that you should, under no circumstances, use as a toy.

No comments:

Post a Comment