Repository files navigation

Simple, fast, and versatile C++ library to perform nuclear decay calculations, retrieve nuclide information, and compute decay products.

ENSDF provides a wealth of raw nuclear information, theBateman equations are well known, but tasks such as determining what gammas will be produced, or the activities of child products from a 20 year old sample of 226-Ra, can still be formidable.SandiaDecay makes performing calculations like these easy.

An example of using this library to perform these calculations is:

#include"SandiaDecay.h"...//Initialize the database from the XML file that has all the nuclear infoSandiaDecay::SandiaDecayDataBasedatabase("sandia.decay.xml" );//Get pointer to Ra226. "Ra226", "Ra-226", "226Ra", etc are all equiv.const SandiaDecay::Nuclide *const ra226 = database.nuclide("Ra226" );//Use a SandiaDecay::NuclideMixture object to perform the decaySandiaDecay::NuclideMixture mixture;//Add 1 mCi of Ra226 to the mixturemixture.addNuclideByActivity( ra226,0.001*SandiaDecay::curie );//Get activities of Ra226 and all of its descendants after 20 years of agingvector<SandiaDecay::NuclideActivityPair> activities = mixture.activity(20*SandiaDecay::year );for(size_t i =0; i < activities.size(); ++i )  cout << activities[i].nuclide->symbol <<" has activity"       << activities[i].activity/SandiaDecay::curie <<" curies\n";//Get all of the x-rays and gammas the sample would producevector<SandiaDecay::EnergyRatePair> photons = mixture.photons(20*SandiaDecay::year,                                                      SandiaDecay::NuclideMixture::OrderByEnergy );for(size_t i =0; i < photons.size(); ++i )  cout << photons[i].numPerSecond <<","       << photons[i].energy <<" keV photons/second\n";

See thesandia_decay_example.cpp file for more examples of things you can do with this library.

SandiaDecay was developed as part ofInterSpec, but has since proven useful in a number of other applications.

If all you care about is performing decay calculations, grab a copy ofInterSpec and open up itsNuclide Decay Info tool from theTools menu. This will let you perform many types of decay calculations, visualize decay chains, and export activities or decay products to CSVs.

If you would like to do complex or specialized calculations, or you want to add nuclide decay capabilities to your application, you will need to compile and link to this library.

The only dependancies required to compile arerapidxml (which is included in the repository), and a C++≥03 compiler. There is aCMake based build file included, but because there are no configurations and the library only consists of a single header and source file, it should be simple to integrate in with your program no matter the build system you use.

To include this library with a CMake based project, just add the following to your CmakeLists.txt file:

add_subdirectory(path/to/SandiaDecay )...target_link_libraries( MyExePRIVATE SandiaDecay )

Or to compile and run the example use code:

cd /path/to/SandiaDecaymkdir build;cd buildcmake ..make./examples/sandia_decay_example ../sandia.decay.xml

Or if you're on a UNIX system you could compile the example-use code using a simple command like:

g++ -I. -I3rdparty SandiaDecay.cpp ./examples/sandia_decay_example.cpp -o example.exe

On a 2017 macbook pro it takes about 100 ms to to initialize the aSandiaDecayDataBase object usingsandia.decay.nocoinc.min.xml, or about 225 ms usingsandia.decay.xml, with the differences between the XML files being how human readable they are and the former not including gamma coincidence information (to save file size).On average it takes about 200 μs to calculate a nuclides decay equations, which only needs to be done once for every nuclide you are interested in, and then about 20 μs to evaluate the decay equations and determine the decay product or activities for given time.ASandiaDecayDataBase object allocates about 10 MB of memory during initialization. After initialization all operations areconst operations, meaning a singleSandiaDecayDataBase can be used in multiple threads without issues; no global variables are used, and except during construction of aSandiaDecayDataBase object, no files are accessed.

Source data insandia.decay.xml is originally based on theENSDF datasheets, with further corrections manually applied to compensate for parsing issues, or discrepencies in observed data by users of this library.

Parsing the ENSDF datasheets is a challenge, so there are almost certainly mistakes or bugs insandia.decay.xml, and so the values returned by this library should not be considered definitive. If you do find any issues, please emailwcjohns@sandia.gov orinterspec@sandia.gov.

Will Johnson (wcjohns@sandia.gov orinterspec@sandia.gov).

Code is written by Will Johnson (SNL), withsandia.decay.xmlprepared by John Mattingly (now NCSU), Steve Horne (SNL), Greg Thoreson (SNL), Will Johnson, and others.

The source code for this project is licensed under the LGPL v2.1 License - see theLICENSE.md file for details

Copyright 2018 National Technology & Engineering Solutions of Sandia, LLC (NTESS).Under the terms of Contract DE-NA0003525 with NTESS, the U.S. Government retains certain rights in this software.

DISCLAIMER OF LIABILITY NOTICE:The United States Government shall not be liable or responsible for any maintenance,updating or for correction of any errors in the SOFTWARE or subsequent approved versionreleases.THE INTERSPEC (SOFTWARE) AND ANY OF ITS SUBSEQUENT VERSIONRELEASES, SOFTWARE IS PROVIDED "AS IS" WITHOUT ANY WARRANTY OFANY KIND, EITHER EXPRESSED, IMPLIED, OR STATUTORY, INCLUDING, BUTNOT LIMITED TO, ANY WARRANTY THAT THE SOFTWARE WILL CONFORM TOSPECIFICATIONS, ANY IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESSFOR A PARTICULAR PURPOSE, OR FREEDOM FROM INFRINGEMENT, ANYWARRANTY THAT THE SOFTWARE WILL BE ERROR FREE, OR ANY WARRANTYTHAT THE DOCUMENTATION, IF PROVIDED, WILL CONFORM TO THESOFTWARE. IN NO EVENT SHALL THE UNITED STATES GOVERNMENT OR ITSCONTRACTORS OR SUBCONTRACTORS BE LIABLE FOR ANY DAMAGES,INCLUDING, BUT NOT LIMITED TO, DIRECT, INDIRECT, SPECIAL ORCONSEQUENTIAL DAMAGES, ARISING OUT OF, RESULTING FROM, OR IN ANYWAY CONNECTED WITH THE SOFTWARE OR ANY OTHER PROVIDEDDOCUMENTATION, WHETHER OR NOT BASED UPON WARRANTY, CONTRACT,TORT, OR OTHERWISE, WHETHER OR NOT INJURY WAS SUSTAINED BYPERSONS OR PROPERTY OR OTHERWISE, AND WHETHER OR NOT LOSS WASSUSTAINED FROM, OR AROSE OUT OF THE RESULT OF, OR USE OF, THESOFTWARE OR ANY PROVIDED DOCUMENTATION. THE UNITED STATESGOVERNMENT DISCLAIMS ALL WARRANTIES AND LIABILITIES REGARDINGTHIRD PARTY SOFTWARE, IF PRESENT IN THE SOFTWARE, AND DISTRIBUTESIT "AS IS."

This InterSpec Software was developed with funds from the Science and Technology Directorate of the Department of Homeland Security.

InterSpec SCR# 2173.1