# Thermal physics and heat transfer

Physical strokes inherit the surrounding native TikZ line width. No custom
line thickness is required; `>=latex` is the common arrow default.

The `tikzphysics.thermalphysics` library supplies eight native apparatus nodes.
It loads with `\usepackage{tikzphysics}` and is included in the generated single-file
Overleaf runtime. For selective loading after TikZ, use
`\usetikzlibrary{tikzphysics.thermalphysics}`. The equivalent
`\usetikzlibrary{tikzphysics.heattransfer}` loader is provided for convenience.

Physical geometry defaults to black outlines and no fill, with a black thermometer
column. Built-in heat-transfer arrows use the PGF `latex` tip, equivalent to the
TikZ `>=latex` convention. Authors can override drawing colors and fills in their
own documents. Each component supports `every <component name>` and
`every physics object` style hooks, ordinary node options, named anchors,
rotation, scaling, and saved per-instance dimensions.

## Percentage-anchor contract

Every documented family accepts **integers 0 through 100**. Write
`(S.axis-25)`, not `(S.axis-25%)`. Percentages describe the geometry along that
family, rather than time, heat-transfer rate or temperature. Zero and one hundred
are the endpoints; fifty is the midpoint in the documented parameter.

| Node | Families and directions |
|---|---|
| `conduction slab` | `bottom`, `right`, `top`, `left` run counterclockwise from the lower left; `axis` left to right |
| `composite wall` | Same boundary/axis families; `interface` bottom to top at the material split |
| `convection surface` | `surface` and `bottom` left to right; `right` bottom to top and `left` top to bottom on the plate; `flow` follows the central heat arrow |
| `cooling fin` | `base` bottom to top on the left face; `axis` root to tip; `fin-bottom` left to right, `fin-tip` bottom to top, `fin-top` right to left |
| `radiating body` | `rim` counterclockwise from the rightmost point; `ray` follows the horizontal heat arrow |
| `thermometer` | `scale` bulb top to stem cap; `column` bulb center to liquid top; `bulb` along the exposed outline counterclockwise from left stem join through bottom to right join; `stem-right` up, `cap` right to left, `stem-left` down |
| `calorimeter` | Counterclockwise `bottom/right/top/left`; `lid`, `surface`, `inner-bottom` left to right |
| `expansion rod` | `original` and `expanded` left to right along the two rod axes |

The default `thermal flow direction=1` points from the plate/body into its
surroundings; `-1` reverses convection and radiation arrows and their `flow`/`ray`
families. Radiation rim percentages keep their direction. Arrow length is a
schematic dimension, independent of the value of heat flux.

## Conduction and composite walls

```tex
\begin{tikzpicture}[>=latex]
  \node[composite wall,composite split=.4] (C) {};
  \node at (C.layer-1-center) {$k_1$};
  \node at (C.layer-2-center) {$k_2$};
  \draw[->] (C.axis-20)--(C.axis-80) node[midway,above] {$\dot Q$};
\end{tikzpicture}
```

`heat-left` and `heat-right` lie at the outer face midpoints. The composite split
is the fraction of total thickness occupied by the left material, and
`layer-1-center` / `layer-2-center` provide label positions. The material interface
is a true physical coordinate, so another object can attach at `(C.interface-50)`.
A conduction slab has one layer; place additional named slabs or composite walls
for larger assemblies.

For steady one-dimensional conduction through a uniform slab, the author may
annotate `Qdot = k A (T1-T2)/L`. Series composite layers have resistance
`sum(L_i/(k_i A))` under the same assumptions. Drawing widths do not determine
conductivity or automatically produce a temperature profile.

## Convection and cooling fins

The convection plate is below the fluid region. `plate-center` and `fluid-center`
provide label coordinates; `heat-start` and `heat-end` identify the central
arrow's tail and head. Labels may need placement below a thin plate to avoid
its outline. The arrows show heat exchange, not a computed fluid velocity field.

```tex
\node[convection surface,thermal flow direction=-1] (S) {};
\node[below] at (S.south) {$T_s$};
```

For a Newton cooling annotation, use `Qdot = h A (Ts-Tinf)` with an independently
supplied coefficient and sign convention. No `h` or fluid circulation is inferred.

The cooling-fin node contains one fin and its base. `fin length` is the total
width including base thickness. `root` is the attachment of the thin fin to its
base; `tip` is the rightmost center; `heat-left` is the external base midpoint.
For an array, attach multiple fins using `anchor=heat-left` at percentages of
another slab's right face, as in the composition gallery. Root-to-tip temperature
variation is an author annotation.

## Radiation

`radiating body` (`radiation source` alias) draws a circular body and eight arrows.
Its automatic border connections meet the body circle. `radiation radius` controls
the body, and `radiation ray length` controls rays outside that circle. Drawing
bounds include the rays while physical compass anchors describe the body itself.

Use outward arrows for emission and inward arrows for absorption. A physical body
can emit and absorb simultaneously; these schematics illustrate the selected
transfer direction. For idealized grey-body exchange with large surroundings,
`Qdot = epsilon sigma A (T^4-Tenv^4)` requires absolute temperatures. The node does
not assign emissivity, radiant power, view factors, or temperature values.

## Thermometers and calorimetry

`thermometer level` is a fraction in `[0,1]` of the useful stem above the bulb.
The bulb remains filled at level zero; the column stops below the cap at level
one. It is independent of any calibrated scale. `bulb-center`, `liquid-top`,
`scale-start` and `scale-end` are named locations. The `thermal liquid color` key
defaults to black; it can be overridden separately from the glass outline.

A calorimeter contains a double-wall vessel, lid and liquid surface.
`calorimeter insulation` is the geometric wall/bottom spacing;
`calorimeter level` is the fraction of usable inner height. It is strictly
between zero and one. Use `liquid-center`, `headspace-center`, `liquid-left` and
`liquid-right` for annotations. The surface is horizontal in the node's own frame.

```tex
\begin{tikzpicture}[>=latex]
  \node[calorimeter,calorimeter width=4cm] (C) {};
  \node[thermometer,fill=white,anchor=bulb-center]
    (T) at ($(C.liquid-center)+(.7,0)$) {};
\end{tikzpicture}
```

White glass fill masks vessel lines behind the inserted thermometer while retaining
its black column. Text, temperature, specific heat, latent heat and mixing balances
remain author inputs; neither level determines an equilibrium temperature.

## Expansion and contraction

`expansion rod` (`thermal expansion rod` alias) draws the reference rod below and
the changed rod above, with a shared left origin. `thermal expansion ratio` is
`changed length / reference length`: above one shows expansion and below one
contraction. The two percentage families remain left to right in either case.
Named endpoints are `original-start`, `original-end`, `expanded-start`,
`expanded-end`. For linear expansion at small strain, the author can supply
`ratio = 1 + alpha * deltaT`; the node does not infer alpha or deltaT.

## Keys and defaults

Lengths accept explicit TeX units; bare geometric lengths are centimetres.
Native dimensions are explicit: node text and minimum-size settings do not enlarge
the physical geometry. Increase module dimension keys when labels need space.

### conduction slab

| Key | Default |
|---|---|
| `conduction width` | `3cm` |
| `conduction height` | `2cm` |

### composite wall

| Key | Default |
|---|---|
| `composite width` | `3cm` |
| `composite height` | `2cm` |
| `composite split` | `.45` |

### convection surface

| Key | Default |
|---|---|
| `thermal plate width` | `3.6cm` |
| `thermal plate thickness` | `.25cm` |
| `thermal fluid height` | `1.2cm` |
| `thermal flow direction` | `1` |

### cooling fin

| Key | Default |
|---|---|
| `fin length` | `3cm` |
| `fin base height` | `1cm` |
| `fin base thickness` | `.25cm` |
| `fin thickness` | `.18cm` |

### radiating body

| Key | Default |
|---|---|
| `radiation radius` | `.65cm` |
| `radiation ray length` | `.8cm` |
| `thermal flow direction` | `1` |

### thermometer

| Key | Default |
|---|---|
| `thermometer height` | `3.2cm` |
| `thermometer bulb radius` | `.32cm` |
| `thermometer stem width` | `.18cm` |
| `thermometer level` | `.6` |
| `thermal liquid color` | `black` |

### calorimeter

| Key | Default |
|---|---|
| `calorimeter width` | `3cm` |
| `calorimeter height` | `2.6cm` |
| `calorimeter insulation` | `.25cm` |
| `calorimeter level` | `.55` |

### expansion rod

| Key | Default |
|---|---|
| `expansion rod length` | `3cm` |
| `expansion rod thickness` | `.16cm` |
| `expansion separation` | `.65cm` |
| `thermal expansion ratio` | `1.1` |

## Validation and examples

All geometric lengths must be positive. The composite split lies strictly between
zero and one. Fin length exceeds base thickness, and base height exceeds fin
thickness. Thermometer height exceeds four bulb radii, stem width is less than
the bulb diameter, and level is within zero and one inclusive. Calorimeter
insulation is less than half either outer dimension. Expansion separation exceeds
rod thickness, and the ratio lies in `(0,3]`. Use moderate dimensions for PGF
fixed-precision arithmetic.

The [component gallery](thermalphysics.pdf), from `examples/thermalphysics.tex`,
shows every native node and both transfer directions. The
[composition gallery](thermalphysics-scenes.pdf), from
`examples/thermalphysics-scenes.tex`, shows percentage markers, connected fins,
a thermometer in a calorimeter, transformations and contraction. Reference cards
cover all eight nodes and aliases; named nodes support `show anchors` and
`show keys` through the standard package tools.