MANUAL

Chapter 1: Do not read this manual

Introduction

Didn't you read the chapter title? Do not read this manual!

You're not the kind to follow directions, are you?

Well, that's okay. The primary goal of Elves is to be so easy to use that you won't need any directions. In fact, I hightly recommend you try running, and talking to the Elves before you read any documentation. If you have any problems understanding what they say to you, or if they have any problems understanding what you say to them, please describe what happened in an email to James Holton. Elves is, after all, an interface between you and your programs, so any communication problems you have using Elves constitute a bug in the Elves interface. Please report bugs to James Holton, he will teach the Elves how to understand you.

Elves Philosophy

The Elves were founded on the principle that made the internet possible: "Be strict about what you send, and forgiving about what you recieve." Elves are the result of the "discovery" that ease of use is not just a luxury in x-ray crystallography, but vital for the correct, systematic, and rapid solution of macromolecular crystal structures.

Elves accept an unprecedentedly wide range of input from almost every possible source. Most common x-ray data file formats are supported, scripts for CCP4 programs can be read directly, or even plain-old English sentences and text files can be used as input to Elves. The "strict" part comes when Elves check with you about what they believe you want them to do. They will write a short, English paragraph about the procedure they intend to execute, and ask you for your approval. This "conversational user interface" was developed to acheive the absolute minimum number of keystrokes input by the user. This minimizes mistakes because human beings are much better at recognizing incorrect information that is presented to them than they are in conceiving and correctly entering all the information that x-ray data processing programs need.

Elves lack a graphical user interface, but, remarkably, they do not need one. GUIs still, unfortunately, require users to come up with all the correct parameter values for their experiment, and, in most cases, need to be "babysat", tying up a terminal while the program is running. Even the best GUIs still require a certain amount of training to learn how to use, and they are still not portable from platform-to-platform. The only "interface" that requires no training, but is flexible enough to describe any x-ray experiment is the user's native language (usually English). A great deal of effort has been put into "porting" English, as an interface in the context of x-ray crystallography into Elves. In the future, Elves may be made to understand spoken English as well.

Elves are also intended to be as widely available as possible. For this reason, they were implementted entirely in csh, which, although an incredibly slow "language" is still (along with its big brother: tcsh) the most popular login shell used by x-ray crystallographers. The slow speed of csh has almost no impact on the speed of Elves, since they spend more than 99% of their time running third-party, compiled binary programs (which are mostly written in FORTRAN, and can't get much faster). The advantage of being written in csh is that Elves are trans-portable to, conceivably, every unix platform. without even the need for a compiler, as a single, universal text file. The Elves "source code" is, therefore, openly readable. Also, because the Elves script is self-configuring, there is no set-up required to use Elves. The script is simply run with plain-English instructions on the command line.

Also for reasons of availability, the third-party software required by Elves are, themselves, widely available and free of charge to academic and not-for-profit users. CCP4 and mosflm are the only programs required to be installed for Elves to work. CCP4 can be difficult for a novice user to configure and compile, but is such a staple of x-ray crystallographers everywhere, that it is, hopefully, not too much to ask of Elves users to have a working copy of CCP4. Elves can also take advantage of shelx, wARP, and the "not free" programs denzo, and solve, but they do not need them.

Elves Credo: The rules that Elves live by

1. Do not waste the user's time.
• All of the following directives stem from this one. Elves were created on the principle that a human's time is valuable, and a computer's time is not. Every aspect of the Elves construction is designed to minimize the expenditure of the human operators time as much as possible. After all, humans have better things to do.
2. Don't ask stupid questions.
• Elves will never ask their user for a peice of information that they can obtain on their own. Requiring users to specifically enter every important parameter into every procedure is one way of being sure that these parameters are correct. However, Elves have a different philosophy. Instead of relying on their user to declare all the correct parameters, Elves only require a user to verify that the parameters obtained by Elves are correct. This saves an enormous amount of keystrokes.
3. Don't babble.
• For a typical structure solution, the programs run by Elves produce about 20 megabytes of logfile text, all of which is organized, and saved to disk for the user to review. However, no human being can read that mutch text in the time allotted to a typical synchrotron visit. Therefore, on the terminal where Elves are launched, they only display information that is likely to be immediately important. Every effort has been made to make sure Elves never give a user more than a screenful of text to read at a time.
4. Never give up.
• Scripted, overnight runs involving many different peices of software have an uncanny way of crashing a few minutes after their author goes home for the night. Elves, therefore, take on a strategy of perseverance. If a program crashes, they set to work on getting it to run. If important information is missing, they go looking for it. If a program they need is missing, they'll go look for it. Once again, Elves rely on their user to verify their work after it is done, and not, necessarily, have the correct instructions for them at the beginning.
5. When in doubt, guess.
• Elves operate under the assumption that omission implies indifference. If you tell Elves to calculate a map from a phased mtz file, and you didn't specify which of several F and PHI columns that are available in that file, then Elves will assume you don't care which, and pick one on their own. Elves base this decision on the resolution, completeness, and signal/noise of each possible data set. This "guessing" on behalf of Elves saves a tremendous amount of typing.
6. Bring your own lunch
• Elves strive to be minimally dependent on third-party software. This includes compilers, which can be expensive on some systems. For these reasons, they use the universally available interpreted "languages" csh and awk. The only non-standard unix programs they need are mosflm and ccp4. Most crystallography labs should at least have these installed, but if you don't, Elves can try to download and/or compile them for you.
7. Don't say you're done unless you really are.
• Elves are very fastidious about convergence. Unless you tell them to "hurry" (by typing the word "hurry" on their command line), they will keep re-running the program they are working with until they get the same refined parameters out of a program that they put into it. (In cases where parameters oscillation is known to be problematic, the Elves will check for it too). Then, and only then, will Elves declare a program's input script to be "optimized".

Back to the Elves Manual Table of Contents.