\subsection{The \emph{luadraw\_log\_axes} module}

This module does not return anything; it adds new graphing methods to the \emph{ld.graph} class, as well as a function in the namespace \emph{luadraw}.

The \emph{luadraw\_log\_axes} module allows you to display a semi-logarithmic or logarithmic grid and to place points on this grid or draw polygonal lines. Creating this grid modifies the 2D matrix of the graph; therefore, the drawing process takes place in three steps:

\begin{enumerate}
    \item Initializing the grid with the \cmd{g:Beginlogview()} method.
    \item Drawing with the \cmd{g:Dlogpolyline()}, \cmd{g:Dlogdots()}, \cmd{Dlogline()} and \cmd{g:Dloglabel()} methods.
    \item Ending the grid with the \cmd{g:Endlogview()} method, which restores the original matrix and allows you to optionally add to the drawing in "normal" coordinates in the original window.
\end{enumerate}

\subsubsection{Initialization: g:Beginlogview()}

The grid initialization and display are handled by the method:
\cmdln{g:Beginlogview(type, xmin, xmax, ymin, ymax, options).}

\begin{itemize}
    \item The argument \argu{type} specifies the desired grid type. Possible values ​​are the strings: \val{"logx"}, \val{"logy"}, or \val{"logxy"}.
    \item The four arguments \argu{xmin}, \argu{xmax}, \argu{ymin}, and \argu{ymax} define the value ranges on the two axes. These ranges are completely independent of the graph's 2D window.
    \item The argument \argu{options} is an array whose fields define the options. These are (with their default values):
    
    \begin{itemize}
    \item \opt{viewport=<current 2D window>}. This option is an array of the form $\{x_1,x_2,y_1,y_2\}$, indicating which area of ​​the graph's 2D window should be used to draw the grid. By default, it's the entire current window (the one defined by the \opt{window} option when the graph was created).
    
    \item \opt{clip=\true}. Boolean indicating whether the grid should clip the drawings. Clipping is disabled after the execution of the \cmd{g:Endlogview()} method.
    
    \item \opt{grid=\{\true,\true\}}. This option allows you to show or hide the vertical grid lines (corresponding to the $x$ axis) and the horizontal grid lines (corresponding to the $y$ axis).
    
    \item \opt{unit=\{"",""\}}. This option specifies the increments for the graduations on the non-logarithmic axes. The default value is the step size (\opt{xstep} on $Ox$, or \opt{ystep} on $Oy$), EXCEPT when the \opt{labeltext} option is not an empty string, in which case \opt{unit} takes the value $1$.
    
    \item \opt{nbsubdiv=\{0 or 3, 0 or 3\}}. This option specifies the number of Subdivisions between two main graduations on the axis. When the axis is non-logarithmic, the default value is zero; otherwise, the default value is $3$.
    
    \item \opt{xstep=nil or 1} and \opt{ystep=nil or 1}. This option specifies the step size on the axes. If the axis is non-logarithmic, the default value is $1$. If the axis is logarithmic, this option represents the difference between the first graduation (the one corresponding to the minimum value) and the second main graduation. If there are multiple decades, this option defaults to \val{nil}, and each decade is divided into $9$ parts. If there is only one decade, this option defaults to one-tenth of the range of values.
    
    \item \opt{defaultloglabels=\{2,3,5,10\}}. This list of values ​​is used to determine the values ​​per decade on the logarithmic axes.

    \item \opt{xdecadeloglabels=\nil} and \opt{ydecadeloglabels=\nil}. This option applies to logarithmic axes. It specifies the list of values ​​for the first decade; these values ​​will provide the main graduations and labels for all decades. If the minimum value on the axis is \emph{vmin}, then the first decade is the interval $[\mathrm{vmin};10\times\mathrm{vmin}]$. By default, this list of values ​​is calculated as: $\{2\times\mathrm{vmin}, 3\times\mathrm{vmin}, 5\times\mathrm{vmin}, 10\times\mathrm{vmin}\}$ (it is unnecessary to specify the first value \emph{vmin}, as it is automatically added). The list $\{2,3,5,10\}$ is the default value for the \opt{defaultloglabels} option
    
    \item \opt{xexponent=0} and \opt{yexponent=0}. This option applies to logarithmic axes. For example, when \opt{xexponent=2}, all the labels on the $x$ axis are divided by $10^2$, and the string $(\times10^2)$ will be added to the legend. The same principle applies to the $y$ axis if it is logarithmic.
    
    \item \opt{xaddloglabels=\{\}} and \opt{yaddloglabels=\{\}}. This option applies to logarithmic axes. It allows you to add a list of values ​​that will provide additional labels; these values ​​must be between the minimum and maximum values ​​of the axis.
    
    \item \opt{tickpos=\{0.5,0.5\}}. This option specifies the position of the tick marks relative to each axis. These are two numbers between $0$ and $1$. The default value of $0.5$ means they are centered on the axis ($0$ and $1$ represent the endpoints).
    
    \item \opt{xyticks=\{0.2,0.2\}}. This option specifies the length of the tick marks on the axes.
    
    \item \opt{xylabelsep=\{0,0\}}. This option specifies the distance between the labels and the tick marks on the axes.
    
    \item \opt{originloc=<lower left corner>}. This option specifies the origin point of the tick marks for the non-logarithmic axis.
    
    \item \opt{originnum=\{minimum,minimum\}}. This option specifies the value at the origin point of the tick marks (tick number $0$) for the non-logarithmic axis. The formula that defines the label at tick number $n$ is:
    \codeln{(originnum + unit*n)"labeltext"/labelden.}
    
    \item \opt{legend=\{"",""\}}. This option specifies a legend for the axes. By default, the x-axis legend is located below the axis and in the middle, and the y-axis legend is located to the left of the axis, in the middle, and is written vertically.
    
    \item \opt{legendpos=\{0.5,0.5\}}. This option specifies the position (between $0$ and $1$) of the legend relative to each axis.
    
    \item \opt{legendsep=\{-0.5,-1\} }. This option specifies the distance between the legend and the axis. The legend is on the opposite side of the axis from the graduations.
    
    \item \opt{legendangle=\{0,90\}}. This option specifies the angle (in degrees) that the legend should make with the axis.
    
    \item \opt{legendstyle=\{"S","N"\}}. Specifies the label style for the legends, with the value \val{"auto"} it is determined automatically, otherwise you can use the values: \val{"N"}, \val{"NW"}, \val{"W"}, \val{"SW"}, \val{"S"}, \val{"SE"}, \val{"E"}, \val{"NE"}.
    
    \item \opt{labelpos=\{"bottom","left"\}}. This option specifies the position of the labels relative to the axis. For the $Ox$ axis, the possible values ​​are: \val{"none"}, \val{"bottom"}, or \val{"top"}; for the $Oy$ axis, it is: \val{"none"}, \val{"right"}, or \val{"left"}.
    
    \item \opt{labelstyle=\{"S","W"\}}. This option defines the style of the labels for each axis. The possible values ​​are: \val{"auto"}, \val{"N"}, \val{"NW"}, \val{"W"}, \val{"SW"}, \val{"S"}, \val{"SE"}, \val{"E"}, \val{"NE"}.
    
    \item \opt{labelangle=\{0,0\}}. This option defines the angle of the labels in degrees relative to the horizontal for each axis.
    
    \item \opt{labelcolor=\{"",""\}}. This option allows you to choose a color for the labels on each axis. The empty string represents the default color.
    
    \item \opt{labelden=\{1,1\}}. ​​This option specifies the denominator of the labels (integer) for the non-logarithmic axis.
    
    \item \opt{labeltext=\{"",""\}}. This option defines the text that will be added to the numerator of the labels for the non-logarithmic axis.
    
    \item \opt{xynode\_options=""}. String that will be passed as is to the \verb|\node{}| instruction for all labels on both axes (but not for legends).
    
    \item \opt{xnode\_options=xynode\_options}. String that will be passed as is to the \verb|\node{}| instruction for all labels on the x-axis (but not for the legend).
    
    \item \opt{ynode\_options=xynode\_options}. String that will be passed as is to the \verb|\node{}| instruction for all labels on the y-axis (but not for the legend).
    
    \item \opt{use\_siunitx=\{siunitx,siunitx\}}. This option specifies whether numeric values ​​should be formatted using the \emph{siunitx} package; the default value is that of the global variable \varglob{siunitx}, which is \false by default.
    
    \item \opt{mylabels=""}. This option allows you to apply custom labels to the non-logarithmic axis. When labels are required, the value passed to this option must be a list of the type: \code{\{pos1,"text1",pos2,"text2",\ldots\}}. The number \argu{pos1} represents an x-coordinate in the coordinate system \code{(A,step)} ($A$ being the origin of the axis), which corresponds to the point with affix \code{A+pos1*step}, the step being either \opt{xstep} or \opt{ystep} along the axis.
    
    \item \opt{gridstyle="solid"}. This option defines the line style for the primary grid.
    
    \item \opt{subgridstyle="solid"}. This option defines the line style for the secondary grid. A secondary grid appears when there are subdivisions on one of the axes.
    
    \item \opt{gridcolor="gray"}. This sets the color of the primary grid.
    
    \item \opt{subgridcolor="lightgray"}. This sets the color of the secondary grid.
    
    \item \opt{gridwidth=4}. Line thickness of the primary grid (which is 0.4pt).
    
    \item \opt{subgridwidth=2}. Line thickness of the secondary grid (which is 0.2pt).
    \end{itemize}
\end{itemize}

\subsubsection{Drawing and Conversion Methods}

\begin{itemize}
    \item The \cmd{g:Dlogpolyline(L \fac{, close, draw\_options})} method draws the 2D polygonal line \argu{L} on the grid; coordinate conversion is automatic. The \argu{close} argument is a boolean indicating whether the line should be closed (\false by default), and the \argu{draw\_options} argument is a string (empty by default) that will be passed to the \drawcmd instruction.

    \item The method \cmd{g:Dlogdots(L \fac{, mark\_options})} draws the scatter plot contained in \argu{L} (a complex number, a list of complex numbers, or a list of lists of complex numbers) on the grid. Coordinate conversion is automatic. The argument \argu{mark\_options} is a string (empty by default) that will be passed to the \drawcmd instruction.

    \item The method \cmd{g:Dlogline(A, B \fac{, draw\_options})} draws the line passing through points \argu{A} and \argu{B} on the grid (coordinate conversion is automatic). The argument \argu{draw\_options} is a string (empty by default) that will be passed to the \drawcmd instruction.

    \item Conversion function: \cmd{ld.Zlog(z)} where \argu{z} is a complex number, returns the affix on the grid of the corresponding point.    
\end{itemize}

\subsubsection{End of grid usage: g:Endlogview()}

The \cmd{g:Endlogview()} method restores the initial graph matrix and the 2D window.

\subsubsection{Examples}

\begin{demo}{Logarithmic x-axis}
\begin{luadraw}{name=logx_example}
local ld = luadraw
local cpx = ld.cpx
local Z = cpx.Z
local log10 = math.log10

local g = ld.graph:new{ size={14,10,0} }
require 'luadraw_log_axes'
g:Beginlogview("logx", 1, 100, -0.2, 2.2, {
   nbsubdiv={3,1},
   ystep = 0.2,
   legend={"The line $(AB)$ and the curve $y=\\log_{10}(x)$ coincide.","$y=\\log_{10}(x)$"}
})
local L = ld.cartesian(function(x) return log10(x) end, 1,100)
local A, B = 1, Z(100,2)
g:Dlogline(A,B, "Pink,line width=2.4pt")
g:Dlogpolyline(L,"blue") 
g:Dlogdots({A,B})
g:Dloglabel("$A$", A, {pos="SE"}, "$B$", B, {pos="NW"})
g:Endlogview()
g:Show()
\end{luadraw}
\end{demo}   


\begin{demo}{Logarithmic x-axis and logarithmic xy-axis}
\begin{luadraw}{name=logy_and_logxy_example}
local ld = luadraw
local cpx = ld.cpx
local Z = cpx.Z
local  exp = math.exp

local g = ld.graph:new{ window={-10,10,-5,5}, size={18,10,0} }
require 'luadraw_log_axes'
g:Beginlogview("logy", -1, 5, 0.2, 200, { viewport={0.25,10,-5,4.5},
    nbsubdiv = {1,1},
    legendsep = {-0.5,-0.5},
    legend = {"The line $(AB)$ and the curve $y=\\exp(x)$ coincide.",""}
})
local L = ld.cartesian(exp, -1, 5)
local A, B = Z(-1,exp(-1)), Z(5,exp(5))
g:Dlogline(A,B, "Pink,line width=2.4pt")
g:Dlogpolyline(L,"blue") 
g:Dlogdots({A,B})
g:Dloglabel("$A$", A, {pos="SE"}, "$B$", B, {pos="NW"})
g:Endlogview()

g:Beginlogview("logxy", 9, 100, 7e2, 1e6, { viewport={-10,-0.25,-5,4.5},
    nbsubdiv = {8,1},
    xaddloglabels={100},
    legendsep = {-0.5,-0.75},
    yexponent=2,
    yaddloglabels={1e6}, 
    labelangle={-90,0}, labelstyle={"E","W"},
    legend = {"The line $(AB)$ and the curve $y=x^3$ coincide.",""}
})
local L = ld.cartesian(function(x) return x^3 end, 9, 100)
local A, B = Z(10,1e3), Z(90,729e3)
g:Dlogline(A,B, "Pink,line width=2.4pt")
g:Dlogpolyline(L,"blue") 
g:Dlogdots({A,B})
g:Dloglabel("$A$", A, {pos="SE"}, "$B$", B, {pos="NW"})
g:Endlogview()
-- drawing on the "normal" 2D window
g:Dlabel("$y=\\mathrm{e}^x$ with a logarithmic y-axis",Z(5,4.5),{pos="N"},
  "$y=x^3$ with logarithmic $xy$-axis.",Z(-5,4.5),{})
g:Show()
\end{luadraw}
\end{demo}
