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
 ${PGMDIR}/obiwan [command] [file(s)]

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 mode; prints extra output to STDERR

Table 5.2.1 File information output by obiwan info




path without the directory


type/class of the object


number of “sets” of data (e.g. burnups)


the format of the dataType in this file


“binary” or “text”


endian-ness for the file itself and the system (mismatches have I/O performance penalties)


version of the application which wrote this file (some formats cannot store this and it appears as “-“)


time in milliseconds to load the file


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


All types and formats do not support all options.


True/False values (boolean) should be specified as 1/0. 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






light nuclides, typically the result of activation of common elements and structural materials, e.g. O-16, Li-6



fissionable actinides and their immediate decay and activation products, e.g. U-235, Pu-239, Cm-244



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. Format options for Origen data resources

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

  • 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


-format=coefft Format options for Origen concentrations files

  • info: information table

  • csv: comma-separated values

  • ii.json: inventory interface in JSON

  • tags: tags stored on each state


-format=info Data filter options


Position in Origen::Library or Origen::StateSet to output. (0 is all positions). < 0 means normalize output to that position (useful for viewing cross-section data across many scales).


Not available for all types / formats.



-cases=[ ... ]

Only consider these cases (-type=f71 only)


Restrict data to this nuclide; e.g. u-235 is 20092235

allow_s=[ ... ]

Allow only certain sublibs, e.g. -allow_s=[2,3] (allows only actinides and fission product sublibraries).

-allow_i=[ ... ]

Allow only certain isomeric states, e.g. -allow_i=[1]

-allow_z=[ ... ]

Allow only certain atomic numbers, e.g. -allow_z=[92]

-allow_a=[ ... ]

Allow only certain mass numbers, e.g. -allow_a=[135,136]


Allow only atomic numbers greater or equal to Z (integer)


Restrict data to this transition id:

dk mode (<0) or reaction MT (>0)

(use -format=coefft to see ids)


Valid for -format=graphviz only


Whether to display decay transitions (boolean)




Whether to display fission transitions (boolean)




Whether to display reaction transitions (boolean)




Whether to include byproduct reactions arrows (boolean)


no Output control options


Number of significant digits to output




Whether to output zero values (boolean)




Whether to transpose table (boolean)




Only available for some tables


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


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


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)

  • With -symbols=0 -idform='{:S}{:I}{:ZZZ}{:AAA}'

  • With -symbols=1 -idform='{:TY}:{:ee}{:AAA}{:m}'


Units used for printing


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


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


-verbose=no Data manipulation options


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


Useful for comparing the magnitude of decay and reaction channels


flux=-1.0 (no flux scaling)


Filepath to a binary Origen data library (.f33)


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

See also

obiwan view -dec


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


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


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

  1. ./obiwan/../data/origen_data/

  2. ${SCALE}/data/origen_data/

  3. ${DATA}/data/origen_data/

See also

obiwan view -lib


Only one of -lib or -dec should be specified for F71 file unit conversions Usage examples 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 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 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.)


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, ... ]


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, ... ] 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,    }


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.


obiwan tag modifies tags on an Origen binary file in-place. 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,    }
     ... 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).


Target output version (file format)

  • 6.1: sets -format=s61

  • 6.2: sets -format=bof


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)


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.


Filter loading to a particular file type

  • f33: Origen::Library

  • f71: Origen::StateSet

  • yld: Origen::YieldResource

  • dec: Origen::DecayResource


Existing directory for converted files


-dir=./ (current directory)


Modify existing files in place

(By default, obiwan will not overwrite existing files)


Remove masses on a library


Remove abundances on a library


Verbose mode (extra output to STDERR)


Request for endianness of converted files

  • big: big endian

  • little: little endian

  • otherwise: system-native endian

(will not be possible in all scenarios)


Enable / disable library thinning (1 = thin)

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


thin=0 (no thinning)


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


near (nearest neighbor)


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


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

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




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




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


-setbu=[1500.0, 3025.0, 10000.0]

5.2.5. obiwan diff

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


Relative tolerance in percent (%)




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




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)


-format=y (smart side-by-side) 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 ...


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


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


Required 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


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


File to import patch data from; existing data or NULL




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


coeff/ and coeff[*]/ are identical


Position on <file> to apply patch

0: attempt to apply to all positions


Load only a particular type

  • f33: Library


Verbose mode (extra output to STDERR) 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