PlotStyleConfig

Matplotlib plot rendering options for GRADIEND visualizations.

GRADIEND always appends \usepackage{amsmath} and \usepackage{amssymb} when text.usetex is enabled (required for \rightleftarrows transition arrows). Set only your extra packages in latex_preamble_extra.

font_family class-attribute instance-attribute

font_family = None

font_path class-attribute instance-attribute

font_path = None

latex_preamble_extra class-attribute instance-attribute

latex_preamble_extra = ''

transition_arrows class-attribute instance-attribute

transition_arrows = 'auto'

use_latex class-attribute instance-attribute

use_latex = 'auto'

from_env classmethod

from_env()

Build config from GRADIEND_PLOT_* environment variables.

Source code in gradiend/visualizer/plot_style_config.py

@classmethod
def from_env(cls) -> "PlotStyleConfig":
    """Build config from ``GRADIEND_PLOT_*`` environment variables."""
    return cls(
        use_latex=_parse_use_latex_env(),
        latex_preamble_extra=os.environ.get(ENV_LATEX_PREAMBLE_EXTRA, "") or "",
        font_path=os.environ.get(ENV_FONT_PATH) or None,
        font_family=os.environ.get(ENV_FONT_FAMILY) or None,
        transition_arrows=_parse_transition_arrows_env(),
    )

Result of :func:configure_plot_style.

configured instance-attribute

configured

latex_usable instance-attribute

latex_usable

text_usetex instance-attribute

text_usetex

transition_arrows instance-attribute

transition_arrows

Apply GRADIEND matplotlib defaults (idempotent unless force).

Parameters:

Name	Type	Description	Default
config	Optional[PlotStyleConfig]	Style options. Defaults to :meth:PlotStyleConfig.from_env on first call.	None
force	bool	Re-apply usetex, font, and preamble even when already configured.	False

Returns:

Type	Description
PlotStyleStatus	Summary of the active matplotlib text settings.

Source code in gradiend/visualizer/plot_style.py

def configure_plot_style(
    config: Optional[PlotStyleConfig] = None,
    *,
    force: bool = False,
) -> PlotStyleStatus:
    """Apply GRADIEND matplotlib defaults (idempotent unless *force*).

    Args:
        config: Style options. Defaults to :meth:`PlotStyleConfig.from_env` on first call.
        force: Re-apply usetex, font, and preamble even when already configured.

    Returns:
        Summary of the active matplotlib text settings.
    """
    global _CONFIGURED
    import matplotlib as mpl

    style = config or get_active_plot_style()
    set_active_plot_style(style)

    if not _CONFIGURED or force:
        mpl.rcParams["text.usetex"] = bool(_resolve_use_latex(style))

        font_family = style.font_family
        font_path = style.font_path
        if font_family and str(font_family).strip():
            _apply_font_family(str(font_family).strip())
        elif font_path and str(font_path).strip():
            _apply_custom_font(str(font_path).strip())
        elif mpl.rcParams.get("text.usetex"):
            _prefer_tex_safe_serif_font()

        _CONFIGURED = True

    if mpl.rcParams.get("text.usetex"):
        _ensure_latex_symbol_preamble()
        _apply_latex_preamble_extra(style.latex_preamble_extra)

    return PlotStyleStatus(
        configured=_CONFIGURED,
        text_usetex=bool(mpl.rcParams.get("text.usetex")),
        latex_usable=_latex_usable(),
        transition_arrows=style.transition_arrows,
    )

Replace transition delimiters with matplotlib-appropriate arrows.

When use_latex is omitted, follows :func:resolve_transition_arrow_mode. Idempotent for labels that already contain $...$ math segments.

Source code in gradiend/visualizer/labels.py

def format_transition_label(label: Any, *, use_latex: Optional[bool] = None) -> str:
    """Replace transition delimiters with matplotlib-appropriate arrows.

    When ``use_latex`` is omitted, follows :func:`resolve_transition_arrow_mode`.
    Idempotent for labels that already contain ``$...$`` math segments.
    """
    from gradiend.visualizer.plot_style_config import resolve_transition_arrow_mode

    text = str(label)
    if label_contains_matplotlib_latex(text):
        return text
    mode = resolve_transition_arrow_mode(use_latex=use_latex)
    if mode == "latex":
        if _TRANSITION_BIDI_RE.search(text):
            return _TRANSITION_BIDI_RE.sub(
                lambda _match: transition_bidi_arrow(use_latex=True),
                text,
            )
        if _TRANSITION_DIRECTED_RE.search(text):
            return _TRANSITION_DIRECTED_RE.sub(
                lambda _match: transition_directed_arrow(use_latex=True),
                text,
            )
        return text
    if mode == "ascii":
        if _TRANSITION_BIDI_RE.search(text):
            return _TRANSITION_BIDI_RE.sub(" <-> ", text)
        return _TRANSITION_DIRECTED_RE.sub(" -> ", text)
    if _TRANSITION_BIDI_RE.search(text):
        return _TRANSITION_BIDI_RE.sub(" ↔ ", text)
    return _TRANSITION_DIRECTED_RE.sub(" → ", text)

Bidirectional transition arrow for matplotlib labels (GRADIEND pair notation).

Source code in gradiend/visualizer/labels.py

def transition_bidi_arrow(*, use_latex: Optional[bool] = None) -> str:
    """Bidirectional transition arrow for matplotlib labels (GRADIEND pair notation)."""
    from gradiend.visualizer.plot_style_config import resolve_transition_arrow_mode

    mode = resolve_transition_arrow_mode(use_latex=use_latex)
    if mode == "latex":
        return "$\\rightleftarrows$"
    if mode == "ascii":
        return " <-> "
    return " ↔ "

Directed transition arrow for matplotlib labels (source to target).

Source code in gradiend/visualizer/labels.py

def transition_directed_arrow(*, use_latex: Optional[bool] = None) -> str:
    """Directed transition arrow for matplotlib labels (source to target)."""
    from gradiend.visualizer.plot_style_config import resolve_transition_arrow_mode

    mode = resolve_transition_arrow_mode(use_latex=use_latex)
    if mode == "latex":
        return "$\\rightarrow$"
    if mode == "ascii":
        return " -> "
    return " → "