ORIGEN API Documentation

Table of Contents

• For Users
• For Developers
• About Us

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.nosp@m.help.nosp@m.@ornl.nosp@m..gov for more information on obtaining the code.

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.

#include <iostream>
#include "Origen/Core/version.h"
int main()
{
    std::cout << "This ORIGEN API is version "<<
        Origen::version() << ".\n" << std::endl;
    std::cout << "Here is additional configuration information:\n";
    std::cout << Origen::config();
    return 0;
}

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.

#include <memory>
#include <sstream>

#include "Origen/Core/io/ReactionResourceIO.h"
#include "Origen/Core/version.h" /*version(), config()*/
#include "ScaleUtils/IO/Binary.h"

using namespace Origen;

namespace user
{

// inherit from the binary format reader
// and implement the methods to read/write your format from a stream
class MyIO_xyz : public ScaleUtils::IO::Binary<ReactionResource>
{
  public:
    // read an object from an istream
    bool read( ReactionResource& obj,
               std::istream& stream,
               ScaleUtils::IO::DB opts )
    {
        // insert actual code here and return false if failed
        return true;
    }

    // write an object to an ostream
    bool write( const ReactionResource& obj,
                std::ostream& stream,
                ScaleUtils::IO::DB opts )
    {
        // insert actual code here and return false if failed
        return true;
    }
};
}

int main()
{

    // either add as a default format (valid for any call anywhere)
    ReactionResourceIO::default_add(
        "xyz", ReactionResourceIO::SP_Format( new user::MyIO_xyz() ) );
    ReactionResourceIO rr_io;
    // or just add your formats to this specific instance
    // rr_io.add("xyz",SP_Format( new user::MyIO_xyz() ) );

    ReactionResource rr;

    ScaleUtils::IO::DB opts;
    rr_io.load( rr, "fake.txt", opts );
    std::cout << opts << std::endl;

    return 0;
}

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
  • dc - data containers
  • ut - utilities
  • io - I/O routines
  • ts - transition system
  • xf - interfaces
  • re - resources
  • fn - functions
• Solver
  • SolverSelector - choose solver
  • cram - CRAM solver
  • matrex - original ORIGEN solver
• Manager
  • emit - fortran particle emission
  • wrap - fortran wrappers
  • libld - library building (experimental)

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.