zhc_ir 0.4.0

Graph-based intermediate representation framework with dialect support
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135

use crate::{AnnIR, Annotation, Dialect, IR, OpMap, visualization::svg::Svg};
use std::path::Path;

mod composition;
mod hierarchy;
mod html;
mod layer_map;
mod layoutlang;
mod placement;
mod svg;
mod visual_annotation;

pub use composition::*;
pub use hierarchy::*;
pub use layer_map::*;
pub use layoutlang::*;
pub use visual_annotation::*;

#[cfg(test)]
mod test;

fn draw_ir<D: Dialect>(ir: &IR<D>, hierarchy_ann: OpMap<Hierarchy>) -> Svg {
    let ann_ir = AnnIR::new(ir, hierarchy_ann, ir.filled_valmap(()));
    let layout_ir = generate_layout_ir(&ann_ir);

    let placed_ir = placement::place(&layout_ir);
    let scene = composition::compose(&placed_ir);
    svg::draw(&scene)
}

fn draw_ann_ir<D: Dialect, OpAnn: Annotation + VisualAnnotation, ValAnn: Annotation>(
    ir: &AnnIR<D, OpAnn, ValAnn>,
    hierarchy_ann: OpMap<Hierarchy>,
) -> Svg {
    let ann_ir = AnnIR::new(ir, hierarchy_ann, ir.filled_valmap(()));
    let mut layout_ir = generate_layout_ir(&ann_ir);
    annotate_layout(&mut layout_ir, ir.op_annotations());
    let placed_ir = placement::place(&layout_ir);
    let scene = composition::compose(&placed_ir);
    svg::draw(&scene)
}

/// Renders an IR graph as a static SVG file.
///
/// The visualization displays operations as nodes and data dependencies as edges.
/// Operations sharing the same hierarchy annotation are grouped together visually,
/// making the logical structure of the program easier to follow.
///
/// For an interactive version with zoom and pan, use [`draw_ir_to_html`]. To include
/// custom per-operation visual annotations (e.g., computed values), use
/// [`draw_ann_ir_to_svg`] instead.
///
/// # Panics
///
/// Panics if the file cannot be written to the given path.
pub fn draw_ir_to_svg<D: Dialect>(
    ir: &IR<D>,
    hierarchy_ann: OpMap<Hierarchy>,
    path: impl AsRef<Path>,
) {
    let svg_output = draw_ir(ir, hierarchy_ann);
    let svg_content = format!("{}", svg_output);
    std::fs::write(path, svg_content).expect("Failed to write SVG file");
}

/// Renders an annotated IR graph as a static SVG file.
///
/// Like [`draw_ir_to_svg`], but accepts an [`AnnIR`] whose operation annotations implement
/// [`VisualAnnotation`]. Each operation's annotation can provide a custom widget (displayed
/// inside the node) and a style modifier (affecting the node's appearance). This is useful
/// for visualizing interpreter results, optimization metadata, or any per-operation data.
///
/// For an interactive version with zoom and pan, use [`draw_ann_ir_to_html`].
///
/// # Panics
///
/// Panics if the file cannot be written to the given path.
pub fn draw_ann_ir_to_svg<D: Dialect, OpAnn: Annotation + VisualAnnotation, ValAnn: Annotation>(
    ir: &AnnIR<D, OpAnn, ValAnn>,
    hierarchy_ann: OpMap<Hierarchy>,
    path: impl AsRef<Path>,
) {
    let svg_output = draw_ann_ir(ir, hierarchy_ann);
    let svg_content = format!("{}", svg_output);
    std::fs::write(path, svg_content).expect("Failed to write SVG file");
}

/// Renders an IR graph as an interactive HTML file.
///
/// The visualization displays operations as nodes and data dependencies as edges.
/// Operations sharing the same hierarchy annotation are grouped together visually,
/// making the logical structure of the program easier to follow. The resulting HTML
/// file supports interactive features such as zooming and panning.
///
/// For a static SVG without interactivity, use [`draw_ir_to_svg`]. To include custom
/// per-operation visual annotations (e.g., computed values), use [`draw_ann_ir_to_html`]
/// instead.
///
/// # Panics
///
/// Panics if the file cannot be written to the given path.
pub fn draw_ir_to_html<D: Dialect>(
    ir: &IR<D>,
    hierarchy_ann: OpMap<Hierarchy>,
    path: impl AsRef<Path>,
) {
    let svg_output = draw_ir(ir, hierarchy_ann);
    let html_output = html::wrap_svg(svg_output);
    let html_content = format!("{}", html_output);
    std::fs::write(path, html_content).expect("Failed to write HTML file");
}

/// Renders an annotated IR graph as an interactive HTML file.
///
/// Like [`draw_ir_to_html`], but accepts an [`AnnIR`] whose operation annotations implement
/// [`VisualAnnotation`]. Each operation's annotation can provide a custom widget (displayed
/// inside the node) and a style modifier (affecting the node's appearance). This is useful
/// for visualizing interpreter results, optimization metadata, or any per-operation data.
/// The resulting HTML file supports interactive features such as zooming and panning.
///
/// For a static SVG without interactivity, use [`draw_ann_ir_to_svg`].
///
/// # Panics
///
/// Panics if the file cannot be written to the given path.
pub fn draw_ann_ir_to_html<D: Dialect, OpAnn: Annotation + VisualAnnotation, ValAnn: Annotation>(
    ir: &AnnIR<D, OpAnn, ValAnn>,
    hierarchy_ann: OpMap<Hierarchy>,
    path: impl AsRef<Path>,
) {
    let svg_output = draw_ann_ir(ir, hierarchy_ann);
    let html_output = html::wrap_svg(svg_output);
    let html_content = format!("{}", html_output);
    std::fs::write(path, html_content).expect("Failed to write HTML file");
}