# Thermodynamics

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

Load everything with `\usepackage{tikzphysics}`, or load only this library after
TikZ with `\usetikzlibrary{tikzphysics.thermodynamics}`. The single-file Overleaf
runtime includes the same implementation. All physical geometry defaults to
black outlines, no fill, and black hatching where insulation is indicated.
Use ordinary TikZ `draw`, `fill`, `pattern color`, and style overrides for color.

## Apparatus and energy flow

Use `thermal reservoir` (`hot reservoir` / `cold reservoir` aliases), `gas chamber`,
`thermal wall`, `conducting wall`, `insulated wall`, `heat engine`, and
`refrigerator` (`heat pump` alias) as ordinary named nodes. The `heat pump diagram` pic is an
alias of `refrigerator diagram` and accepts the same options. Gas chambers represent
closed schematic boundaries; the existing fluids `piston cylinder` provides a
movable-piston drawing. No material properties or equilibrium states are inferred.

Rectangular boundaries have `bottom-0..100` left to right, `right-0..100` bottom
to top, `top-0..100` right to left, and `left-0..100` top to bottom. Reservoirs,
chambers and walls expose `heat-left`, `heat-right`, `heat-top`, `heat-bottom`.
The engine's `rim-0..100` runs counterclockwise from the rightmost point. Its
diagonal compass anchors and automatic path connections lie on the circle.
Rectangular devices use rectangular borders.
Devices expose `hot` above, `cold` below and `work` on the right. For engines,
`heat-in` is above and `heat-out` below; refrigerators reverse these heat ports.

```tex
\begin{tikzpicture}[>=latex]
  \pic (E) {heat engine diagram};
  \pic (R) at (7,0) {refrigerator diagram};
\end{tikzpicture}
```

These pics supply reservoirs, device, labels and energy arrows. The engine receives
heat from the hot reservoir, rejects heat to the cold reservoir and delivers work.
The refrigerator receives work and heat from the cold reservoir and rejects heat
to the hot reservoir. Heat/work labels denote positive magnitudes; arrow direction
defines input/output. Neither pic calculates heat, work, efficiency or COP.

A named pic `(E)` exports child nodes `E-hot`, `E-cold`, `E-device` and coordinates
`E-origin`, `E-work`. Ordinary child anchors such as `(E-hot.bottom-30)` work.
Use distinct names for multiple pics. Three coordinate families accept every
integer percentage from 0 to 100, measured along the arrow from tail to head:

| Pic coordinate | Engine direction | Refrigerator / heat pump direction |
|---|---|---|
| `(E-heat-hot-0)` ... `(E-heat-hot-100)` | hot reservoir to device | device to hot reservoir |
| `(E-heat-cold-0)` ... `(E-heat-cold-100)` | device to cold reservoir | cold reservoir to device |
| `(E-work-0)` ... `(E-work-100)` | device to work port | work port to device |

For example, `(E-heat-hot-50)` is the hot heat-flow midpoint and
`(E-work-25)` lies a quarter of the way along the work arrow. These are named
pic coordinates, accessed with a hyphen after the pic name; native node anchors
use a dot, for example `(E-device.rim-25)`. Rotations and scaling transform both
kinds of coordinates. The `heat pump diagram` alias uses the same families.
`\physicshelp{heat pump diagram}` and the apparatus aliases resolve to their
canonical reference cards.

Pass pic keys in braces:

```tex
\pic (E) {heat engine diagram={
  thermo diagram separation=2.5cm,
  thermo hot label={$600\,\mathrm K$},
  thermo cold label={$300\,\mathrm K$}}};
```

| Pic key | Default / meaning |
|---|---|
| `thermo diagram separation` | `2cm`, center-to-center device/reservoir distance |
| `thermo diagram work length` | `1.5cm`, from device edge to external work port |
| `thermo hot label`, `thermo cold label` | `$T_H$`, `$T_C$` |
| `thermo engine label`, `thermo refrigerator label` | `$E$`, `$R$` |
| `thermo hot heat label`, `thermo cold heat label`, `thermo work label` | `$Q_H$`, `$Q_C$`, `$W$` |
| `every thermo flow` | `>=latex` black arrows; customize using `/.append style` |
| `every thermo label` | small text; customize using `/.append style` |

Reservoir and device dimension keys also apply inside pics. Separation must exceed
half the sum of reservoir height and device size; work length must be positive.

## Pressure-volume curves

All PV nodes include two axes, but leave text, ticks and arrows to the author.
Pressure and volume keys accept numbers in consistent author-chosen units, not
TeX dimensions. For example, choose litres and kilopascals and label the axes
accordingly. `pv width` and `pv height` set the physical drawing dimensions.
The plot maps `(V,P)` to `(-width/2 + width*V/Vmax,
-height/2 + height*P/Pmax)` relative to its node center. The physical zero point
is `origin`; it is not the node center.

| Process | Relation |
|---|---|
| `isothermal process` | `P = Pstart * Vstart / V` (ideal gas, constant temperature) |
| `isobaric process` | `P = Pstart` |
| `isochoric process` | `V = Vstart`, pressure interpolated to `pv end pressure` |
| `adiabatic process` | `P = Pstart * (Vstart/V)^gamma`, reversible ideal gas |
| `polytropic process` | `P = Pstart * (Vstart/V)^n`, `n = pv exponent` |

`process-0..100` advances linearly in volume, except for isochoric curves where it
advances linearly in pressure. It is not arc length or elapsed time. `start` and
`end` coincide with process endpoints; `start-volume` and `end-volume` project
these onto the horizontal axis. `start-pressure` and `end-pressure` project
onto the vertical axis. `volume-axis-0..100` runs right from `origin`;
`pressure-axis-0..100` runs up from `origin`. Endpoints are also named
`volume-end` and `pressure-end`. Compression is supported by a smaller end volume.
For an isochoric process `pv end volume` is ignored; set `pv end pressure` instead.

```tex
\begin{tikzpicture}[>=latex]
  \node[isothermal process,pv width=5cm] (P) {};
  \node[right] at (P.volume-end) {$V$};
  \node[above] at (P.pressure-end) {$P$};
  \draw[->] (P.process-45)--(P.process-55);
  \fill (P.start) circle (1.5pt);
\end{tikzpicture}
```

## Cycles

`rectangular cycle` runs clockwise: A=(low volume,low pressure), B=(low volume,
high pressure), C=(high volume,high pressure), D=(high volume,low pressure).
`AB-0..100`, `BC-0..100`, `CD-0..100`, `DA-0..100` advance along each branch.

`carnot cycle` constructs a reversible ideal-gas cycle from `V_A`, hot constant
`K_H = P_A V_A`, absolute-temperature ratio `r = T_C/T_H`, expansion ratio
`e = V_B/V_A`, and `gamma`. It derives `f = (1/r)^(1/(gamma-1))`,
`V_B=e V_A`, `V_D=f V_A`, `V_C=f V_B`, and `K_C=r K_H`.
Thus the hot and cold isotherms and the two adiabats meet at shared states.
Use Kelvin (or another absolute scale) for the temperature ratio, never Celsius.
The `pv start pressure` key does not apply to Carnot cycles; use the hot constant.

| Family | Direction / equation |
|---|---|
| `hot-0..100` | A to B, `P=K_H/V` |
| `expansion-0..100` | B to C, reversible adiabatic expansion |
| `cold-0..100` | C to D, `P=K_C/V` |
| `compression-0..100` | D to A, reversible adiabatic compression |

Both cycle nodes expose `state-A` through `state-D`, plus the same axis anchors
as process nodes. Every state has `state-A-volume` / `state-A-pressure`
projections, with the same spelling for B, C and D. Each Carnot branch percentage interpolates volume. Direction
arrows are optional author additions; reverse them to illustrate the reversed cycle.

## Overlaying processes on a shared frame

Use `pv diagram` for an empty axes frame. Set `pv show axes=false` on process
or cycle nodes to draw only their physical curve. All compass, zero, axis,
percentage and projection anchors remain available even when axes are hidden.
The option defaults to `true` on all PV nodes and is stored with each instance.

Keep `pv width`, `pv height`, `pv max volume` and `pv max pressure` identical
for every overlaid node, and place each at the frame's center. Use solid, dashed
or dotted styles to compare processes without color. Ordinary TikZ `draw=...`
after the process style changes its color when explicitly requested.

```tex
\begin{tikzpicture}[>=latex,pv width=6cm,pv height=4cm]
  \node[pv diagram] (F) {};
  \node[isothermal process,pv show axes=false] (I) at (F.center) {};
  \node[adiabatic process,pv show axes=false,dashed] (A) at (F.center) {};
  \node[above] at (F.pressure-end) {$P$};
  \node[right] at (F.volume-end) {$V$};
  \draw[densely dotted] (I.start-pressure)--(I.start)--(I.start-volume);
\end{tikzpicture}
```

Projection coordinates remain in the node's local frame under rotation, scaling
and translation. For a complete pic whose child shapes and labels should rotate
and scale, use `\pic[rotate=90,scale=.8,transform shape] ...`. Without
`transform shape`, standard TikZ keeps node shapes and text upright while it
transforms positions; explicit native node `rotate` and `scale` options transform
that node's geometry.

The physical sizes are explicit: text, `minimum width`, `minimum height` and
padding do not enlarge these native diagrams. Increase the module dimension
keys to fit longer labels. Flow and label style hooks work as normal TikZ styles:

```tex
\tikzset{
  every thermal reservoir/.append style={draw=black,thick},
  every thermo flow/.append style={dashed},
  every thermo label/.append style={font=\footnotesize}
}
```

## Parameter reference

Lengths accept explicit TeX units; bare geometric lengths are centimetres.
Saved geometry belongs to each instance, so later key changes do not move anchors.
Rotation, scaling and translation transform the geometry and anchors together.

All process and cycle nodes also accept `pv show axes=true` (default) or
`false`.

### pv diagram

| Key | Default |
|---|---|
| `pv width` | `4cm` |
| `pv height` | `3cm` |
| `pv max volume` | `4` |
| `pv max pressure` | `4` |
| `pv show axes` | `true` |

### thermal reservoir

| Key | Default |
|---|---|
| `reservoir width` | `3cm` |
| `reservoir height` | `.8cm` |

### gas chamber

| Key | Default |
|---|---|
| `chamber width` | `2.4cm` |
| `chamber height` | `1.8cm` |

### thermal wall

| Key | Default |
|---|---|
| `thermal wall width` | `.3cm` |
| `thermal wall height` | `2cm` |

### heat engine

| Key | Default |
|---|---|
| `thermal device size` | `1.2cm` |

### refrigerator

| Key | Default |
|---|---|
| `thermal device size` | `1.2cm` |

### isothermal process

| Key | Default |
|---|---|
| `pv width` | `4cm` |
| `pv height` | `3cm` |
| `pv max volume` | `4` |
| `pv max pressure` | `4` |
| `pv start volume` | `1` |
| `pv start pressure` | `3` |
| `pv end volume` | `3` |

### isobaric process

| Key | Default |
|---|---|
| `pv width` | `4cm` |
| `pv height` | `3cm` |
| `pv max volume` | `4` |
| `pv max pressure` | `4` |
| `pv start volume` | `1` |
| `pv start pressure` | `3` |
| `pv end volume` | `3` |

### isochoric process

| Key | Default |
|---|---|
| `pv width` | `4cm` |
| `pv height` | `3cm` |
| `pv max volume` | `4` |
| `pv max pressure` | `4` |
| `pv start volume` | `1` |
| `pv start pressure` | `3` |
| `pv end pressure` | `1.5` |

### adiabatic process

| Key | Default |
|---|---|
| `pv width` | `4cm` |
| `pv height` | `3cm` |
| `pv max volume` | `4` |
| `pv max pressure` | `4` |
| `pv start volume` | `1` |
| `pv start pressure` | `3` |
| `pv end volume` | `3` |
| `pv gamma` | `1.4` |

### polytropic process

| Key | Default |
|---|---|
| `pv width` | `4cm` |
| `pv height` | `3cm` |
| `pv max volume` | `4` |
| `pv max pressure` | `4` |
| `pv start volume` | `1` |
| `pv start pressure` | `3` |
| `pv end volume` | `3` |
| `pv exponent` | `1.2` |

### rectangular cycle

| Key | Default |
|---|---|
| `pv width` | `4cm` |
| `pv height` | `3cm` |
| `pv max volume` | `4` |
| `pv max pressure` | `4` |
| `pv low volume` | `1` |
| `pv high volume` | `3` |
| `pv low pressure` | `1` |
| `pv high pressure` | `3` |

### carnot cycle

| Key | Default |
|---|---|
| `pv width` | `4cm` |
| `pv height` | `3cm` |
| `pv max volume` | `4` |
| `pv max pressure` | `4` |
| `pv start volume` | `1` |
| `carnot hot constant` | `3` |
| `carnot temperature ratio` | `.75` |
| `carnot expansion ratio` | `1.5` |
| `pv gamma` | `1.4` |

## Validation and limits

Dimensions and axis maxima must be positive. Process endpoints must be positive,
distinct in the varying coordinate and within both axis limits. Adiabatic gamma
must exceed one; the polytropic exponent magnitude is limited to ten. Rectangular
cycle limits must be strictly ordered. Carnot requires positive start volume and
hot constant, gamma greater than one, expansion ratio greater than one, and a
cold/hot ratio strictly between zero and one; all states must fit the axes. Endpoint pressure and Carnot extent bounds are
checked in logarithmic form before powers are evaluated, so impossible large
expansions produce the axis-limit diagnostic rather than a PGF power overflow.

PGF uses finite-precision arithmetic: use moderately scaled pressure and volume
values and avoid extreme powers or gamma arbitrarily close to one. These nodes
are educational drawing primitives, not a numerical thermodynamic solver. They
do not integrate work, calculate entropy, model phase changes or determine real-gas
properties. Curved paths use sampled segments; named anchors evaluate the equation.

See [the three-page gallery](thermodynamics.pdf) and its editable source in
`examples/thermodynamics.tex`. The companion
[composition gallery](thermodynamics-scenes.pdf), from
`examples/thermodynamics-scenes.tex`, covers overlays, compression, automatic
circular connections, heat pumps, transformed pics and cycle projections.
The package reference cards include every new node
and both pics. The standard `show anchors` tools apply to named native nodes.