davidchall / topas2numpy

Reading TOPAS results into NumPy arrays

topas2numpy

Reading TOPAS results into NumPy arrays.

Features

TOPAS is a Monte Carlo tool for particle simulation, designed for medical physics research. It can output two data types:

• binned: a quantity (e.g. dose) is accumulated within a binned geometry component
• ntuple: multiple data columns are recorded per particle history

This package is able to read both data types, enabling analysis within Python.

Basic Usage

from topas2numpy import BinnedResult
x = BinnedResult('Dose.csv')

from topas2numpy import read_ntuple
y = read_ntuple('Beam.phsp')

topas2numpy's Issues

Cannot read ntuples other than phasespace files

We discover the ntuple file format based upon the first line of the header (https://github.com/davidchall/topas2numpy/blob/master/topas2numpy/ntuple.py#L43). But this first line is specific to phase space output.

Detect best NumPy dtype (use unsigned int for SurfaceTrackCount)

When the TOPAS scorer mode is set to 'SurfaceTrackCount' then the result is an integer. It would be best if the numpy dtype of the loaded data was set to an unsigned integer type in this case.

It seems this library loads such arrrays as 'float64' type which uses only 53 of the 64 bits to store the mantissa, meaning 11/64 bits are wasted in the case of 'SurfaceTrackCount', which unecessarily increases filesize.

It's also unexpected to receive a NumPy array of type 'float64' when the data consists of unsigned integers so this may have a usability impact also.

Is it possible to change this library so that it bases the data type whether the scorer is 'SurfaceTrackCount' or something else?

Add support for upcoming binary ntuple headers

In the next version of TOPAS, we shall change the column description in the binary ntuple header file. topas2numpy needs to support reading both.

Before

Byte order of each record is as follows:
 0- 3: Position X (cm)
 4- 7: Position Y (cm)
 8-11: Position Z (cm)
12-15: Direction Cosine X
16-19: Direction Cosine Y
20-23: Energy (MeV)
24-27: Weight
28-31: Particle Type (in PDG Format)
32-32: Flag to tell if Third Direction Cosine is Negative (1 means true)
33-33: Flag to tell if Is New History (1 means true)

After

Byte order of each record is as follows:
f4: Position X (cm)
f4: Position Y (cm)
f4: Position Z (cm)
f4: Direction Cosine X
f4: Direction Cosine Y
f4: Energy (MeV)
f4: Weight
i4: Particle Type (in PDG Format)
b1: Flag to tell if Third Direction Cosine is Negative (1 means true)
b1: Flag to tell if Is New History (1 means true)

Data axes are incorrectly ordered

The NumPy arrays inside a BinnedResult.data property have the axes in reverse order. The first axis should be Z, then Y, then X as per convention.

TOPAS generates .csv in such a way that 'Z' is incremented first, then Y then X. So when np.genfromtxt or np.loadtxt are used naively, the axes are in reverse order.

I haven't tested this but I think a quick fix is arr = arr.reshape(tuple(reversed(arr.shape)), order='F') after loading the data with np.loadtxt. A more efficient implementation would read the *.csv in reverse order after consuming the header.

Issue when opening binary simulation results

Hi,
I'm experiencing an issue when trying to open the attached binary simulation result:
TDK_0.zip

The error message I receive is:

Thanks!

BinnedResult.quantity still has comment symbol

>>> dose = BinnedResult('Dose.csv')
>>> print dose.quantity
# DoseToWaterBinned

Catch when unable to read file

Possible reasons:

• Files don't exist
• Unrecognized header format
• Cannot read metadata from header