Results Module

Conceptual Overview

The Results class is the primary container for storing, managing, and exporting all outputs from an OpenFLASH simulation. It is built on top of the powerful xarray library, which provides labeled, multi-dimensional arrays, making the data self-describing and easy to work with.

When you run a simulation, especially a frequency sweep using the run_and_store_results() method, the engine will return a fully populated Results object.

Key Features

• Structured Data: All data is stored in an xarray.Dataset with named dimensions (like ‘frequencies’, ‘modes’, ‘r’, ‘z’) and coordinates, eliminating ambiguity.

• Comprehensive Storage: Capable of storing key outputs, including hydrodynamic coefficients (added mass, damping) and detailed spatial field data (potentials, velocities).

• NetCDF Export: Provides a simple method to export the entire dataset to a NetCDF (.nc) file, a standard format for scientific data that preserves the data’s structure and labels.

Example Usage

The most common workflow involves receiving a Results object from the MEEMEngine and then accessing or exporting its data.

from openflash import MEEMEngine, MEEMProblem
import numpy as np

# --- Assume 'engine' and 'problem' are already configured ---
# problem.set_frequencies(np.linspace(0.5, 4.0, 50))

# 1. Run the simulation to get a populated Results object
results = engine.run_and_store_results(problem_index=0)

# 2. Access the underlying xarray.Dataset
dataset = results.get_results()
print("--- Accessing Added Mass Data ---")
print(dataset['added_mass'])

# 3. Display a summary of the dataset
print("\n--- Dataset Summary ---")
results.display_results()

# 4. Export all results to a file
results.export_to_netcdf("my_simulation_output.nc")
print("\nResults saved to my_simulation_output.nc")

API Reference

class openflash.results.Results(problem: MEEMProblem)

Class to store results in an xarray format similar to Capytaine’s conventions. Provides methods to store, access, and export results to a .nc file.

Data Storage Methods

These methods are used by the MEEMEngine to populate the dataset. Users typically do not need to call these directly.

store_hydrodynamic_coefficients(frequencies: ndarray, added_mass_matrix: ndarray, damping_matrix: ndarray)

Store hydrodynamic coefficients (added mass and damping).

Parameters:

• frequencies – Array of frequency values.

• added_mass_matrix – 3D array (frequencies x modes x modes) of added mass coefficients.

• damping_matrix – 3D array (frequencies x modes x modes) of damping coefficients.

store_all_potentials(all_potentials_batch: list[dict])

Store potentials for all frequencies and modes in a structured xarray DataArray.

Parameters:

all_potentials_batch – A list where each element corresponds to a frequency-mode calculation. Each element is a dictionary: {‘frequency_idx’: int, ‘mode_idx’: int, ‘data’: {‘domain_name’: {‘potentials’: np.ndarray, ‘r_coords_dict’: dict, ‘z_coords_dict’: dict}}}

Data Access and Export

These methods are the primary public interface for interacting with a populated Results object.

get_results()

Get the stored results as an xarray Dataset.

Returns:

xarray.Dataset containing the results.

display_results()

Display the stored results in a readable format.

Returns:

String representation of the results.

export_to_netcdf(file_path: str)

Exports the dataset to a NetCDF file. Complex values are split into real and imaginary parts for compatibility.