MEEM Engine

Conceptual Overview

The MEEMEngine is the central processing unit of the OpenFLASH package. It takes one or more MEEMProblem objects and orchestrates the entire simulation process, from assembling the mathematical system to calculating the final physical results.

The engine is designed around an internal caching system (ProblemCache) that significantly optimizes performance, especially when running simulations over multiple frequencies. It pre-calculates parts of the system that are frequency-independent and stores functions to efficiently compute the frequency-dependent parts.

Primary Workflows

There are two primary ways to use the MEEMEngine:

1. Single Frequency Analysis: This workflow is ideal for detailed inspection of the system at a single wave frequency. The user typically calls solve_linear_system_multi() to get the solution vector, then uses that vector with post-processing methods like calculate_potentials() or calculate_velocities() to generate spatial field data for visualization.

2. Frequency Sweep Analysis: This is the most common and powerful workflow. The user configures a MEEMProblem with a range of frequencies and then makes a single call to the run_and_store_results() method. The engine handles the entire loop internally, solving the system for each frequency and packaging all the hydrodynamic coefficients into a convenient Results object.

API Reference

class openflash.meem_engine.MEEMEngine(problem_list: List[MEEMProblem])

Manages multiple MEEMProblem instances and performs actions such as solving systems of equations, assembling matrices, and visualizing results.

Core Solver Methods

These are the main methods for running simulations.

solve_linear_system_multi(problem: MEEMProblem, m0) → ndarray

Solve the linear system A x = b for the given problem (multi-region, optimized).

run_and_store_results(problem_index: int) → Results

Perform the full MEEM computation for all frequencies defined in the selected MEEMProblem, and store results in a Results object.

This method correctly solves the N-body radiation problem by:

• Looping through each frequency.

• Looping through each radiating mode i (inferred from the problem’s heaving flags).

• Creating a temporary problem where only body i heaves.

• Solving for the potential X_i from this single radiation.

• Calculating the forces on all bodies j from X_i to get column i of the hydrodynamic matrices (A_ji, B_ji).

• Storing the full N x N matrices.

• Storing the potential coefficients Cs_i for each radiation problem.

Post-Processing & Analysis Methods

These methods are used after solving the system to compute physical quantities.

compute_hydrodynamic_coefficients(problem, X, m0, modes_to_calculate: ndarray | None = None)

Compute hydrodynamic coefficients (added mass and damping) for each mode defined in the problem.

Parameters:

• problem – Problem object containing the geometry

• X – Solution vector from eigenfunction solver

• m0 – Mode number (used for omega and excitation terms)

• modes_to_calculate – A list of all body indices to calculate forces for. If None, defaults to problem.modes (which infers from the problem’s own geometry’s heaving flags).

Returns:

List of dictionaries, one per mode, with hydrodynamic properties

calculate_potentials(problem, solution_vector: ndarray, m0, spatial_res, sharp) → Dict[str, Any]

Calculate full spatial potentials phiH, phiP, and total phi on a meshgrid for visualization.

Parameters: - problem: MEEMProblem instance containing domain and geometry info - solution_vector: solution vector X from linear system solve - spatial_res: resolution of spatial grid for R and Z (default=50) - sharp: whether to refine meshgrid near boundaries (default=True)

Returns: - Dictionary containing meshgrid arrays R,Z and potentials phiH, phiP, phi

calculate_velocities(problem, solution_vector: ndarray, m0, spatial_res, sharp) → Dict[str, Any]

Calculate full spatial velocities vr and vz on a meshgrid for visualization.

Utility & Visualization Methods

reformat_coeffs(x: ndarray, NMK, boundary_count) → list[ndarray]

Reformats a single vector of coefficients (x) into a list of lists, where each inner list contains the coefficients for a specific region. This output is typically used for plotting or detailed analysis per region.

Parameters:

x – The single, concatenated solution vector of coefficients.

Returns:

A list of NumPy arrays, where each array corresponds to the coefficients of a particular fluid region.

visualize_potential(field, R, Z, title)

Creates a contour plot of a potential field.

Returns:

A tuple containing the Matplotlib figure and axes objects (fig, ax).

Return type:

tuple