Plotting Functions

plot_planar_simplicial(sc::AbstractComplex,
                       coords::Vector{<:Vector{<:Real}},
                       fname::String;
                       [mvf::CellSubsets=Vector{Vector{Int}}([]),]
                       [labeldir::Vector{<:Real}=Vector{Int}([]),]
                       [labeldis::Real=8,]
                       [hfac::Real=1.2,]
                       [vfac::Real=1.2,]
                       [sfac::Real=0,]
                       [pdim::Vector{Bool}=[true,true,true],]
                       [pv::Bool=false])

Create an image of a planar simplicial complex, and if specified, a Forman vector field on it.

The vector coords contains coordinates for every one of the vertices of the simplicial complex sc. The image will be saved in the file with name fname, and the ending determines the image type. Accepted are .pdf, .svg, .png, and .eps.

If the optional mvf is specified and is a Forman vector field, then this Forman vector field is drawn as well. The optional vector labeldir contains directions for the vertex labels, and labeldis the distance from the vertex. The directions have to be reals between 0 and 4, with 0,1,2,3 corresponding to E,N,W,S. The optional constants hfac and vfac contain the horizontal and vertical scale vectors, while sfac describes a uniform scale. If sfac=0 the latter is automatically determined. The vector pdim specifies in which dimensions cells are drawn; the default shows vertices, edges, and triangles. Finally if one passes the argument pv=true, then in addition to saving the file a preview is displayed.

Examples

Suppose we have created a simplicial complex using the commands

sc, coords = create_simplicial_delaunay(300, 300, 30, 20)
fname = "sc_plot_test.pdf"

Then the following code creates an image of the simplicial complex without labels, but with a preview:

plot_planar_simplicial(sc, coords, fname, pv=true)

If we want to see the labels, we can use

ldir = fill(0.5, sc.ncells);
plot_planar_simplicial(sc, coords, fname, labeldir=ldir, labeldis=10, pv=true)

This command puts all labels in the North-East direction at a distance of 10.

plot_planar_simplicial(ec::EuclideanComplex,
                       fname::String;
                       kwargs...)

Create an image of a planar simplicial complex from an EuclideanComplex.

The vertex positions for every cell are taken directly from ec.coords[k], which stores the complete vertex coordinates for each cell k. This means the function works correctly even when some vertices are no longer present as cells in the complex (e.g. after subcomplex creation), as long as the higher-dimensional cells still carry their coordinates.

plot_planar_simplicial_morse(sc::AbstractComplex,
                             coords::Vector{<:Vector{<:Real}},
                             fname::String,
                             morsesets::CellSubsets;
                             [hfac::Real=1.2,]
                             [vfac::Real=1.2,]
                             [sfac::Real=0,]
                             [pdim::Vector{Bool}=[false,true,true],]
                             [pv::Bool=false,]
                             [ci::Bool=false])

Create an image of a planar simplicial complex, together with Morse sets, or also selected multivectors.

The vector coords contains coordinates for every one of the vertices of the simplicial complex sc. The image will be saved in the file with name fname, and the ending determines the image type. Accepted are .pdf, .svg, .png, and .eps.

The vector morsesets contains a list of Morse sets, or more general, subsets of the simplicial complex. For every k, the set described by morsesets[k] will be shown in a distinct color.

The optional constants hfac and vfac contain the horizontal and vertical scale vectors for the margins, while sfac describes a uniform scale. If sfac=0 the latter is automatically determined. The vector pdim specifies in which dimensions cells are drawn; the default only shows edges and triangles. If one passes the argument pv=true, then in addition to saving the file a preview is displayed. Lastly, passing the argument ci=true will color code the Morse sets according to their respective Conley indices.

plot_planar_simplicial_morse(ec::EuclideanComplex,
                             fname::String,
                             morsesets::CellSubsets;
                             kwargs...)

Create an image of a planar simplicial complex with Morse sets from an EuclideanComplex.

The vertex positions for every cell are taken directly from ec.coords[k], which stores the complete vertex coordinates for each cell k. This means the function works correctly even when some vertices are no longer present as cells in the complex (e.g. after subcomplex creation), as long as the higher-dimensional cells still carry their coordinates.

plot_planar_cubical(cc::AbstractComplex,
                    coords::Vector{<:Vector{<:Real}},
                    fname::String;
                    [hfac::Real=1.2,]
                    [vfac::Real=1.2,]
                    [cubefac::Real=0,]
                    [pdim::Vector{Bool}=[true,true,true],]
                    [pv::Bool=false])

Create an image of a planar cubical complex.

The vector coords contains coordinates for every one of the vertices of the cubical complex cc. The image will be saved in the file with name fname, and the ending determines the image type. Accepted are .pdf, .svg, .png, and .eps. The optional constants hfac and vfac contain the horizontal and vertical scale vectors. The optional argument cubefac specifies the side length of an elementary cube for plotting, and it will be automatically determined otherwise. The vector pdim specifies which cell dimensions should be plotted, with pdim[k] representing dimension k-1. Finally if one passes the argument pv=true, then in addition to saving the file a preview is displayed.

Examples

Suppose we have created a cubical complex using the commands

cubes = ["00.11", "01.01", "02.10", "11.10", "11.01", "22.00"]
coords = [[0,0],[0,1],[0,2],[1,0],[1,1],[1,2],[2,1],[2,2]]
cc = create_cubical_complex(cubes)
fname = "cc_plot_test.pdf"

Then the following code creates an image of the simplicial complex without labels, but with a preview:

plot_planar_cubical(cc, coords, fname, pv=true)

If one only wants to plot the edges in the complex, but not the vertices or rectangles, then one can use:

plot_planar_cubical(cc, coords, fname, pv=true, pdim=[false,true,false])

plot_planar_cubical(cc::AbstractComplex,
                    fname::String;
                    [hfac::Real=1.2,]
                    [vfac::Real=1.2,]
                    [cubefac::Real=0,]
                    [pdim::Vector{Bool}=[true,true,true],]
                    [pv::Bool=false])

Create an image of a planar cubical complex.

This is an alternative method which does not require the specification of the vertex coordinates. They will be taken from the cube vertex labels.

plot_planar_cubical(ec::EuclideanComplex,
                    fname::String;
                    kwargs...)

Create an image of a planar cubical complex from an EuclideanComplex.

The vertex positions for every cell are taken directly from ec.coords[k], which stores the complete vertex coordinates for each cell k. This means the function works correctly even when some vertices are no longer present as cells in the complex (e.g. after subcomplex creation), as long as the higher-dimensional cells still carry their coordinates.

plot_planar_cubical_morse(cc::AbstractComplex,
                          coords::Vector{<:Vector{<:Real}},
                          fname::String,
                          morsesets::CellSubsets;
                          [hfac::Real=1.2,]
                          [vfac::Real=1.2,]
                          [cubefac::Real=0,]
                          [pdim::Vector{Bool}=[false,true,true],]
                          [pv::Bool=false])

Create an image of a planar cubical complex, together with Morse sets, or also selected multivectors.

The vector coords contains coordinates for every one of the vertices of the cubical complex cc. The image will be saved in the file with name fname, and the ending determines the image type. Accepted are .pdf, .svg, .png, and .eps.

The vector morsesets contains a list of Morse sets, or more general, subsets of the cubical complex. For every k, the set described by morsesets[k] will be shown in a distinct color.

The optional constants hfac and vfac contain the horizontal and vertical scale vectors for the margins, while cubefac describes a uniform scale. If cubefac=0 the latter is automatically determined. The vector pdim specifies in which dimensions cells are drawn; the default only shows edges and squares. Finally if one passes the argument pv=true, then in addition to saving the file a preview is displayed.

plot_planar_cubical_morse(cc::AbstractComplex,
                          fname::String,
                          morsesets::CellSubsets;
                          [hfac::Real=1.2,]
                          [vfac::Real=1.2,]
                          [cubefac::Real=0,]
                          [pdim::Vector{Bool}=[false,true,true],]
                          [pv::Bool=false])

Create an image of a planar cubical complex, together with Morse sets, or also selected multivectors.

This is an alternative method which does not require the specification of the vertex coordinates. They will be taken from the cube vertex labels.

plot_planar_cubical_morse(ec::EuclideanComplex,
                          fname::String,
                          morsesets::CellSubsets;
                          kwargs...)

Create an image of a planar cubical complex with Morse sets from an EuclideanComplex.

The vertex positions for every cell are taken directly from ec.coords[k], which stores the complete vertex coordinates for each cell k. This means the function works correctly even when some vertices are no longer present as cells in the complex (e.g. after subcomplex creation), as long as the higher-dimensional cells still carry their coordinates.

plot_morse_strata(lc, ap, fname; A=nothing, title="", figw=nothing, figh=nothing, pv=false)

Hasse-style diagram of the Morse-vector strata of AP^d(X). Nodes are distinct Morse vectors, drawn as circles labeled (M) and n=... (the number of AP^d(X) partitions with that Morse vector), placed by level sum(M) (monotone under refinement) – note that "adjacent" levels need not differ by 1 in sum(M): every weight-1 jump already raises it by 2, since ek + e{k-1} sums to 2.

Edges are drawn between every pair of strata found adjacent by stratum_adjacency, labeled |c|=<weight>, <covered>/<total> (how many of the coarser stratum's partitions admit an atomic refinement into the finer one, out of how many total), and styled by the classification spelled out in the figure's own legend:

• solid green: weight |c| = 1 (always uniform)
• solid gray: weight |c| >= 2, but every partition happens to be covered for this particular complex anyway
• dashed red: weight |c| >= 2 and not every partition is covered (a realized counterexample to the naive question)

An edge that skips an intermediate level is bent aside so it doesn't draw on top of the shorter edges passing through that level.

figw and figh default to nothing, which auto-sizes the canvas: the full layout (nodes and every bend point) is computed first, then the canvas is sized and the whole picture shifted to fit it exactly (with a floor wide enough for the legend text even when there's very little else to draw), so nothing is ever cut off regardless of how far a bend ends up needing to reach. Pass explicit values to override – explicit figw and figh are used as-is, not auto-corrected. title, if given, is drawn at the top of the figure.

See also plot_morse_reachability for the analogous diagram of eventual (multi-step) reachability between strata, rather than single-step adjacency.

Examples

Consider the triangle ABC with a pendant edge CD attached at C:

labels    = ["A", "B", "C", "D"]
simplices = [[1, 2, 3], [3, 4]]
lc = create_simplicial_complex(labels, simplices)

ap = construct_ap_space(lc)
plot_morse_strata(lc, ap, "strata.pdf", title="Triangle ABC with pendant edge CD")

If both plot_morse_strata and plot_morse_reachability are wanted for the same complex, precompute atomic_distances once and pass it to both, since it is the expensive step and is otherwise recomputed by each call:

A = atomic_distances(lc, ap)
plot_morse_strata(lc, ap, "adjacency.pdf"; A=A)
plot_morse_reachability(lc, ap, "reachability.pdf"; A=A)

plot_morse_reachability(lc, ap, fname; A=nothing, title="", figw=nothing, figh=nothing, pv=false)

Hasse-style diagram of eventual reachability between the Morse-vector strata of AP^d(X), i.e. the multi-step generalization of plot_morse_strata: an edge M2 -> M1 here means some element of AP_{M2} reaches AP_{M1} via a chain of atomic refinements of any length (stratum_reachability), not just a single one (stratum_adjacency). Nodes are laid out exactly as in plot_morse_strata – distinct Morse vectors, drawn as circles labeled (M) and n=..., placed by level sum(M).

Because eventual reachability is transitive, stratum_reachability reports an edge for every comparable pair of strata reachable by some chain – far denser than the single-step covering relation plot_morse_strata draws. To keep the picture legible, only the transitive reduction of that relation is drawn, computed by _stratum_transitive_reduction. An edge M2 -> M1 is omitted whenever it is already implied by some other drawn path M2 -> ... -> M1. This means the absence of a drawn edge between two strata does not mean one is unreachable from the other – only that a shown path already establishes it. The full (unreduced) edge set and underlying element-level reachability are both available in the return value for anything needing the raw data.

Edges are labeled |c|=<weight>, <covered>/<total> (how many of the coarser stratum's partitions eventually reach the finer one, out of how many total), and colored:

• solid green: uniform – every partition of the coarser stratum eventually reaches the finer one
• dashed red: not uniform – at least one partition of the coarser stratum never reaches the finer one

Unlike plot_morse_strata, there is no weight-based three-way split: the weight-1 uniformity guarantee is specifically about single atomic refinements and does not extend to multi-step chains, so no analogous "guaranteed" tier exists here to draw a distinction around.

figw, figh, title, and pv behave exactly as in plot_morse_strata.

Examples

Consider the triangle ABC with a pendant edge CD attached at C:

labels    = ["A", "B", "C", "D"]
simplices = [[1, 2, 3], [3, 4]]
lc = create_simplicial_complex(labels, simplices)

ap = construct_ap_space(lc)
plot_morse_reachability(lc, ap, "reachability.pdf",
                        title="Triangle ABC with pendant edge CD")

If both plot_morse_reachability and plot_morse_strata are wanted for the same complex, precompute atomic_distances once and pass it to both, since it is the expensive step and is otherwise recomputed by each call:

A = atomic_distances(lc, ap)
plot_morse_reachability(lc, ap, "reachability.pdf"; A=A)
plot_morse_strata(lc, ap, "adjacency.pdf"; A=A)

SimplicialComplexPlot

Wrapper type for plotting a planar simplicial complex via Plots.jl.

Constructed automatically by plot_simplicial, but instances can also be passed directly to Plots.plot.

CubicalComplexPlot

Wrapper type for plotting a planar cubical complex via Plots.jl.

SimplicialMorsePlot

Wrapper type for plotting a planar simplicial complex with Morse sets via Plots.jl.

CubicalMorsePlot

Wrapper type for plotting a planar cubical complex with Morse sets via Plots.jl.

MVFPlot

Wrapper type for plotting a multivector field on a planar complex via Plots.jl. Each multivector is rendered as a stadium (pill) shaped region.

MVRegionPlot

Wrapper type for plotting a single multivector on a planar complex via Plots.jl. The multivector is rendered as an inflated convex hull per maximal cell.

plot_simplicial(ec::EuclideanComplex; kwargs...) -> Plots.Plot

Plot a planar simplicial complex. Requires using Plots before using ConleyDynamics.

Optional keyword arguments:

• mvf::CellSubsets=[]: Forman vector field to overlay (arrows + critical cells)
• labeldir::Vector{<:Real}=[]: label directions per cell (0=E,1=N,2=W,3=S)
• labeldis::Real=0.05: label offset in data-space units
• pdim::Vector{Bool}=[true,true,true]: which dimensions (0,1,2) to draw

plot_simplicial_morse(ec::EuclideanComplex, morsesets::CellSubsets;
                      kwargs...) -> Plots.Plot

Plot a planar simplicial complex with Morse sets highlighted.

Requires using Plots before using ConleyDynamics.

Optional keyword arguments:

• pdim::Vector{Bool}=[false,true,true]: which dimensions (0,1,2) to draw
• ci::Bool=false: color Morse sets by their Conley index
• addcritical::Bool=false: when true, cells absent from morsesets are shown as implicit singletons

plot_simplicial_mvf(ec::EuclideanComplex, mvf::CellSubsets;
                    kwargs...) -> Plots.Plot

Plot a planar simplicial complex with multivector field regions shaded. Each multivector is rendered as a single colored region, inset from cell boundaries so adjacent multivectors are visually distinct. Requires using Plots before using ConleyDynamics.

Optional keyword arguments:

• pdim::Vector{Bool}=[true,true,true]: which dimensions to show in background
• tubefac::Real=0.05: tube half-width as fraction of average edge length
• mvfcolor::Union{String,Vector{String}}="darkorange": color(s) for multivector regions; a single string applies to all, a vector cycles through multivectors in order
• mvfalpha::Real=0.3: fill opacity (0.0 = transparent, 1.0 = opaque)
• addcritical::Bool=true: when true, cells absent from the MVF are shown as implicit singletons
• ci::Bool=false: color each multivector by its Conley index instead of using mvfcolor

plot_simplicial_mv(ec::EuclideanComplex, mv; kwargs...) -> Plots.Plot

Plot a single multivector on a planar simplicial complex background. The multivector is rendered as an inflated convex hull of barycenters, one hull per maximal cell of the multivector. Requires using Plots before using ConleyDynamics.

mv may be a Vector{Int} (cell indices) or Vector{String} (cell labels).

Optional keyword arguments:

• pdim::Vector{Bool}=[true,true,true]: which background dimensions to draw
• tubefac::Real=0.05: inflation radius as fraction of average edge length
• mvfcolor::String="darkorange": X11 color name for the region
• mvfalpha::Real=0.3: fill opacity (0.0 = transparent, 1.0 = opaque)

plot_cubical(ec::EuclideanComplex; kwargs...) -> Plots.Plot

Plot a planar cubical complex. Requires using Plots before using ConleyDynamics.

Optional keyword arguments:

• mvf::CellSubsets=[]: multivector field to overlay (arrows + critical-cell dots)
• pdim::Vector{Bool}=[true,true,true]: which dimensions (0,1,2) to draw

plot_cubical_morse(ec::EuclideanComplex, morsesets::CellSubsets;
                   kwargs...) -> Plots.Plot

Plot a planar cubical complex with Morse sets highlighted.

Requires using Plots before using ConleyDynamics.

Optional keyword arguments:

• pdim::Vector{Bool}=[false,true,true]: which dimensions (0,1,2) to draw
• ci::Bool=false: color Morse sets by their Conley index
• addcritical::Bool=false: when true, cells absent from morsesets are shown as implicit singletons

plot_cubical_mvf(ec::EuclideanComplex, mvf::CellSubsets;
                 kwargs...) -> Plots.Plot

Plot a planar cubical complex with multivector field regions shaded. Requires using Plots before using ConleyDynamics.

Optional keyword arguments:

• pdim::Vector{Bool}=[true,true,true]: which dimensions to show in background
• tubefac::Real=0.05: tube half-width as fraction of average edge length
• mvfcolor::Union{String,Vector{String}}="darkorange": color(s) for multivector regions
• mvfalpha::Real=0.3: fill opacity (0.0 = transparent, 1.0 = opaque)
• addcritical::Bool=true: when true, cells absent from the MVF are shown as implicit singletons
• ci::Bool=false: color each multivector by its Conley index instead of using mvfcolor

plot_cubical_mv(ec::EuclideanComplex, mv; kwargs...) -> Plots.Plot

Plot a single multivector on a planar cubical complex background. See plot_simplicial_mv for details.

_plot_strata_diagram(strata, edges, fname; title, figw, figh, pv, legendh,
                     edge_style, legend_header, legend_swatches)

Shared Luxor rendering core behind plot_morse_strata and plot_morse_reachability: lays out one node per key of strata (a Dict{Vector{Int},Vector{Int}} as returned by stratum_partition) by level sum(M), and draws an edge for every element of edges (NamedTuples shaped like the output of stratum_adjacency and stratum_reachability, using .M1, .M2, .weight, .ncovered, .ntotal).

The legend is built from two pieces:

• legend_header: plain text lines shown at the top of the legend.
• legend_swatches: one colored line-and-caption block per entry, given as a vector of named tuples with fields color, dash, width, and caption (a Vector{String}).

edge_style(e) maps an edge to its (color, dash, width) – this is the one piece of classification logic that differs between callers. legendh is the fixed height reserved for the legend block; callers size it to their own header/swatch content.

Returns (pos, figwI, fighI) for the caller to fold into its own return value alongside whatever edge/strata data it wants to expose.