GumCalc Home ► Software ► GumCalc

Borland C++ Version

To install the measurement-modeling soft­ware (GumCalc, Borland C++ version) on your Windows-based computer:

1. Right-click the link below and down­load the file GumCalc.zip to a folder of your choice.
2. If you’re running Windows XP or later, you can usually just open GumCalc.zip on your com­puter as if it were an or­di­nary folder.
3. Run the in­stal­la­tion pro­gram, install.exe (e.g., by double-clicking it).

Gen­er­ally you can accept the default answers in the in­stal­la­tion pro­gram. You should not need admin­istrator privi­leges to per­form the in­stallation.

The Borland C++ version of Gum­Calc is no longer main­tained or updated.

Download Borland C++ version (updated 2005-10-17)

Microsoft Visual C++ Version

The more recent work on Gum­Calc 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 Gum­Calc and re­quired files on your computer. The 2009 version has a couple of known minor bugs. The bugs in the 2010 version (produced using Visual Studio 2008 and Windows 7) are still unknown.

 Download Microsoft Visual C++ version (2009-09-06 build)
 Download Microsoft Visual C++ version (2010-06-29 build)

GumCalc began as a Windows XP project, although I’ve seen it run under Vista too. I only recently acquired a Windows 7 computer (64-bit). I installed GumCalc on it with­out any obvious prob­lems and now I’m main­tain­ing it there, but I can’t yet promise that there are no issues at all.

The 2010 version pro­vides 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)).

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.

The program allows the user to specify a meas­ure­ment model as a collec­tion of def­ini­tions of vari­ables and functions. 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 was de­vel­oped at the USEPA National Air and Radia­tion Environ­mental Labo­ra­tory about 1994. Keith never enjoyed using elec­tronic spread­sheet pro­grams to auto­mate typical labo­ra­tory cal­cu­la­tions; so, he 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 Keith bor­rowed the con­cepts he 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 this library was pre­sented at the 2003 Radio­bioassay and Radio­chemi­cal Meas­ure­ments Con­ference (RRMC) in Jackson, WY, and the source code was made avail­able for free down­load at this web site. (In 2007 the old code was removed from public view, because Keith had a newer, better implementation.)

For several years, while Keith 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 Keith de­velop a GUI appli­ca­tion to wrap around the class li­brary de­scribed at the RRMC. Keith agreed with Carl in prin­ciple, but he knew that either task would be less sim­ple than it sounded. From time to time, Keith’s 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 Keith started the Gum­Calc proj­ect. Gum­Calc is in­tended to be what Lab­Calc always wanted to be when it grew up.

Features

GumCalc is still a work in prog­ress, but it has many of the fea­tures en­visioned, 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")
  • 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)

Features available only in the Visual C++ version:

• more than one export template
• labeled CSV formats for import (with named columns)
• ability to print each model in an attractive format – not just “export to text”
• propa­ga­tion of time zones through date-time calculations
• more flex­ible for­mat speci­fi­ca­tions for dates and times
• more options for dis­play­ing dates and times – not just UTC
• more com­plete im­ple­men­ta­tion of “pre­ferred units”
• 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 include:

• Celsius and Fahrenheit tempera­tures – not just tem­pera­ture differences
• user inter­face for edit­ing the con­stant library
• default values for miss­ing im­port variables
• a small change in the syntax for iterated sums and products
• Monte Carlo methods for propa­gating distributions
• effective degrees of free­dom for com­bined uncertainties
• XML formats for import­ing and ex­port­ing data
• more reporting options
• least-squares regression
• use of the con­cept of the “type” of a meas­ur­able quan­tity, not just its dimension
• 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

The first four of these items are likely to be imple­mented first. When these four fea­tures are in place and the sys­tem has been rigor­ously tested, GumCalc might be con­sidered to be fully opera­tional. On the other hand the next two items (Monte Carlo and ef­fec­tive de­grees of free­dom) seem im­por­tant too, and they might be im­ple­mented to­gether with the first four.

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 interval.

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 Gum­Calc won’t de­tect the error. Of course Gum­Calc 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 Gum­Calc 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.

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

25 Apr 2010 Keith