Using octpgfpl you can create diagrams for use with LaTeX/pdfLaTeX from GNU Octave.

Octpgfpl does not attempt to replace GNU Octaves graphics
toolkits or Gnuplot, it is best used in conjunction with them.

Typically you use the graphics toolkits or Gnuplot to explore a
function first, later you use *pgfplot()* to create
illustrations for use with LaTeX.

A 3-clauses BSD style license is used for octpgfpl:

Copyright (c) 2014, Dirk Krause All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above opyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of Dirk Krause nor the names of contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

**pgfplot**

Draw 2D diagrams as *.pgf or *.tex files.

**pgfplot_cs**

Cubic spline interpolation.

The difference to*interp1()*and*csape()*is that you are allowed to specify the first derivative value for any curve points.

**pgfplot_merge**

Merge two vectors.

**pgfplot_varargs**

Return all arguments in a one-dimensional cell array.

Please use the "Discussion" link at the project page on SourceForge 〈1〉 to report bugs, request features, submit patches, make suggestions or give comments.

A bug report should include a minimal example to reproduce the bug, the results you expect and the results found.

This package uses the *is_function_handle()* function which
is available in Octave 3.8.0 and above.

So you need at least version 3.8.0.

- In your home directory create a directory $HOME/octave/octpgfpl (also create $HOME/octave if it does not yet exist).
- Copy all the *.m files from the inst subdirectory into the $HOME/octave/octpgfpl directory.
- Edit the $HOME/.octaverc file, add a line
addpath(genpath("/home/joe/octave/octpgfpl"));

Replace /home/joe by your home directory.

- Find the prefix of your GNU Octave installation. Type
which octave

Remove the final ``/bin/octave'' from the output. The prefix is typically ``/usr'' if you installed GNU Octave using the systems package management or ``/usr/local'' if you installed from source. - Create the ${prefix}/share/octave/packages/octpgfpl directory if it does not yet exist. If some of the parent directories do not yet exist, create them too.
- Copy all the *.m files from the source archives ``inst'' directory into the ${prefix}/share/octave/packages/octpgfpl directory.
- Edit the ${prefix}/share/octave/site/m/startup/octaverc file.
Create the file if it does not yet exist. If some of the parent
directories do not yet exist, create them too.

Make sure there is a lineaddpath(genpath("/usr/share/octave/packages/octpgfpl"));

in the file. Replace ``/usr'' by your prefix if the prefix differs from ``/usr''.

I recommend the "curve" style whenever applicable. When in doubt, make a style=curve test plot.

Polyline plotting is recommended only if one of the following conditions is fullfilled:

- There are regions of steep rise or fall.
- There are discontinuities in the first or second derivative.

If there is only a few discontinuities in the first or second derivative, use the breakpoints mechanism to split the curve into multiple curve segments.

Curves are drawn as sequence of Bezier segments. Each segment is
specified by start point, control point after start point, control
point before end point and end point.

The control points are calculated using the first derivative of the
curve in start and end point.

So we need the first derivative in all the points.

If the derivative is not specified, the program uses a cubic spline
interpolation to find values for the first derivative. This might
take time as solving a linear system of equations is required.

For illustration in article or books the line width for illustrations (including diagrams) should be equal to the "T" character stem width which is typically 0.4pt. So 0.4pt is the default line width.

If you use a larger document size (I prefer 12pt instead of the 10pt used by default) the characters are probably scaled. So for a text size of 12 pt I would recommend a line width of 0.48pt.

If some journals or publishing houses do not accept line widths below a specified minimum, you should use this minimum (i.e. 0.5pt).

The line width for the plot items should differ significantly
from the line width used for grid and box.

I use factor 2.

It depends:

- For diagrams viewed on screen only, you can use colors.
- If you expect anyone to print the document containing your
diagram, you should use just one color: black.

If you do any page layout i.e. to A4 or letter paper size you expect printing (otherwise you would use HTML or any document language not related to any paper size).

Take a look at the example containing a colored and a black diagram and print the page. The colored diagram looks better on screen, the black diagram looks better in print.

The default for the decimal separator (dot or comma) depends on
the unit (dot for inch, comma for cm).

You can use a key/value pair

decimal.separator, ".",

in the *pgfplot()* instruction to change the decimal
separator.

A spline is a contiguous curve specified by a set of discrete data.

A piecewise polynomial (PP) is a function specified in intervals
(pieces). For each interval there is a set of coefficients. For
each *x* in the interval
*x*_{i}≤*x*≤*x*_{i+1}
we can find the *y* value using the formula:

In a spline interpolation we construct a piecewise polynomial using cubic polynomials for the curve pieces.

See the tutorial section Interpolation using cubic splines for details.

The *interp1()* function is included in the GNU Octave
distribution. It uses a not-a-knot condition. I recommend to use
*interp1()* whenever possible.

The *csape()* function from the *spline* package
provides further conditions (variational, complete, second,
periodic). If you need one of these conditions use
*csape()*.

The *pgfplot_cs()* function provides further conditions:
fast and fast-periodic.

In addition to the conditions one can specify values for the first
derivative for the given points.

The *interp1()* and *csape()* functions use optimized
algorithms for the different conditions to find the polynomial
coefficients.

The *pgfplot_cs()* function is more flexible as you can
replace continuity and end point conditions by the value for the
first derivative given. But the function needs to create and solve
a linear system of equations.

So you should use *pgfplot_cs()* only for problems
*interp1()* and *csape()* can not handle.

- Make sure the document preamble includes the following
packages:
- color
- graphicx
- fancybox
- pgfcore

- In the simplest form, use
\input{example01.pgf}

- Typically you want to have your diagram in a figure
environment:
\begin{figure}% {\centering% \input{example01.pgf}% \caption{My example diagram}\label{fig:my-diagram}% }% \end{figure}

You can produce either a *.tex or a *.pgf file.

- *.tex

Run pdflatex on the *.tex file to produce a *.pdf file. - *.pgf

Include the *.pgf file in a *.tex source. You can use either pdflatex or latex/dvi*xyz*to process the *.tex source. - *.tex/*.pdf combination for standalone processing

Use*filename*.pdftexs as filename in the*pgfplot()*function. Run pdflatex on the *.tex file to produce a *.pdf file. - *.tex/*.pdf combination for inclusion in pdfLaTeX documents

Use*filename*.pdftex as filename in the*pgfplot()*function. Include the *.tex file in a *.tex document source.

Create a *.tex file, run pdflatex on it to produce a *.pdf file and see the Graphics conversion hints 〈2〉 how to convert the PDF to other file types.

1 | http://sourceforge.net/projects/octpgfpl |

2 | http://gxhints.sourceforge.net |

Dirk Krause

Schmalkalden, 2017-09-24