Math-Intensive Reports with GNU Emacs and Calc, Part 1

I'm trained as an engineer, and I work in the structural analysis field. As part of my job, I have to perform structural stress analyses and document the results in reports. For me, GNU Emacs has solved several longstanding problems related to the authoring and publication of such reports.

The unique situation that engineering analysts like me encounter is preliminary engineering calculation reports must be written at specific points in time as an engineering project evolves. These preliminary reports must be complete and accurate relative to the current state of the design, even if the design itself is still incomplete and in flux. Such reports are required by contract to be delivered to design review meetings as an integral part of the in-process documentation of a design. They are checked by the customer's representatives, and if problems are found (either with the hardware as exposed by the analysis or with the analysis report itself), they must be corrected right away. This is a different matter considering the problem of writing papers whose accuracy is checked only once before publication in a scholarly journal.

I know other engineers (of whatever specialty area) experience the same problems, and I believe they will be interested in learning about useful software tools that can solve them. In fact, almost anyone who needs to write reports documenting on-going calculations should find this article to be of use.

I have only recently started using Emacs. In fact, this article evolved from numerous small text files I'd made for testing various aspects of Emacs. For years I had been intrigued by what I'd heard about it, but I also felt intimidated by its legendary size and complexity. Three things finally compelled me to buckle down and try Emacs. The first was my discovery that Emacs is actually quite small compared to the average late-1990s word processor installation. The second was a sense of revulsion that overcame me when my favorite word processor, WordPerfect, was consigned to the scrap heap of history by a notably inferior product being pushed along by a marketing juggernaut. The third and most important was calc.el, the Elisp Calc math package. Today, having become fairly comfortable with Emacs+Calc, I am not looking back.

If you do math, you probably recognize that it's not only about the numbers. It's about your assumptions, your mathematical model of reality, your results, your interpretation and understanding of them and your ability to make them clear to other readers. It's about leaving behind a record of what you did and why you did it, so others can review, comment on, criticize and update what your work. Only in this way can a calculation carry any significance. In short, I am talking about a report.

Whether it's figuring out your car's gas mileage or the best way to intercept an incoming asteroid, you need to keep a record for yourself as well as for others. Therefore, you need to write a report. It may be only a few sentences, or it could be a thousand pages. It may be only for yourself, if you think you might have trouble remembering what you did, or it may be to convince NASA authorities to accept your science payload for a ride on the Space Shuttle. While you alone are responsible for calculating your car's miles per gallon, your calculations of the structural integrity of a Shuttle payload affect, and are affected by, a great many people. In cases like these, a formal report is absolutely required.

The great bugaboo with all such reports, however, is the need to track changes. The calculation results need to be updated every time design changes are made, and the report must be reissued for design review meetings. What kinds of design changes? Many: changes in dimensions, material specifications, the manner of attaching and fastening parts, numbers and sizes of bolts and screws and estimated loading cases, to mention a few. In an engineering design project, redesigns come almost hourly in the early phases. Later on, as the design becomes more mature, things stabilize a bit, and the rate at which design changes occurs drops dramatically. The problem is, by this time in the project, you have generated many pages of extremely detailed analyses. Coping with even a minor change can set your publication date back by weeks. Keeping a stress calculation report current, based on the latest design information, is a massive headache. Enter Emacs+Calc.

Emacs is described by its author as an "extensible, customizable, self-documenting real-time display editor". Emacs is written almost entirely in its own version of the Lisp language (Emacs Lisp, or elisp). Elisp is a general-purpose programming language. Almost all of Emacs' built-in editing functions are implemented as calls to a predefined library of elisp functions. Emacs is extensible because expert users can write full-fledged application program libraries in elisp. Once a useful elisp library or application program has been written and tested, it becomes available to any user of Emacs, whether or not he knows elisp. Indeed, the Emacs distribution comes with a great many elisp packages, and many more are available from various sources on the Internet.

If you have ever used the Autocad drafting package, you'll know that it also uses an embedded version of Lisp (Autolisp) as a medium for writing all kinds of extensions. There is a lively trade in Autolisp libraries and applications among the worldwide body of Autocad users. Not all of these users know how to write anything at all in Autolisp, but one doesn't need to know Autolisp simply to use an Autolisp add-on package. It's the same way with Emacs and elisp.

Using elisp software, it is possible to use Emacs as your primary user interface to a computer system. Emacs' elisp packages make it possible to:

All this is done without leaving Emacs.