Readers

class stagpyviz.BinHeader(file: BufferedReader)

Class to read and extract information from the 32 bits binary files produced by StagYY.

Parameters:: file (io.BufferedReader) – A binary file object opened in ‘rb’ mode.
Attributes:

f

The binary file object from which the header and fields will be read.

Type:: io.BufferedReader

int_str

The format string for reading 32-bit signed integers.

Type:: str

float_str

The format string for reading 32-bit single precision floats.

Type:: str

sizeof_int

The size in bytes of a 32-bit signed integer.

Type:: int

sizeof_float

The size in bytes of a 32-bit single precision float.

Type:: int

header

A dictionary containing the extracted header information from the binary file.

Type:: dict

Methods:

interpret_magic(magic: int) → tuple[int, int]

Interprets the “magic” number read from the binary file header to determine what to expect from the raw binary file content.

Parameters:: magic (int) – The magic number read from the binary file header.
Returns:: A tuple (nval, magic) containing the number of variables per grid point and the remaining magic number after extracting the number of variables.
Return type:: tuple[int, int]

read_fields() → ndarray

Read the field data from the binary file. Very inspired from this stagpy function.

Returns:: A 5D numpy array containing the field data, indexed as (component, x, y, z, block).
Return type:: np.ndarray

read_float(n: int = 1) → float | list[float]

Reads n 32-bit single precision floats from the binary file and returns them as a float or a list of floats.

Parameters:: n (int) – The number of floats to read. Default is 1.
Returns:: A float if n is 1, otherwise a list of floats.
Return type:: float | list[float]

read_header() → dict

Read the header information from the binary file and store it in the header attribute as a dictionary. The header contains the following information:

nval: Number of variables per grid point. 4 for velocity-pressure fields, 1 for scalar fields.
xyp: 1 if the file contains velocity-pressure fields, 0 otherwise.
ntot: Total number of grid points in each dimension (x, y, z, block).
aspect: Aspect ratio of the grid, 2 entries.
npar: Number grid points per parallel subdomains in each dimension (x, y, z, block).
rpoints: Radial coordinates of grid points in the z direction. Shape is (ntot[2]+1,).
rcells: Radial coordinates of cell centers in the z direction. Shape is (ntot[2],).
rcmb: Radius of the core-mantle boundary.
istep: Simulation step number.
time: Simulation time.
erupta_total: 2 entries if the magic number is greater or equal to 12, otherwise 1 entry.
intruda: Only if the magic number is greater or equal to 12. Shape (2,).
TTGmass: Only if the magic number is greater or equal to 12. Shape (3,).
Tbot: Only if the magic number is greater or equal to 6.
Tcore: Only if the magic number is greater or equal to 10.
water: Only if the magic number is greater or equal to 11.
x, y, z: Coordinates of grid points in each dimension, only if the magic number is greater or equal to 3.
scale: Scaling factor for the field values, only if nval is greater or equal to 4.
ncpu: Number of parallel subdomains in each dimension, calculated as ntot[i] / npar[i].
npi: Total number of grid points per parallel subdomain, calculated as (ncpu[0]+xyp) * (ncpu[1]+xyp) * ncpu[2] * ncpu[3] * nval.

Returns:: The header information as a dictionary.
Return type:: dict

read_int(n: int = 1) → int | list[int]

Reads n 32-bit signed integers from the binary file and returns them as an integer or a list of integers.

Parameters:: n (int) – The number of integers to read. Default is 1.
Returns:: An integer if n is 1, otherwise a list of integers.
Return type:: int | list[int]

class stagpyviz.BinHeader64(file: BufferedReader)

Class to read the binary header of a StagYY output file, for 64-bit files. It inherits from BinHeader, and overrides the necessary attributes and methods to handle 64-bit data.

interpret_magic(magic) → tuple[int, int]

Interprets the “magic” number read from the binary file header to determine what to expect from the raw binary file content.

Parameters:: magic (int) – The magic number read from the binary file header.
Returns:: A tuple (nval, magic) containing the number of variables per grid point and the remaining magic number after extracting the number of variables.
Return type:: tuple[int, int]

stagpyviz.read_stag_bin(fname: str) → tuple[dict, ndarray]

Read a StagYY binary file and return the header and field data. Automatically detects whether the file is in 32-bit or 64-bit format and uses the appropriate reader.

Parameters:: fname (str) – The path to the StagYY binary file.
Returns:: A tuple containing the header (as a dictionary) and the field data (as a NumPy array).
Return type:: tuple[dict, np.ndarray]