5.2. OBIWAN: A tool for viewing and manipulating Origen binary files

S. E. Skutnik and W. A. Wieselquist

OBIWAN ( Origen Binary Interrogation Without A scale iNput) is a command-line utility for viewing, manipulating, and converting ORIGEN binary output files.

OBIWAN can be called directly from the command line, from ${SCALE}/bin/obiwan; in addition, it can be called within a SCALE input within a =shell block, i.e.:

Example 5.2.1 An OBIWAN command within a shell block

 =shell
 ${PGMDIR}/obiwan [command] [file(s)]
 end
 ...

OBIWAN supports the following modes:

convert convert between versions of files

diff diff/compare two files

info print basic info about multiple files

interp interpolate files

patch patch data in files

tag manipulate tags on a file

view view a file

Each of these methods (including supported capabilities and syntax) are discussed in the following sections. OBIWAN also emits command-line help if you run it without any files/arguments.

5.2.1. obiwan info

Displays information about an on-disk binary Origen file.

Usage: obiwan info [-type=TYPE] FILE

-type [f33 / hdf5 / f71 / yld ]

Optionally specify OBIWAN to load only a particular file type

Options are:

f33: Origen::Library
hdf5: Origen::Archive
f71: Origen::StateSet
yld: Origen::YieldResource

By default, OBIWAN will attempt to infer the filetype by trial-and-error

-verbose: Verbose mode; prints extra output to STDERR

Table 5.2.1 File information output by `obiwan info`
Column	Description
fileName	path without the directory
dataType	type/class of the object
numSets	number of “sets” of data (e.g. burnups)
fileFormat	the format of the dataType in this file
fileType	“binary” or “text”
file/sysEndian	endian-ness for the file itself and the system (mismatches have I/O performance penalties)
appVersion	version of the application which wrote this file (some formats cannot store this and it appears as “-“)
ms	time in milliseconds to load the file
directory	directory portion of path

5.2.2. obiwan view

Displays detailed contents of ORIGEN results and data files.

Usage: obiwan view [-type=TYPE -format=FORMAT options] FILE

The -type=TYPE flag tells the loader to assume a data type for FILE. If not provided, trial and error is used.

-type [f33 / hdf5 / f71 / yld ]

f33: Origen::Library
hdf5: Origen::Archive
f71: Origen::StateSet
yld: Origen::YieldResource

The -format=FORMAT flag tells the printer to output data a certain way. If not provided, specific to the type of data.

5.2.2.1. Output formatting

obiwan view offers several options for formatting output which are specific to the file type being viewed (i.e., corresponding to obiwan view -type); these are discussed further within this section.

Note

All types and formats do not support all options.

Note

True/False values (boolean) should be specified as 1/0.

5.2.2.1.1. ORIGEN nuclide ID formatting

The most general form for an ORIGEN nuclide id is known as a SIZZZAAA, an 8-digit integer composed of four parts.

S - 1 digit for sublib integer

I - 1 digit for isomeric state

ZZZ - 3 digits of atomic number

AAA - 3 digits of mass number

Only the “sublib” is a non-standard nuclide parameter, specific to a design decision in ORIGEN where it is allowed to track two different versions of a nuclide, e.g. Gd-155 as both a fission product and fuel dopant. Below is a short description of the typical sublibs.

Table 5.2.2 Origen sublibrary definition
S	TY	DESCRIPTION
1	LT	light nuclides, typically the result of activation of common elements and structural materials, e.g. O-16, Li-6
2	AC	fissionable actinides and their immediate decay and activation products, e.g. U-235, Pu-239, Cm-244
3	FP	fission products and their decay and activation products, e.g. Te-135, Cs-135, Xe-135

When S=0 (in most cases), this implies the sum over all versions of a nuclide.

5.2.2.1.2. Format options for Origen data resources

Available format options for Origen data resources (including Origen::Library, Origen::Archive, and Origen::YieldResource) are as-follows:

-format

coeff: output tabular transition coefficients
coefft: coeff but with transition ids
matrix: output full transition matrix
json: output in JSON format
tags: output file tags
nucl: nuclide list
nprodr: neutron production ratio
genneu: neutron generation
loxs: loss xs
fisxs: fission xs
burnups: output burnup list
reaction: allowed reactions
graphviz: output dot file transitions to STDOUT

Default:: -format=coefft

5.2.2.1.3. Format options for Origen concentrations files

-format

info: information table
csv: comma-separated values
ii.json: inventory interface in JSON
tags: tags stored on each state

Default:: -format=info

5.2.2.3. Output control options

-prec=

Number of significant digits to output

Default:: 4

-output_zeros=

Whether to output zero values (boolean)

Default:: yes

-transpose=

Whether to transpose table (boolean)

Default:: no

Note

Only available for some tables

-symbols=: Whether to output numeric ids (1001) or symbols (H-1)

Tip

Same as -idform='{:TY}:{:ee}{:AAA}{:m}'

-idform=

Controls printout of ids, the following are subsituted:

{:S} - sublib integer

{:TY} - sublib name

{:I} - isomeric state integer

{:ZZZ} - up to 3 digits of atomic number (also Z, ZZ)

{:AAA} - up to 3 digits of mass number (also A, AA)

{:EE} - up to 2 characters elemental symbol (also Ee,ee for different case)

{:M} - metastable indicator ‘M’ for first, ‘M2’ for second, etc. (also m)

Default:

With -symbols=0 -idform='{:S}{:I}{:ZZZ}{:AAA}'
With -symbols=1 -idform='{:TY}:{:ee}{:AAA}{:m}'

-units

Units used for printing

Note

Only applies to -type=f71 and -format=csv

Available units:

abso (total absorption xs)
fiss (total fission xs)
capt (total capture xs)
airm (raditoxicity index in air, m^3)
apel
atom
becq (activity in becquerels)
curi (activity in curies)
gamw (thermal output from gammas in watts)
gamm
gato (mass in gram-atoms)
gper (isotopic mass percent by element)
gram (mass in grams)
h2om (radiotoxicity index in water, m^3)
kilo (mass in kilograms)
wpel (weight percent by element)
watt (total thermal output in watts)
mevs
part
inte
ener

-verbose=

Display verbose output (includes echo of all input data; boolean)

Default:: -verbose=no

5.2.2.4. Data manipulation options

-flux=

If flux>=0, then multiply reaction matrix coeff (one-group xs in barns) by the factor flux(n/cm^2s) * 1e-24(barns/cm) in order to display reactions/second units

Tip

Useful for comparing the magnitude of decay and reaction channels

Default:: flux=-1.0 (no flux scaling)

-lib=: Filepath to a binary Origen data library (.f33)

Tip

Needed for certain Origen::StateSet (.f71) unit conversions

See also

obiwan view -dec

-dec=

Filepath to an on-disk Origen DecayResource (e.g., origen.rev*.decay.data)

Tip

Needed for certain Origen::StateSet (.f71) unit conversions

Default:

Search for origen.rev*.decay.data in each of the following locations (in order):

./obiwan/../data/origen_data/
${SCALE}/data/origen_data/
${DATA}/data/origen_data/

5.2.2.5. Usage examples

5.2.2.5.1. Displaying a table of loss cross-section data

Note here that pos=0 corresponds to all positions (burnups) on a library.

Example 5.2.2 Using OBIWAN to view loss cross-sections on a library

 $ obiwan view -format=loxs -pos=0 ./a10_e15w01.bof 2>/dev/null

  nuclide  0.0000e+00  1.5000e+03  4.5000e+03  7.5000e+03  1.0500e+04  1.3500e+04
 10001001  2.5724e-01  2.6172e-01  2.6315e-01  2.6400e-01  2.6582e-01  2.6731e-01
 10001002  8.9254e-03  9.6637e-03  9.8350e-03  9.9177e-03  1.0278e-02  1.0590e-02
 10001003  2.3025e-04  2.4988e-04  2.5428e-04  2.5635e-04  2.6587e-04  2.7415e-04
 10001004  1.2445e+11  1.3507e+11  1.3744e+11  1.3856e+11  1.4371e+11  1.4818e+11
 ...

While the output can be piped through a command such as grep to filter on a specific nuclide, e.g.:

$ obiwan view -format=loxs -pos=0 ./a10_e15w01.bof | grep 20092235

in many cases, the transpose table (combined with a nuclide filter using obiwan view -sizzzaaa is typically a better option, such as shown below. (Note the normalization to the first position value).

Example 5.2.3 Using OBIWAN to view U-235 loss cross-sections, relative to the first burnup position

 $ obiwan view -format=loxs -sizzzaaa=20092235 -pos=-1 -transpose=1 ./a10_e15w01.bof 2>/dev/null

          nuclide    20092235
       0.0000e+00  1.0000e+00
       1.5000e+03  9.9738e-01
       4.5000e+03  1.0177e+00
       7.5000e+03  1.0398e+00
       1.0500e+04  1.0466e+00
       1.3500e+04  1.0517e+00
       1.6500e+04  1.0560e+00
       3.1500e+04  1.0677e+00
       4.6500e+04  1.0709e+00
       5.8500e+04  1.0711e+00
       7.0500e+04  1.0707e+00

5.2.2.5.2. Output transitions to a graphical format

The following example demonstrates dumping a transition matrix set to a node-based graph (.dot) file; the neato program from graphviz works best for viewing this output.:

$ obiwan view -format=graphviz -allow_s="[1,2,3]" -include_byproducts=0 \
    $DATA/origen_library/pwr.rev03.orglib >transitions.dot

$ neato -n1 transitions.dot -T pdf >transitions.pdf

5.2.2.5.3. Output a JSON-based inventory interface file

The following example outputs a inventory interface file restricted to actinides and fission products:

$ obiwan view -format=ii.json -allow_s="[2,3]" my.f71 >my.ii.json

Here note that the ii.json output is normally directed to STDOUT; in this case, it is redirected to the file my.ii.json.

5.2.3. obiwan tag

obiwan tag is used to add, modify, and delete “tags” on Origen binary files. These “tags” come in two types: “ID” tags used for categorical identification, and “interp” tags representing real values used to denote state points for interpolation. (Examples of typical “interpolation” tags might include features such as initial enrichment, average moderator density, etc.; i.e., characteristics that are expected to influence the shape of the neutron energy spectrum and thus the resulting one-group cross-sections.)

-idtags=

Key-value pairs corresponding to “categorical” information about a data set on a binary file. Each key is a string mapped to a string value; ID keys are used to identify common characteristics of different sets of data (e.g., assembly type, size, and other characteristic features used to identify and group together similar sets of data).

One or more values are given as key-value pairs within an array, e.g.:

-idtags=[ tag1=val1, tag2=val2, ... ]

-interptags=

Key-value pairs corresponding to “interpolable” information about the position on the binary file. Each key is a string mapped to a real, floating-point point value; these interpolation values can then be used as “knots” on an interpolation grid to interpolate Origen::Library and Origen::StateSet data.

One or more values are given as an array, e.g.:

-interptags=[ tag1=val1, tag2=val2, ... ]

5.2.3.1. Viewing tags on on a file

To view tags present on an Origen::Library, call obiwan tag [filename] without specyfing any ID or interpolation tags, e.g.:

Example 5.2.4 Using OBIWAN to view all existing tags on a file

obiwan view libs/w17_15_tagged.arplib

     libs/w17_new.arplib: {
        idtags: {
           size: 17,
           vendor: Westinghouse }
        interptags: {
           enr: 1.5,    }
     }

Note

For Origen::Archive, obiwan tag viewing will display the “lowest common denominator” set of tags, i.e., exclusively the tags present on all Library objects on the Archive.

Note

obiwan tag modifies tags on an Origen binary file in-place.

5.2.3.2. Adding tags to a file

To add a tag to a file, specify the tag name and value as a key-value pair; multiple tags can be added simultaneously by separating each key-value pair by a comma. The entire series of key-value pairs must be enclosed by a pair of single quotes, e.g.:

$ obiwan tag idtags='tag1=val1, tag2=val2, ...'

If a tag name already exists on the file, the tag value is automatically updated to the new value provided by the user; otherwise, the tag is created and added to the Library.

Example 5.2.5 Adding tags to multiple Origen::Library files simultaneously; note that all output is directed to the file “log”

 cp $DATA/arplibs/w17* new
 obiwan tag new/\* -idtags='size=17,vendor=W' 2>log
 obiwan tag new/\*e60.arplib -interptags='enr=6.0' 2>>log
 obiwan tag new/\*e50.arplib -interptags='enr=5.0' 2>>log
 obiwan tag new/\*e40.arplib -interptags='enr=4.0' 2>>log
 obiwan tag new/\*e30.arplib -interptags='enr=3.0' 2>>log
 obiwan tag new/\*e20.arplib -interptags='enr=2.0' 2>>log
 obiwan tag new/\*e15.arplib -interptags='enr=1.5' 2>>log

The newly-created tags can be similarly viewed using a wildcard operator:

Example 5.2.6 Viewing newly-added tags on multiple files

$ obiwan tag new/\*.arplib

     new/w17_e15.arplib: {
        idtags: {
           size: 17,
           vendor: W   }
        interptags: {
           enr: 1.5,    }
     }

     new/w17_e20.arplib: {
        idtags: {
           size: 17,
           vendor: W   }
        interptags: {
           enr: 2,    }
     }
     ...

5.2.3.3. Deleting tags on a file

To delete a tag from a file, simply specify the name of an existing tag on the file with an empty value, e.g.:

$ obiwan tag -idtags='assembly='

5.2.4. obiwan convert

Converts between different file formats for Origen::Library (reactor data libraries) and Origen::StateSet (stored concentrations).

-version=

Target output version (file format)

6.1: sets -format=s61
6.2: sets -format=bof

-format=

Target output format (mutually exclusive with -version)

s61: SCALE 6.1 fortran binary
s62b: SCALE 6.2 beta fortran binary
bof: SCALE 6.2+ Binary Object Format
hdf5: SCALE 6.3+ HDF5 format (EXPERIMENTAL)

Warning

The HDF5 format for Origen::Library is currently under development and may change in future releases; at present, it is provided as a convenience method for users to import Origen::Library data from external sources and to export data into HDF5 format for expedited viewing & processing.

-type=

Filter loading to a particular file type

f33: Origen::Library
f71: Origen::StateSet
yld: Origen::YieldResource
dec: Origen::DecayResource

-dir=

Existing directory for converted files

Default:: -dir=./ (current directory)

-i

Modify existing files in place

(By default, obiwan will not overwrite existing files)

-remove_mass: Remove masses on a library

-remove_abund: Remove abundances on a library

-verbose: Verbose mode (extra output to STDERR)

-endian=

Request for endianness of converted files

big: big endian
little: little endian
otherwise: system-native endian

(will not be possible in all scenarios)

-thin=

Enable / disable library thinning (1 = thin)

“Thinning” library by interpolating to a user-specified series of burnups

Default:: thin=0 (no thinning)

interp=

Time / burnup interpolation method

near: Interpolate to nearest time / burnup point lin: Linearly interpolate between time / burnup points cubic: Cubic spline interpolaiton between time / burnup points

Default:: near (nearest neighbor)

tvals=: List of times (MWd/MTHM) to keep/interpolate to in JSON array format, e.g. tvals=[0,100,250,1000,50000]

rvar=

Response variable to base thinning on: e.g., loss xs (loxs), fission xs (fisxs)

loxs: Total loss cross-section fisxs: Fission cross-section

Default:: rvar='loxs'

rnuc=

Nuclide response to use for response variable (e.g., pu240) for interpolation / thinning

Default:: pu240

-setbu=

Array of burnups to set on the library (i.e., burnup points to interpolate to)

Example:: -setbu=[1500.0, 3025.0, 10000.0]

5.2.5. obiwan diff

Usage: obiwan diff -format=String(y) [opts] file1 file2

-reltol=

Relative tolerance in percent (%)

Default:: reltol=0.01

-pos=

Position in file to output (0 corresponds to all positions)

Default:: -pos=1

-format=

Controls output format

Options include:

y: smart side-by-side
genneu: neutron generation
eq: fast exact match (no output)
approx_eq: fast aprox match (no output)

Default:: -format=y (smart side-by-side)

5.2.5.1. Obiwan diff examples

Take the difference between two files at the first file position, display differences using smart side-by-size, while redirecting STDERR to the file log and STDOUT to the file out:

$ obiwan diff -pos=1 -format=y \
              $DATA/arplibs/a10_e15w01.arplib \
              $DATA/arplibs/a10_e20w01.arplib 2>log >out
$ echo $? #return value should be 3 indicating difference

Same as before, but now allow for a 30% relative tolerance for reporting differences:

$ obiwan diff -pos=1 =format=y -reltol=30 \
              $DATA/arplibs/a10_e15w01.arplib \
              $DATA/arplibs/a10_e20w01.arplib 2>log >out
$ echo $? #return value should be 0 indicating no difference >30%

5.2.6. obiwan interp

obiwan interp interpolates between ORIGEN libraries based on a specified series of tag attributes to generate a new library.

Usage: obiwan interp [-idtags='tag1=[v1],tag2=[v2]'] [-interptags='tag3=[v3],tag4=[v4]'] file1 file2 ...

-idtags=

List of ID tags to down-select for interpolation. (i.e., Libraries without all of the matching ID tags are excluded from interpolation).

Accepts an array of key-value pairs separated by commas, e.g. -idtags='tag1=[v1],tag2=[v2],...]

Values are interpreted as strings

-interptags=

List of interpolable values to interpolate the new library to.

Accepts an array of key-value pairs separated by commas, e.g. -interptags='tag1=[v1],tag2=[v2],...]

Here, values are floating-point real numbers

Note

Required

5.2.6.1. Interpolation usage examples

Example 5.2.7 illustrates a basic interpolation case, selecting all libraries with ID tags Assembly Type matching w17x17 and Fuel Type matching UOX, interpolating along dimensions Enrichment and Moderator Density to values of 4.5% and 0.55 g/cc, respectively.

Example 5.2.7 Interpolate all libraries with ID tags Assembly Type=w17x17
and Fuel Type=UOX to an enrichment of 4.5% and moderator
density of 0.55 g/cc.

obiwan interp
       -idtags='Assembly Type=w17x17,Fuel Type=UOX'
       -interptags='Enrichment=4.5,Moderator Density=0.55' /path/to/libraries

Note

When interpolating, obiwan will produce a new library file called InterpLib.bof.

5.2.7. obiwan patch

Patch an ORIGEN file with data from another file

Usage: obiwan patch -from=SOURCE -data="path/to/data" [opts] file

-from=

File to import patch data from; existing data or NULL

Default:: -from=ft33f001

-data=

A special a hierarchical data description using “/” separators.

Data paths supported:

coeff[POS]/n_production_xs
coeff[POS]/nu

POS=1,2,...,N where N is the total number of positions

POS=* can be used to specify all positions

POS=1|2|... can be used to specify a list of positions

Note

coeff/ and coeff[*]/ are identical

-pos=

Position on <file> to apply patch

0: attempt to apply to all positions

-type=

Load only a particular type

Options:

f33: Library

-verbose: Verbose mode (extra output to STDERR)

5.2.7.1. obiwan patch usage examples

The following examples illustrate how to use obiwan patch to patch data on Origen Library files.

Example 5.2.8 illustrates patching all neutron production cross-sections from the first position of an existing Library file.

Example 5.2.8 Patch all neutron production cross sections with a single data set (position 1 on my.f33)

 $ obiwan patch -from=my.f33 -data=coeff[1]/n_production_xs patched.f33
 $ obiwan view -format=genneu -type=f33 -pos=1 patched.f33

Example 5.2.9 nullifies (replaces with zeroes) all neutron production cross-sections as position 2 on the Library file.

Example 5.2.9 Zero out neutron production cross-sections at position #2

 $ obiwan patch -from=NULL -data=coeff/n_production_xs -pos=2 patched.f33

Example 5.2.10 demonstrates replacing data on a three-position library, using data from source position 1 for the first two positions on the patched library and from source position 2 on the third position of the patched library.

Example 5.2.10 Patch a 3-position library with data from positons 1, 1, and 2 on my.f33, respectively

 $ obiwan patch -from=my.f33 -data=coeff[1|1|2]/n_production_xs patched.f33

Example 5.2.11 and Example 5.2.11 demonstrate synonymous ways of sequentially replacing three positions on a patched library with the sequential positions from a source Library. (Note that the source library my.f33 must have the same number of positions as the Library being patched.)

Example 5.2.11 Patch 3-position library with new data from my.f33 in sequential order. (Note that my.f33 must have 3 positions.)

 $ obiwan patch -from=my.f33 -data=coeff[*]/n_production_xs patched.f33

Example 5.2.12 Patch 3-position library with new data from my.f33 in sequential order. (Note that my.f33 must have 3 positions.)

$ obiwan patch -from=my.f33 -data=coeff/n_production_xs patched.f33

Finally, Example 5.2.13 replaces only the nu portion (i.e., average neutron production per incident neutron) of the actinide neutron (i.e., average neutron production per incident neutron production data, assuming it is dominant).

Example 5.2.13 Just correct the nu portion of actinides production, assuming it is dominant, i.e. nu=from_prodxs/from_fisxs --> to_prodxs=nu*to_fisxs

 $ obiwan patch -from=my.f33 -data=coeff/nu patched.f33

5.2. OBIWAN: A tool for viewing and manipulating Origen binary files

5.2.1. obiwan info

5.2.2. obiwan view

5.2.2.1. Output formatting

5.2.2.1.1. ORIGEN nuclide ID formatting

5.2.2.1.2. Format options for Origen data resources

5.2.2.1.3. Format options for Origen concentrations files

5.2.2.2. Data filter options

5.2.2.3. Output control options

5.2.2.4. Data manipulation options

5.2.2.5. Usage examples

5.2.2.5.1. Displaying a table of loss cross-section data

5.2.2.5.2. Output transitions to a graphical format

5.2.2.5.3. Output a JSON-based inventory interface file

5.2.3. obiwan tag

5.2.3.1. Viewing tags on on a file

5.2.3.2. Adding tags to a file

5.2.3.3. Deleting tags on a file

5.2.4. obiwan convert

5.2.5. obiwan diff

5.2.5.1. Obiwan diff examples

5.2.6. obiwan interp

5.2.6.1. Interpolation usage examples

5.2.7. obiwan patch

5.2.7.1. obiwan patch usage examples