This module provides a class to hold, manipulate and employ various
options for rendering a graph in .
AUTHORS:
Many mathematical objects in Sage have representations, and graphs are no exception. For a graph g, the command view(g) or view(g, pdflatex=True), issued at the Sage command line or in the notebook, will create a graphic version of g. Similarly, latex(g) will return a (long) string that is a representation of the graph in
. Other ways of employing
in Sage, such as %latex in a notebook cell, or the Typeset checkbox in the notebook, will handle g appropriately.
To use in Sage you of course need a working
installation and it will work best if you have the dvipng and convert utilities. For graphs you need the tkz-graph.sty and tkz-berge.sty style files of the tkz-graph package. You can find these at:
Customizing the output is accomplished in several ways. Suppose g is a graph, then g.set_latex_options() can be used to efficiently set or modify various options. Setting individual options, or querying options, can be accomplished by first using a command like opts = g.latex_options() to obtain a sage.graphs.graph_latex.GraphLatex object which has several methods to set and retrieve options. The following session illustrates the use of these commands. The full output of latex(g) is not included, but the two calls would produce different output due to the change of the style.
The range of possible options are carefully documented at sage.graphs.graph_latex.GraphLatex.set_option().
EXAMPLES:
sage: g = graphs.PetersenGraph()
sage: g.set_latex_options(tkz_style = 'Classic')
sage: from sage.graphs.graph_latex import check_tkz_graph
sage: check_tkz_graph() # random - depends on TeX installation
sage: latex(g)
\begin{tikzpicture}
...
\end{tikzpicture}
sage: opts = g.latex_options()
sage: opts
LaTeX options for Petersen graph: {'tkz_style': 'Classic'}
sage: opts.set_option('tkz_style', 'Art')
sage: opts.get_option('tkz_style')
'Art'
sage: opts
LaTeX options for Petersen graph: {'tkz_style': 'Art'}
sage: latex(g)
\begin{tikzpicture}
...
\end{tikzpicture}
A class to hold, manipulate and employ options for converting
a graph to .
This class serves two purposes. First it holds the values of
various options designed to work with the tkz-graph
package for rendering graphs. As such, a
graph that uses this class will hold a reference to it. Second,
this class contains the code to convert a graph into the
corresponding
constructs, returning a string.
EXAMPLES:
sage: from sage.graphs.graph_latex import GraphLatex
sage: opts = GraphLatex(graphs.PetersenGraph())
sage: opts
LaTeX options for Petersen graph: {'tkz_style': 'Normal'}
sage: g = graphs.PetersenGraph()
sage: opts = g.latex_options()
sage: g == loads(dumps(g))
True
Two sage.graphs.graph_latex.GraphLatex objects are equal if their options are equal.
The graphs they are associated with are ignored in the comparison.
TESTS:
sage: from sage.graphs.graph_latex import GraphLatex
sage: opts1 = GraphLatex(graphs.PetersenGraph())
sage: opts2 = GraphLatex(graphs.CompleteGraph(10))
sage: opts1.set_option('tkz_style', 'Art')
sage: opts2.set_option('tkz_style', 'Art')
sage: opts1 == opts2
True
sage: opts2.set_option('tkz_style', 'Normal')
sage: opts1 == opts2
False
Returns a GraphLatex object, which holds all the parameters needed for
creating a string that will be rendered as a picture of the graph.
See sage.graphs.graph_latex for more documentation.
EXAMPLES:
sage: from sage.graphs.graph_latex import GraphLatex
sage: GraphLatex(graphs.PetersenGraph())
LaTeX options for Petersen graph: {'tkz_style': 'Normal'}
Returns a string representation of a sage.graphs.graph_latex.GraphLatex object which includes the name of the graph and the dictionary of current options.
EXAMPLES:
sage: g = graphs.PetersenGraph()
sage: opts = g.latex_options()
sage: opts.set_option('tkz_style', 'foo')
sage: print opts._repr_()
LaTeX options for Petersen graph: {'tkz_style': 'foo'}
Returns the current value of the named option.
INPUT:
OUTPUT:
If the name is not present in sage.graphs.graph_latex.__graphlatex_options it is an error to ask for it. If an option has not been set then the returned value is None. Otherwise, the value of the option is returned.
EXAMPLES:
sage: g = graphs.PetersenGraph()
sage: opts = g.latex_options()
sage: opts.set_option('tkz_style', 'Art')
sage: opts.get_option('tkz_style')
'Art'
sage: opts.set_option('tkz_style')
sage: opts.get_option('tkz_style') == None
True
sage: opts.get_option('bad_name')
...
ValueError: bad_name is not a Latex option for a graph.
Returns a string in representing a graph.
This is the command that is invoked by
_latex_() for
a graph, so it returns a string of
commands that can be incorporated
into a
document unmodified. The exact contents
of this string are influenced by the options set via the methods
sage.graphs.graph.GenericGraph.set_latex_options(),
set_option(), and set_options().
Right now it only calls one procedure for creating strings using the tkz-graph package, but by passing in an option and implementing a new procedure, other packages could be supported in the future.
EXAMPLES:
sage: from sage.graphs.graph_latex import check_tkz_graph
sage: check_tkz_graph() # random - depends on TeX installation
sage: g = graphs.CompleteGraph(2)
sage: opts = g.latex_options()
sage: print opts.latex()
\begin{tikzpicture}
%
\definecolor{col_a0}{rgb}{1.0,1.0,1.0}
\definecolor{col_a1}{rgb}{1.0,1.0,1.0}
%
%
\definecolor{col_lab_a0}{rgb}{0.0,0.0,0.0}
\definecolor{col_lab_a1}{rgb}{0.0,0.0,0.0}
%
%
\definecolor{col_a0-a1}{rgb}{0.0,0.0,0.0}
%
%
\GraphInit[vstyle=Normal]
%
\SetVertexMath
%
\SetVertexNoLabel
%
\renewcommand*{\VertexLightFillColor}{col_a0}
\Vertex[x=5.0cm,y=5.0cm]{a0}
\renewcommand*{\VertexLightFillColor}{col_a1}
\Vertex[x=0.0cm,y=0.0cm]{a1}
%
%
\AssignVertexLabel{a}{2}{
\color{col_lab_a0}{$0$},
\color{col_lab_a1}{$1$}
}
%
%
\renewcommand*{\EdgeColor}{col_a0-a1}
\Edge(a0)(a1)
%
%
\end{tikzpicture}
Sets, modifies, clears a legitimate
option for rendering a graph.
INPUTS:
Possible option names, and associated values are given below. For precise details consult the documentation for the tkz-graph package.
EXAMPLES:
Set, then modify, then clear the tkz_style option, and finally show an error for an unrecognized option name.
sage: g = graphs.PetersenGraph()
sage: opts = g.latex_options()
sage: opts
LaTeX options for Petersen graph: {'tkz_style': 'Normal'}
sage: opts.set_option('tkz_style', 'foo')
sage: opts
LaTeX options for Petersen graph: {'tkz_style': 'foo'}
sage: opts.set_option('tkz_style', 'bar')
sage: opts
LaTeX options for Petersen graph: {'tkz_style': 'bar'}
sage: opts.set_option('tkz_style')
sage: opts
LaTeX options for Petersen graph: {}
sage: opts.set_option('bad_name', 'nonsense')
...
ValueError: bad_name is not a LaTeX option for a graph.
Set several options for a graph all at once.
INPUTS:
- kwds - any number of option/value pairs to se many graph latex options at once (a variable number, in any order). Existing values are overwritten, new values are added. Existing values can be cleared by setting the value to None. Errors are raised in the set_option() method.
EXAMPLES:
sage: g = graphs.PetersenGraph()
sage: opts = g.latex_options()
sage: opts.set_options(tkz_style = 'Welsh')
sage: opts.get_option('tkz_style')
'Welsh'
Return a string of commands representing a graph as a tikzpicture.
This routine interprets the graph’s properties and the options in
_options to render the graph with commands from the tkz-graph
package.
This requires that the optional packages
tkz-graph and tkz-berge be installed. You may also need a
current version of the pgf package. If the tkz-graph and
tkz-berge packages are present in the system’s TeX
installation, the appropriate \\usepackage{} commands
will be added to the
preamble as part of
the initialization of the graph. If these two packages
are not present, then this command will return a warning
on its first use, but will return a string that could be
used elsewhere, such as a
document.
For more information about tkz-graph you can visit http://altermundus.com/pages/graph.html
EXAMPLES:
sage: from sage.graphs.graph_latex import check_tkz_graph
sage: check_tkz_graph() # random - depends on TeX installation
sage: g = graphs.CompleteGraph(3)
sage: opts = g.latex_options()
sage: print opts.tkz_picture()
\begin{tikzpicture}
%
\definecolor{col_a0}{rgb}{1.0,1.0,1.0}
\definecolor{col_a1}{rgb}{1.0,1.0,1.0}
\definecolor{col_a2}{rgb}{1.0,1.0,1.0}
%
%
\definecolor{col_lab_a0}{rgb}{0.0,0.0,0.0}
\definecolor{col_lab_a1}{rgb}{0.0,0.0,0.0}
\definecolor{col_lab_a2}{rgb}{0.0,0.0,0.0}
%
%
\definecolor{col_a0-a1}{rgb}{0.0,0.0,0.0}
\definecolor{col_a0-a2}{rgb}{0.0,0.0,0.0}
\definecolor{col_a1-a2}{rgb}{0.0,0.0,0.0}
%
%
\GraphInit[vstyle=Normal]
%
\SetVertexMath
%
\SetVertexNoLabel
%
\renewcommand*{\VertexLightFillColor}{col_a0}
\Vertex[x=2.5cm,y=5.0cm]{a0}
\renewcommand*{\VertexLightFillColor}{col_a1}
\Vertex[x=0.0cm,y=0.0cm]{a1}
\renewcommand*{\VertexLightFillColor}{col_a2}
\Vertex[x=5.0cm,y=0.0cm]{a2}
%
%
\AssignVertexLabel{a}{3}{
\color{col_lab_a0}{$0$},
\color{col_lab_a1}{$1$},
\color{col_lab_a2}{$2$}
}
%
%
\renewcommand*{\EdgeColor}{col_a0-a1}
\Edge(a0)(a1)
\renewcommand*{\EdgeColor}{col_a0-a2}
\Edge(a0)(a2)
\renewcommand*{\EdgeColor}{col_a1-a2}
\Edge(a1)(a2)
%
%
\end{tikzpicture}
TESTS:
Graphs with preset layouts that are vertical or horizontal can cause problems. First test is a horizontal layout on a path with three vertices.
sage: from sage.graphs.graph_latex import check_tkz_graph
sage: check_tkz_graph() # random - depends on TeX installation
sage: g = graphs.PathGraph(3)
sage: opts = g.latex_options()
sage: print opts.tkz_picture()
\begin{tikzpicture}
%
\definecolor{col_a0}{rgb}{1.0,1.0,1.0}
\definecolor{col_a1}{rgb}{1.0,1.0,1.0}
\definecolor{col_a2}{rgb}{1.0,1.0,1.0}
%
%
\definecolor{col_lab_a0}{rgb}{0.0,0.0,0.0}
\definecolor{col_lab_a1}{rgb}{0.0,0.0,0.0}
\definecolor{col_lab_a2}{rgb}{0.0,0.0,0.0}
%
%
\definecolor{col_a0-a1}{rgb}{0.0,0.0,0.0}
\definecolor{col_a1-a2}{rgb}{0.0,0.0,0.0}
%
%
\GraphInit[vstyle=Normal]
%
\SetVertexMath
%
\SetVertexNoLabel
%
\renewcommand*{\VertexLightFillColor}{col_a0}
\Vertex[x=0.0cm,y=2.5cm]{a0}
\renewcommand*{\VertexLightFillColor}{col_a1}
\Vertex[x=2.5cm,y=2.5cm]{a1}
\renewcommand*{\VertexLightFillColor}{col_a2}
\Vertex[x=5.0cm,y=2.5cm]{a2}
%
%
\AssignVertexLabel{a}{3}{
\color{col_lab_a0}{$0$},
\color{col_lab_a1}{$1$},
\color{col_lab_a2}{$2$}
}
%
%
\renewcommand*{\EdgeColor}{col_a0-a1}
\Edge(a0)(a1)
\renewcommand*{\EdgeColor}{col_a1-a2}
\Edge(a1)(a2)
%
%
\end{tikzpicture}
Scaling to a bounding box is problematic for graphs with just one vertex, or none.
sage: from sage.graphs.graph_latex import check_tkz_graph
sage: check_tkz_graph() # random - depends on TeX installation
sage: g = graphs.CompleteGraph(1)
sage: opts = g.latex_options()
sage: print opts.tkz_picture()
\begin{tikzpicture}
%
\definecolor{col_a0}{rgb}{1.0,1.0,1.0}
%
%
\definecolor{col_lab_a0}{rgb}{0.0,0.0,0.0}
%
%
%
%
\GraphInit[vstyle=Normal]
%
\SetVertexMath
%
\SetVertexNoLabel
%
\renewcommand*{\VertexLightFillColor}{col_a0}
\Vertex[x=2.5cm,y=2.5cm]{a0}
%
%
\AssignVertexLabel{a}{1}{
\color{col_lab_a0}{$0$}
}
%
%
%
%
\end{tikzpicture}
Checks if the proper
packages for the tikzpicture environment are
installed in the user’s environment.
If the requisite packages are not found on the first call to this function, warnings are printed. Thereafter, the function caches its result in the variable _have_tkz_graph, and any subsequent time, it just checks the value of the variable, without printing any warnings.
So any doctest that illustrates the use of the tkz-graph packages should call this once as having random output to exhaust the warnings before testing output.
TESTS:
sage: from sage.graphs.graph_latex import check_tkz_graph
sage: check_tkz_graph() # random - depends on TeX installation
sage: check_tkz_graph() # at least the second time, so no output
Returns True if the proper packages
for the tikzpicture environment are installed in the
user’s environment.
The first time it is run, this function caches its result in the variable _have_tkz_graph, and any subsequent time, it just checks the value of the variable.
TESTS:
sage: from sage.graphs.graph_latex import have_tkz_graph, _have_tkz_graph
sage: have_tkz_graph() # random - depends on TeX installation
sage: _have_tkz_graph is None
False
sage: _have_tkz_graph == have_tkz_graph()
True