Table of Contents
The ORIGEN API is an Application Programmer's Interface (API) to ORIGEN (Oak Ridge Isotope GENeration), a general purpose transmutation code developed at Oak Ridge National Laboratory. It provides a set of classes in C++/Fortran for performing depletion and decay calculations with the central model equation given by the system of ODEs
\[ \frac{d \vec{n}}{dt} = \mathbf{A}\vec{n}(t)+\vec{F}(t) \]
where \( \vec{n} \) is an isotopic vector, and \( \mathbf{A} \) is a transition matrix, and \( \vec{F} \) is a "feed" term. The ORIGEN API can also be used to
- access fundamental data sources (such as decay constants, molar masses, radiotoxicity factors, decay heat, and more),
- calculate particle emission spectra and source strengths,
- build hierarchical compositions, and
- perform unit conversions.
See the Changelog for version information.
For Users
The ORIGEN API is distributed with SCALE, which may be obtained through RSICC. Contact scale for more information on obtaining the code. help @ornl .gov
Building the API
The ORIGEN API is callable from both C++ and Fortran. The C++ API may be straightforwardly used from any SCALE installation. However, the Fortran API requires Fortran module files compiled with the Fortran compiler you will build your code with. For this reason, in order to use the Fortran API, you must have access to SCALE/ORIGEN source and build SCALE alongside your project.
There are other reasons to configure and build your own ORIGEN API libraries. SCALE/ORIGEN uses CMake to manage configuring and building on the three major platforms: Linux, Mac, and Windows. With a system meeting the prerequisites, building the code is as simple as cmake $SCALE_SOURCE_DIR && make -j4 install
, assuming a Linux command line. However, there are a few other cmake
options that can be handy.
Configuration Details
I like to make my build directories in a subdirectory of the source directory called build
. I typically have two builds, a release and a debug, located at $SCALE_SOURCE_DIR/build/release
and $SCALE_SOURCE_DIR/build/debug
. I then create a file called do-config.sh
with everything I need to configure for a particular build. Then I install to the subdirectory INSTALL
within a specific build directory. Here is a minimal do-config.sh
file which would build static release libraries of the ORIGEN API.
Release/Static do-config.sh
#Release/Static Configuration# #ensure that cache is blown away each time rm -rf CMake* #example of scale data directory, source directory, and install directory export SCALE_DATA_DIR=$PWD/../../data export SCALE_SOURCE_DIR=$PWD/../../ export INSTALL_DIR=$PWD/INSTALL #cmake command using QUICKBUILD_ORIGEN_API cmake -D CMAKE_BUILD_TYPE:STRING=RELEASE \ -D SCALE_DATA_DIR:FILEPATH="$SCALE_DATA_DIR" \ -D CMAKE_INSTALL_PREFIX:FILEPATH="$INSTALL_DIR" \ -D QUICKBUILD_ORIGEN_API:BOOL=ON \ -D BUILD_SHARED_LIBS:BOOL=OFF \ $SCALE_SOURCE_DIR
I do my development on Linux, and I source the configuration file, source do-config.sh && make -j4 install
. If tests are enabled, then you can add a ctest -j4
on the end to test the build.
The main thing to notice is the QUICKBUILD_ORIGEN_API
flag. This flag is special and can only be used for the purpose of building the ORIGEN API. The main additional options you may need are the following.
- enable/disable tests (SCALE_ENABLE_TESTS:BOOL=OFF)
- enable/disable Design By Contract (NEMESIS_DBC=0)
- control whether static or shared libraries are built (BUILD_SHARED_LIBS:BOOL=OFF)
- enable debugging output (DEBUG_OUTPUT=0)
Debug/Shared do-config.sh
To build debug libraries, I use the following config script.
#Debug/Shared Configuration# #ensure that cache is blown away each time rm -rf CMake* #example of scale data directory, source directory, and install directory export SCALE_DATA_DIR=$PWD/../../data export SCALE_SOURCE_DIR=$PWD/../../ export INSTALL_DIR=$PWD/INSTALL cmake -D CMAKE_BUILD_TYPE:STRING=DEBUG \ -D SCALE_DATA_DIR:FILEPATH="$SCALE_DATA_DIR" \ -D CMAKE_INSTALL_PREFIX:FILEPATH="$INSTALL_DIR" \ -D SCALE_ENABLE_TESTS:BOOL=ON \ -D NEMESIS_DBC=7 \ -D DEBUG_OUTPUT=0 \ -D BUILD_SHARED_LIBS:BOOL=ON \ -D QUICKBUILD_ORIGEN_API:BOOL=ON \ $SCALE_SOURCE_DIR
Setting DEBUG_OUTPUT=1
can give you a lot of additional output but it can be difficult figuring out where it is coming from. With tests enabled, you can run them all with ctest -j4
.
Build time is currently about 30 cpu-minutes. So -j4
really helps it take a coffee break versus a lunch break.
Linking
The ORIGEN API includes 3 libraries which you can link to.
- libOrigenCore: core classes (data containers and interfaces)
- libOrigenSolvers: CRAM and MATREX solvers
- libOrigenManager: additional top level methods
If you build static libraries, then you will be able to link relatively easily. The following C++ main may be used to test linking to libOrigenCore.
Using the GNU compilers, and assuming we are in the root of the build directory, the following command builds your executable.
g++ -std=c++11 -I $INSTALL_DIR/include \ $INSTALL_DIR/lib/libOrigenCore.a origen_api_version.cpp ./a.out
Note that C++11 is required. If you have shared libraries, then a considerable larger set of libraries is required, ordered from highest to lowest dependency level in the heirarchy. The output will look something like this.
This ORIGEN API is version 0.5.2. Here is additional configuration information: scale_version 6.3 origen_api_version 0.5.2 build_type RELEASE build_shared_libs OFF release_category BETA dbc_level 0 commit_hash 48e90437a818+ commit_date 2016-08-28 19:27 -0400
For a more sophisticated executable (still static) just list all the libraries.
touch fake.txt g++ -std=c++11 \ -L /opt/local/libexec/qt4/lib -llapack -lblas -lQtCore \ -I $INSTALL_DIR/include $INSTALL_DIR/lib/*.a example_new_data_type.cpp ./a.out
Note that in most cases you must supply the library path for QtCore. This main demonstrates how to add a new ORIGEN data type.
You should see the following JSON output indicating the fake file was processed correctly.
{ "bool(fileExists)" : true, "string(directory)" : ".", "string(fileName)" : "fake.txt", "string(loadedFileFormat)" : "xyz", "string(loadedFileType)" : "binary" }
For Developers
The ORIGEN API is organized into 3 main subpackages for the Core, Solver, Manager. The backbone of the API is written in C++, with special Fortran bindings developed for the most important features. One is produced for each subpackage. If Fortran is enabled, the Fortran libraries have an _f
appended at the end.
Each subpackage directory is further organized into subdirectories.
- Core
- Solver
- SolverSelector - choose solver
- cram - CRAM solver
- matrex - original ORIGEN solver
- Manager
Scattered throughout are subdirectories called "f", "c", "tests", and "examples" which contain CIX Fortran binding files, C interface files, tests, and examples, respectively.
About Us
The ORIGEN API has been developed by the ORIGEN team at ORNL, including contributions from
- William A. Wieselquist (project lead & general development)
- Steve Skutnik (general development)
- Shane Hart (./Tester subpackage)
- Aarno Isotalo (./Solver/cram subpackage)
- Frantisek Havluj (initial ./Core & other infrastructure)
- Gokhan Yesilyurt (early development)
- Ian Gauld (data & advising)
- Mark Williams (advising)
- Doro Wiarda (data & advising)
The ORIGEN API is used in
- SCALE 6.2 Polaris and Triton sequences for all depletion calculations,
- in the MPACT CASL Core Simulator for full-core, pin-resolved LWR depletion, and
- voxel-based activation of ITER components to calculated shutdown dose rate analysis through ADVANTG.