coconut_tools.create_hdf

Module for extracting and converting plasma simulation data into HDF5 format.

This module provides utility functions to process different types of simulation outputs:

• CFmesh format (custom structured mesh files)

• VTU files (e.g., from Paraview-compatible simulations like COCONUT)

• Formatted .dat files

The main functionalities include:

• Sampling physical quantities (velocity, magnetic field, density, temperature, etc.) at satellite locations or specific grid coordinates

• Interpolating or extracting the closest grid point

• Saving extracted time series into standardized HDF5 format

Available functions:

• create_hdf_from_cfmesh: For CFmesh files

• create_hdf_from_vtu: For VTU files

• create_hdf_from_dat: For formatted .dat files with spherical coordinates

Functions

create_hdf_from_cfmesh(satellite_positions, ...)	Extract plasma quantities from CFmesh files and save time series (incl.
create_hdf_from_dat(folder_patterns, ...)	Creates HDF5 files from .dat files containing spherical grid data.
create_hdf_from_vtu(satellite_positions, ...)	Extracts plasma quantities from VTU files at satellite positions and stores them in HDF5.
find_closest_index_cf(x, y, z, target_coord)	Find the index of the point closest to a given target in 3D Cartesian coordinates.
find_closest_indices(clt, lon, target_clt, ...)	Finds the indices in colatitude and longitude grids closest to the desired values (in degrees).
find_nearest_index_vtu(points, target)	Find the index of the point closest to the target coordinates from vtu file.
read_cfmesh(input_cfmesh)	Reads and parses a CFmesh formatted MHD input file to extract geometry and plasma variables.
readstruct(lines)	Parses the structure of a CFmesh file by locating key section headers.

coconut_tools.create_hdf.create_hdf_from_cfmesh(satellite_positions, folder_patterns, output_dir, delta_t, time_step, method='nearest')

Extract plasma quantities from CFmesh files and save time series (incl. spherical components).

Return type:

None

Parameters:

• satellite_positions (Dict[str, Tuple[float, float, float]])

• folder_patterns (Dict[str, str])

• output_dir (Path)

• delta_t (float)

• time_step (float)

• method (str)

Parameters

satellite_positionsDict[str, Tuple[float, float, float]]

Satellite positions in Cartesian coordinates (x, y, z) in solar radii (R☉).

folder_patternsDict[str, str]

Mapping of case names to glob patterns of CFmesh files.

output_dirPath

Directory to store output HDF5 files.

delta_tfloat

Base time step duration (code units).

time_stepfloat

Output time step multiplier.

methodstr, optional

‘nearest’ to extract at closest mesh node, or ‘interpolate’ to RBF-interpolate the fields at the satellite position.

Produces

For each case, an HDF5 file with datasets:

Bx, By, Bz, Vx, Vy, Vz, rho, T, P, time, vr, vclt, vlon, br, bclt, blon

Notes

• Spherical components follow (r, θ, φ) with θ the colatitude.

• The time array uses the user’s original scaling i * delta_t * time_step * 0.402.

coconut_tools.create_hdf.create_hdf_from_dat(folder_patterns, output_dir, target_clt, target_lon)

Creates HDF5 files from .dat files containing spherical grid data.

Parameters:

• folder_patterns (Dict[str, str]) – Dictionary of simulation name -> glob pattern for dat files.

• output_dir (Path) – Output directory for HDF5 files.

• target_clt (float) – Desired colatitude in degrees.

• target_lon (float) – Desired longitude in degrees.

Return type:

None

Returns:

None

coconut_tools.create_hdf.create_hdf_from_vtu(satellite_positions, folder_patterns, output_dir, delta_t, time_step)

Extracts plasma quantities from VTU files at satellite positions and stores them in HDF5.

Parameters:

• satellite_positions (Dict[str, List[float]]) – Mapping of satellite names to 3D positions.

• folder_patterns (Dict[str, str]) – Mapping of case names to glob patterns of VTU files.

• output_dir (Path) – Directory to store output HDF5 files.

• delta_t (float) – Time step duration (in code units).

• time_step (float) – Output time step multiplier.

Return type:

None

Returns:

None

coconut_tools.create_hdf.find_closest_index_cf(x, y, z, target_coord)

Find the index of the point closest to a given target in 3D Cartesian coordinates.

Parameters:

• x (np.ndarray) – X coordinates of the mesh points.

• y (np.ndarray) – Y coordinates of the mesh points.

• z (np.ndarray) – Z coordinates of the mesh points.

• target_coord (Tuple[float, float, float]) – Target point in Cartesian coordinates (x, y, z).

Returns:

Index of the closest point in the mesh.

Return type:

int

coconut_tools.create_hdf.find_closest_indices(clt, lon, target_clt, target_lon)

Finds the indices in colatitude and longitude grids closest to the desired values (in degrees).

Parameters:

• clt (np.ndarray) – Array of colatitudes (degrees).

• lon (np.ndarray) – Array of longitudes (degrees).

• target_clt (float) – Target colatitude in degrees.

• target_lon (float) – Target longitude in degrees.

Returns:

Indices for colatitude and longitude.

Return type:

Tuple[int, int]

coconut_tools.create_hdf.find_nearest_index_vtu(points, target)

Find the index of the point closest to the target coordinates from vtu file.

Parameters:

• points (np.ndarray) – Array of shape (N, 3) containing point coordinates.

• target (List[float]) – Target coordinates [x, y, z].

Returns:

Index of the closest point.

Return type:

int

coconut_tools.create_hdf.read_cfmesh(input_cfmesh)

Reads and parses a CFmesh formatted MHD input file to extract geometry and plasma variables.

Parameters:

input_cfmesh (str or Path) – Path to the CFmesh file.

Returns:

cell_center_x, cell_center_y, cell_center_z, Bx, By, Bz, rho, Vx, Vy, Vz, Pressure, Temperature

Return type:

Tuple of NumPy arrays containing

coconut_tools.create_hdf.readstruct(lines)

Parses the structure of a CFmesh file by locating key section headers.

Parameters:

lines (List[str]) – List of lines from the CFmesh file.

Returns:

idx0 (int): Index where element connectivity starts. idx1 (int): Index where nodal coordinates start. idx2 (int): Index where state vector starts. idx3 (int): Index marking start of outlet-related section. nbelements (int): Number of elements in the mesh. nend (int): Number of !END markers. comment (List[Tuple[int, str]]): Positions and content of all comment lines.

Return type:

Tuple containing