The APyT file format conversion module

APT data can exist in multiple file formats—often representing the same measurement dataset, but stored differently (e.g., as raw binary or decoded ASCII). This module provides easy-to-use functions to convert between various file formats commonly encountered in atom probe tomography (APT) workflows. It enables standardized preprocessing and ensures compatibility across software tools within the APyT ecosystem.

Raw file format

The APT group at the University of Stuttgart uses a binary file format to record APT measurements. Each file entry corresponds to a single evaporation event and follows Little Endian byte ordering.

The binary format includes the following fields:

Field	Data type	Description
U_base	float32	base voltage (V)
U_pulse	float32	pulse voltage (V)
U_reflectron	float32	reflectron voltage (V)
x_det	float32	x detector position (mm)
y_det	float32	y detector position (mm)
tof	float32	time of flight (ns)
epoch	int32	epoch of evaporation event
pulse_num	uint32	pulse number of evaporation event

List of functions

The following functions are available for format conversion:

• epos_to_raw(): Convert an ePOS file to a RAW file.

• raw_to_ascii(): Convert a raw measurement file to a human-readable ASCII file.

• tapsim_to_raw(): Convert TAPSim ASCII file to raw file.

apyt.io.conv.epos_to_raw(epos_file, raw_file=None)

Convert an ePOS file to a RAW file.

This function reads an input ePOS file, maps overlapping fields between the ePOS and RAW data types, and writes the converted data to a binary RAW file. Fields that exist in both formats are copied directly.

Parameters:

• epos_file (str or Path) – Path to the input ePOS file.

• raw_file (str or Path, optional) – Path to the output RAW file. If not provided, it will be generated automatically by replacing the extension of epos_file with .raw.

Returns:

Path to the generated RAW file, or None if the input file does not exist.

Return type:

Path or None

Warns:

UserWarning – If the input ePOS file does not exist.

apyt.io.conv.raw_to_ascii(raw_file, ascii_file)

Convert a raw measurement file to a human-readable ASCII file.

This function enables the conversion from a raw measurement file to a human-readable ASCII file. The binary file is read in chunks of 32 bytes, (representing one evaporation event), decoded into the respective data types, and written to an ASCII text file.

Parameters:

• raw_file (str) – The name of the raw file.

• ascii_file (str) – The name of the ASCII file.

apyt.io.conv.tapsim_to_raw(tapsim_file, raw_file, id_range_list)

Convert TAPSim ASCII file to raw file.

This function enables the conversion from a TAPSim ASCII file to a raw file for further processing (e.g. reconstruction). A certain subset of columns is imported from the TAPSim file, manipulated accordingly to match the raw file format, and eventually written to a binary file. A constant base voltage is used for all events and the time of flight is arranged such that it is constant for one distinct species. The epoch is set to a constant time plus 1 event/s, the pulse number corresponds to the evaporation event.

The conversion is illustrated in the following table:

Raw file	Data type	TAPSim file	Comment
U_base	float32	5000 V	constant
U_pulse	float32	0	zero
U_reflectron	float32	0	zero
x_det	float32	col. 7	conversion from meter to millimeter
y_det	float32	col. 8	conversion from meter to millimeter
tof	float32	constant per species	constant for one species, separation 50 ns
epoch	int32	946681200 + event	(2000-01-01 00:00:00) + 1 event/s
pulse_num	uint32	0, 1, 2, …	corresponds to evaporation event

Parameters:

• tapsim_file (str) – The name of the TAPSim file.

• raw_file (str) – The name of the raw file.

• id_range_list (list) – The list of id ranges used for mapping the atomic species, each of type tuple of length 2, specifying the respective minimum and maximum id.