sparseSpatialSampling.utils module

Helper functions for loading OpenFOAM fields and for encapsulating the complete workflow of loading, interpolating, and exporting fields.

Additionally, provides a function to compute the SVD of data from \(S^3\) for a given data matrix and associated weights.

sparseSpatialSampling.utils.compute_svd(data_matrix, cell_area, rank=None)[source]

Compute a weighted SVD for a given field, where the field is weighted by the cell area (2D) or volume (3D).

For more information on determining the optimal rank, see the FlowTorch documentation: flowtorch.analysis.svd.SVD.opt_rank.

Parameters:

  • data_matrix (pt.Tensor) – Data matrix with snapshots; the last dimension is expected to represent temporal evolution

  • cell_area (pt.Tensor) – Area (2D) or volume (3D) for each cell

  • rank (int | None) – Number of modes to compute the SVD. If None, the optimal rank will be used

Returns:

Tuple containing the singular values, modes, and mode coefficients as (s, U, V)

Return type:

Tuple[pt.Tensor, pt.Tensor, pt.Tensor]

sparseSpatialSampling.utils.export_openfoam_fields(datawriter, load_path, boundaries, batch_size=None, fields=None)[source]

Wrapper function for interpolating the original CFD data (from OpenFOAM) onto the grid generated by \(S^3\).

If the data was not generated with OpenFOAM, the export_data() method of the DataWriter class needs to be called directly with the CFD data and coordinates of the original grid, as illustrated in Tutorial 2.

Important Note:

This wrapper function only exports fields available at all time steps, based on the fields present in the first time step. If fields exist only at every Nth time step, this function cannot be used. In that case, the time steps and field name must be provided directly to the export_data method, as shown in Tutorial 2.

Example usage without this function:

times = [0.1, 0.2, 0.3]
export = execute_grid_generation(...)
export.write_times = times  # times needs to be a list of str
export.export_data(...)
Parameters:

  • datawriter (DataWriter) – DataWriter object resulting from the refinement with \(S^3\)

  • load_path (str) – Path to the original CFD data

  • boundaries (dict) – Boundaries used for generating the mesh

  • batch_size (int | None) – Number of snapshots to interpolate and export at once. If None, all snapshots are exported at once

  • fields (str | list[str] | None) – Fields to export, either a string or a list of strings. If None, all available fields at the first time step are exported

Returns:

None

Return type:

None

sparseSpatialSampling.utils.load_foam_data(load_dir, boundaries, field_name='p', n_dims=2, t_start=0.4, scalar=True)[source]

Load a single OpenFOAM field (scalar or vector) from all write times greater than or equal to t_start.

Differences from load_original_Foam_fields:

  • Designed for a single field only.

  • Time filtering is based on a numerical threshold (t_start), instead of requiring explicit lists of times.

  • Input requires explicit scalar/vector flag rather than inferring from field data.

  • Always returns the simulation weights in addition to field data and coordinates.

  • Has a simpler interface but less flexibility.

Use this function if:

  • You want a streamlined way to load one field from a time window.

  • You already know whether the field is scalar or vector.

  • You specifically need the weights array from the loader.

Parameters:

  • load_dir (str) – Path to the simulation data

  • boundaries (list[list[float]]) – List of [lower, upper] boundaries defining the mask

  • field_name (str) – Name of the field to load

  • n_dims (int) – Number of physical dimensions (2 for 2D, 3 for 3D)

  • t_start (int | float) – Starting time; all snapshots with time >= t_start will be loaded

  • scalar (bool) – Flag indicating whether the field is scalar (True) or vector (False)

Returns:

  • Tensor containing the field values at each write time

  • Tensor with x-, y-, and z-coordinates of the vertices (depending on 2D or 3D)

  • Tensor with the masked coordinates of the vertices

  • List of write times as strings

Return type:

Tuple[pt.Tensor, pt.Tensor, pt.Tensor, list[str]]

sparseSpatialSampling.utils.load_original_Foam_fields(load_dir, n_dimensions, boundaries, field_names=None, write_times=None, get_field_names_and_times=False)[source]
Load one or multiple OpenFOAM fields for arbitrary write times, with flexible options for returning either:

  • available field names and times, or

  • actual field data (scalar or vector).

Differences from load_foam_data:

  • Supports multiple fields at once, or a single field.

  • Supports custom lists of write times instead of only filtering by t_start.

  • Can return only metadata (field names + times) without loading data via get_field_names_and_times=True.

  • Returns a list of (coord, data) pairs when multiple fields are requested.

  • Handles variable dimensionality of fields (scalar or vector) dynamically.

Use this function if:

  • You need more general-purpose access to OpenFOAM data.

  • You want to query available fields/times before loading.

  • You want to load multiple fields in one call.

Note

This function is used in export_openfoam_fields to easily export all fields and time steps to \(S^3\) data formats. For loading OpenFOAM data, e.g., to pass it to \(S^3\) for grid generation it is recommended to use load_foam_data.

Parameters:

  • load_dir (str) – Path to the original CFD data

  • n_dimensions (int) – Number of physical dimensions

  • boundaries (dict) – Boundaries of the numerical domain, must match those used for the execution of \(S^3\)

  • field_names (str | list[str]) – Names of the fields to be exported

  • write_times (str | list[str]) – Numerical time steps to export; can be a string or a list of strings

  • get_field_names_and_times (bool) – If True, return available field names at the first available time steps and write times

Returns:

  • If get_field_names_and_times=True: Tuple of (write_times, field_names_at_first_time_step)

  • If False:

    • Single field: Tuple of (coord, data)

    • Multiple fields: List of tuples [(coord1, data1), (coord2, data2), ...]

    • No matching fields: (None, None)

Return type:

Union[ Tuple[list, list], Tuple[pt.Tensor, pt.Tensor], List[Tuple[pt.Tensor, pt.Tensor]], Tuple[None, None]

]

sparseSpatialSampling.utils.write_svd_s_cube_to_file(field_names, load_dir, file_name, new_file, n_modes=None, rank=None, t_start=0)[source]

Compute an SVD for multiple fields and export the results to HDF5 and XDMF for visualization (e.g., in ParaView).

Parameters:

  • field_names (str | list[str]) – Names of the fields for which the SVD should be computed

  • load_dir (str) – Directory from which the results of \(S^3\) should be loaded. The SVD results will be written into the same directory

  • file_name (str) – Name of the file from which the data should be loaded. For clarity, ‘_svd’ will be appended to the output file containing the SVD results

  • new_file (bool) – Flag indicating whether all exported fields are saved in a single HDF5 file or each field is written into a separate file

  • n_modes (int) – Number of modes to write to the file. If larger than available modes, all available modes will be written

  • rank (int | None) – Number of modes to use for computing the SVD. If None, the optimal rank will be used

  • t_start (int | float) – Starting time; all snapshots with time >= t_start will be loaded

Returns:

None

Return type:

None