# Heat Transfer Simulator

### What is this tool?

The Heat Transfer Simulator is a comprehensive web-based thermal modelling application that enables architects, engineers, and building scientists to create, simulate, and analyze 2D heat transfer models. It provides an integrated environment for geometry creation, material assignment, boundary condition specification, mesh generation, and steady-state heat transfer simulation directly in your browser.

<figure><img src="/files/zxydG4RW8Pw54Qx5hUCY" alt=""><figcaption></figcaption></figure>

Version 1.2 introduces a unified ISO 10211:2017 compliant calculation approach. The solver now automatically detects material properties and selects the optimal calculation method for each case. Use it for preliminary analysis and design exploration, but verify critical results through other means.&#x20;

**Key Capabilities:**

* Visual geometry creation with precision drawing tools including structural steel sections
* Thermal simulation using finite difference analysis
* Material library with 49+ predefined building materials
* Boundary condition management with 6 standard conditions
* Interactive results visualization including temperature contours and heat flux vectors
* U-value and PSI-value calculation for thermal performance analysis
* JSON model save/load for complete project persistence

{% hint style="info" %}
This is version 1.0 Beta, which means we're releasing it knowing there's more to learn, more to refine. Use it for preliminary analysis and design exploration, but verify critical results through other means. Use at your own risk. It requires no installation and runs entirely in your web browser. For support or feature requests, please contact <support@betterbuilding.io> for support or use the [Support Ticket](https://docs.betterbuilding.io/support-and-training/support-tickets) system.
{% endhint %}

{% hint style="success" %}
Register and download the tool [here](https://tinyurl.com/7xsfay3z)
{% endhint %}

***

### V1.2 Changes&#x20;

Version 1.2 unifies Standard Mode and Validation Mode under a single ISO 10211:2017 compliant calculation approach:

#### 1. Aspect-Ratio-Aware Gridding (Always Enabled)

* Ensures square cells for all simulations
* Prevents directional bias in the Laplacian operator
* Maintains consistent accuracy across all domain shapes

#### 2. Exact Geometry Bounds (No Padding)

* Removed 50mm padding from bounds calculation
* Ensures perfect alignment between polygon edges and grid boundaries
* Fixes boundary condition detection and enforcement issues

#### 3. Auto-Detect Uniform Conductivity

* New `detectUniformConductivity()` function automatically selects optimal solver
* Uses simple Laplacian for uniform k (validated against ISO 10211)
* Uses harmonic mean solver for multi-material (ISO 10211 compliant)

#### 4. Automatic Solver Selection

* Removed manual `forceISO10211Solver` override
* Solver branch selected based on conductivity variation (1% threshold)

#### Solver Behavior:

| Condition                      | Solver Used                               |
| ------------------------------ | ----------------------------------------- |
| Uniform k (variation ≤1%)      | Simple 5-point Laplacian with SOR (ω=1.5) |
| Multi-material (variation >1%) | Harmonic mean interface conductivity      |

Both solvers are ISO 10211:2017 compliant. The auto-detection ensures optimal accuracy for each case.

***

### Key Features

#### Geometry Creation

* **Precision Drawing Tools**: Rectangle, polygon, and line drawing with snap-to-grid
* **Steel Section Library**: 8 standard structural steel sections (H-Shape, I-Shape, Channel, Angles, T-Shape, SHS, RHS)
* **Steel Section Auto-Cut**: Steel sections automatically cut through underlying materials when placed
* **Precise Polygon Tool**: Enter exact dimensions for each segment
* **Edge Management**: Add, edit, and delete edges with visual feedback
* **Layer Organization**: Multi-layer support with visibility control
* **DXF Import/Export**: Import geometry from AutoCAD and other CAD software

#### Material & BC Management

* **49+ Predefined Materials**: Complete thermal materials library organized by category
* **6 Built-in Boundary Conditions**: Standard interior, exterior, and adiabatic conditions
* **Visual Feedback**: Color-coded materials and BCs with interactive assignment
* **Custom Materials**: Create and manage custom thermal materials with full property editing
* **Custom BCs**: Define custom boundary conditions with specific parameters
* **Thin Material Warning**: Automatic notification when materials < 5mm thickness require finer grid resolution

#### Simulation & Analysis

* **Finite Difference Solver**: Heat transfer simulation using Gauss-Seidel iteration
* **ISO 10211 Unified Solver** (V1.2): Automatic solver selection based on material properties
* **Temperature Visualization**: Interactive contour plots with customizable color schemes and ranges
* **Heat Flux Analysis**: Vector field visualization of heat flow
* **U-Value Calculation**: Automatic thermal transmittance calculation
* **PSI-Value Calculation**: Linear thermal transmittance for thermal bridges (ISO 10211)
* **Convergence Monitoring**: Real-time iteration tracking

#### Legend Settings

* **Color Schemes**: 6 options - THERM (default), Rainbow, Blue-Red, Grayscale, Viridis, Hot
* **Temperature Range**: Auto (from simulation results) or Manual (user-defined min/max)
* **Apply Settings**: Update visualization without re-running simulation

#### File Management

* **JSON Save**: Export complete model including geometry, materials, BCs, measurements, and view settings
* **JSON Open**: Import previously saved models
* **DXF Export**: Export geometry for CAD software
* **DXF Import**: Import geometry from AutoCAD

***

### System Requirements

#### Browser Compatibility

* Chrome 90+ (Recommended)
* Firefox 88+
* Edge 90+
* Safari 14+

#### Hardware

* **Minimum**: 4GB RAM, modern dual-core processor
* **Recommended**: 8GB+ RAM, quad-core processor for large models
* **Display**: 1920x1080 or higher resolution recommended

#### Network

* Internet connection required for initial load (CDN resources)
* Offline use possible after initial load (application cached)

***

### Access

The Heat Transfer Simulator is a standalone HTML file that runs entirely in your web browser:

1. Register and download `Heat_Transfer_Simulator_V1.2.html`
2. Double-click to open in your default browser
3. No installation or server required
4. All processing happens locally in your browser

***

### Basic Workflow (7 Steps)

#### Step 1: Set Up Grid and Snapping

**Top Control Bar:**

* Set grid spacing (default: 10mm)
* Enable/disable grid visibility
* Enable/disable snap-to-grid
* Configure snap modes (Grid, Vertex, Edge, Ortho)

**Recommended Settings:**

```
Grid Spacing: 10mm (for precision)
Grid Visible: Yes
Snap to Grid: Yes
Snap Modes: Grid + Vertex enabled
```

#### Step 2: Draw Geometry

**Drawing Tools (Toolbar):**

* **Polygon Tool** (default): Click points, right-click or click near first point to close
* **Precise Polygon Tool**: Click points, enter dimensions for each segment
* **Rectangle Tool**: Click two corners to create rectangle
* **Steel Section Tool**: Select section type, set dimensions, click to place
* **Select Tool**: Click to select layers for editing

**Best Practices:**

* Work from outside to inside (exterior walls first)
* Use consistent dimensions (multiples of grid spacing)
* Close all polygons (no open shapes)
* Avoid overlapping or gaps between materials

**Example - Simple Wall:**

```
1. Select Rectangle Tool
2. Click at (0, 0)
3. Click at (300, 2400) - creates 300mm × 2400mm wall
4. Layer automatically created
```

#### Step 3: Insert Steel Sections (Optional)

For structural steel elements:

1. Click Steel Section button (H-icon) in toolbar
2. Select section type from dropdown (H-Shape, I-Shape, Channel, etc.)
3. Adjust dimensions as needed (Height, Width, Thicknesses)
4. Choose material (Steel, Stainless Steel, Aluminum, Copper)
5. Click "Click to Place"
6. Click on canvas to position section
7. Section extends down and to the right from click point
8. With Auto-cut enabled: Steel automatically cuts through any underlying materials

**Available Steel Sections:**

| Section       | Default Size | Key Parameters       |
| ------------- | ------------ | -------------------- |
| H-Shape       | 200×200mm    | H, B, tw=8, tf=12    |
| I-Shape       | 200×100mm    | H, B, tw=5.5, tf=8.5 |
| Channel       | 150×75mm     | H, B, tw=6, tf=9     |
| Unequal Angle | 100×75mm     | L1, L2, t=8          |
| Equal Angle   | 75×75mm      | L, t=6               |
| T-Shape       | 100×100mm    | H, B, tw=6, tf=10    |
| SHS           | 100×100mm    | H=B, t=5             |
| RHS           | 150×100mm    | H, B, t=5            |

#### Step 4: Assign Materials to Layers

**Material Assignment:**

1. Select a layer in the Layers panel (right sidebar)
2. Click the palette icon or choose material from Materials dropdown
3. Layer updates with material color
4. Repeat for all layers

**Material Categories:**

* Metals (7 materials)
* Insulation (8 materials)
* Wood (6 materials)
* Masonry (10 materials)
* Glass (3 materials)
* Plastics (4 materials)
* Boards (3 materials)
* Membranes (2 materials)
* Air (2 materials)
* Other (4 materials)

**Visual Feedback:**

* Each material has a distinct color
* Selected layer highlights in red
* Material name and k-value display in Layers panel

#### Step 5: Assign Boundary Conditions to Edges

**BC Assignment Process:**

1. Select "BC" mode from toolbar
2. Hover over edges to highlight them
3. Click on an edge to select it
4. Choose BC from dropdown in sidebar
5. Edge color updates to BC color
6. Repeat for all boundary edges

**BC Types:**

| BC Type              | h (W/m²·K) | Temp (°C) | Use                 |
| -------------------- | ---------- | --------- | ------------------- |
| Interior, horizontal | 7.692      | 20        | Vertical walls      |
| Interior, upwards    | 10.0       | 20        | Ceiling surfaces    |
| Interior, downwards  | 5.882      | 20        | Floor surfaces      |
| Exterior, air        | 25.0       | 0         | Exposed exterior    |
| Exterior, ventilated | 7.692      | 0         | Ventilated cavities |
| Adiabatic            | 0.0        | N/A       | Symmetry planes     |

**Auto-Assignment:**

* Interior edges between materials automatically treated as continuous
* Only assign BCs to exterior/boundary edges
* Adiabatic for cut planes and symmetry boundaries

#### Step 6: Run Simulation

**Simulation Panel (Settings):**

* Set grid resolution (default: 75×75)
* Set convergence tolerance (default: 0.0001°C)
* Set maximum iterations (default: 2000)
* Click "Run Simulation"
* Monitor convergence in real-time

**V1.2 Auto-Detection:** The solver automatically detects whether your model has uniform or varying thermal conductivity and selects the appropriate solver branch. Check the browser console for messages like:

* `"ISO 10211 unified (V1.2): Uniform conductivity detected..."` → Simple Laplacian
* `"ISO 10211 unified (V1.2): Multi-material detected..."` → Harmonic mean solver

**Thin Material Warning:** If any material is less than 5mm thick, a warning will appear recommending higher grid resolution.

**Simulation Parameters:**

* **Grid Resolution**: 50 (fast) to 200 (accurate)
* **Convergence Tolerance**: Maximum temperature change between iterations
* **Max Iterations**: Safety limit to prevent infinite loops
* **Typical Time**: 5-30 seconds for most models

**Convergence Monitoring:**

```
Iteration 100: Max ΔT = 0.543°C
Iteration 200: Max ΔT = 0.012°C
Iteration 287: Max ΔT = 0.00009°C ✓ CONVERGED
```

#### Step 7: Visualize Results

**Visualization Controls (Status Bar):**

* **Contour**: Toggle temperature contours on/off
* **Labels**: Toggle BC/measurement labels
* **Opacity-/+**: Adjust contour transparency (10% increments)
* **Fit**: Zoom to fit all geometry

**Results Modal (View Results button):**

* **Temperature Field**: Color-coded temperature distribution with isotherms
* **Material Distribution**: Thermal conductivity map (log scale)
* **Heat Flux Magnitude**: Heat flow intensity visualization
* **Heat Flux Vectors**: Arrows showing heat flow direction and magnitude

**Legend Settings (in Settings modal):**

* **Color Scheme**: Choose from 6 visualization schemes
* **Temperature Range**: Auto or Manual min/max values
* **Apply to Current**: Update visualization without re-running simulation

**Analysis Tools:**

* **U-Line**: Draw line through assembly to calculate U-value
* **U-Span**: 3-point measurement for equivalent U-value
* **PSI**: 6-point measurement for linear thermal transmittance
* **Dim**: Measure and annotate distances
* **Clear**: Remove all measurements

***

### Steel Section Tool

The Steel Section Tool allows rapid insertion of standard structural steel profiles commonly found in building construction.

#### Auto-Cut Feature

When Auto-cut is enabled (default), steel sections automatically cut through any underlying materials:

* Steel shape is subtracted from overlapping layers
* Boundary conditions on affected edges are cleared
* Internal edges (steel-to-material interface) are created
* Assign new BCs to exposed edges after placement

#### Section Types

**Solid Sections:**

| Type          | Description                      | Parameters   |
| ------------- | -------------------------------- | ------------ |
| H-Shape       | Wide flange beam (equal flanges) | H, B, tw, tf |
| I-Shape       | Standard I-beam (narrow flanges) | H, B, tw, tf |
| Channel       | C-channel section                | H, B, tw, tf |
| T-Shape       | T-section beam                   | H, B, tw, tf |
| Unequal Angle | L-section with unequal legs      | L1, L2, t    |
| Equal Angle   | L-section with equal legs        | L, t         |

**Hollow Sections:**

| Type | Description                | Parameters |
| ---- | -------------------------- | ---------- |
| SHS  | Square Hollow Section      | H (=B), t  |
| RHS  | Rectangular Hollow Section | H, B, t    |

#### Material Options

| Material        | k (W/m·K) | Color        |
| --------------- | --------- | ------------ |
| Steel           | 45        | Dark Gray    |
| Stainless Steel | 17        | Light Gray   |
| Aluminum        | 237       | Silver       |
| Copper          | 380       | Orange-Brown |

#### Thermal Bridge Analysis

Steel sections are significant thermal bridges due to their high conductivity. Use the PSI tool to quantify the additional heat loss:

1. Place steel section in wall assembly
2. Run simulation
3. Use PSI tool to measure linear thermal transmittance
4. Compare with 1D calculation to determine thermal bridge effect

***

### Measurement Tools

#### U-Value Line (U-Line)

Measures thermal transmittance through a building assembly section.

**Usage:**

1. Select U-Line tool from toolbar
2. Click start point (typically on Interior BC)
3. Click end point (typically on Exterior BC)
4. U-value calculates and displays on the line

#### U-Value Span (U-Span)

Measures equivalent U-value using surface heat flux (3-point workflow).

**Usage:**

1. Select U-Span tool from toolbar
2. Click start of interior surface
3. Click end of interior surface
4. Click reference point on exterior
5. Equivalent U-value calculated from total heat flow

#### PSI-Value Line (PSI)

Measures linear thermal transmittance for thermal bridges per ISO 10211.

**6-Point Measurement Process:**

| Point | Description                                        |
| ----- | -------------------------------------------------- |
| 1     | External start point (first construction)          |
| 2     | External reference point (defines external offset) |
| 3     | External end point (second construction)           |
| 4     | Internal start point (first construction)          |
| 5     | Internal reference point (defines internal offset) |
| 6     | Internal end point (second construction)           |

**Calculation:**

```
ψ = L₂D - Σ(Uᵢ × lᵢ)
```

#### Dimension Tool (Dim)

Adds dimension annotations to the model.

**Usage:**

1. Select Dim tool from toolbar
2. Click start point of measurement
3. Click end point of measurement
4. Click reference point to set dimension offset side
5. Dimension displays in meters

#### Clear Measurements

Removes all U-value lines, U-value spans, PSI lines, and dimensions from the model.

***

### File Import/Export

#### JSON Save/Open

Complete model persistence including:

* All layers with geometry and materials
* Boundary conditions
* U-value lines, U-value spans, PSI lines
* Dimensions
* View settings (pan, zoom, grid)

**Usage:**

* **Save**: Click Save button → downloads .json file
* **Open**: Click Open button → select .json file to load

#### DXF Export/Import

Geometry exchange with CAD software:

* **DXF Export**: Exports layer geometry only
* **DXF Import**: Imports geometry from AutoCAD/CAD files

***

### Settings

#### Legend Settings

* **Color Scheme**: THERM (default), Rainbow, Blue-Red, Grayscale, Viridis, Hot
* **Temperature Range**:
  * Auto: Uses min/max from simulation results
  * Manual: User-defined min/max for comparing multiple models
  * Use Auto button: Copies current simulation range to manual inputs
* **Apply to Current**: Updates visualization without re-running simulation

#### Solver Settings

* **Grid Resolution**: 50 (fast) to 200 (accurate)
* **Max Iterations**: Default 2000
* **Convergence Tolerance**: Default 0.0001°C
* **Adiabatic BC Mode**: Fixed Temperature or Zero Flux (true adiabatic)
* **Number of Contours**: 5-50 isotherms

#### V1.2 Solver Information

The solver now displays which calculation branch is being used in the browser console:

* `uniform (ISO 10211 V1.2 - auto-detected uniform k)` - For homogeneous materials
* `advanced (ISO 10211 V1.2 - harmonic mean for multi-material)` - For multi-material models
* `kField (ISO 10211 V1.2 - harmonic mean for multi-material)` - Alternative multi-material path

***

### Default Model

The tool loads with a demonstration wall detail showing steel thermal bridging:

**Construction (exterior to interior):**

* 100mm Concrete (k=1.4 W/m·K) - structural
* 100mm Glass Wool (k=0.038 W/m·K) - insulation
* Steel frame (k=45 W/m·K) - 5mm flanges & webs with air cavity
* 10mm Gypsum Board (k=0.25 W/m·K) - interior finish

**Boundary Conditions:**

* Exterior: 0°C with h=7.692 W/(m²·K)
* Interior: 20°C with h=7.692 W/(m²·K)
* Adiabatic: Cut edges (symmetry planes)

This detail demonstrates steel thermal bridging through insulation and is ideal for PSI-value and U-value analysis.

***

### Material & Boundary Condition Library

#### Metals (7 materials)

| Material        | k (W/m·K) | ε    | Color      |
| --------------- | --------- | ---- | ---------- |
| Aluminum        | 160.0     | 0.05 | Silver     |
| Steel           | 45.0      | 0.20 | Dark Gray  |
| Stainless Steel | 17.0      | 0.15 | Light Gray |
| Copper          | 380.0     | 0.05 | Orange     |
| Brass           | 120.0     | 0.05 | Gold       |
| Bronze          | 65.0      | 0.10 | Brown      |
| Zinc            | 112.0     | 0.05 | Blue-Gray  |

#### Insulation (8 materials)

| Material               | k (W/m·K) | ε    | Color        |
| ---------------------- | --------- | ---- | ------------ |
| Fiberglass             | 0.040     | 0.90 | Light Pink   |
| Mineral Wool           | 0.038     | 0.90 | Gray-Pink    |
| XPS                    | 0.029     | 0.90 | Light Blue   |
| EPS                    | 0.033     | 0.90 | White        |
| Polyurethane           | 0.023     | 0.90 | Yellow       |
| Polyisocyanurate (PIR) | 0.022     | 0.90 | Orange       |
| Cellulose              | 0.039     | 0.90 | Beige        |
| Spray Foam             | 0.026     | 0.90 | Light Yellow |

#### Wood (6 materials)

| Material           | k (W/m·K) | ε    | Color        |
| ------------------ | --------- | ---- | ------------ |
| Wood-Softwood      | 0.12      | 0.90 | Light Brown  |
| Wood-Hardwood      | 0.16      | 0.90 | Dark Brown   |
| Wood-Plywood       | 0.13      | 0.90 | Tan          |
| Wood-OSB           | 0.13      | 0.90 | Orange-Brown |
| Wood-Particleboard | 0.17      | 0.90 | Medium Brown |
| Wood-MDF           | 0.14      | 0.90 | Gray-Brown   |

#### Masonry (10 materials)

| Material              | k (W/m·K) | ε    | Color       |
| --------------------- | --------- | ---- | ----------- |
| Concrete-Normal       | 1.40      | 0.90 | Gray        |
| Concrete-Lightweight  | 0.80      | 0.90 | Light Gray  |
| Concrete Block-Hollow | 0.60      | 0.90 | Medium Gray |
| Concrete Block-Solid  | 1.00      | 0.90 | Dark Gray   |
| Brick-Common          | 0.70      | 0.90 | Red         |
| Brick-Face            | 1.00      | 0.90 | Dark Red    |
| Stone-Granite         | 2.80      | 0.90 | Dark Gray   |
| Stone-Limestone       | 1.50      | 0.90 | Beige       |
| Stone-Sandstone       | 1.70      | 0.90 | Tan         |
| Mortar                | 0.80      | 0.90 | Light Gray  |

#### Glass (3 materials)

| Material     | k (W/m·K) | ε           | Color      |
| ------------ | --------- | ----------- | ---------- |
| Glass-Clear  | 1.00      | 0.84        | Light Blue |
| Glass-Low-E  | 1.00      | 0.10/0.84\* | Blue       |
| Glass-Tinted | 1.00      | 0.84        | Dark Blue  |

\*Low-E glass: εfront=0.10, εback=0.84

#### Plastics (4 materials)

| Material     | k (W/m·K) | ε    | Color       |
| ------------ | --------- | ---- | ----------- |
| PVC          | 0.17      | 0.90 | White       |
| EPDM Rubber  | 0.25      | 0.90 | Black       |
| Polyethylene | 0.42      | 0.90 | Translucent |
| Acrylic      | 0.20      | 0.90 | Clear       |

#### Boards (3 materials)

| Material     | k (W/m·K) | ε    | Color     |
| ------------ | --------- | ---- | --------- |
| Gypsum Board | 0.16      | 0.90 | Off-White |
| Plaster      | 0.50      | 0.90 | White     |
| Cement Board | 0.25      | 0.90 | Gray      |

#### Membranes (2 materials)

| Material             | k (W/m·K) | ε    | Color       |
| -------------------- | --------- | ---- | ----------- |
| Air Barrier Membrane | 0.20      | 0.90 | Light Green |
| Vapor Barrier        | 0.16      | 0.90 | Light Blue  |

#### Air (2 materials)

| Material   | k (W/m·K) | ε    | Color           |
| ---------- | --------- | ---- | --------------- |
| Air-Cavity | 0.026     | 1.00 | Very Light Blue |
| Air-Still  | 0.024     | 1.00 | Pale Blue       |

#### Built-in Boundary Conditions

| BC Name              | h (W/m²·K) | Temp (°C) | Use               |
| -------------------- | ---------- | --------- | ----------------- |
| Interior, upwards    | 10.0       | 20        | Ceiling surfaces  |
| Interior, downwards  | 5.882      | 20        | Floor surfaces    |
| Interior, horizontal | 7.692      | 20        | Vertical walls    |
| Exterior, air        | 25.0       | 0         | Exposed exterior  |
| Exterior, ventilated | 7.692      | 0         | Ventilated cavity |
| Adiabatic            | 0.0        | N/A       | Symmetry planes   |

***

### Keyboard Shortcuts

#### General Shortcuts

| Key    | Action                                           |
| ------ | ------------------------------------------------ |
| Esc    | Cancel current operation / Return to select tool |
| Delete | Delete selected layer(s)                         |

#### View Shortcuts

| Key        | Action      |
| ---------- | ----------- |
| Scroll     | Zoom in/out |
| Shift+Drag | Pan view    |

#### Drawing Shortcuts

| Key                    | Action         |
| ---------------------- | -------------- |
| Right-click            | Finish polygon |
| Click near first point | Close polygon  |

***

### Common Issues & Troubleshooting

#### Issue: "Simulation already running" Error

**Symptoms:**

* Cannot start new simulation
* Button appears disabled or shows warning

**Solutions:**

* Wait for current simulation to complete
* Refresh the page to reset simulation state
* Clear simulation results using "Remove Results" button

#### Issue: Steel Section Not Appearing

**Symptoms:**

* Click on canvas but no geometry appears
* Console shows errors

**Solutions:**

* Ensure you clicked "Click to Place" button in modal first
* Check that modal closed after clicking the button
* Click within the canvas boundaries
* Verify material exists in database (Steel, Stainless Steel, Aluminum, Copper)

#### Issue: Steel Section Not Cutting Through Material

**Symptoms:**

* Steel placed on top of insulation but doesn't cut it

**Solutions:**

* Ensure "Auto-cut" checkbox is enabled in top toolbar
* Steel will only cut layers that existed before placement

#### Issue: Boundary Conditions Not Assigning

**Symptoms:**

* Edge doesn't change color when clicked
* BC doesn't appear on edge

**Solutions:**

* Ensure "BC" mode is active (button highlighted)
* Click directly on edge line, not nearby
* Hover over edge first to see highlight
* Check that both Interior and Exterior BCs are assigned before simulation

#### Issue: No Contours Displayed After Simulation

**Symptoms:**

* Simulation completes but no temperature visualization
* Contour button doesn't show results

**Solutions:**

* Click "Contour" button in status bar to enable display
* Check that simulation actually converged (no error messages)
* Verify geometry has valid boundary conditions
* Try "View Results" button for detailed visualizations

#### Issue: Thin Material Warning

**Symptoms:**

* Warning appears about thin material and grid resolution

**Solutions:**

* Open Settings → Solver Settings
* Increase Grid Resolution (125+ for materials 3-5mm, 150+ for 2-3mm, 200 for <2mm)
* Warning is informational - simulation will still run

#### Issue: Simulation Won't Converge

**Symptoms:**

* Maximum iterations reached
* Final residual above tolerance

**Solutions:**

* Increase max iterations in Settings (try 5000)
* Increase grid resolution for complex geometry
* Check boundary conditions are correctly assigned
* Verify material properties are reasonable (no zero conductivity)
* Simplify model geometry if very complex

#### Issue: JSON Import Fails

**Symptoms:**

* Error message when opening saved model

**Solutions:**

* Ensure file is valid JSON format
* Check file was exported from this tool (version 1.2)
* Try clearing model first, then importing

***

### Best Practices

#### Geometry Creation

* **Start Simple**: Create basic geometry first, add complexity gradually
* **Use Actual Scale**: Model at 1:1 scale in millimeters
* **Clean Geometry**: No overlapping faces, no gaps between materials
* **Close Polygons**: Ensure all shapes are properly closed

#### Steel Section Placement

* **Consider Thermal Bridging**: Steel has high conductivity (k=45 W/m·K)
* **Use Thermal Breaks**: Add insulation around steel sections where possible
* **Check Dimensions**: Verify section sizes match actual specifications
* **Multiple Sections**: Place each section separately for complex frames
* **Enable Auto-cut**: Allows steel to replace underlying materials

#### Material Assignment

* **Systematic Approach**: Work from outside to inside
* **Verify Properties**: Check k-values match manufacturer data
* **Use Validation**: Run model validation before simulation

#### Boundary Conditions

* **Minimum Requirements**: At least one Interior and one Exterior BC
* **Adiabatic Planes**: Use for symmetry and cut boundaries
* **Correct Direction**: Interior upwards for ceilings, downwards for floors

#### Simulation Settings

| Use Case              | Grid Resolution | Tolerance | Max Iterations |
| --------------------- | --------------- | --------- | -------------- |
| Quick Check           | 50×50           | 0.001     | 1000           |
| Standard Analysis     | 100×100         | 0.0001    | 2000           |
| Detailed Study        | 150×150         | 0.00001   | 5000           |
| Thin Materials (<5mm) | 150-200         | 0.0001    | 3000           |

***

### Frequently Asked Questions

**Can I use this tool offline?** Partially. After the first load (which requires internet for CDN resources), the application works offline. However, you cannot reload the page without internet.

**What units does the tool use?** Millimeters (mm) for dimensions, °C for temperature, W/m·K for conductivity, and W/m²·K for heat transfer coefficients.

**How do I save and reload my model?** Use the Save button to export a .json file containing your complete model. Use the Open button to reload it later.

**How do steel sections interact with existing layers?** With Auto-cut enabled, steel sections automatically cut through and replace overlapping materials. Boundary conditions on affected edges are cleared and must be reassigned.

**Can hollow sections be modeled correctly?** Yes. SHS and RHS sections are created as 4 separate wall elements, leaving an air cavity in the center for accurate thermal simulation.

**How accurate are the simulation results?** Results are suitable for preliminary analysis and comparative studies. V1.2 uses ISO 10211:2017 compliant solvers with automatic selection for optimal accuracy. For critical applications, verify with dedicated FEA software.

**How do I calculate PSI-values for thermal bridges?** Use the PSI tool which requires 6 points to define external and internal measurement planes per ISO 10211. The tool calculates the linear thermal transmittance automatically.

**What if my model won't converge?** Common causes: (1) missing boundary conditions, (2) unrealistic material properties, (3) grid too coarse. Solutions: check BCs, verify materials, increase resolution and iterations.

**Can I export my model?** Yes. Use JSON Save for complete project persistence, DXF Export for geometry only, or THERM XML export for compatibility with LBNL THERM software.

**How do I change the contour colors?** Open Settings → Legend Settings → Color Scheme. Choose from THERM, Rainbow, Blue-Red, Grayscale, Viridis, or Hot.

**Can I set a fixed temperature range for the legend?** Yes. In Settings → Legend Settings, uncheck "Auto" and enter manual Min/Max values. Useful for comparing multiple simulations with the same scale.

**What solver does V1.2 use?** V1.2 automatically detects material properties and selects: (1) Simple Laplacian for uniform conductivity models, or (2) Harmonic mean interface solver for multi-material models. Both are ISO 10211:2017 compliant.

***

### Underlying Mathematical Equations

The Heat Transfer Simulator solves the steady-state heat conduction equation using the finite difference method. This section describes the governing equations, boundary conditions, and numerical formulation.

#### Governing Equation: Steady-State Heat Conduction

The fundamental equation governing heat transfer by conduction in a solid is Fourier's law combined with energy conservation. For a two-dimensional domain D in steady state (no time dependence), the governing partial differential equation is:

```
∇·(k∇T) = 0  in D
```

Expanded in Cartesian coordinates (x, y):

```
∂/∂x(k·∂T/∂x) + ∂/∂y(k·∂T/∂y) = 0
```

Where:

* T(x,y) = Temperature field \[°C or K]
* k(x,y) = Thermal conductivity \[W/(m·K)]
* ∇ = Gradient operator (del operator)
* ∇· = Divergence operator

**Physical Meaning**: This equation states that in steady state, the net heat flux into any infinitesimal volume must be zero (conservation of energy with no storage term).

#### Fourier's Law of Heat Conduction

The heat flux vector q (heat flow per unit area) is related to the temperature gradient by Fourier's law:

```
q = -k∇T
```

In component form:

```
qₓ = -k·∂T/∂x
qᵧ = -k·∂T/∂y
```

Where:

* q = Heat flux vector \[W/m²]
* qₓ, qᵧ = Heat flux components in x and y directions \[W/m²]
* The negative sign indicates heat flows from hot to cold (down the temperature gradient)

**Magnitude of Heat Flux:**

```
|q| = √(qₓ² + qᵧ²) = k·|∇T|
```

#### Material Properties

**Thermal Conductivity k:**

* Measures a material's ability to conduct heat
* Isotropic materials: k is scalar (same in all directions)
* In Heat Transfer Simulator: k varies spatially but is constant within each material layer
* Higher k → better heat conductor (metals)
* Lower k → better insulator (fiberglass, foam)

**Typical Values:**

```
Metals:      k = 15 - 400 W/(m·K)
Masonry:     k = 0.5 - 3.0 W/(m·K)
Wood:        k = 0.1 - 0.2 W/(m·K)
Insulation:  k = 0.02 - 0.05 W/(m·K)
```

#### Boundary Conditions

The solution requires boundary conditions on the boundary ∂D of the domain. Three types are used:

**1. Dirichlet Boundary Condition (Temperature Specified)**

```
T = T₀  on ∂Dᴅ
```

* Temperature is prescribed directly
* Example: T = 20°C on interior surface
* Strong enforcement (replaces equation at boundary nodes)

**2. Neumann Boundary Condition (Heat Flux Specified)**

```
q·n = -k·∂T/∂n = q₀  on ∂Dₙ
```

Where:

* n = Outward unit normal vector to boundary
* ∂T/∂n = Temperature gradient normal to boundary
* q₀ = Prescribed heat flux \[W/m²]

**Special Case - Adiabatic Boundary:**

```
∂T/∂n = 0  on ∂Dₐ
```

* No heat flux crosses boundary
* Used for symmetry planes and insulated boundaries

**3. Robin (Convective) Boundary Condition**

```
q·n = -k·∂T/∂n = h(T - T∞)  on ∂Dᵣ
```

Where:

* h = Heat transfer coefficient \[W/(m²·K)]
* T∞ = Ambient (fluid) temperature \[°C]
* T = Surface temperature \[°C]

**Physical Meaning**: Heat flux at surface is proportional to temperature difference between surface and ambient fluid (Newton's law of cooling).

**Typical h Values:**

```
Still air (interior):        h = 5 - 10 W/(m²·K)
Moving air (interior):       h = 10 - 20 W/(m²·K)
Exterior (sheltered):        h = 10 - 15 W/(m²·K)
Exterior (exposed/windy):    h = 20 - 40 W/(m²·K)
```

#### Finite Difference Discretization

**Temperature Approximation**: The continuous temperature field T(x,y) is approximated on a regular grid:

```
T(x,y) ≈ Tᵢ,ⱼ  at grid point (i,j)
```

Where:

* i, j = Grid indices in x and y directions
* Δx, Δy = Grid spacing in x and y directions
* Tᵢ,ⱼ = Temperature at grid node (i,j) (unknown)

**Central Difference Approximation:**

For interior nodes, the Laplacian is approximated using central differences:

```
∂²T/∂x² ≈ (Tᵢ₊₁,ⱼ - 2Tᵢ,ⱼ + Tᵢ₋₁,ⱼ) / Δx²
∂²T/∂y² ≈ (Tᵢ,ⱼ₊₁ - 2Tᵢ,ⱼ + Tᵢ,ⱼ₋₁) / Δy²
```

For uniform grid (Δx = Δy = h):

```
Tᵢ,ⱼ = (Tᵢ₊₁,ⱼ + Tᵢ₋₁,ⱼ + Tᵢ,ⱼ₊₁ + Tᵢ,ⱼ₋₁) / 4
```

This is the **5-point stencil** for Laplace's equation.

#### V1.2 Solver Selection (ISO 10211 Unified)

**Material Interface Handling:**

V1.2 automatically detects conductivity uniformity and selects the appropriate method:

**For Uniform Conductivity (variation ≤1%):**

```
Tᵢ,ⱼ = (Tᵢ₊₁,ⱼ + Tᵢ₋₁,ⱼ + Tᵢ,ⱼ₊₁ + Tᵢ,ⱼ₋₁) / 4
```

Simple 5-point Laplacian with SOR (ω=1.5)

**For Multi-Material (variation >1%):**

At interfaces between materials with different conductivities:

```
keff = 2·k₁·k₂ / (k₁ + k₂)
```

This harmonic mean ensures proper heat flux continuity across material boundaries (ISO 10211 compliant).

The weighted temperature update becomes:

```
Tᵢ,ⱼ = (k_east·T_E + k_west·T_W + k_north·T_N + k_south·T_S) / (k_east + k_west + k_north + k_south)
```

#### Solution Method: Gauss-Seidel Iteration

Heat Transfer Simulator uses the Gauss-Seidel iterative method to solve the discretized system.

**Algorithm:**

```
Initialize: T⁰ᵢ,ⱼ = initial guess (e.g., average of boundary temperatures)

For iteration n = 1, 2, 3, ...
  For each interior node (i,j):
    Tⁿ⁺¹ᵢ,ⱼ = (Tⁿ⁺¹ᵢ₋₁,ⱼ + Tⁿᵢ₊₁,ⱼ + Tⁿ⁺¹ᵢ,ⱼ₋₁ + Tⁿᵢ,ⱼ₊₁) / 4
  
  Compute residual: rₘₐₓ = maxᵢ,ⱼ|Tⁿ⁺¹ᵢ,ⱼ - Tⁿᵢ,ⱼ|
  
  If rₘₐₓ < tolerance:
    CONVERGED
    Exit
```

**Key Features:**

* Uses most recent values immediately (Tⁿ⁺¹ for already-computed nodes)
* Generally faster convergence than Jacobi method
* No matrix factorization required
* Low memory requirements

**Convergence:**

* Guaranteed for well-posed heat conduction problems
* Typical convergence: 100-2,000 iterations
* Default tolerance: 0.0001°C

#### U-Value Calculation

**Overall U-Value Definition**

The U-value (thermal transmittance) quantifies the overall rate of heat transfer through a building assembly under steady-state conditions.

**Basic Definition:**

```
U = Q/(A·ΔT)  [W/(m²·K)]
```

Where:

* U = U-value (thermal transmittance) \[W/(m²·K)]
* Q = Total heat transfer rate \[W]
* A = Area of assembly \[m²]
* ΔT = Temperature difference between interior and exterior \[K]

**Physical Meaning**: The U-value represents the heat flux (W/m²) per unit temperature difference. Lower U-values indicate better insulation.

**R-Value (Thermal Resistance)**

```
R = 1/U  [m²·K/W]
```

**For Multi-Layer Assembly:**

```
R_total = Rₛᵢ + R₁ + R₂ + ... + Rₙ + Rₛₑ
```

Where:

* Rᵢ = Thermal resistance of layer i = dᵢ/kᵢ
* dᵢ = Thickness of layer i \[m]
* kᵢ = Thermal conductivity of layer i \[W/(m·K)]

#### PSI-Value (Linear Thermal Transmittance)

The PSI value (ψ) quantifies additional heat loss due to thermal bridging at junctions, edges, and geometric discontinuities.

**Definition of PSI (ψ):**

```
ψ = L₂ᴅ - Σᵢ (Uᵢ·lᵢ)  [W/(m·K)]
```

Where:

* ψ = Linear thermal transmittance (PSI value) \[W/(m·K)]
* L₂ᴅ = 2D thermal conductance of complete junction \[W/(m·K)]
* Uᵢ = U-value of connecting element i \[W/(m²·K)]
* lᵢ = Length of connecting element i in 2D model \[m]

**Physical Meaning**: PSI represents the additional heat flow due to multidimensional effects not captured in 1D U-value calculations. A positive ψ indicates a thermal bridge (extra heat loss), while negative ψ indicates thermal improvement.

**Typical PSI Values:**

| Junction Type     | Good   | Moderate  | Poor   |
| ----------------- | ------ | --------- | ------ |
| Wall-Floor        | < 0.15 | 0.15-0.40 | > 0.40 |
| Wall-Roof         | < 0.10 | 0.10-0.30 | > 0.30 |
| Window Frame      | < 0.03 | 0.03-0.10 | > 0.10 |
| Corner (External) | < 0.05 | 0.05-0.15 | > 0.15 |

Units: W/(m·K)

#### Heat Flux Post-Processing

**Flux Calculation:**

At each grid node, temperature gradients are computed using central differences:

```
∂T/∂x ≈ (Tᵢ₊₁,ⱼ - Tᵢ₋₁,ⱼ) / (2·Δx)
∂T/∂y ≈ (Tᵢ,ⱼ₊₁ - Tᵢ,ⱼ₋₁) / (2·Δy)
```

**Heat Flux Components:**

```
qₓ = -k·∂T/∂x
qᵧ = -k·∂T/∂y
```

**Flux Magnitude and Direction:**

```
|q| = √(qₓ² + qᵧ²)
θ = atan2(qᵧ, qₓ)  (angle from x-axis)
```

#### Summary of Numerical Formulation

1. **Grid**: Divide domain into regular rectangular grid (V1.2: always aspect-ratio-aware)
2. **Material Assignment**: Assign thermal conductivity k to each cell
3. **Boundary Conditions**: Apply temperature or convection BCs at boundaries (V1.2: exact geometry bounds)
4. **Discretization**: Replace derivatives with finite differences
5. **Solver Selection** (V1.2): Auto-detect uniform vs multi-material conductivity
6. **Solve**: Gauss-Seidel iterations until convergence
7. **Post-Process**: Compute heat flux and U-value

**Advantages of Finite Difference Method:**

* Simple implementation
* Fast for rectangular domains
* Low memory requirements
* Easy parallelization
* Direct handling of material interfaces

***

### FEAScript Integration

The Heat Transfer Simulator can export models for advanced analysis using FEAScript, an open-source JavaScript finite element library.

#### Export Workflow to FEAScript

For complex geometries requiring unstructured meshing or multi-physics analysis, export your model and continue in FEAScript:

**Step 1: Export Geometry**

1. Complete your geometry in Heat Transfer Simulator
2. Use DXF Export to save geometry file
3. Import DXF into Gmsh to generate .msh mesh file

**Step 2: Set Up FEAScript Model**

```javascript
import { FEAScriptModel, importGmshQuadTri, plotSolution } 
  from "https://core.feascript.com/dist/feascript.esm.js";

// Load mesh exported from Heat Transfer Simulator
const meshContent = await (await fetch("exported_model.msh")).text();
const meshFile = new File([meshContent], "exported_model.msh");
const parsedMesh = await importGmshQuadTri(meshFile);

// Configure heat conduction solver
const model = new FEAScriptModel();
model.setSolverConfig("heatConductionScript");
model.setMeshConfig({
  parsedMesh, 
  meshDimension: "2D", 
  elementOrder: "linear"
});

// Apply boundary conditions (use Gmsh physical group tags)
model.addBoundaryCondition("1", ["thermal", "convection", h, T_ambient]);
model.addBoundaryCondition("2", ["thermal", "convection", h, T_interior]);

// Solve and visualize
const { solutionVector, nodesCoordinates } = model.solve();
plotSolution(solutionVector, nodesCoordinates, model.solverConfig, 
  model.meshConfig.meshDimension, "contour", "resultsCanvas");
```

**Step 3: Advanced Analysis**

FEAScript enables capabilities beyond Heat Transfer Simulator:

* Unstructured triangular/quadrilateral meshes for complex shapes
* Higher-order elements for improved accuracy
* Custom solver configurations
* Integration with Node.js for batch processing

#### When to Use FEAScript

| Use Case                         | Recommended Tool        |
| -------------------------------- | ----------------------- |
| Quick thermal bridge analysis    | Heat Transfer Simulator |
| Standard U-value/PSI-value       | Heat Transfer Simulator |
| Complex curved geometries        | Export to FEAScript     |
| Batch processing multiple models | FEAScript API           |
| Custom web application           | FEAScript API           |
| Transient heat transfer          | FEAScript               |

#### FEAScript Resources

* **Website**: <https://feascript.com>
* **Heat Conduction Tutorial**: <https://feascript.com/tutorials/heat-conduction-2d-fin.html>
* **GitHub**: <https://github.com/FEAScript/FEAScript-core>
* **License**: MIT (free for all uses)

***

### Standards and References

#### Referenced Standards

* **ISO 10211**: Thermal bridges in building construction - Heat flows and surface temperatures - Detailed calculations
* **ISO 14683**: Thermal bridges in building construction - Linear thermal transmittance - Simplified methods and default values
* **ISO 6946**: Building components and building elements - Thermal resistance and thermal transmittance - Calculation methods
* **EN 673**: Glass in building - Determination of thermal transmittance (U value) - Calculation method

***

### Validation

The solver has been validated against ISO 10211:2007 Annex A Case 2:

* **Target**: 9.5 W/m heat flow
* **Achieved**: 9.505 W/m (99.95% accuracy)

**V1.2 Validation Notes:**

* Both solver branches (uniform Laplacian and harmonic mean) are ISO 10211:2017 compliant
* Auto-detection ensures optimal solver selection for each model type
* All 28 reference points in ISO 10211 Case 1 pass within ±0.1°C tolerance


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.betterbuilding.io/user-guide/tools-and-plugins/heat-transfer-simulator.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.