\newpage

\section{Maths tools} % (fold)
\label{sec:maths_tools}

The \tkzname{maths tools} module provides general-purpose mathematical functions for solving algebraic equations and linear systems. These tools serve as computational backbones for various geometric or algebraic operations in the \tkzNamePack{tkz-elements} library.

The key features include:
\begin{itemize}
\item Solving polynomial equations of degree 1, 2, or 3.
\item Solving linear systems via augmented matrix transformation.
\end{itemize}

These functions handle both symbolic and numerical workflows and are suitable for educational, demonstrative, or computational geometry contexts.

\subsection*{Functions overview}

\begin{center}
  \bgroup
  \catcode`_=12
  \small
  \captionof{table}{Math functions} \label{line:methods_maths}
\begin{tabular}{ll}
\toprule
\textbf{Name}  & \textbf{Reference} \\
\midrule
\tkzFct{tkz}{tkz.solve(...)} & \\
\midrule
\tkzFct{tkz}{tkz.solve\_linear\_system} & \\
\bottomrule
\end{tabular}
\egroup
\end{center}


\subsection{\tkzFct{tkz}{solve(...)}} % (fold)
\label{sub:function_solve}

This general-purpose function solves polynomial equations of degree 1, 2, or 3 with real or complex coefficients. It delegates to specific solvers depending on the number of parameters.

\paragraph{Syntax.}
\begin{verbatim}
x = solve(a, b) -- solves ax + b = 0
x1, x2 = solve(a, b, c) -- solves ax^2 + bx + c = 0
x1, x2, x3 = solve(a, b, c, d) -- solves ax^3 + bx^2 + cx + d = 0
\end{verbatim}

\paragraph{Arguments.}
\begin{itemize}
\item 2 parameters: $a$, $b$ — coefficients of a linear equation $ax + b = 0$.
\item 3 parameters: $a$, $b$, $c$ — coefficients of a quadratic equation.
\item 4 parameters: $a$, $b$, $c$, $d$ — coefficients of a cubic equation.
\end{itemize}

\paragraph{Return.}
Depending on the degree of the equation:
\begin{itemize}
\item \code{solve(a,b)} returns one value (or an error if $a = 0$).
\item \code{solve(a,b,c)} returns two roots (real or \code{false} if complex and unsupported).
\item \code{solve(a,b,c,d)} returns up to three real roots (complex roots not currently supported).
\end{itemize}

\paragraph{Examples.}
\begin{verbatim}
x = solve(2, -4) -- x = 2
x1, x2 = solve(1, -3, 2) -- x1 = 2, x2 = 1
x1, x2, x3 = solve(1, -6, 11, -6) -- x1 = 1, x2 = 2, x3 = 3
\end{verbatim}

\paragraph{Notes.}
\begin{itemize}
\item For quadratics with complex solutions, the function currently returns \code{false, false}.
\item Cubic solving is limited to real roots using Cardano's method and assumes $a \ne 0$.
\item Internally uses the functions \code{tkz.solve\_quadratic} and \code{tkz.solve\_cubic}.
\end{itemize}

% subsection function_solve (end)


\subsection{Function \tkzFct{math}{solve\_linear\_system(M, N)}} % (fold)
\label{ssub:solve_linear_system}

Solves the linear system $MX = N$ using Gauss–Jordan elimination on the augmented matrix $[M\|N]$.

\begin{itemize}
\item \texttt{M} is the coefficient matrix ($m \times n$).
\item \texttt{N} is the right-hand side column vector ($m \times 1$).
\item Returns the unique solution vector $X$ ($n \times 1$), if it exists.
\end{itemize}

\paragraph{Return value.}
\begin{itemize}
\item Returns a new \tkzClass{matrix} representing the solution.
\item Returns |nil| and an error message if:
\begin{itemize}
\item the system is inconsistent (no solution),
\item the system is underdetermined (infinite solutions),
\item dimensions are incompatible.
\end{itemize}
\end{itemize}

\paragraph{Example.}
\begin{tkzexample}[code only]
M = matrix({{2,1}, {4,-6}})
N = matrix({{5}, {-2}})
X = solve_linear_system(M, N)
\end{tkzexample}



% subsection solve_linear_system (end)