PyFluent API Limitation: Cannot Extract Local Wall Data at Arbitrary Axial Positions

# PyFluent API Limitation: Cannot Extract Local Wall Data at Arbitrary Axial Positions

## Summary

Attempting to extract local heat transfer coefficient (HTC) at arbitrary axial positions in a multi-zone CHT simulation fails due to PyFluent API limitations. This capability is required for entry length studies and validation of developing flow regions.

**Impact**: Blocks validation of entry length corrections for industrial heat exchanger design, where flow enters tubes from branch connections in developing state.

**Status**: Partially solved (iso-surface creation fixed), but fundamental limitation remains with extracting wall boundary data.

---

## Problem Description

### Objective
Extract local HTC at multiple axial stations (x/D = 0.5, 1.0, 1.5, ..., 10.0) along internal pipe flow to characterize thermal entry length effects:

```
h_local(x) = |Q(x)| / (A(x) × |T_wall(x) - T_bulk(x)|)
```

### Geometry Context
- **Multi-zone CHT**: External crossflow (exhaust gas @ 700K) + Internal pipe flow (ammonia-air @ 300-362K) + Solid tube walls
- **Goal**: Extract h(x) from internal flow only, not contaminated by external flow
- **Challenge**: Need wall interface data (heat flux, temperature) at specific X coordinates

---

## What Works ✅

### 1. ISO Surface Creation (Settings API)
Successfully fixed using Settings API instead of TUI:

```python
# ✅ WORKS - Creates iso-surface at X coordinate
solver.settings.results.surfaces.iso_surface["wall_ring_1"] = {}
solver.settings.results.surfaces.iso_surface["wall_ring_1"].field = "x-coordinate"
solver.settings.results.surfaces.iso_surface["wall_ring_1"].iso_values = [0.027395] # Must be list!
```

**Key learnings**:
- TUI `solver.tui.surface.iso_surface(...)` has inconsistent syntax and fails with "invalid command"
- Settings API is reliable and documented in PyFluent examples
- `iso_values` must be a list even for single value

### 2. Plane Surface Creation (Settings API)
```python
# ✅ WORKS - Creates plane at X coordinate
plane = solver.settings.results.surfaces.plane_surface.create(name="station_1")
plane.method = "yz-plane"
plane.x = 0.027395
```

### 3. Temperature Extraction from ISO Surface
```python
# ✅ WORKS - Gets temperature from iso-surface
T_wall = get_area_weighted_avg(solver, ["wall_ring_1"], "temperature")
# Returns ~700K (average across all zones cut by iso-surface)
```

---

## What Doesn't Work ❌

### 1. Zone Restriction for Plane Surfaces

**Expected behavior** (from PyFluent examples):
```python
plane = solver.settings.results.surfaces.plane_surface.create(name="station_1")
plane.method = "yz-plane"
plane.x = 0.027395
plane.zone_names = ["fluid-internal-1"] # Should restrict to this zone
```

**Actual behavior in PyFluent 0.37.1**:
```
AttributeError: 'plane_surface_child' object has no attribute 'zone_names'.
The most similar names are: name.
```

**Impact**:
- Cannot restrict plane to internal fluid zone
- Temperature extraction averages across ALL zones (returns ~700K instead of ~330K)
- Bulk temperature extraction contaminated by external flow

**References**:
- Ansys PyFluent examples show `zone_names` attribute exists in theory
- Attribute not implemented in `plane_surface_child` class in v0.37.1

### 2. Heat Flux Extraction from ISO Surface

**Attempted approach**:
```python
# Create iso-surface at X coordinate
solver.settings.results.surfaces.iso_surface["wall_ring_1"].iso_values = [0.027395]

# Try to extract heat flux
Q_local = get_surface_integral(solver, ["wall_ring_1"], "heat-flux")
# Returns 0.00 W (heat flux not defined on iso-surface)
```

**Root cause**:
- ISO surfaces cut through volume cells at a coordinate value
- Heat flux is only defined on **wall boundary zones** (interfaces between solid-fluid)
- ISO surface at arbitrary X doesn't coincide with wall interface nodes/faces
- Heat flux on volume-cutting surface returns zero

**What's needed**:
- Method to extract wall interface data at specific axial positions
- Possibly: intersection of wall boundary zone with plane at X coordinate
- Or: surface clipping operations that preserve boundary data

---

## Attempted Solutions

### Approach 1: ISO Surface on Wall Zone ❌
```python
solver.tui.surface.iso_surface(
"wall_ring_1",
"solid-tube-1:1", # Wall interface zone
"x-coordinate",
0.027395,
0.027395
)
# Error: "invalid command" - TUI syntax doesn't match expectations
```

### Approach 2: Zone-Restricted Plane Surface ❌
```python
plane = solver.settings.results.surfaces.plane_surface.create(name="station_1")
plane.zone_names = ["fluid-internal-1"]
# AttributeError: 'plane_surface_child' object has no attribute 'zone_names'
```

### Approach 3: Settings API ISO Surface ⚠️ Partial
```python
# Creates surface successfully, but heat flux returns 0.00
solver.settings.results.surfaces.iso_surface["wall_ring_1"].field = "x-coordinate"
solver.settings.results.surfaces.iso_surface["wall_ring_1"].iso_values = [0.027395]
```

---

## What Would Solve This?

### Option A: Zone Restriction Implementation
**Fix PyFluent 0.37.1 to support `zone_names` on dynamically created surfaces:**

```python
# Should work but doesn't in v0.37.1
plane = solver.settings.results.surfaces.plane_surface.create(name="station_1")
plane.method = "yz-plane"
plane.x = 0.027395
plane.zone_names = ["fluid-internal-1"] # ✅ Implement this!
```

**Benefit**: Solves bulk temperature extraction issue

**Limitation**: Still doesn't solve heat flux extraction (iso-surfaces don't carry boundary data)

### Option B: Wall Intersection Surface API
**New API for creating surfaces that preserve boundary data:**

```python
# Hypothetical API - doesn't exist
wall_section = solver.settings.results.surfaces.wall_intersection.create(name="wall_ring_1")
wall_section.wall_zones = ["solid-tube-1:1", "fluid-internal-1-solid-tube-1"]
wall_section.intersect_with_plane = {"method": "yz-plane", "x": 0.027395}

# Would return surface that:
# - Contains only wall boundary faces at X=0.027395
# - Preserves heat flux field data
# - Allows proper HTC calculation
```

### Option C: TUI Command Documentation
**Document correct TUI syntax for iso_surface on wall zones:**

The TUI command exists but syntax is unclear. If this pattern works, document it:
```python
# What's the correct signature?
solver.tui.surface.iso_surface(???)
```

---

## Workarounds

### Current Approach: Theoretical Correlations
Using well-validated entry length correlation instead of CFD extraction:
```
h_local(x) = h_fd × [1 + (D/x)^0.67]
```

**Justification**:
- Entry length effects well-established for turbulent pipe flow (Re > 2300)
- Our CFD shows excellent agreement with correlations for:
- External flow: ±8% error
- Fully-developed internal flow: +0.8% error
- Theoretical correlation reliable for design use

**Limitation**: Cannot validate correlation specifically for this geometry/conditions

### Alternative: Export and Post-Process Externally
1. Export CFD solution to file format with boundary data (e.g., EnSight, Tecplot)
2. Use external post-processing tools to extract wall data at X coordinates
3. Import results back for plotting

**Drawback**: Defeats purpose of PyFluent automation

---

## Environment

- **Ansys Fluent**: 2025 R2 (v252)
- **PyFluent**: 0.37.1
- **Python**: 3.10 (via uv)
- **OS**: Windows 10
- **Case Type**: Multi-zone CHT (5 cell zones: 2 fluid, 2 solid, 1 external fluid)

---

## PyFluent Examples Referenced

Successful patterns from Ansys PyFluent repository:

1. **steady_vortex.py**: ISO surface for phase interface
```python
solver_session.settings.results.surfaces.iso_surface.create(name="freesurface")
freesurface = IsoSurface(solver_session, name="freesurface")
freesurface.field = "water-vof"
freesurface.iso_values = [0.5]
```

2. **conjugate_heat_transfer.py**: ISO surface for coordinate slice
```python
solver_session.settings.results.surfaces.iso_surface["x=0.012826"] = {}
solver_session.settings.results.surfaces.iso_surface["x=0.012826"].field = "x-coordinate"
solver_session.settings.results.surfaces.iso_surface["x=0.012826"] = {"iso_values": [0.012826]}
```

**Note**: These examples don't demonstrate:
- Zone restriction on plane surfaces
- Heat flux extraction from iso-surfaces
- Wall boundary data extraction at arbitrary positions

---

## Request for Ansys Team

### Question 1: Zone Restriction
Is `zone_names` supposed to work on dynamically created `plane_surface` objects? If yes:
- Which PyFluent version implements this?
- Is there alternative syntax for v0.37.1?

### Question 2: Wall Data Extraction
What is the recommended approach for extracting heat flux at arbitrary axial positions on wall boundaries?
- Can iso-surfaces preserve boundary data?
- Is there a wall intersection/clipping API?
- Should we use TUI commands instead? (if so, what's the syntax?)

### Question 3: TUI Documentation
Can you provide the correct `solver.tui.surface.iso_surface()` signature for creating iso-surfaces on boundary zones?

---

## Use Case

**Application**: Industrial heat exchanger thermal validation

**Requirement**: Validate thermal entry length corrections for pipe flow that starts from branch connections (developing flow). Standard correlations give fully-developed HTC, but entry region shows 1.5-3× enhancement.

**Next Study**: Similar validation needed for different heat exchanger geometries with varying L/D ratios.

**Why This Matters**: Accurate HTC prediction in entry regions critical for thermal stress analysis and material selection in high-temperature industrial systems.

---

## Acceptance Criteria

Solution allows:
1. ✅ Create iso-surface at arbitrary X coordinate (already works)
2. ❌ Restrict plane surface to specific zone for bulk temperature extraction
3. ❌ Extract heat flux from wall interface at arbitrary X coordinate
4. ❌ Calculate h_local = |Q(x)| / (A(x) × |T_wall(x) - T_bulk(x)|) with all values from correct zones/boundaries

---

**Priority**: Medium (workaround exists, but automation blocked)