GumCalc Home ► Software ► GumCalc

Downloads

The first version of GumCalc was developed using Borland C++, but all the recent work has been done using Micro­soft Visual C++. The Visual C++ ver­sion pro­vides a bet­ter user inter­face and more fea­tures than the origi­nal ver­sion. The newer de­velop­ment sys­tem also pro­vides a more stand­ard ver­sion of the C++ lan­guage and stand­ard library.

The links below allow you to down­load an in­stall­er pack­age, Gum Calculator.msi, which will install GumCalc and re­quired files on your computer. The 2009 version has a couple of known bugs. The bugs in the 2011 (and now 2012) ver­sions, which were pro­duced using Visual Studio 2008 and Windows 7, are being eliminated as quickly as I find them (and likely being replaced by new bugs as I continue working).

Download 2009-09-06 version

Download 1.0 beta (2012-01-26)

If you don’t want to install GumCalc, or can’t, you can just copy the con­tents of this compressed folder to a folder of your choice and run the pro­gram from there. You may not be able to con­fig­ure the pro­gram com­plete­ly, but it should run and pro­duce results.

Please provide feedback if you find bugs. GumCalc has grown into a large, com­pli­cated project, and thor­ough test­ing has become more than one per­son can easily handle. There are many fea­tures large and small, and I am occa­sion­ally sur­prised by a bug in a fea­ture I sel­dom use or a bug that oc­curs only in an un­usual situ­ation. The cause may be noth­ing more than a typo or an over­looked line of code, but the effect may be a pro­gram crash.

What Is It? What Does It Do?

GumCalc is an auto­mated measurement-modeling tool. The most im­por­tant fea­ture, which makes it dif­fer­ent from most other cal­cu­la­tion tools, is its abil­ity to propa­gate meas­ure­ment un­cer­tainty auto­matically. A second un­usual fea­ture is its abil­ity to propa­gate the di­men­sions of meas­ur­able quan­tities. These two fea­tures together pro­vide the de­vel­oper’s ra­tion­ale for call­ing it a “measurement-modeling tool” rather than a cal­cu­lator program.

Note: Although GumCalc lets you create meas­ure­ment models, you can use it every day for calcu­la­tions and unit con­ver­sions with­out ever creat­ing a model at all. You just type an ex­pres­sion in the Evaluation win­dow and click a button to evalu­ate it. There is an op­tion to specify the unit of meas­ure­ment for the result.

The program allows you to specify a meas­ure­ment model as a collec­tion of def­ini­tions of vari­ables and func­tions. Each model may be saved in an elec­tronic file and re­opened and edited later. GumCalc also pro­vides a capa­bil­ity to “run” a model on im­ported sets of data, with the values of speci­fied vari­ables being obtained from im­port files in CSV format. When the model runs, it can also ex­port results to CSV files, which pre­sumably can then be up­loaded to other soft­ware sys­tems or even a LIMS.

Model variables come in four types:

• imported variables (whose values are ob­tained from CSV im­port files)
• text variables
• input quan­tities (or input estimates)
• output quan­tities (output estimates)

Measurement un­cer­tainty is intro­duced into a model via the in­put quan­tities. The user speci­fies the value and un­cer­tainty of an input quan­tity by speci­fy­ing a type of proba­bility dis­tribu­tion and the values of the param­eters of the dis­tribu­tion. When other results (out­put quan­tities) are cal­cu­lated from input quan­tities, they acquire un­cer­tainty too. The un­cer­tainty of an out­put quan­tity (com­bined stand­ard un­cer­tainty) is auto­matically deter­mined by un­cer­tainty propagation.

The creator of a model can define vari­ables and func­tions in any order, with­out worry­ing about the order of evalu­ation. The applica­tion itself deter­mines the evalu­ation order that is needed to obtain mean­ing­ful results. It is pos­sible for the model creator to create cir­cular def­initions, but GumCalc will detect any cir­cularity with­out enter­ing an in­finite recur­sion, which would crash the program.

Dimensions in GumCalc are built up from the seven base quan­tities of the Inter­national Sys­tem of Units (SI). The seven base units of the SI are “hard-coded” in the program, while all other units are defined in XML setup files. The unit pre­fixes of the SI are also hard-coded in the pro­gram, and the unit set­up files specify which units can be used with prefixes.

History

GumCalc is directly descended from a primi­tive DOS-based an­ces­tor called “LabCalc,” which I de­vel­oped at the USEPA National Air and Radia­tion Environ­mental Labo­ra­tory about 1994. I never enjoyed using elec­tronic spread­sheet pro­grams to auto­mate typical labo­ra­tory cal­cu­la­tions; so, I designed Lab­Calc to let the user de­fine a meas­ure­ment model by typing a set of equa­tions that de­fined vari­ables and func­tions, each identi­fied by name. A model could be de­vel­oped con­ceptually as a set of writ­ten equa­tions (e.g., in Word, Word­Perfect, or TEX) and then trans­lated easily into LabCalc’s lan­guage, one equa­tion at a time. Although LabCalc propa­gated un­cer­tainty auto­matically, it did not propa­gate the di­men­sions of quan­tities. It pro­vided some fea­tures for unit con­ver­sions, which were use­ful but hardly breath­taking.

Since LabCalc was DOS-based and command-line oriented, almost no­body but the de­vel­oper ever took ad­van­tage of its capabilities.

During the late 1990s I bor­rowed the con­cepts I had used to pro­vide auto­matic un­cer­tainty propa­ga­tion in Lab­Calc (a stand­alone appli­ca­tion), and created C++ li­brary classes and func­tions to allow other soft­ware sys­tems to propa­gate un­cer­tainty auto­matically. The classes were de­signed so that a pro­grammer could write code to cal­cu­late the result of a meas­ure­ment and let the library propa­gate un­cer­tainty in the back­ground. Eventually I pre­sented this library at the 2003 Radio­bioassay and Radio­chemi­cal Meas­ure­ments Con­ference (RRMC) in Jackson, WY, and made the source code avail­able for free down­load at this web site. (In 2007 the old code was removed from public view, because I had a newer, better implementation.)

For several years, while I was a mem­ber of the MARLAP work­group, Dr. Carl Gogolak, another work­group member, occasion­ally sug­gested that Lab­Calc be re­written as a Win­dows GUI appli­ca­tion, or that I de­velop a GUI appli­ca­tion to wrap around the class li­brary de­scribed at the RRMC. I agreed with Carl in prin­ciple, but I knew that either task would be less sim­ple than it sounded. From time to time, my boss, Dr. John Griggs, who chaired the MARLAP work­group, also said that new soft­ware would be needed to help radio­chem­istry labs implement MARLAP’s guid­ance. The MARLAP manual was finally approved and released in 2004; and in late 2004, I started the Gum­Calc proj­ect. Gum­Calc is in­tended to be what Lab­Calc always wanted to be when it grew up.

GumCalc began as a Windows XP project, although I’ve seen it run under Vista too. In early 2010, I acquired a Windows 7 computer (64-bit) and installed GumCalc on it with­out any obvious prob­lems. I’ve been running it on that computer ever since. Windows 7 has created some problems with the original loca­tion of the GumCalc library files, which may make them effectively read-only, but you can move the files to a new folder if you need to update them. The 2011/2012 versions install the library files in a folder of your choice.

In February and March 2011, I made the leap from 8-bit char­acters (char) to 16-bit char­acters (wchar_t). I prefer a serif font like Times New Roman when print­ing mathe­matical sym­bols, but the cur­rent ver­sion of that font in Windows does not pro­vide all the Unicode char­acters I want to use. So, for now at least, I am switch­ing to Arial Unicode MS for print­ing (2011-03-19). Some­time in the future I hope to pro­vide a better math font for the ordinary char­acters and use Arial Unicode MS only for special char­acters that may not print cor­rectly without it.

In October 2011, I made major changes in the date-parsing algo­rithms. The old parser was work­ing reliably but I was afraid to tinker with it because of its com­plexity — a con­sequence of rapid proto­typ­ing and the passage of time. So, I scrapped much of that code and re­placed it with some­thing that should be easier to main­tain. The new approach allows me to add more fea­tures, which I have done. The down­side is that more test­ing is needed to veri­fy that I haven’t broken some part of it.

Note: I’ve found one break so far, in an apparently un­related fea­ture that I don’t pro­mote and sel­dom use: the sub­script oper­ator for strings, vectors, and matrices. The bug was caused by an un­detected class naming con­flict and has been cor­rect­ed (2012-01-26 build).

In November and December 2011, I tried to make a final push to com­plete every­thing I had planned for ver­sion 1.0. (Yes, finally, after seven years of inter­mittent work on the project, and partly moti­vated by Ken Inn’s adver­tis­ing the pro­gram at the RRMC, I decided it was time to finish it.) The last re­quired but still miss­ing fea­ture had been a user inter­face for edit­ing the con­stant library. That inter­face now ex­ists (under Tools | Edit constants…). I also tried to fix a lot of the little annoy­ing things that had not been high priori­ties before. For example I hope that all the accel­er­ator keys now work in all the con­texts where users ex­pect them. I also couldn’t resist implement­ing some of the fea­tures that I had planned for later ver­sions of the pro­gram. The most sig­nificant of these is a pop-up list that appears as soon as you start typ­ing an identifier in an ex­pres­sion. The list con­tains all the cur­rent­ly avail­able con­stants, vari­ables, func­tions, and param­eters; and it high­lights the first one that matches the char­acters you have typed. When this pop-up list appears you can either keep typ­ing or just select the identi­fier you want from the list. A similar pop-up list of escape sequences for Unicode char­acters appears in most edit con­trols when you start typ­ing a sequence start­ing with an ampersand (&).

I tested the pop-up lists ex­tensive­ly in a couple of places in the pro­gram, barely tested them in a couple of others, and pub­lished the pro­gram here. I later found the fea­ture to be a nuisance as imple­mented in some of the envir­on­ments I hadn’t tested well, but the cur­rent build should cor­rect those problems.

For some time I had thought about providing “inline” uncertainty func­tions, which create in­put esti­mates in the middle of an ex­pres­sion without the need for a model. I thought it would be easy to do, but I focused on other things instead. In December 2011, I thought about this idea a little more and realized that for many would-be casual users, those in­line uncertainty func­tions would provide a lot of “bang for the buck” — i.e., a lot of bene­fit for them at the cost of very little effort on my part. So, the new­est ver­sion of the pro­gram pro­vides such func­tions (N, Rect, Tri, Trap, U, and Poi). To make it easier to build up large expres­sions using these func­tions, I increased the size of the Expression field in the Evaluation window. It is now a multi-line edit con­trol with a scroll­bar. A casual user might use this win­dow and noth­ing else in the program.

As always, new features probably mean new bugs, but since the new year (2012) began my focus has been on eliminat­ing bugs and polish­ing exist­ing fea­tures rather than add­ing new fea­tures. I am also work­ing to make the help sys­tem more complete.

Features

GumCalc now has all of the fea­tures en­visioned for version 1.0, including:

• automatic uncertainty propagation
• automatic propa­ga­tion of di­men­sions of quan­tities and easy con­ver­sion of units
• extensible library of pre­defined math­emati­cal and physi­cal con­stants (XML)
• built-in SI base units
• extensible library of SI de­rived units and off-system units (XML)
• experimentally deter­mined units (with un­cer­tainty), such as the elec­tron­volt and the uni­fied atomic mass unit (XML)
• handling of cor­re­la­tions be­tween model vari­ables and also be­tween the pre­defined con­stants and experimentally de­ter­mined units
• built-in library of stand­ard math­emati­cal functions
• dates and times, with pars­ing functions
• special func­tions for the radio­chem­istry laboratory
  • half-life — e.g., HalfLife("Co-60")
  • decay constant — e.g., lambda("Co-60")
  • decay factor — e.g., decay("Co-60", 160 {d}) or decay("Co-60", date("2008-07-15 12:00 CDT"))
  • specific activity — e.g., a("Co-60")
  • atomic mass — e.g., m("U-238") or m("U")
  • molecular mass — e.g., m("Sr(NO3)2")
• extensible set of prob­abil­ity dis­tribu­tions for defining input quan­tities (XML)
• a nuclide database, with half-lives, iso­topic abundances (not yet used), and atomic masses
• an element data­base, with atomic num­bers and rela­tive atomic masses (XML)
• vector and matrix operations
• data import and export (via CSV files)
• formatting options for results with uncertainty:
  • either stand­ard un­cer­tainty or ex­panded uncertainty
  • user’s choice of cover­age factor (k) for ex­panded uncertainties
  • parenthetical format for stand­ard un­cer­tain­ties; ± format for ex­panded uncertainties
  • automatic round­ing of un­cer­tain results, per rec­ommenda­tions of the GUM, MARLAP, ANSI N42.23, etc., with choice of the num­ber of fig­ures in the uncertainty
• uncertainty budgets
• automatic backups of model-definition files
• an online help system (never quite up-to-date or complete — sorry)
• labeled CSV formats for import (with named columns)
• ability to print each model in an attractive format
• time zone and format options for dates and times
• propa­ga­tion of time zones through date-time calculations
• an im­ple­men­ta­tion of “pre­ferred units” for calculated quantities, and propagation of preferred units through many calculations
• Celsius and Fahrenheit tempera­tures – not just tem­pera­ture differences
• most recent atomic weight data from IUPAC (2005, 2007)
• an XML version of the nuclide data­base, allow­ing users to up­date data and re­compile

Ideas for future work after ver­sion 1.0 include:

1. a slicker user inter­face, per­haps taking inspira­tion from the user inter­face of Visual Studio
2. default values for miss­ing im­port variables
3. Monte Carlo methods for propa­gating distributions
4. effective degrees of free­dom for com­bined uncertainties
5. XML formats for import­ing and ex­port­ing data
6. more reporting options
7. least-squares regression
8. use of the con­cept of the “type” of a meas­ur­able quan­tity, not just its dimension
9. a more sophis­ticated nuclide data­base with parent-child rela­tion­ships, allow­ing built-in func­tions for cal­cu­lating in­growth factors

I really want a better user inter­face (item 1), and I have some ideas for the design. Items 2–4 would also be nice to have.

Although it is listed last, provid­ing built-in func­tions to cal­cu­late in­growth fac­tors with un­cer­tainties is appeal­ing. The func­tions would prob­ably be called decayP and decayA, and they would cal­cu­late decay/ingrowth fac­tors based on prob­abil­ity (or atoms) and activ­ity, respectively. There would also be over­loaded ver­sions for aver­age decay and in­growth fac­tors during a count­ing inter­val. Note that a func­tion for cal­cu­lat­ing simple decay fac­tors (decay) is already included, since it does not re­quire a new database.

A few other user-friendly inter­face features will also be added. For example there will be a tool to search a model for oc­cur­rences of speci­fied identi­fiers or text strings. The current ver­sion already imple­ments mouse-over tool­tips for com­po­nents of math­emati­cal ex­pres­sions. It also matches pa­ren­the­ses and other group­ing sym­bols auto­mat­i­cally as you type (by color-high­light­ing both of the paired sym­bols) and by re­quest (by select­ing the match­ing sym­bol when you select one of a matched pair and type Ctrl-]).

I also intend to update many of the nuclide half-lives. You can wait for me to do it or you can do it yourself. I down­loaded a large file of nuclide data from the National Nuclear Data Center years ago and did not up­date it again. Only recently have I started manually updat­ing half-lives using data from Laboratoire National Henri Becquerel (www.nucleide.org).

Quirks

GumCalc has some aspects that may seem odd on first enc­ounter. Many of us are accus­tomed to per­form­ing a series of cal­cu­la­tions with num­bers, using math­ematical func­tions such as exp, log, or sin, with­out worry­ing about the units of meas­ure­ment till the final result is ob­tained. Since GumCalc propa­gates the di­men­sions of quan­tities step by step as it cal­cu­lates the results of these func­tions, it must en­force some restric­tions on the values of the arguments.

Since the dimen­sion of a quan­tity is a prod­uct of powers of the seven “base di­men­sions,” it makes sense to raise a quan­tity x to a power or take its square root, but it makes no metro­logical sense to say exp(x), log(x), or sin(x) un­less x is di­men­sion­less. This does not mean that x can­not be ex­pressed in some unit of meas­ure­ment, but the unit must be a di­men­sion­less unit, such as the radian, degree, or percent.

Similar observa­tions can be made about raising a quan­tity y to the power x. The ex­pres­sion y^x makes no sense unless x is dimension­less.

One may en­counter ex­pres­sions of this sort in the litera­ture, but they make sense only if the unit of meas­ure­ment is speci­fied. When an equa­tion is writ­ten in terms of the nu­meri­cal values of quan­tities rela­tive to speci­fied units, all the vari­ables in the equa­tion become di­men­sion­less and any­thing goes. GumCalc on the other hand allows one to write equa­tions in terms of the values of the quan­tities, not just the numerical values, and this fact requires one to be more careful. It also helps the soft­ware detect logical errors in the user’s work.

Looking at it another way, writing “y^x where x is the mass of the resi­due in milli­grams” is equiva­lent to writing “y^{x/(1 mg)} where x is the mass of the resi­due.” The lat­ter ver­sion makes it clear that the expo­nent is a di­men­sion­less ratio. It would be non­sensical to say “y^x where x is the mass of the resi­due” with­out speci­fying the unit of meas­ure­ment for x.

A second issue is the fact that Gum­Calc can­not dis­tin­guish be­tween dif­fer­ent types of quan­tities unless they have dif­fer­ent di­men­sions. For ex­ample, ac­tiv­ity, count rate, and fre­quency are three dif­fer­ent types of quan­tities and are usually ex­pressed in dif­fer­ent units. How­ever, since all three have the di­men­sion of re­cip­ro­cal time, T⁻¹, GumCalc can­not dis­tin­guish one type from the other, and it allows you to ex­press any of these quan­tities in any unit of meas­ure­ment that has the di­men­sion of re­cip­ro­cal time. For ex­ample, you can con­vert a fre­quency from hertz (Hz) to bec­que­rels (Bq), and GumCalc won’t de­tect the error. Of course GumCalc will not let you use a unit with the wrong di­men­sion for the quan­tity being expressed.

One other quirk exists because of the soft­ware’s need to com­pare di­men­sional ex­po­nents with­out round­ing error when add­ing or sub­tract­ing quan­tities. To elim­inate round­ing error, GumCalc re­quires that di­men­sional expo­nents be ra­tional num­bers, not floating-point num­bers. So, a quan­tity that is not di­men­sion­less can­not be raised to a power that isn’t ra­tional. There­fore, if the di­men­sion of x is not unity, you can evalu­ate x^3/5 but not x^0.6, be­cause GumCalc ob­tains a ra­tional value for the ex­pres­sion 3/5 and a floating-point value for the ex­pres­sion 0.6. With an en­hanced nu­mer­ic pars­ing func­tion, this limita­tion might be partially elim­inated, so that the pro­gram would recog­nize 0.6 as equiva­lent to 3/5, but the re­quire­ment that di­men­sional ex­po­nents be ra­tional is likely to remain.

The versions of GumCalc produced since 2010 pro­vide the abil­ity to in­clude arbitrary positive numerical fac­tors in a unit ex­pres­sion, allow­ing ex­pres­sions like pCi/100 cm2. I’m not sure how kosher this is, but it is a com­mon prac­tice when report­ing swipe meas­ure­ment results in the U.S. This fea­ture raises new ques­tions about the syn­tax of unit ex­pres­sions, since an ex­pres­sion of the form a2/3 b could reason­ably be inter­preted now as either a^2/3 b or a² / (3 b). The parser cur­rently uses the first of these inter­pre­ta­tions, but I recom­mend that you use paren­theses to eliminate any pos­sible ambi­guity (either a(2/3) b or a2/(3 b)).

Temperature Functions

In 2011, I implemented absolute temperatures in the pro­gram with a choice of tempera­ture scales. (Note that I have not imple­mented either “Celsius temperature” or “Fahrenheit tempera­ture” as a new type of quantity.) To specify an abso­lute tempera­ture, you can use any of the func­tions celsius, fahrenheit, kelvin, or rankine. Since these func­tions return abso­lute tempera­tures, some arith­metic opera­tions are un­defined on the results. The only opera­tions currently guaranteed to be pro­vided are certain types of addi­tion and subtrac­tion. Although it makes sense to mul­tiply or divide a tempera­ture by a numerical fac­tor, it may be con­fus­ing to many users. For example what result do you ex­pect if you type the ex­pres­sion celsius(4) * 2? Since celsius(4) is equivalent to kelvin(277.15), the cor­rect result is 554.3 K, or 281.15 °C, not 8 °C. I may decide that to avoid con­fu­sion, mul­tiplica­tion and division of these tempera­tures should not be allowed.

I’m also reconsider­ing the decision to have the celsius and fahrenheit func­tions return abso­lute tempera­tures instead of Celsius and Fahrenheit tempera­tures (rela­tive to 0 °C and 0 °F, respectively). The rationale for the original design is that it makes the results from all the new tempera­ture func­tions com­par­able, so that sub­trac­tion is easy and unit con­ver­sions make sense. The down­side is that there is a small but notice­able loss of pre­cision when ex­press­ing the results rela­tive to 0 °C or 0 °F. Because of this loss of pre­cision, the imple­men­ta­tion may change.

Units and Uncertainty

Combining auto­matic un­cer­tainty propa­ga­tion with “unit propa­ga­tion” re­veals rela­tion­ships be­tween the two that may not be ob­vious. In par­ticular, the un­cer­tainty of the result of a meas­ure­ment depends on the unit of meas­ure­ment. It should be clear that the numeri­cal value of the un­cer­tainty de­pends on the unit of meas­ure­ment, but in fact the ac­tual value of the un­cer­tainty de­pends on it too.

Why does the un­cer­tainty de­pend on the unit of meas­ure­ment? Because meas­ur­ing a quan­tity really means de­ter­min­ing the ratio of that quan­tity to another speci­fied quan­tity — the unit of meas­ure­ment — and the un­cer­tainty of that ratio depends on the unit. The value of the ratio may be known better for some units than others. For ex­am­ple, if you want the un­cer­tainty of the mass of the proto­type kilo­gram stand­ard, it mat­ters whether the value is ex­pressed in kilo­grams or uni­fied atomic mass units. If the unit is the kilo­gram, the un­cer­tainty is exactly zero. If the unit is the uni­fied atomic mass unit, the un­cer­tainty is posi­tive. Con­versely, the mass of an atom of carbon-12 in its ground state is known with no un­cer­tainty if it is ex­pressed in atomic mass units, but it has posi­tive un­cer­tainty if it is ex­pressed in kilo­grams.

Although the un­cer­tainty of a meas­ure­ment result depends on the unit, the inter­face that Gum­Calc pre­sents does not make this fact ob­vious, be­cause it pro­vides a func­tion u(x) that returns the stand­ard un­cer­tainty of the argu­ment x, and the unit of meas­ure­ment is not speci­fied. Gum­Calc can do this only be­cause it im­plicitly bases all quan­tities on the Inter­national Sys­tem of Units (SI), which pro­vides a frame of ref­er­ence in which the con­cept of the un­cer­tainty is un­ambiguous.

In GumCalc the ex­pres­sion u(x) re­turns u({x}) × [x], where [x] is the appro­priate SI unit for x (base unit or co­herent de­rived unit) and {x} is the nu­meri­cal value of x with re­spect to that unit. When you evalu­ate the ex­pres­sion x in the Evalu­ation win­dow, you can specify any appro­priate unit for the re­sult, and Gum­Calc will evalu­ate the un­cer­tainty prop­erly for the chosen unit. Note: The un­cer­tainty you get may dif­fer from what you would get by evalu­ating the ex­pres­sion u(x) with the same unit.

About the Icon

The GumCalc icon (a red-green-blue delta) has no sig­nifi­cance. It was de­signed only to be easily recog­nizable on the desktop.

Feedback

top

26 Jan 2012 Keith