\section{PV tutorial: butane in a domestic gas lighter}
\label{sec:tutorial-butane-pv}

This tutorial uses a rigid lighter reservoir containing liquid and vapour
butane to build a reproducible LuaCoolProp teaching sequence. The statement,
graphical reasoning, and numerical checks are presented in English; every
diagram is generated from CoolProp data.

The four tasks are to identify phase regions, recognize the ideal-gas limit,
locate the initial state, and predict the effect of heating the closed rigid
reservoir. A separate mechanical ignition analysis is outside this PV tutorial.

\begin{LCPNote}[What the five generated pages show]
The executable file \texttt{tutorial/butane-pv.tex} produces one five-page PDF.
Page~1 is the unannotated student worksheet.  Page~2 identifies the phase
regions and critical isotherm.  Page~3 overlays the ideal-gas prediction on the
$515\,\mathrm K$ isotherm.  Page~4 obtains the initial tank state from a TikZ
intersection and reports its pressure, specific volume, and mass.  Page~5
draws the isochoric heating path and obtains the new vapour quality from the
same process call.
\end{LCPNote}

\subsection{Translate the exercise into thermodynamic data}

The working fluid is pure normal butane.  CoolProp accepts \texttt{Butane} for
this fluid.  The tank dimensions and initial state are
\[
  V=(4\,\mathrm{cm})(1\,\mathrm{cm})(1\,\mathrm{cm})
    =4.0\times10^{-6}\,\mathrm{m^3},
  \qquad T_A=305\,\mathrm K,
\]
and $70\%$ of the butane mass is liquid.  LuaCoolProp and CoolProp use vapour
mass quality, so the remaining $30\%$ gives
\[
  x_A=0.30.
\]
For a pure substance the liquid and vapour contain the same molecular species,
but \key{quality} should still be read as a mass fraction in the package API.

The exercise can be assigned progressively:
\begin{enumerate}
  \item delimit compressed liquid, liquid--vapour equilibrium, and
        superheated vapour; identify the critical isotherm;
  \item use the shape of the $515\,\mathrm K$ isotherm to identify where the
        ideal-gas approximation becomes credible;
  \item locate $A$ from $T_A$ and $x_A$, then read $p_A$ and $v_A$ and calculate
        $m=V/v_A$; and
  \item deduce the path followed when the sealed rigid tank is heated and the
        direction in which its vapour quality changes.
\end{enumerate}

This is an especially useful introduction to PV coordinates because every
piece of graphical geometry has a direct physical interpretation: an isotherm
has a horizontal two-phase plateau, an isochore is vertical, and the dilute-gas
limit is a straight line of slope $-1$ on logarithmic axes.

\subsection{Keep one executable source for all five stages}

The tutorial consists of a thin multi-page driver and one shared graphical
implementation:
\begin{center}
\begin{tabularx}{\textwidth}{@{}>{\raggedright\arraybackslash\ttfamily}p{.42\textwidth}>{\raggedright\arraybackslash}X@{}}
\toprule
File & Responsibility \\
\midrule
tutorial/butane-pv.tex & Selects the standalone multi-picture document.\\
tutorial/source/butane-pv-diagrams.tex & Defines the common background,
annotations, named construction paths, state exports, and five stages.\\
\bottomrule
\end{tabularx}
\end{center}

The driver contains no thermodynamic value:

\begin{LCPExample}{Five-page standalone driver}
\documentclass[tikz,border=5mm,multi={tikzpicture}]{standalone}
\input{tutorial/source/butane-pv-diagrams.tex}
\end{LCPExample}

Keeping the diagram in one implementation means that a changed pressure range,
fluid model, or quality grid updates both the worksheet and every solution
stage.  No correction is drawn on top of a stale imported image.

\subsection{Step 1: build a readable log--log worksheet}

The worksheet uses pascals, while LuaCoolProp's default PV pressure
coordinate is bar.  Set \key{pressure scale=1} on every generated family and
label the Y axis in pascals.  Specific volume already uses
$\mathrm{m^3\,kg^{-1}}$, so its default scale remains one.

\begin{LCPExample}{Common PV axis in SI units}
\LCPSetup{fluid=Butane}
\begin{tikzpicture}
\begin{loglogaxis}[
  lcp fluid=Butane,
  width=17cm,height=11cm,
  xmin=.001,xmax=1.4,
  ymin=50000,ymax=15000000,
  xlabel={Specific volume $v$ (\si{\cubic\metre\per\kilogram})},
  ylabel={Pressure $p$ (\si{\pascal})},
  grid=both,clip mode=individual,
  auto node placement,
  auto node algorithm=repair,
  auto node bbox mode=oriented,
  auto node failure mode=hide-low-priority
]
  % Quality curves and isotherms go here.
\end{loglogaxis}
\end{tikzpicture}
\end{LCPExample}

The range spans roughly three orders of magnitude in specific volume and two
and a half in pressure.  A linear plot would compress the liquid states into an
unreadable strip.  In a \texttt{loglogaxis}, equal distances represent equal
ratios and positive coordinates are mandatory.

Add the saturated boundaries and interior qualities in blue.  Explicit values
make the pedagogical interpolation grid reproducible:

\begin{LCPExample}{Butane quality grid}
\LCPAddPVQuality[
  fluid=Butane,
  pressure min=50000,pressure max=15000000,
  pressure scale=1,
  quality values={0,0.1,0.2,0.3,0.4,0.5,
    0.6,0.7,0.8,0.9,1},
  quality symbol=x,
  quality color=blue,quality boundary color=blue,
  interior style={line width=.38pt},
  boundary style={line width=.9pt},
  labels=true,quality label pos=.2,
  quality label sloped=true
]
\end{LCPExample}

The red isotherm family is specified in kelvin to match the exercise.  Below
the critical temperature, LuaCoolProp generates the compressed-liquid branch,
the exact saturation-pressure plateau, and the superheated-vapour branch as one
named curve.

\begin{LCPExample}{Butane isotherm grid in kelvin}
\LCPAddPVIsotherms[
  fluid=Butane,
  pressure min=50000,pressure max=15000000,
  pressure scale=1,
  temperature unit=K,
  temperature values={275,285,295,305,315,335,
    365,415,425.125,515,615,715},
  isotherm color=red,
  isotherm style={line width=.42pt},
  curve style for={lcp-pv-T-425p125-K}{
    densely dashed,line width=.9pt},
  labels=true,isotherm label pos=.76,
  isotherm label sloped=true
]
\end{LCPExample}

Both families use adaptive sampling in log--log display coordinates.  The
executable source tightens \key{tolerance}, increases \key{max depth}, and
increases \key{log x weight} so that the critical neighbourhood and narrow
liquid branch remain smooth at worksheet size.  Label placement is still
entirely delegated to \pkg{pgfplots-autonode}.

\begin{center}
  \includegraphics[page=1,width=.96\textwidth]{tutorial/butane-pv.pdf}
\end{center}

The first page is ready to place in an exercise statement.  It contains the
data needed for graphical reasoning but no phase names, selected state, or
heating arrow.

\subsection{Step 2: read phase regions and the critical isotherm}

The $x=0$ and $x=1$ branches bound the liquid--vapour coexistence region and
meet at the critical point.  Compressed liquid lies to the left, superheated
vapour to the right, and two-phase equilibrium lies between them.  Intermediate
quality curves are meaningful only inside this coexistence region.

Butane's critical constants can be queried instead of copied from a drawing:

\begin{LCPExample}{Critical coordinates from the fluid macros}
\LCPDeclareFluid{Butane}
\pgfmathsetmacro{\ButaneCriticalVolume}{1/\LCPFluidRhocritSI}
% Critical point in an SI-scaled PV axis:
\fill (axis cs:\ButaneCriticalVolume,\LCPFluidPcritSI)
  circle[radius=2pt];
\end{LCPExample}

For the CoolProp release used to build this manual,
\[
  T_c=425.125\,\mathrm K=151.975\,{}^\circ\mathrm C,
  \qquad p_c=3.796\,\mathrm{MPa}.
\]
The dashed curve at $425.125\,\mathrm K$ is therefore the critical isotherm
$\mathcal C$ requested by the exercise.

\begin{center}
  \includegraphics[page=2,width=.96\textwidth]{tutorial/butane-pv.pdf}
\end{center}

\begin{LCPWarning}[Use ``supercritical'' precisely]
Crossing above $T_c$ removes the liquid--vapour phase transition, but a state is
strictly in the supercritical region when both $T>T_c$ and $p>p_c$.  At
$T>T_c$ and $p<p_c$ it is often clearer to say ``gas-like single-phase
fluid''.  Simplified school diagrams sometimes label every state above the
critical isotherm as supercritical; an instructor should state which convention
is expected.
\end{LCPWarning}

\subsection{Step 3: recognize the ideal-gas region geometrically}

For a perfect gas,
\[
  pV=nRT,\qquad m=nM,\qquad v=\frac Vm,
\]
so a fixed-temperature line satisfies
\[
  pv=\frac RM T,
  \qquad
  \log p=-\log v+\log\!\left(\frac RM T\right).
\]
An ideal-gas isotherm is therefore a straight line of slope $-1$ in log--log
PV coordinates.  For butane, with $M=0.05812\,\mathrm{kg\,mol^{-1}}$, the
$515\,\mathrm K$ reference is generated by:

\begin{LCPExample}{Ideal-gas comparison line}
\addplot[green!60!black,line width=1.15pt,
  domain=.025:1.25,samples=2]
  {(8.314462618/0.05812*515)/x};
\end{LCPExample}

\begin{center}
  \includegraphics[page=3,width=.96\textwidth]{tutorial/butane-pv.pdf}
\end{center}

The green ideal-gas line and red CoolProp isotherm become indistinguishable as
specific volume increases and pressure decreases.  A useful numerical audit is
the compressibility factor
\[
  Z=\frac{pvM}{RT}.
\]
At $515\,\mathrm K$, CoolProp gives approximately $Z=0.9835$ at
$v=0.2\,\mathrm{m^3\,kg^{-1}}$ and $Z=0.9934$ at
$v=0.5\,\mathrm{m^3\,kg^{-1}}$.  The phrase ``ideal-gas region'' therefore
expresses an accuracy decision, not an exact boundary.

\subsection{Step 4: locate the initial state with TikZ intersections}

The initial state must satisfy two independent constraints:
$T_A=305\,\mathrm K$ and $x_A=0.30$.  Do not copy a coordinate from the model
solution.  Create two invisible but named thermodynamic paths, then let the
TikZ \texttt{intersections} library locate their crossing:

\begin{LCPExample}{Named paths defining state A}
\LCPAddPVProcess[
  fluid=Butane,type=isotherm,temperature=305K,
  pressure scale=1,
  from={pressure=1bar},to={pressure=10bar},
  name=butane-state-a-isotherm,
  style={draw=none}]
\LCPAddPVProcess[
  fluid=Butane,type=quality,quality=0.3,
  pressure scale=1,
  from={temperature=275K},to={temperature=415K},
  name=butane-state-a-quality,
  style={draw=none}]
\path[name intersections={of=butane-state-a-isotherm and
  butane-state-a-quality,by=ButaneA}];
\node[above right] at (ButaneA) {$A$};
\end{LCPExample}

The named paths extend beyond the immediate crossing so the construction
remains stable if the plotting range changes.  Their styles are invisible, but
their geometry is genuine CoolProp output.  State $A$ is consequently tied to
the two thermodynamic definitions, not to an explicit pair of plot numbers.

\begin{center}
  \includegraphics[page=4,width=.96\textwidth]{tutorial/butane-pv.pdf}
\end{center}

The equation-of-state evaluation gives
\[
  p_A=2.99460\times10^5\,\mathrm{Pa},
  \qquad
  v_A=4.11233\times10^{-2}\,\mathrm{m^3\,kg^{-1}}.
\]
These values support graphical estimates of about
$3\times10^5\,\mathrm{Pa}$ and $4\times10^{-2}\,\mathrm{m^3\,kg^{-1}}$.
The butane mass is
\[
  m=\frac{V}{v_A}
   =\frac{4.0\times10^{-6}}{4.11233\times10^{-2}}
   =9.73\times10^{-5}\,\mathrm{kg}
   =0.0973\,\mathrm g.
\]
The printed exercise quite reasonably rounds this graphical result to
$10^{-4}\,\mathrm{kg}$.

\subsection{Step 5: draw the rigid-tank heating process}

The reservoir is closed, so $m$ is constant.  It is rigid, so $V$ is constant.
It follows immediately that
\[
  v=\frac Vm=\text{constant}.
\]
The state therefore moves vertically upward on the log--log PV chart as
temperature and pressure rise.  LuaCoolProp expresses the modelling hypothesis
directly with \key{type=isochore}.  The starting state supplies the conserved
specific volume; the endpoint needs only its new temperature:

\begin{LCPExample}{Isochoric heating with exported states}
\LCPAddPVProcess[
  fluid=Butane,
  type=isochore,
  pressure scale=1,
  from={temperature=305K,quality=0.3},
  to={temperature=335K},
  name=butane-isochoric-heating,
  color=orange,
  style={line width=1.6pt,-Latex},
  export coordinates=ButaneHeatingState,
  coord digits=10,
  log coordinates=true
]
\end{LCPExample}

\begin{center}
  \includegraphics[page=5,width=.96\textwidth]{tutorial/butane-pv.pdf}
\end{center}

The endpoint macros come from the same call that draws the orange segment.  No
second numerical model is maintained:

\begin{LCPExample}{Use and log the exported PV values}
Initial pressure:
\qty{\ButaneHeatingStateFromPressureSI}{\pascal}.

Initial specific volume:
\qty{\ButaneHeatingStateFromSpecificVolumeSI}
  {\cubic\metre\per\kilogram}.

Quality at 335 K:
\num{\ButaneHeatingStateToQuality}.

\typeout{Initial butane pressure (Pa):
  \ButaneHeatingStateFromPressureSI}
\typeout{Butane quality at 335 K:
  \ButaneHeatingStateToQuality}
\end{LCPExample}

At $335\,\mathrm K$, the process gives
\[
  p=6.67608\times10^5\,\mathrm{Pa},
  \qquad x=0.66525.
\]
The vapour mass fraction has increased from $0.30$ to about $0.665$: liquid is
evaporating as the tank warms.  If heating continues at the same specific
volume, the path reaches saturated vapour near $351.70\,\mathrm K$ and
$9.801\times10^5\,\mathrm{Pa}$.  Beyond that boundary the state is single-phase
vapour and quality is undefined; it must not be extrapolated beyond one.

\begin{LCPNote}[A regression exposed by this tutorial]
This example also tests an important API case.  For an isochore whose initial
state is given by $T,Q$ and whose target specifies only $T$, LuaCoolProp must
retain the target's derived $T,\rho$ pair while requesting every other property
from CoolProp.  Replacing it midway with the saturation pair $p,T$ is ambiguous.
The numerical test suite now exercises this butane path explicitly.
\end{LCPNote}

\subsection{Rebuild and adapt the tutorial}

The generated PDF and its log are part of the reproducible documentation
workflow.  Build it together with every example, tutorial, index, and the
manual using:

\begin{LCPExample}{Reproducible repository build}
export LUACOOLPROP_LIB=/path/to/libCoolProp.dylib
./scripts/build-examples.sh
\end{LCPExample}

The build places \texttt{butane-pv.pdf} next to its driver.  Its transcript is
written to \path{tutorial/logs/butane-pv.log}.  To adapt the exercise:
\begin{enumerate}
  \item select another pure fluid with \key{fluid};
  \item query its critical constants rather than copying butane's values;
  \item choose pressure and volume limits from the intended physical problem;
  \item state whether temperature values are Celsius or kelvin;
  \item define every marked state through two independent properties and named
        TikZ paths;
  \item use \macro{\LCPAddPVProcess} for the physical transformation;
  \item export endpoint properties for tables, calculations, and logs; and
  \item distinguish diagram-reading precision from direct equation-of-state
        precision in the model solution.
\end{enumerate}

The central lesson is methodological: the diagram, annotations, and numerical
answer should be different views of one thermodynamic construction.  When a
given property, fluid, or process changes, CoolProp and LuaCoolProp regenerate
all three together.