Readme: XMolCalc-1.0 by mkhd; 1999
Part I: The Program Part II: Installation/Requirements Part III: Distribution/Comments/Disclaimer
Part I: The Program
- What's the program doin'?
Type a molecular formula into the entry widget and hit <return> or press the "mass" button to get the molecular weight of the compound. Pretty simple, looks cool and is handy. It does accept all 104 elements, but no isotopes. There is an upper limit of 9999 for the indexes allowed.
- Why such a thing?
Well, as a chemist I always missed such a utility that allows you to calculate a molecular weight under Unix/X. Of course there are huge packages out there that include such subroutines but I never saw a small program doing that without a lot else. This is intended to be the chemists version of the X desktop calculator. For me it was an experience writing a program. The book "Practical C-Programming" by Steve Oualline (third ed.) solely enabled me to write the C part; it's unbelievably great!
- What's good about it?
It's customizable and transparent; read below "How to customize it". I included a lot of comments (for myself), so this helps to understand how the program works (it's very simple anyway).
- Explanation of the program and the files provided in the archive:
The core is an executable named "masscalc", which is actually the
string digesting engine written in plain C. The files masscalc.c,
mfunct.c, mproc.c, makefile and elements.h belong to this part.
The file mfunct.c consists of seven functions that are scanning the
input string for several kinds of entries. If found, the mass fragment
is calculated, kept in mind, and the portion (e.g. Cl2) is removed
from the string until nothing's left. So it works like a bundle of
filters; remainders give errors! All functions together form
a bigger one called process_mass, as defined in mproc.c. There also
the conditionals are hidden.
To get a graphical user interface the most easy was to modify the
masscalc routine to read an input string from a temporary file mass.tmp
(will be created), then calculate the mass, and put back the result
into this temp file. Now the result will be read from the file and
displayed in a result widget. When <return> or the <mass> button is hit,
masscalc is executed. I think now it's clear: The *.tcl files are simply
front-ends to the masscalc executable. They are written in tcl/tk and
where mostly generated with GUI builders (read the makefile).
acid.xbm Icon chemistry.gif Background GIF displayed in xmolcalc.tcl interface elements.h List of elemental masses install.sh My installation script (requires root; see below) makefile Well, the makefile for masscalc and some cosmetics masscalc.c The most upperlevel file of the calculation engine mfunct.c Here all the basic functions are prototyped/declared mproc.c Puts one big function together to do the calculation xmolcalc.tcl Interface file made with vtcl (uses the .gif file) xmolcalc.ui.tcl Interface file made with SpecTcl (more simple)
Note for chemists:
Chemistry.gif shows a retrosynthetic analysis of lysergic acid; this
was part of my recent research project and is published in
Journal of Organic Chemistry, 64 (4),1372-1374; 1999.
- How to hack it"
To adjust the elemental masses open elements.h with your editor and correct the values there. Be aware that the values are the actual elemental masses x 100! If you want more digits: Open the masscalc.c file and change the line "fprintf(out_file, "%.2f MU", M_compound);" Here, number 2 tells that you want to display 2 digits. For five digits put a 5 there. Definitely you'll have to recompile. To get your own background GIF, name it "chemistry.gif" and exchange the gifs then (only the xmolcalc.tcl interface file displays it).
Interface customizations:
I was using vtcl and SpecTcl to build a basic interface, then I added
more functions. The *.ui.tcl file is very simple, however it resizes
the result window automatically to display (not very reasonable) large
numbers. It cannot be reopened with the generator SpecTcl.
The luxurious *.tcl file was made with vtcl and can be opened again by
vtcl allowing you to do a lot to it. Make your choice in the makefile
(there is a lot of info too). Max length for the input line is 20. You
can set it to 50 in the makefile or you can modify it totally by changing
the value MAXLENGTH in masscalc.c.
- Different versions available
First a general assumption: Think of the formula C3H8SNBCl3; now write it in small letters c3h8snbcl3. If you want to allow the omission of 1 as index, then you must use correct cases. Or, if you want to use small and capital letters, then you must use also 1 for index (e.g. c2H5o1h1). How should the program know what snb should be? Sn+B, or S+N+B, or S+Nb? There are two versions to choose from in the makefile. The CASE_NO_INDEX_DUTY version (DEFAULT) allows C2H5OH for ethanol. Two-char elements like Cl, Sm.. are allowed only as Cl, Sm. If not so you'll get an error. The same applies to C, H, N....only capitals are fine. The NO_CASE_INDEX_DUTY verions allows c2h5o1h1 and C2H5O1H1. Here for the two-char elements like Sm..., Sm and sm are accepted. But index '1' is required. Make your choice in the makefile. Bad input will result in an error rather then a wrong number. At least I hope :-).
Part II: Installation/Requirements
- Porting information
This program was developed on a PowerMac 8500/150 MHz, running Power
MachTen 4.3CU1 from Tenon Intersystems and later on my SGI Indy XZ with
R5K and IRIX 6.5.2. (yeah, I'm soooo proud). It further compiled on:
SGI O2 with R5K running IRIX 6.3;
SGI Indigo2 with R10K running 6.2;
RISC System/6000 running AIX Version 4;
SunOS 5.6 and LINUX 2.0.35 (S.u.S.E.).
- Installation
######################################################################### You need Tcl/Tk8.0.x. You can get it from http://www.scriptics.com. ######################################################################### You possibly have to correct the path for the wish executable in the interface *.tcl files; currently the default is /usr/local/bin/wish. This is the very first line in the *.tcl files - Don't be afraid to open them. If you have wish in $HOME/tcl8.0/bin, put $HOME/tcl8.0/bin/wish there. ######################################################################### If you freshly install tcl/tk, make sure you have a link named "wish", that points to the wish8.0 file, which is the actual executable in the tcl/tk distribution. Same applies for tk, analogously. On the other hand you can, of course, call wish8.0 instead of wish in the above *tcl files.
After unpacking, open the makefile and customize it if you want; enter the
XMolCalc-1.0 directory and type "make". Now it will proceed all alone.
To use gcc instead of cc, change the makefile. As long as you are not
root or don't want to install it, you may just execute it inside the
XMolCalc-1.0 directory by typing XMolCalc or ./XMolCalc. That way you are
done now.
XMolCalc is actually only a link generated by the makefile. It points to
the interface file you've selected in the makefile. If you want to install
it, type "make install" now. The default dirs for the installation are
/usr/local/bin and /usr/local. The first dir will receive a new file xmol
that is a script to execute the actual program that is in
/usr/local/XMolCalc-1.0.In other words, if you installed it, you may just
type xmol somewhere to execute it as long as /usr/local/bin is in your path.
In case you were doing changes and want to recompile it again, or decide
to try the "other version", type "make new".
The install.sh is pretty save I think. If you're not root, it exits and
tells you about. It also writes to the screen what it does!
Part III: Distribution/Comments/Disclaimer
This is freeware! However, I look at it as my property! If you modify it for the outer world, ask me before. Please feel free to give this program away; I love the idea that it might get included in CD ROMs even - great - but: Send me a note about and include all of the files here, also this Readme. If not so, I'll get mad if I see it! No warranty either expressed or implied. Whatever this program does to your machine or your life or something else, it's not my reliability - in no way!!!!!!!! No warranty at all - for nothing! blah blah....
If you like it, please send me a postcard. This will motivate me to continue writing such small utilities. If you want to exaggerate: Send me a bottle of beer from your country: That's what it usually took to keep me going on programming this (as a total newbee to C and so on) :-)
Dr. Martin K.-H. Doll
Organisch Chemisches Institut der Universitaet Zurich
Winterthurerstrasse 190
CH-8057 Zurich
Switzerland
Enjoy,
Martin Doll, Ph.D.; Zurich, March 1999.
Permanent e-mail address: mkhd@omni.cc.purdue.edu