\documentclass[11pt,a4paper]{article}

% =========================================================
% phtitration — Package Manual
% XeLaTeX edition
% =========================================================

\usepackage{fontspec}
\usepackage{geometry}
\geometry{margin=2.25cm}

\usepackage{amsmath,amssymb}
\usepackage{booktabs}
\usepackage{array}
\usepackage{tabularx}
\usepackage{longtable}
\usepackage{enumitem}
\usepackage{xcolor}
\usepackage{tikz}
\usepackage{pgfplots}
\pgfplotsset{compat=1.18}
\usepackage{phtitration}
\usepackage{listings}
\usepackage{hyperref}
\usepackage{microtype}


\definecolor{phtblue}{RGB}{30,105,150}
\definecolor{phtgray}{RGB}{245,247,249}
\definecolor{phtdark}{RGB}{35,45,55}
\definecolor{phtgreen}{RGB}{35,125,90}
\definecolor{phtred}{RGB}{170,65,55}

\hypersetup{
	colorlinks=true,
	linkcolor=phtblue,
	urlcolor=phtblue,
	citecolor=phtblue,
	pdftitle={phtitration Package Manual},
	pdfauthor={Khaldi Mohammed Elhadi}
}

\lstset{
	language=[LaTeX]TeX,
	basicstyle=\ttfamily\small,
	backgroundcolor=\color{phtgray},
	frame=single,
	rulecolor=\color{black!15},
	breaklines=true,
	columns=fullflexible,
	keepspaces=true,
	showstringspaces=false,
	xleftmargin=4pt,
	xrightmargin=4pt
}

\setlength{\parindent}{0pt}
\setlength{\parskip}{5pt}
\renewcommand{\arraystretch}{1.25}

\newcolumntype{Y}{>{\centering\arraybackslash}X}

\newcommand{\pkg}{\texttt{phtitration}}
\newcommand{\key}[1]{\texttt{#1}}
\newcommand{\type}[1]{\texttt{#1}}

\pgfplotsset{
	phtmanualaxis/.style={
		width=14cm,
		height=8cm,
		xmin=0,
		ymin=0,
		ymax=14,
		axis lines=left,
		grid=both,
		major grid style={dotted,thick},
		minor grid style={dotted},
		minor x tick num=1,
		minor y tick num=1,
		xlabel={Titrant volume (mL)},
		ylabel={pH},
		ticklabel style={font=\small},
		axis line style={thick}
	}
}

\begin{document}
	
	% =========================================================
	% Cover
	% =========================================================
	
	\begin{titlepage}
		\centering
		\vspace*{2cm}
		
		{\Huge\bfseries \pkg\par}
		\vspace{0.35cm}
		{\Large Package Manual\par}
		
		\vspace{0.5cm}
		{\large Numerical pH--Metric Titration Curves with TikZ and PGFPlots\par}
		
		\vspace{1.5cm}
		
		\begin{tikzpicture}
			\node[
			draw=phtblue,
			line width=1.2pt,
			rounded corners=8pt,
			fill=phtblue!5,
			inner sep=16pt,
			text width=11cm,
			align=center
			]{
				\Large
				\textbf{XeLaTeX Edition}\\[4pt]
				\normalsize
				Eight acid--base titration systems\\
				Monoprotic, diprotic and triprotic models\\
				Numerical charge-balance solution
			};
		\end{tikzpicture}
		
		\vfill
		
		{\large\bfseries Khaldi Mohammed Elhadi\par}
		\vspace{0.2cm}
		{\large Version 1.0.0\par}
		{\large 16 August 2026\par}
		
		\vspace{1cm}
		{\small
			This manual describes the interface and numerical model of
			\pkg\ v1.0.0.
		}
		
	\end{titlepage}
	
	\tableofcontents
	\newpage
	
	% =========================================================
	\section{Introduction}
	% =========================================================
	
	\pkg\ is a LaTeX package for generating educational pH--metric
	acid--base titration curves directly in a \LaTeX\ document.
	It is built on \texttt{TikZ} and \texttt{PGFPlots} and is intended
	to be compiled with \textbf{XeLaTeX}.
	
	The package provides one main command:
	
\begin{lstlisting}
\phtitration[ ... ]
\end{lstlisting}
	
	The chemical system is selected by a single key, \key{type}.
	The remaining keys specify concentrations, initial volume,
	acid/base dissociation constants and the visible titration range.
	
	\textbf{Important design principle:} \pkg\ does not create a separate
	plot when used in its main form. The command is intended to be placed
	\textbf{inside an existing PGFPlots \texttt{axis}} environment. This
	makes it possible to use the package together with a personal graph
	style or another TikZ-based coordinate-system package.
	
	% =========================================================
	\section{Installation}
	% =========================================================
	
	\subsection{Local installation}
	
	The simplest method is to place
	
\begin{lstlisting}
phtitration.sty
\end{lstlisting}
	
	in the same directory as the \texttt{.tex} document.
	
	Then load it in the preamble:
	
\begin{lstlisting}
\usepackage{phtitration}
\end{lstlisting}
	
	The package loads the internal dependencies \texttt{TikZ},
	\texttt{PGFPlots}, and \texttt{etoolbox} itself.
	
	\subsection{TeXstudio}
	
	For a local project, keeping \texttt{phtitration.sty} beside the
	main \texttt{.tex} file is recommended.
	
	If a future version provides a TeXstudio completion file
	(\texttt{phtitration.cwl}), it can be installed separately to obtain
	command/key completion.
	
	\subsection{Compiler}
	
	Use:
	\begin{verbatim}
		XeLaTeX
	\end{verbatim}

	
	The package itself does not load \texttt{fontspec}, \texttt{polyglossia}
	or \texttt{bidi}. This is intentional: the package remains independent
	of the language and typography of the user's document.
	
	% =========================================================
	\section{Minimal Working Example}
	% =========================================================
	
	The smallest practical example is:
	
\begin{lstlisting}
\documentclass{article}
\usepackage{tikz}
\usepackage{pgfplots}
\pgfplotsset{compat=1.18}
\usepackage{phtitration}

\begin{document}
	
	\begin{tikzpicture}
		\begin{axis}[
			width=14cm,
			height=8cm,
			xmin=0, xmax=40,
			ymin=0, ymax=14,
			axis lines=left,
			grid=both,
			xlabel={Titrant volume (mL)},
			ylabel={pH}
			]
			\phtitration[
			type=weak-acid,
			Ca=0.100,
			Va=20,
			Cb=0.100,
			pKa=4.76
			]
		\end{axis}
	\end{tikzpicture}
	
\end{document}
\end{lstlisting}
	
	The important point is the nesting:
	
\begin{lstlisting}
\begin{tikzpicture}
	\begin{axis}[...]
		\phtitration[...]
	\end{axis}
\end{tikzpicture}
\end{lstlisting}
	
	% =========================================================
	\section{Supported Titration Systems}
	% =========================================================
	
	The package supports eight systems.
	
	\begin{longtable}{>{\ttfamily}p{3.2cm} p{7.2cm} c}
		\toprule
		\textnormal{\bfseries Type} & \textnormal{\bfseries Titration system}
		& \textnormal{\bfseries Equivalence points}\\
		\midrule
		\endhead
		
		strong-acid & Strong acid + strong base & 1\\
		weak-acid & Monoprotic weak acid + strong base & 1\\
		diprotic-acid & Diprotic acid + strong base & 2\\
		triprotic-acid & Triprotic acid + strong base & 3\\
		strong-base & Strong base + strong acid & 1\\
		weak-base & Monoprotic weak base + strong acid & 1\\
		dibase & Dibase + strong acid & 2\\
		tribase & Tribase + strong acid & 3\\
		
		\bottomrule
	\end{longtable}
	
	Thus the complete list is:
	
\begin{lstlisting}
strong-acid
weak-acid
diprotic-acid
triprotic-acid

strong-base
weak-base
dibase
tribase
\end{lstlisting}
	
	% =========================================================
	\section{Command Syntax}
	% =========================================================
	
	The main command has the form
	
\begin{lstlisting}
\phtitration[
type=...,
...
]
\end{lstlisting}
	
	The key \key{type} selects the chemical model.
	
	\subsection{Acid titration group}
	
\begin{lstlisting}
\phtitration[
type=strong-acid,
Ca=...,
Va=...,
Cb=...
]
\end{lstlisting}
	
\begin{lstlisting}
\phtitration[
type=weak-acid,
Ca=...,
Va=...,
Cb=...,
pKa=...
]
\end{lstlisting}
	
\begin{lstlisting}
\phtitration[
type=diprotic-acid,
Ca=...,
Va=...,
Cb=...,
pKa1=...,
pKa2=...
]
\end{lstlisting}
	
\begin{lstlisting}
\phtitration[
type=triprotic-acid,
Ca=...,
Va=...,
Cb=...,
pKa1=...,
pKa2=...,
pKa3=...
]
\end{lstlisting}
	
	\subsection{Base titration group}
	
\begin{lstlisting}
\phtitration[
type=strong-base,
Cb=...,
Vb=...,
Ca=...
]
\end{lstlisting}
	
\begin{lstlisting}
\phtitration[
type=weak-base,
Cb=...,
Vb=...,
Ca=...,
pKb=...
]
\end{lstlisting}
	
\begin{lstlisting}
\phtitration[
type=dibase,
Cb=...,
Vb=...,
Ca=...,
pKb1=...,
pKb2=...
]
\end{lstlisting}
	
\begin{lstlisting}
\phtitration[
type=tribase,
Cb=...,
Vb=...,
Ca=...,
pKb1=...,
pKb2=...,
pKb3=...
]
\end{lstlisting}
	
	% =========================================================
	\section{Parameter Reference}
	% =========================================================
	
	\subsection{Chemical parameters}
	
	\begin{longtable}{>{\ttfamily}p{2.2cm} p{4.2cm} p{5.2cm}}
		\toprule
		\textnormal{\bfseries Key} & \textnormal{\bfseries Meaning}
		& \textnormal{\bfseries Unit / use}\\
		\midrule
		\endhead
		
		type & Chemical system & One of the eight supported types\\
		Ca & Initial acid concentration & mol\,L$^{-1}$\\
		Va & Initial acid volume & mL\\
		Cb & Titrant/base concentration & mol\,L$^{-1}$\\
		Vb & Initial base volume & mL\\
		pKa & Monoprotic acid p$K_a$ & dimensionless\\
		pKa1 & First acid p$K_a$ & dimensionless\\
		pKa2 & Second acid p$K_a$ & dimensionless\\
		pKa3 & Third acid p$K_a$ & dimensionless\\
		pKb & Monoprotic base p$K_b$ & dimensionless\\
		pKb1 & First base p$K_b$ & dimensionless\\
		pKb2 & Second base p$K_b$ & dimensionless\\
		pKb3 & Third base p$K_b$ & dimensionless\\
		
		\bottomrule
	\end{longtable}
	
	\subsection{Plotting parameters}
	
	\begin{longtable}{>{\ttfamily}p{2.8cm} p{7.5cm} p{2.5cm}}
		\toprule
		\textnormal{\bfseries Key} & \textnormal{\bfseries Meaning}
		& \textnormal{\bfseries Default}\\
		\midrule
		\endhead
		
		xmin & Minimum titrant volume used for curve generation & 0\\
		xmax & Maximum titrant volume used for curve generation & 40\\
		samples & Number of calculated curve intervals & 41\\
		mark size & Size of equivalence/half-equivalence markers & 2pt\\
		show-equivalence & Enables equivalence-point markers & false\\
		show-half-equivalence & Enables half-equivalence markers & false\\
		
		\bottomrule
	\end{longtable}
	
	\textbf{PGFPlots options are not package keys.}
	Options such as \key{width}, \key{height}, \key{ymin}, \key{ymax},
	\key{grid}, \key{xlabel}, \key{ylabel}, \key{axis lines}, colours,
	line width, ticks, and fonts belong to the surrounding
	\texttt{axis} environment.
	
	This separation is deliberate and allows the user to keep a personal
	PGFPlots style.
	
	% =========================================================
	\section{Equivalence Volumes}
	% =========================================================
	
	For a monoprotic acid titrated by a strong base,
	
	\[
	V_{\mathrm{eq},1}
	=
	\frac{C_aV_a}{C_b}.
	\]
	
	For a diprotic acid,
	
	\[
	V_{\mathrm{eq},1}
	=
	\frac{C_aV_a}{C_b},
	\qquad
	V_{\mathrm{eq},2}
	=
	2\frac{C_aV_a}{C_b}.
	\]
	
	For a triprotic acid,
	
	\[
	V_{\mathrm{eq},n}
	=
	n\frac{C_aV_a}{C_b},
	\qquad n=1,2,3.
	\]
	
	For bases titrated with a strong acid, the analogous expressions are
	
	\[
	V_{\mathrm{eq},1}
	=
	\frac{C_bV_b}{C_a},
	\]
	
	with successive equivalence volumes equal to integer multiples for
	dibases and tribases.
	
	\subsection{Why the plotting range matters}
	
	For polyprotic systems, the final equivalence point may be far from
	the origin. Therefore, choose \key{xmax} large enough to display the
	whole titration.
	
	For example:
	
\begin{lstlisting}
type=triprotic-acid,
Ca=0.100,
Va=20,
Cb=0.100,
pKa1=2.10,
pKa2=6.30,
pKa3=10.30,
xmax=75
\end{lstlisting}
	
	% =========================================================
	\section{Equivalence and Half-Equivalence Markers}
	% =========================================================
	
	\subsection{Equivalence markers}
	
	Use:
	
\begin{lstlisting}
show-equivalence
\end{lstlisting}
	
	or explicitly:
	
\begin{lstlisting}
show-equivalence=true
\end{lstlisting}
	
	To suppress them:
	
\begin{lstlisting}
show-equivalence=false
\end{lstlisting}
	
	For example:
	
\begin{lstlisting}
\phtitration[
type=weak-acid,
Ca=0.100,
Va=20,
Cb=0.100,
pKa=4.76,
show-equivalence=true
]
\end{lstlisting}
	
	\subsection{Half-equivalence markers}
	
	Use:
	
\begin{lstlisting}
show-half-equivalence=true
\end{lstlisting}
	
	For a monoprotic weak acid,
	
	\[
	\mathrm{pH}=pK_a
	\]
	
	at half-equivalence.
	
	For a polyprotic acid, the successive half-equivalence regions
	correspond to the successive $pK_a$ values.
	
	For a weak base,
	
	\[
	\mathrm{pH}=14-pK_b
	\]
	
	at half-equivalence under the usual $25^\circ$C relation
	$pK_w=14$ used by the model.
	
	% =========================================================
	\section{The Numerical Model}
	% =========================================================
	
	Version 1.0.0 uses a numerical charge-balance approach for weak and
	polyprotic systems.
	
	For a monoprotic acid, the charge-balance residual is constructed from
	the hydrogen-ion concentration, hydroxide concentration, titrant
	concentration, and the analytical concentration of the acid family.
	
	For diprotic and triprotic acids, the package computes the fractional
	distribution of the protonation states from the supplied $pK_a$
	values and evaluates the corresponding average charge.
	
	The pH is then found by a \textbf{bisection search} over the interval
	
	\[
	0\leq \mathrm{pH}\leq14.
	\]
	
	The same strategy is used for weak bases, dibases and tribases after
	converting the supplied $pK_b$ values through the standard relation
	
	\[
	pK_a = 14-pK_b.
	\]
	
	The package therefore avoids the old approach in which every region of
	a polyprotic curve was simply stitched together with independent
	Henderson--Hasselbalch expressions.
	
	\subsection{Numerical precision}
	
	The solver in v1.0.0 performs a fixed number of bisection iterations.
	Consequently, the result is a numerical approximation rather than a
	symbolic exact solution.
	
	Increasing \key{samples} increases the number of volume positions at
	which the chemistry is evaluated; it does \textbf{not} increase the
	internal bisection iterations.
	
	% =========================================================
	\section{Why \texttt{samples} Matters}
	% =========================================================
	
	The key
	
\begin{lstlisting}
samples=...
\end{lstlisting}
	
	controls how many volume positions are evaluated along the curve.
	
	For a normal curve:
	
\begin{lstlisting}
samples=101
\end{lstlisting}
	
	is usually sufficient.
	
	For a very steep transition or a publication-quality graph, a larger
	value may be preferable:
	
\begin{lstlisting}
samples=301
\end{lstlisting}
	
	or
	
\begin{lstlisting}
samples=501
\end{lstlisting}
	
	However, a larger value also increases compilation time.
	
	% =========================================================
	\section{Using a Personal PGFPlots Style}
	% =========================================================
	
	This is one of the main advantages of the current interface.
	
	Suppose your document already defines:
	
\begin{lstlisting}
\pgfplotsset{
	myaxis/.style={
		width=12cm,
		height=8cm,
		xmin=0,
		xmax=40,
		ymin=0,
		ymax=14,
		axis lines=middle,
		grid=both,
		ticklabel style={font=\tiny}
	}
}
\end{lstlisting}
	
	You can then simply write:
	
\begin{lstlisting}
\begin{tikzpicture}
	\begin{axis}[myaxis]
		\phtitration[
		type=weak-acid,
		Ca=0.100,
		Va=20,
		Cb=0.100,
		pKa=4.76
		]
	\end{axis}
\end{tikzpicture}
\end{lstlisting}
	
	The chemistry remains controlled by \pkg, while the appearance remains
	controlled by your own PGFPlots style.
	
	% =========================================================
	\section{Complete Examples}
	% =========================================================
	
	\subsection{1. Strong Acid + Strong Base}
	
\begin{lstlisting}
\begin{tikzpicture}
	\begin{axis}[phtmanualaxis,xmax=40]
		\phtitration[
		type=strong-acid,
		Ca=0.100,
		Va=20,
		Cb=0.100,
		show-equivalence=true
		]
	\end{axis}
\end{tikzpicture}
\end{lstlisting}
	
\begin{center}
	\begin{tikzpicture}
		\begin{axis}[phtmanualaxis,xmax=40]
			\phtitration[
			type=strong-acid,
			Ca=0.100,
			Va=20,
			Cb=0.100,
			show-equivalence=true
			]
		\end{axis}
	\end{tikzpicture}
\end{center}
	
	\subsection{2. Monoprotic Weak Acid + Strong Base}
	
\begin{lstlisting}
\begin{tikzpicture}
	\begin{axis}[phtmanualaxis,xmax=40]
		\phtitration[
		type=weak-acid,
		Ca=0.100,
		Va=20,
		Cb=0.100,
		pKa=4.76,
		show-equivalence=true,
		show-half-equivalence=true
		]
	\end{axis}
\end{tikzpicture}
\end{lstlisting}
	
\begin{center}
	\begin{tikzpicture}
		\begin{axis}[phtmanualaxis,xmax=40]
			\phtitration[
			type=weak-acid,
			Ca=0.100,
			Va=20,
			Cb=0.100,
			pKa=4.76,
			show-equivalence=true,
			show-half-equivalence=true
			]
		\end{axis}
	\end{tikzpicture}
\end{center}
	
	\subsection{3. Diprotic Acid + Strong Base}
	
\begin{lstlisting}
\begin{tikzpicture}
	\begin{axis}[phtmanualaxis,xmax=50]
		\phtitration[
		type=diprotic-acid,
		Ca=0.100,
		Va=20,
		Cb=0.100,
		pKa1=4.30,
		pKa2=9.70,
		show-equivalence=true,
		show-half-equivalence=true
		]
	\end{axis}
\end{tikzpicture}
\end{lstlisting}
	
	\begin{center}
		\begin{tikzpicture}
			\begin{axis}[phtmanualaxis,xmax=50]
				\phtitration[
				type=diprotic-acid,
				Ca=0.100,
				Va=20,
				Cb=0.100,
				pKa1=4.30,
				pKa2=9.70,
				show-equivalence=true,
				show-half-equivalence=true
				]
			\end{axis}
		\end{tikzpicture}
	\end{center}
	
	\subsection{4. Triprotic Acid + Strong Base}
	
\begin{lstlisting}
\begin{tikzpicture}
	\begin{axis}[phtmanualaxis,xmax=70]
		\phtitration[
		type=triprotic-acid,
		Ca=0.100,
		Va=20,
		Cb=0.100,
		pKa1=2.10,
		pKa2=6.30,
		pKa3=10.30,
		show-equivalence=true,
		show-half-equivalence=true
		]
	\end{axis}
\end{tikzpicture}
\end{lstlisting}
	
	\begin{center}
		\begin{tikzpicture}
			\begin{axis}[phtmanualaxis,xmax=70]
				\phtitration[
				type=triprotic-acid,
				Ca=0.100,
				Va=20,
				Cb=0.100,
				pKa1=2.10,
				pKa2=6.30,
				pKa3=10.30,
				show-equivalence=true,
				show-half-equivalence=true
				]
			\end{axis}
		\end{tikzpicture}
	\end{center}
	
	\subsection{5. Strong Base + Strong Acid}
	
\begin{lstlisting}
\begin{tikzpicture}
	\begin{axis}[phtmanualaxis,xmax=40]
		\phtitration[
		type=strong-base,
		Cb=0.100,
		Vb=20,
		Ca=0.100,
		show-equivalence=true
		]
	\end{axis}
\end{tikzpicture}
\end{lstlisting}
	
	\begin{center}
		\begin{tikzpicture}
			\begin{axis}[phtmanualaxis,xmax=40]
				\phtitration[
				type=strong-base,
				Cb=0.100,
				Vb=20,
				Ca=0.100,
				show-equivalence=true
				]
			\end{axis}
		\end{tikzpicture}
	\end{center}
	
	\subsection{6. Monoprotic Weak Base + Strong Acid}
	
\begin{lstlisting}
\begin{tikzpicture}
	\begin{axis}[phtmanualaxis,xmax=40]
		\phtitration[
		type=weak-base,
		Cb=0.100,
		Vb=20,
		Ca=0.100,
		pKb=4.75,
		show-equivalence=true,
		show-half-equivalence=true
		]
	\end{axis}
\end{tikzpicture}
\end{lstlisting}
	
	\begin{center}
		\begin{tikzpicture}
			\begin{axis}[phtmanualaxis,xmax=40]
				\phtitration[
				type=weak-base,
				Cb=0.100,
				Vb=20,
				Ca=0.100,
				pKb=4.75,
				show-equivalence=true,
				show-half-equivalence=true
				]
			\end{axis}
		\end{tikzpicture}
	\end{center}
	
	\subsection{7. Dibase + Strong Acid}
	
\begin{lstlisting}
\begin{tikzpicture}
	\begin{axis}[phtmanualaxis,xmax=50]
		\phtitration[
		type=dibase,
		Cb=0.100,
		Vb=20,
		Ca=0.100,
		pKb1=3.00,
		pKb2=8.00,
		show-equivalence=true,
		show-half-equivalence=true
		]
	\end{axis}
\end{tikzpicture}
\end{lstlisting}
	
	\begin{center}
		\begin{tikzpicture}
			\begin{axis}[phtmanualaxis,xmax=50]
				\phtitration[
				type=dibase,
				Cb=0.100,
				Vb=20,
				Ca=0.100,
				pKb1=3.00,
				pKb2=8.00,
				show-equivalence=true,
				show-half-equivalence=true
				]
			\end{axis}
		\end{tikzpicture}
	\end{center}
	
	\subsection{8. Tribase + Strong Acid}
	
\begin{lstlisting}
\begin{tikzpicture}
	\begin{axis}[phtmanualaxis,xmax=70]
		\phtitration[
		type=tribase,
		Cb=0.100,
		Vb=20,
		Ca=0.100,
		pKb1=2.50,
		pKb2=6.50,
		pKb3=10.50,
		show-equivalence=true,
		show-half-equivalence=true
		]
	\end{axis}
\end{tikzpicture}
\end{lstlisting}
	
	\begin{center}
		\begin{tikzpicture}
			\begin{axis}[phtmanualaxis,xmax=70]
				\phtitration[
				type=tribase,
				Cb=0.100,
				Vb=20,
				Ca=0.100,
				pKb1=2.50,
				pKb2=6.50,
				pKb3=10.50,
				show-equivalence=true,
				show-half-equivalence=true
				]
			\end{axis}
		\end{tikzpicture}
	\end{center}
	
	% =========================================================
	\section{Changing the Plot Appearance}
	% =========================================================
	
	Because \pkg\ adds a PGFPlots curve, ordinary PGFPlots commands can
	be used around it.
	
	For example:
	
\begin{lstlisting}
\begin{axis}[
	width=13cm,
	height=8cm,
	xmin=0, xmax=40,
	ymin=0, ymax=14,
	axis lines=middle,
	grid=both,
	major grid style={dotted},
	minor x tick num=1,
	minor y tick num=1,
	xlabel={$V_{\mathrm{NaOH}}$ (mL)},
	ylabel={pH},
	ticklabel style={font=\small}
	]
	\phtitration[
	type=weak-acid,
	Ca=0.100,
	Va=20,
	Cb=0.100,
	pKa=4.76
	]
\end{axis}
\end{lstlisting}
	
	The curve itself is inserted by an \texttt{\textbackslash addplot}
	operation, so it inherits the surrounding PGFPlots environment.
	
	% =========================================================
	\section{Integration with a TikZ-Only Physics Package}
	% =========================================================
	
	If your main document already contains a personal TikZ-only package
	for physics diagrams or coordinate systems, there is no requirement
	to replace it with PGFPlots.
	
	A typical preamble can be:
	
\begin{lstlisting}
	\usepackage{yourphysics}
	\usepackage{phtitration}
\end{lstlisting}
	
	Your physics package can continue to define colours, TikZ styles,
	coordinates and graphical constructions. \pkg\ is responsible only
	for generating the pH titration data/curve inside the PGFPlots
	\texttt{axis}.
	
	This separation is useful when a larger educational package already
	has its own visual identity.
	
	% =========================================================
	\section{Arabic Documents with XeLaTeX}
	% =========================================================
	
	The manual is written in English, but \pkg\ can be used in Arabic
	XeLaTeX documents.
	
	For example:
	
\begin{lstlisting}
\documentclass{article}

\usepackage{fontspec}
\usepackage{polyglossia}
\setdefaultlanguage{arabic}
\newfontfamily\arabicfont[Script=Arabic]{Amiri}

\usepackage{tikz}
\usepackage{pgfplots}
\pgfplotsset{compat=1.18}
\usepackage{phtitration}

\begin{document}
	
	\begin{tikzpicture}
		\begin{axis}[
			xmin=0, xmax=40,
			ymin=0, ymax=14,
			xlabel={Volum (mL)},
			ylabel={pH},
			grid=both
			]
			\phtitration[
			type=weak-acid,
			Ca=0.100,
			Va=20,
			Cb=0.100,
			pKa=4.76
			]
		\end{axis}
	\end{tikzpicture}
	
\end{document}
\end{lstlisting}
	
	The important rule is that \texttt{fontspec}, \texttt{polyglossia} and
	other language-related packages belong to the document. They are not
	loaded automatically by \pkg.
	
	% =========================================================
	\section{Troubleshooting}
	% =========================================================
	
	\subsection{The command is undefined}
	
	Make sure the package is loaded:
	
\begin{lstlisting}
\usepackage{phtitration}
\end{lstlisting}
	
	Also verify that \texttt{phtitration.sty} is in the same directory as
	the main \texttt{.tex} file.
	
	\subsection{PGFPlots or TikZ errors appear}
	
	Make sure PGFPlots is available and use:
	
\begin{lstlisting}
\pgfplotsset{compat=1.18}
\end{lstlisting}
	
	The package itself loads TikZ and PGFPlots.
	
	\subsection{The curve stops before the final equivalence point}
	
	Increase \key{xmax}. For example:
	
\begin{lstlisting}
xmax=70
\end{lstlisting}
	
	This is especially important for triprotic and tribasic systems.
	
	\subsection{The curve is visually too coarse}
	
	Increase:
	
\begin{lstlisting}
samples=101
\end{lstlisting}
	
	or:
	
\begin{lstlisting}
samples=301
\end{lstlisting}
	
	\subsection{The graph looks strange near a steep transition}
	
	Avoid excessively low values of \key{samples}. Also avoid using a
	plotting range that is much larger than necessary when the transition
	region is the main feature of interest.
	
	The chemical calculation and the visual interpolation are separate
	issues: \key{samples} controls the number of chemical evaluations,
	while PGFPlots controls the visual rendering.
	
	\subsection{A key is reported as unknown}
	
	Only the keys documented in Section~5 are package keys in v1.0.0.
	
	For example, \key{width}, \key{height}, \key{grid}, \key{ymin},
	\key{ymax}, colours and line styles should be placed in the
	surrounding \texttt{axis} environment, not inside \verb|\phtitration|.
	
	% =========================================================
	\section{Scientific Scope and Limitations}
	% =========================================================
	
	\pkg\ is designed primarily for \textbf{educational and graphical
		purposes}.
	
	The numerical model assumes ideal-solution behaviour and uses the
	standard $pK_w=14$ convention for the pH range considered here.
	Activity coefficients, ionic-strength corrections and detailed
	thermodynamic effects are not modelled.
	
	The numerical solver is a fixed-iteration bisection method. Therefore,
	the package should not be presented as a general-purpose
	research-grade chemical-equilibrium solver.
	
	For advanced equilibrium calculations involving, for example,
	
	\begin{itemize}[leftmargin=1.5em]
		\item significant activity effects,
		\item very dilute solutions,
		\item coupled equilibria,
		\item metal--ligand complexation,
		\item precipitation,
		\item redox equilibria,
		\item temperature-dependent $K_w$,
	\end{itemize}
	
	a dedicated chemical-equilibrium program or a more advanced numerical
	model should be used.
	
	% =========================================================
	\section{Recommended Workflow}
	% =========================================================
	
	A practical workflow for creating a graph is:
	
	\begin{enumerate}[leftmargin=1.6em]
		\item Choose the chemical system through \key{type}.
		\item Enter the initial analytical concentrations and volume.
		\item Enter the relevant $pK_a$ or $pK_b$ values.
		\item Set \key{xmax} beyond the last equivalence point.
		\item Choose the surrounding PGFPlots dimensions and axis limits.
		\item Enable \key{show-equivalence} when equivalence markers are useful.
		\item Enable \key{show-half-equivalence} when teaching buffer regions.
		\item Increase \key{samples} only when the curve requires finer volume
		resolution.
	\end{enumerate}
	
	% =========================================================
	\section{Quick Reference}
	% =========================================================
	
\begin{lstlisting}
% Acid group
	type=strong-acid
	type=weak-acid
	type=diprotic-acid
	type=triprotic-acid

% Base group
	type=strong-base
	type=weak-base
	type=dibase
	type=tribase
\end{lstlisting}
	
	\subsection*{Monoprotic weak acid}
	
\begin{lstlisting}
\phtitration[
type=weak-acid,
Ca=0.100,
Va=20,
Cb=0.100,
pKa=4.76,
xmax=40,
show-equivalence=true,
show-half-equivalence=true
]
\end{lstlisting}
	
	\subsection*{Diprotic acid}
	
\begin{lstlisting}
\phtitration[
type=diprotic-acid,
Ca=0.100,
Va=20,
Cb=0.100,
pKa1=4.30,
pKa2=9.70,
xmax=50,
show-equivalence=true
]
\end{lstlisting}
	
	\subsection*{Triprotic acid}
	
\begin{lstlisting}
\phtitration[
type=triprotic-acid,
Ca=0.100,
Va=20,
Cb=0.100,
pKa1=2.10,
pKa2=6.30,
pKa3=10.30,
xmax=70,
show-equivalence=true
]
\end{lstlisting}
	
	
	\vfill
	
	\begin{center}
		\textcolor{phtblue}{\rule{0.65\textwidth}{0.6pt}}\\[6pt]
		{\large\bfseries \pkg}\\
		Numerical pH--metric titration curves for XeLaTeX\\[4pt]
		\textit{End of Manual}
	\end{center}
	
\end{document}