sofic 0.1.0__py3-none-any.whl

sofic/viz/_rational.py

@@ -0,0 +1,20 @@
+"""Shared rational-number helper for viz label formatting."""
+
+from __future__ import annotations
+
+from fractions import Fraction
+
+_TWO_DIGIT_RATIONAL_ATOL = 1e-9
+_MAX_TWO_DIGIT_RATIONAL = 99
+
+
+def two_digit_rational(value: float, *, atol: float = _TWO_DIGIT_RATIONAL_ATOL) -> Fraction | None:
+    """Return a reduced rational with 1 <= p, q <= 99 when ``value`` matches exactly."""
+    if value <= 0.0 or value >= 1.0:
+        return None
+    frac = Fraction(value).limit_denominator(_MAX_TWO_DIGIT_RATIONAL)
+    if abs(float(frac) - value) >= atol:
+        return None
+    if not (1 <= frac.numerator <= _MAX_TWO_DIGIT_RATIONAL and 1 <= frac.denominator <= _MAX_TWO_DIGIT_RATIONAL):
+        return None
+    return frac

sofic/viz/_tikz_compile.py

@@ -0,0 +1,177 @@
+"""Compile Vaucanson TikZ fragments to PDF/PNG/SVG via ``pdflatex``."""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+
+_VAUCANSON_ASSET = Path(__file__).resolve().parent / "assets" / "vaucanson.tikz"
+
+# GUI-launched notebooks often omit MacTeX / Homebrew from PATH.
+_TOOL_SEARCH_DIRS = (
+    Path("/Library/TeX/texbin"),
+    Path("/usr/local/texlive/2026/bin/universal-darwin"),
+    Path("/usr/local/texlive/2025/bin/universal-darwin"),
+    Path("/usr/local/texlive/2024/bin/universal-darwin"),
+    Path("/opt/homebrew/bin"),
+    Path("/usr/local/bin"),
+)
+
+
+class TikzCompileError(RuntimeError):
+    """Raised when LaTeX compilation or image conversion fails."""
+
+
+def find_executable(name: str) -> str | None:
+    """Locate a CLI tool on PATH or in common TeX/Homebrew install dirs."""
+    found = shutil.which(name)
+    if found is not None:
+        return found
+    for directory in _TOOL_SEARCH_DIRS:
+        candidate = directory / name
+        if candidate.is_file() and os.access(candidate, os.X_OK):
+            return str(candidate)
+    return None
+
+
+def _require_pdflatex() -> str:
+    path = find_executable("pdflatex")
+    if path is None:
+        raise TikzCompileError(
+            "TikZ image export requires pdflatex (e.g. MacTeX or TeX Live). "
+            "Install TeX and ensure pdflatex is on PATH, typically "
+            "/Library/TeX/texbin on macOS."
+        )
+    return path
+
+
+def compilation_document(body: str) -> str:
+    """Wrap a ``tikzpicture`` fragment in a standalone LaTeX document."""
+    return (
+        r"\documentclass[tikz,border=2pt]{standalone}"
+        "\n"
+        r"\usepackage{amsmath}"
+        "\n"
+        r"\usepackage{xcolor}"
+        "\n"
+        r"\pagecolor{white}"
+        "\n"
+        r"\definecolor{honeydew}{RGB}{240,255,240}"
+        "\n"
+        r"\definecolor{mistyrose}{RGB}{255,228,225}"
+        "\n"
+        r"\usepackage{nicefrac}"
+        "\n"
+        r"\providecommand{\half}{\nicefrac{1}{2}}"
+        "\n"
+        r"\usetikzlibrary{automata,positioning,arrows.meta}"
+        "\n"
+        r"\input{vaucanson.tikz}"
+        "\n"
+        r"\begin{document}"
+        "\n"
+        f"{body}\n"
+        r"\end{document}"
+        "\n"
+    )
+
+
+def compile_tikz_fragment(fragment: str, *, format: str = "png") -> bytes:
+    """Compile a ``tikzpicture`` fragment and return raster/vector bytes."""
+    normalized = format.lower().lstrip(".")
+    if normalized not in {"pdf", "png", "svg"}:
+        raise ValueError(f"unsupported compile format {format!r}; expected pdf, png, or svg")
+
+    pdflatex = _require_pdflatex()
+    with tempfile.TemporaryDirectory(prefix="sofic-tikz-") as tmp:
+        workdir = Path(tmp)
+        shutil.copy2(_VAUCANSON_ASSET, workdir / "vaucanson.tikz")
+        tex_path = workdir / "sofic_tikz.tex"
+        tex_path.write_text(compilation_document(fragment), encoding="utf-8")
+
+        result = subprocess.run(
+            [pdflatex, "-halt-on-error", "-interaction=nonstopmode", tex_path.name],
+            cwd=workdir,
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        pdf_path = workdir / "sofic_tikz.pdf"
+        if result.returncode != 0 or not pdf_path.is_file():
+            log_tail = (workdir / "sofic_tikz.log").read_text(encoding="utf-8", errors="replace")
+            raise TikzCompileError("pdflatex failed to compile TikZ figure.\n" + log_tail[-4000:])
+
+        if normalized == "pdf":
+            return pdf_path.read_bytes()
+        if normalized == "png":
+            return _pdf_to_png(pdf_path, workdir / "sofic_tikz.png")
+        return _pdf_to_svg(pdf_path, workdir / "sofic_tikz.svg")
+
+
+def _pdf_to_png(pdf_path: Path, png_path: Path) -> bytes:
+    pdftocairo = find_executable("pdftocairo")
+    if pdftocairo is not None:
+        subprocess.run(
+            [pdftocairo, "-png", "-singlefile", str(pdf_path), str(png_path.with_suffix(""))],
+            check=True,
+            capture_output=True,
+        )
+        if png_path.is_file():
+            return png_path.read_bytes()
+
+    gs = find_executable("gs")
+    if gs is not None:
+        subprocess.run(
+            [
+                gs,
+                "-dNOPAUSE",
+                "-dBATCH",
+                # Opaque RGB (not pngalpha) so the page background is white.
+                "-sDEVICE=png16m",
+                "-dGraphicsAlphaBits=4",
+                "-dTextAlphaBits=4",
+                "-r200",
+                "-dFirstPage=1",
+                "-dLastPage=1",
+                f"-sOutputFile={png_path}",
+                str(pdf_path),
+            ],
+            check=True,
+            capture_output=True,
+        )
+        if png_path.is_file():
+            return png_path.read_bytes()
+
+    if os.uname().sysname == "Darwin":
+        sips = find_executable("sips")
+        if sips is not None:
+            subprocess.run([sips, "-s", "format", "png", str(pdf_path), "--out", str(png_path)], check=True)
+            if png_path.is_file():
+                return png_path.read_bytes()
+
+    raise TikzCompileError(
+        "compiled PDF but could not convert to PNG; install poppler (pdftocairo) or ghostscript (gs)"
+    )
+
+
+def _pdf_to_svg(pdf_path: Path, svg_path: Path) -> bytes:
+    pdftocairo = find_executable("pdftocairo")
+    if pdftocairo is not None:
+        subprocess.run(
+            [pdftocairo, "-svg", str(pdf_path), str(svg_path)],
+            check=True,
+            capture_output=True,
+        )
+        if svg_path.is_file():
+            return svg_path.read_bytes()
+
+    pdf2svg = find_executable("pdf2svg")
+    if pdf2svg is not None:
+        subprocess.run([pdf2svg, str(pdf_path), str(svg_path)], check=True, capture_output=True)
+        if svg_path.is_file():
+            return svg_path.read_bytes()
+
+    raise TikzCompileError("compiled PDF but could not convert to SVG; install poppler (pdftocairo) or pdf2svg")

sofic/viz/_tikz_format.py

@@ -0,0 +1,122 @@
+"""LaTeX / TikZ label formatting for Vaucanson-style machine figures."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any
+
+from sofic.viz import _labels
+from sofic.viz._rational import _TWO_DIGIT_RATIONAL_ATOL, two_digit_rational
+
+_LATEX_SPECIAL = {
+    "\\": r"\textbackslash{}",
+    "{": r"\{",
+    "}": r"\}",
+    "#": r"\#",
+    "$": r"\$",
+    "%": r"\%",
+    "&": r"\&",
+    "_": r"\_",
+    "^": r"\^{}",
+    "~": r"\textasciitilde{}",
+}
+
+
+def latex_escape(text: str) -> str:
+    """Escape plain text for use outside math mode in TikZ node labels."""
+    escaped = []
+    for char in text:
+        escaped.append(_LATEX_SPECIAL.get(char, char))
+    return "".join(escaped)
+
+
+def _latex_arg(text: str) -> str:
+    """Escape content for a LaTeX macro argument (no math mode)."""
+    if text == "":
+        return "{}"
+    if any(char in text for char in "{}\\#%&_^~$"):
+        return f"{{{latex_escape(text)}}}"
+    return text
+
+
+def format_state_latex(state: Any) -> str:
+    return _labels.format_state(state, escape=latex_escape, epsilon=r"\varepsilon")
+
+
+def format_state_tikz_node(state: Any) -> str:
+    """TikZ-safe state label (commas in joint states must not parse as options)."""
+    label = format_state_latex(state)
+    return label.replace(",", "{,}")
+
+
+def format_belief_tikz_node(belief: Sequence[Any]) -> str:
+    """LaTeX-safe belief simplex label for TikZ node text (μ implied)."""
+    parts = [format_prob_latex(value) for value in belief]
+    return rf"$\scriptstyle({', '.join(parts)})$"
+
+
+def format_symbol_latex(symbol: Any) -> str:
+    return _labels.format_symbol(symbol, escape=_latex_arg, epsilon=r"\varepsilon")
+
+
+def format_prob_latex(value: Any, *, precision: int = 3) -> str:
+    """Format a probability for Vaucanson edge labels (float or sympy Expr)."""
+    try:
+        from sofic.generators.prob import is_symbolic, simplify_prob
+    except ImportError:  # pragma: no cover
+        is_symbolic = lambda _v: False  # noqa: E731
+        simplify_prob = lambda v: v  # noqa: E731
+
+    if is_symbolic(value):
+        simplified = simplify_prob(value)
+        try:
+            import sympy as sp
+
+            return latex_escape(sp.latex(simplified))
+        except Exception:
+            return latex_escape(str(simplified))
+
+    numeric = float(value)
+    if numeric <= 0.0:
+        return "0"
+    if numeric >= 1.0:
+        return "1"
+    if abs(numeric - 0.5) < _TWO_DIGIT_RATIONAL_ATOL:
+        return r"\half"
+    frac = two_digit_rational(numeric)
+    if frac is not None:
+        if frac.numerator == frac.denominator:
+            return "1"
+        return rf"\nicefrac{{{frac.numerator}}}{{{frac.denominator}}}"
+    return latex_escape(f"{numeric:.{precision}g}")
+
+
+def format_symbol_macro(symbol: Any) -> str:
+    return rf"\Symbol{{{format_symbol_latex(symbol)}}}"
+
+
+def format_edge_latex(symbol: Any, prob: Any) -> str:
+    """Return ``$\\Edge{sym}{prob}$`` math content."""
+    return rf"$\Edge{{{format_symbol_latex(symbol)}}}{{{format_prob_latex(prob)}}}$"
+
+
+def format_tedge_latex(forward: Any, reverse: Any, prob: Any) -> str:
+    """Return ``$\\TEdge{f}{r}{prob}$`` math content."""
+    return (
+        rf"$\TEdge{{{format_symbol_latex(forward)}}}"
+        rf"{{{format_symbol_latex(reverse)}}}"
+        rf"{{{format_prob_latex(prob)}}}$"
+    )
+
+
+def format_symbol_only_latex(symbol: Any) -> str:
+    return rf"$\Symbol{{{format_symbol_latex(symbol)}}}$"
+
+
+def format_transducer_edge_latex(input_symbol: Any, output_symbol: Any | None = None) -> str:
+    if output_symbol is None:
+        return format_symbol_only_latex(input_symbol)
+    return (
+        rf"$\Symbol{{{format_symbol_latex(input_symbol)}}}"
+        rf"\mid\Symbol{{{format_symbol_latex(output_symbol)}}}$"
+    )

sofic/viz/_tikz_layout.py

@@ -0,0 +1,218 @@
+"""Layout helpers for TikZ machine figures."""
+
+from __future__ import annotations
+
+import math
+import re
+from collections import defaultdict
+from collections.abc import Hashable, Mapping
+from typing import Any
+
+from sofic.base import StateMachine
+from sofic.viz._names import node_name
+
+_LOOP_STYLES = ("loop above", "loop right", "loop below", "loop left")
+_BEND_STYLES = ("bend left", "bend right")
+_LOOP_STYLE_ANGLES = {
+    "loop above": 90.0,
+    "loop right": 0.0,
+    "loop below": -90.0,
+    "loop left": 180.0,
+}
+_LOOP_CONFLICT_RADIUS = 55.0
+
+
+def layout_circle(
+    model: StateMachine,
+    *,
+    radius: str = "2cm",
+    positions: Mapping[Hashable, tuple[float, float]] | None = None,
+    angles: Mapping[Hashable, float] | None = None,
+) -> dict[Hashable, str]:
+    """Return TikZ ``at (...)`` clauses for each state on a circle."""
+    states = sorted(model.states(), key=repr)
+    if not states:
+        return {}
+
+    radius_value, radius_unit = _split_dim(radius)
+    coords: dict[Hashable, str] = {}
+
+    if positions is not None:
+        for state in states:
+            if state not in positions:
+                raise ValueError(f"missing position override for state {state!r}")
+            x, y = positions[state]
+            coords[state] = f"at ({x}{radius_unit}, {y}{radius_unit})"
+        return coords
+
+    count = len(states)
+    for index, state in enumerate(states):
+        angle = angles[state] if angles is not None and state in angles else 90.0 - index * (360.0 / count)
+        coords[state] = f"at ({angle:.4g}:{radius_value}{radius_unit})"
+    return coords
+
+
+def _split_dim(value: str) -> tuple[str, str]:
+    match = re.fullmatch(r"([0-9.]+)([a-zA-Z]+)", value.strip())
+    if match is None:
+        raise ValueError(f"expected dimension like '2cm', got {value!r}")
+    return match.group(1), match.group(2)
+
+
+def layout_graphviz(
+    model: StateMachine,
+    *,
+    style: str = "auto",
+    rankdir: str | None = None,
+) -> dict[Hashable, str]:
+    """Return TikZ ``at (...)`` clauses using Graphviz node positions."""
+    from sofic.viz.graphviz import model_to_graphviz
+
+    dot = model_to_graphviz(model, style=style, rankdir=rankdir)
+    plain = dot.pipe(format="plain").decode("utf-8")
+    positions = _parse_plain_positions(plain)
+    coords: dict[Hashable, str] = {}
+    for state in model.states():
+        node = node_name(state)
+        if node not in positions:
+            raise RuntimeError(f"graphviz layout missing position for node {node!r}")
+        x_cm, y_cm = positions[node]
+        coords[state] = f"at ({x_cm:.4f}cm, {y_cm:.4f}cm)"
+    return coords
+
+
+def _parse_plain_positions(plain: str) -> dict[str, tuple[float, float]]:
+    """Parse Graphviz plain format node lines into cm coordinates.
+
+    Graphviz ``plain`` node positions are in **inches** (same unit as the graph
+    width/height on the ``graph`` header line), not PostScript points.
+    """
+    inch_to_cm = 2.54
+    positions: dict[str, tuple[float, float]] = {}
+    for line in plain.splitlines():
+        if not line.startswith("node "):
+            continue
+        parts = line.split()
+        if len(parts) < 4:
+            continue
+        name = parts[1].strip('"')
+        x_cm = float(parts[2]) * inch_to_cm
+        y_cm = float(parts[3]) * inch_to_cm
+        positions[name] = (x_cm, y_cm)
+    return positions
+
+
+def placement_to_xy(placement: str) -> tuple[float, float]:
+    """Convert a TikZ ``at (...)`` clause to ``(x, y)`` in cm (0° = east)."""
+    inner = placement.removeprefix("at (").removesuffix(")")
+    polar = re.fullmatch(r"([-\d.]+):([-\d.]+)(cm)", inner)
+    if polar is not None:
+        angle_deg = float(polar.group(1))
+        radius = float(polar.group(2))
+        rad = math.radians(angle_deg)
+        return radius * math.cos(rad), radius * math.sin(rad)
+    cart = re.fullmatch(r"([-\d.]+)cm, ([-\d.]+)cm", inner)
+    if cart is not None:
+        return float(cart.group(1)), float(cart.group(2))
+    raise ValueError(f"unsupported placement {placement!r}")
+
+
+def _angle_diff_deg(a: float, b: float) -> float:
+    return abs((a - b + 180.0) % 360.0 - 180.0)
+
+
+def _outgoing_bearings(
+    source: Hashable,
+    positions: Mapping[Hashable, tuple[float, float]],
+    grouped: Mapping[tuple[Hashable, Hashable], list[Any]],
+) -> list[float]:
+    """Bearings at ``source`` that outgoing edges already occupy."""
+    bearings: list[float] = []
+    sx, sy = positions[source]
+    for (src, target), _group in grouped.items():
+        if src != source or target == source:
+            continue
+        if target not in positions:
+            continue
+        tx, ty = positions[target]
+        angle = math.degrees(math.atan2(ty - sy, tx - sx))
+        bearings.append(angle)
+        if (target, source) in grouped:
+            bearings.append(angle + 90.0)
+    return bearings
+
+
+def _pick_loop_style(
+    bearings: list[float],
+    used: list[str],
+    *,
+    preferred_order: tuple[str, ...] = _LOOP_STYLES,
+) -> str:
+    def score(style: str) -> float:
+        anchor = _LOOP_STYLE_ANGLES[style]
+        penalty = 1000.0 if style in used else 0.0
+        for bearing in bearings:
+            diff = _angle_diff_deg(anchor, bearing)
+            if diff < _LOOP_CONFLICT_RADIUS:
+                penalty += (_LOOP_CONFLICT_RADIUS - diff) ** 2
+        return penalty
+
+    return min(preferred_order, key=score)
+
+
+def plan_loop_styles(
+    positions: Mapping[Hashable, tuple[float, float]],
+    grouped: Mapping[tuple[Hashable, Hashable], list[Any]],
+) -> dict[tuple[Hashable, Hashable, int], str]:
+    """Assign self-loop styles that avoid outgoing-edge corridors."""
+    styles: dict[tuple[Hashable, Hashable, int], str] = {}
+    loops_by_state: dict[Hashable, list[tuple[Hashable, Hashable, int]]] = defaultdict(list)
+    for key, group in grouped.items():
+        source, target = key
+        if source != target:
+            continue
+        for index in range(len(group)):
+            loops_by_state[source].append((source, target, index))
+
+    for source, loops in loops_by_state.items():
+        bearings = _outgoing_bearings(source, positions, grouped)
+        used: list[str] = []
+        for key in loops:
+            style = _pick_loop_style(bearings, used)
+            styles[key] = style
+            used.append(style)
+    return styles
+
+
+def edge_style(
+    source: Hashable,
+    target: Hashable,
+    *,
+    parallel_index: int,
+    total_parallel: int,
+    has_reverse: bool = False,
+    loop_style: str | None = None,
+) -> str:
+    """Choose bend/loop options for one transition."""
+    if source == target:
+        return loop_style or _LOOP_STYLES[parallel_index % len(_LOOP_STYLES)]
+    if has_reverse:
+        return _reciprocal_bend(parallel_index, total_parallel)
+    if total_parallel == 1:
+        return ""
+    if total_parallel == 2:
+        return _BEND_STYLES[parallel_index % 2]
+    base = 30 + 25 * parallel_index
+    return f"bend left, out={base}, in={180 - base}"
+
+
+def _reciprocal_bend(parallel_index: int, total_parallel: int) -> str:
+    """Bend both directions of a reciprocal pair the same way (cpfci convention)."""
+    if total_parallel == 1:
+        return "bend left"
+    if total_parallel == 2 and parallel_index == 0:
+        return "bend left, out=45, in=135"
+    if total_parallel == 2:
+        return "bend left"
+    base = 30 + 25 * parallel_index
+    return f"bend left, out={base}, in={180 - base}"

sofic/viz/assets/vaucanson.tikz

@@ -0,0 +1,71 @@
+\tikzstyle{vaucanson}=[
+  %node distance=1.25cm,
+  node distance=3cm,
+  bend angle=15,
+  auto,
+  % For some reason, the loop direction cannot be overwritten if we set the
+  % style for "every loop" to be "->".  Curiously, this doesn't seem to be
+  % an issue for "every edge".
+  every loop/.style={},
+  every edge/.style={->,draw=black,line width=1.2,>=latex,shorten <=1pt, shorten >=1pt},
+  every state/.style={draw=black,line width=2,font=\large},
+  loop right/.style={right,out=22,in=-22,loop},
+  loop above/.style={above,out=112,in=68,loop},
+  loop left/.style={left,out=202,in=158,loop},
+  loop below/.style={below,out=292,in=248,loop},
+  loop above right/.style={right,out=67,in=23,loop},
+  loop above left/.style={left,out=157,in=113,loop},
+  loop below left/.style={left,out=247,in=203,loop},
+  loop below right/.style={right,out=337,in=293,loop},
+  binode/.style={minimum size=1cm,inner sep=0pt},
+]
+
+\tikzset{
+  mystate/.style={circle,draw,fill=black}
+}
+
+%%% Command for bicausal nodes. This only supports relative positioning.
+%%% Use as: \binode[state][red,blue] (AC) [left=of someNode] {$\A:\:C$};
+\makeatletter
+\newcommand{\binode}[1][state]{%
+  \@ifnextchar[{\binode@i[{#1}]}{\binode@i[{#1}][{yellow},{gray!70}]}%
+}
+\def\binode@i[#1][#2,#3]{%
+  \@ifnextchar({\binode@ii[{#1}][{#2},{#3}]}{\binode@ii[{#1}][{#2},{#3}]({})}%
+}
+\def\binode@ii[#1][#2,#3](#4){%
+  \@ifnextchar[{\binode@iii[{#1}][{#2},{#3}]({#4})}{\binode@iii[{#1}][{#2},{#3}]({#4})[{}]}%
+}
+\def\binode@iii[#1][#2,#3](#4)[#5]#6{%
+
+  \node[#1,binode] (#4) [#5] {#6};
+  \node[yshift=-10pt] (#4SS) at (#4.270) {};
+  \node[xshift=-10pt] (#4WW) at (#4.180) {};
+  \node[xshift=-10pt] (#4NN) at (#4.180) {};
+  \node[xshift=-10pt,yshift=10pt] (#4NW) at (#4.135) {};
+  % forward shading
+  \begin{scope}
+    \path[clip] (#4.255) -- +(-.8cm,0cm) -- +(-.8cm,1cm) -- (#4.75) -- cycle;
+    \node[#1,fill=#2,binode] (#4f) [#5] {#6};
+  \end{scope}
+  % reverse shading
+  \begin{scope}
+    \path[clip] (#4.75) -- +(.8cm,0cm) -- +(.8cm,-1cm) -- (#4.255) -- cycle;
+%    ++(0cm,-.2cm) -- ++(.8cm,0cm)  -- ++(0cm,1cm) -- (#4.75) -- cycle;
+    \node[#1,fill=#3,binode] (#4r) [#5] {#6};
+  \end{scope}
+  \node {} % semicolon purposefully omitted. this is a dummy call
+}
+\makeatother
+
+\providecommand{\Symbol}[1]{\textcolor{blue}{#1}}
+\providecommand{\Edge}[2]{\Symbol{#1}\!:\!#2}
+\providecommand{\TEdge}[3]{\Symbol{#1}|\Symbol{#2}\!:\!#3}
+
+\definecolor{honeydew}{RGB}{240,255,240}
+\definecolor{mistyrose}{RGB}{255,228,225}
+\definecolor{FCSA}{RGB}{141,211,199}
+\definecolor{FCSB}{RGB}{255,255,179}
+\definecolor{RCSC}{RGB}{185,138,196}
+\definecolor{RCSD}{RGB}{231,143,111}
+\definecolor{RCSE}{RGB}{128,177,211}