Basic Region Geometry Module

Conceptual Overview

The BasicRegionGeometry class is the primary concrete implementation of the abstract Geometry class. It is designed for the most common use case: a set of simple, concentric bodies whose radii are strictly increasing from the center outwards.

Its main responsibility is to take a physical description of the bodies (via a ConcentricBodyGroup) and automatically partition the fluid volume into a series of non-overlapping Domain objects. This process is crucial as it translates the user-defined physical problem into the structured set of sub-regions required by the MEEMEngine for solving.

Primary Usage (Object-Oriented)

The standard way to use this class is by first defining your physical objects and then passing them to the constructor.

from openflash import SteppedBody, ConcentricBodyGroup, BasicRegionGeometry

# 1. Define the physical bodies
body1 = SteppedBody(a=np.array([5.0]), d=np.array([20.0]), heaving=True)
body2 = SteppedBody(a=np.array([10.0]), d=np.array([10.0]), heaving=False)

# 2. Group the bodies into an arrangement
arrangement = ConcentricBodyGroup(bodies=[body1, body2])

# 3. Define other parameters
h = 100.0  # Total water depth
NMK = [30, 30, 30] # Harmonics for inner, middle, and outer domains

# 4. Create the Geometry object
# This object will automatically generate the fluid domains internally.
geometry = BasicRegionGeometry(
    body_arrangement=arrangement,
    h=h,
    NMK=NMK
)

Alternative Usage (Vector-Based)

For convenience, the classmethod from_vectors() allows you to create a BasicRegionGeometry instance directly from NumPy arrays without explicitly creating SteppedBody objects. This can be useful for scripting or when working with data from other sources.

from openflash import BasicRegionGeometry
import numpy as np

# Define geometry using simple arrays
a_vals = np.array([5.0, 10.0])
d_vals = np.array([20.0, 10.0])
heaving_flags = [True, False]
h = 100.0
NMK = [30, 30, 30]

# Create the geometry object directly from vectors
geometry = BasicRegionGeometry.from_vectors(
    a=a_vals,
    d=d_vals,
    h=h,
    NMK=NMK,
    heaving_map=heaving_flags
)

API Reference

class openflash.basic_region_geometry.BasicRegionGeometry(body_arrangement: ConcentricBodyGroup, h: float, NMK: List[int])[source]

Bases: Geometry

A geometry where body radii are increasing from the center.

This configuration results in a simple, non-overlapping series of circular fluid domains, where the mapping from bodies to domains is trivial.

Parameters:

  • body_arrangement (ConcentricBodyGroup) – A group of concentric bodies.

  • h (float) – The total water depth.

  • NMK (List[int]) – List of the number of harmonics for each resulting domain.

property domain_list: dict

Returns a dictionary of domains keyed by index. Required for MEEMEngine compatibility.

classmethod from_vectors(a: ndarray, d: ndarray, h: float, NMK: List[int], slant_angle: ndarray | None = None, body_map: List[int] | None = None, heaving_map: List[bool] | None = None)[source]

Method to create a BasicRegionGeometry from vector inputs. This is useful for users who prefer to define the geometry directly without explicitly creating Body objects. This version includes robust validation to prevent invalid body_map/heaving_map combinations and enforces the global monotonicity invariant required by BasicRegionGeometry.

make_fluid_domains() → List[Domain][source]

Creates a list of fluid domains for the simple concentric case.