view release on metacpan or  search on metacpan

doc-src/diagram-en.tex  view on Meta::CPAN

required explicitly.

The module does not attempt to replace other mathematics and
plotting software, instead it is best used in combination
with
GnuPlot\footnote{\url{http://gnuplot.sourceforge.net}}
and
wxMaxima\footnote{\url{http://maxima.sourceforge.net}}.

\clearpage
\section{Tutorial}
\subsection[Function]{Example 1: Function plot}
\figimage{diagf003}{Example circuit}

In an electronic circuit as seen in figure~\vref{fig:diagf003}
we have a voltage source \(U_{\text{q}}=1\,\text{V}\) with an internal resistance
\(R_{i}=4\,\Omega\). For a variable load resistor
\(0\leq R_{\text{L}}\leq 10\,\Omega\) we want to print the current
\(I\) for each \(R_{\text{L}}\) value.

The formula
\begin{align*}I&=\frac{U_{\text{q}}}{R_{\text{L}}+R_{\text{i}}}\end{align*}
can be used to calculate \(I\).

For a first overview we use GnuPlot:
\begin{lstlisting}[language=GnuPlot]
Uq=1.0
Ri=4.0
set xrange [0:10.0]
plot Uq/(Ri+x) title "Strom"
\end{lstlisting}
The maximum current is \(\tfrac{1}{4}\,\text{A}\), so we use a grid with
of 10\,cm and a grid height of 6\,cm to show currents up to 0,3\,A.

\clearpage
\lstinputlisting[float,title={../examples/test001a.pl},language=Perl]{../examples/test001a.pl}
For the first plot we use the file ../examples/test001a.pl.

In line 3 we use the LaTeX::PGF::Diagram2D module.

The function \textit{I} calculates the current for a resistor value,
the resistor value is the function argument (line 8\ldots{}13).

``LaTeX::PGF::Diagram2D->new'' creates a new diagram, the grid size
is \(10\times{}6\)\,cm (line 16).

The image is used in a \LaTeX{} source written for a font size of
12\.pt (line 18).

The lower \(x\) axis (b: bottom) covers a range 0,0\ldots{}10,0
using a linear scale. Grid lines are drawn for a distance of 1 (line 20),
grid values are printed for a distance of 1 (line 21).

The left \(y\) axis (l: left) covers a range 0,0\ldots{}0,3.
We draw grid lines for a distance of 0,05 and create grid values
for a distance of 0,1 (lines 22 and 23).

The \textit{axis()\/} method of the diagram object returns a reference
for an axis object. A number of axis object methods is used to
set up the axis. Each of the methods returns the axis object reference,
so the methods can be cascaded.

The \textit{plot()\/} method of the diagram object creates a new
plot object and returns the reference to it (line 23).
The \textit{set\textunderscore{}xy\textunderscore{}fct()\/} method
configures the plot object to use the \textit{I()\/} to calculate
the values (line 26).

We save the diagram to file ``../examples/test001a.pgf'' (line 28).

\includepgfimage{../examples/test001a}{Current depending on resistor value.}
\clearpage
\subsection[Labels]{Example 2: Labels and units}
\lstinputlisting[float,language=Perl,title={../examples/test002a.pl}]{../examples/test002a.pl}
\includepgfimage{../examples/test002a}{Diagram with labels and units.}
The \textit{set\textunderscore{}label()\/} axis method sets the
axis label.
The \textit{set\textunderscore{}unit()\/} method sets the unit.
The label is normally set in math mode, the unit is written upright.
Both label and unit are passed to \LaTeX{} so we can use \LaTeX{}
markup here. For each backslash we want to pass to \LaTeX{} we have
to write two backslashes in the Perl source code.

The arrows are added automatically to the axis labels.
The unit is placed between the last two scale values.
\clearpage
\subsection[Space for unit]{Example 3: More space for the unit}
\includepgfimage{../examples/test003a}{More space for \(x\) axis unit}
In the previous example there is very few space between ``9'', ``\(\Omega\)''
and ``10''. So we decide to omit one scale value. If necessary we could
omit multiple values but we are not allowed to omit value ``0''.

The \textit{set\textunderscore{}omit()\/} is used to specify the number
of values to omit.
\lstinputlisting[float,language=Perl,title={../examples/test003a.pl}]{../examples/test003a.pl}
\clearpage
\subsection[Multiple curves]{Example 4: Multiple curves}
\includepgfimage{../examples/test004a}{Multiple curves in one diagram}
We can draw multiple curves into one diagram, we simply have to
create and configure multiple plot objects.
In the example we create a second plot for an internal resistance
of \(6\,\Omega\).

Before we change a variable which is a parameter of a plot function
we must call the \textit{finish()\/} method for all the previous
plot objects. This method does all the calculations needed for the
plot, it can be called after completely configuring the plot.
If the method is not called explicitly, it is called automatically
when the output file is written.

In the example we configure the plot object for the first curve
using \(R_{\text{i}}=4\,\Omega\). Before we change the
``\textdollar{}Ri'' variable to 6.0 we have to calls the
\textit{finish()\/} method of this plot object.
\lstinputlisting[float,language=Perl,title={../examples/test004a.pl}]{../examples/test004a.pl}
\clearpage
\subsection[Text labels]{Example 5: Text labels}
\includepgfimage{../examples/test005a}{Text labels}
Text labels can be used to identify curves. The
\textit{label()\/} diagram method creates a text label.
The arguments are the axis names, the coordinates and the label text.