Skip to content

Visualisation

Plotly-based plot helpers, theme registry, and time-series recorders. Requires the [viz] extra.

pip install "simweave[viz]"

Plot helpers

Every helper returns a plotly.graph_objects.Figure. Each accepts an optional theme= and title=.

Helper Input
plot_state_trajectories SimulationResult
plot_phase_portrait SimulationResult with ≥2 state channels
plot_queue_length QueueLengthRecorder
plot_service_utilisation ServiceUtilisationRecorder
plot_warehouse_stock WarehouseStockRecorder
plot_mc_fan MCResult, ndarray, or (times, samples)
plot_agent_path Agent (with optional graph=)

Recorders

Recorders are Entity subclasses. Snapshot at registration and at the end of every tick. Register them after the entity they observe:

qrec = sw.QueueLengthRecorder(svc)
env.register(svc)
env.register(qrec)            # ticks after svc

Themes

sw.available_themes()         # ['light', 'dark', 'presentation', 'minimal']
sw.set_default_theme("dark")

Brand themes via register_theme:

sw.register_theme(
    "edgeweave",
    template="plotly_white",
    palette=["#1c5d99", "#f49d37", "#0b132b", "#5fad56"],
    layout_overrides={"font": {"family": "Inter, system-ui"}},
)
sw.set_default_theme("edgeweave")

EdgeWeave consumption

Every figure round-trips through JSON cleanly:

import json
fig = sw.plot_state_trajectories(res)
parsed = json.loads(fig.to_json())
assert "data" in parsed and "layout" in parsed

Live output of every helper, regenerated on each docs build:

End-to-end demo

demos/14_viz_tour.py exercises every helper, writes one HTML per figure under demos/viz_out/, and produces an index.html.

API

simweave.viz -- plotly-based visualisation helpers.

Every helper returns a plotly.graph_objects.Figure so JS frontends (such as EdgeWeave) can consume the figure via fig.to_json() without losing structure. Themes are applied via a small registry so users can switch between light, dark and custom palettes without rebuilding plots.

Importing this module is cheap; plotly is only required when a plot helper is actually called. Install via the optional extra::

pip install simweave[viz]

Quick start::

from simweave.viz import (
    plot_state_trajectories,
    set_default_theme,
)
from simweave.continuous import simulate, MassSpringDamper

res = simulate(MassSpringDamper(), t_span=(0, 10), dt=0.01)
set_default_theme("dark")
fig = plot_state_trajectories(res)
fig.show()              # or fig.write_html("msd.html"), or fig.to_json()

Theme dataclass 

Theme(name: str, template: str, palette: tuple[str, ...] = tuple(), layout_overrides: dict[str, Any] = dict())

A named plotly styling bundle.

QueueLengthRecorder 

QueueLengthRecorder(queue: 'Queue', name: str | None = None)

Bases: _Recorder

Sample len(queue) each tick.

Attributes:

Name Type Description
times list[float]

Simulation times of each sample.
lengths list[int]

Queue length at each sample (matches times element-wise).
Source code in src/simweave/viz/recorders.py 
82
83
84
85
def __init__(self, queue: "Queue", name: str | None = None) -> None:
    super().__init__(name=name or f"qlen({queue.name})")
    self.queue = queue
    self.lengths: list[int] = []

ServiceUtilisationRecorder 

ServiceUtilisationRecorder(service: 'Service', name: str | None = None)

Bases: _Recorder

Sample a Service's per-channel and aggregate utilisation each tick.

The simweave :class:~simweave.discrete.services.Service keeps a monotonic busy_time per channel. We capture that snapshot and also derive an aggregate running-mean utilisation sum(busy_time) / (capacity * elapsed).

Attributes:

Name Type Description
times list[float]

Simulation times of each sample.
busy_time list[ndarray]

(n_samples, n_channels) cumulative busy time per channel.
utilisation list[float]

Running aggregate utilisation in [0, 1] at each sample.
instantaneous_busy list[ndarray]

(n_samples, n_channels) boolean array; True where the channel was busy at the moment of sampling. Useful for Gantt-style views.
Source code in src/simweave/viz/recorders.py 
113
114
115
116
117
118
119
def __init__(self, service: "Service", name: str | None = None) -> None:
    super().__init__(name=name or f"util({service.name})")
    self.service = service
    self.busy_time: list[np.ndarray] = []
    self.utilisation: list[float] = []
    self.instantaneous_busy: list[np.ndarray] = []
    self._t0: float | None = None

WarehouseStockRecorder 

WarehouseStockRecorder(warehouse: 'Warehouse', name: str | None = None)

Bases: _Recorder

Sample warehouse.inv.stock_level each tick.

Attributes:

Name Type Description
times list[float]

Simulation times of each sample.
stock list[ndarray]

(n_samples, n_skus) stock-level history.
sku_names tuple[str, ...]

Names of the SKUs (snapshot at registration; stable thereafter).
reorder_points ndarray

Reorder points snapshot at registration.
Source code in src/simweave/viz/recorders.py 
154
155
156
157
158
159
160
161
def __init__(self, warehouse: "Warehouse", name: str | None = None) -> None:
    super().__init__(name=name or f"stock({warehouse.name})")
    self.warehouse = warehouse
    self.stock: list[np.ndarray] = []
    self.sku_names: tuple[str, ...] = tuple(warehouse.inv.part_names)
    self.reorder_points: np.ndarray = np.asarray(
        warehouse.inv.reorder_points, dtype=float
    ).copy()

apply_theme 

apply_theme(fig: Any, theme: str | None = None) -> Any

Apply theme to fig in place and return fig.

Called by every plot helper. Safe to call again on a returned figure if the user wants to re-theme without rebuilding the data.

Source code in src/simweave/viz/themes.py 
175
176
177
178
179
180
181
182
183
184
185
186
187
def apply_theme(fig: Any, theme: str | None = None) -> Any:
    """Apply ``theme`` to ``fig`` in place and return ``fig``.

    Called by every plot helper. Safe to call again on a returned figure
    if the user wants to re-theme without rebuilding the data.
    """
    t = get_theme(theme)
    layout: dict[str, Any] = {"template": t.template}
    if t.palette:
        layout["colorway"] = list(t.palette)
    layout.update(t.layout_overrides)
    fig.update_layout(**layout)
    return fig

available_themes 

available_themes() -> tuple[str, ...]

Return the names of all currently-registered themes.

Source code in src/simweave/viz/themes.py 
104
105
106
def available_themes() -> tuple[str, ...]:
    """Return the names of all currently-registered themes."""
    return tuple(_REGISTRY.keys())

get_default_theme 

get_default_theme() -> str

Return the name of the theme used when no theme= is passed.

Source code in src/simweave/viz/themes.py 
109
110
111
def get_default_theme() -> str:
    """Return the name of the theme used when no ``theme=`` is passed."""
    return _DEFAULT_NAME

get_theme 

get_theme(name: str | None = None) -> Theme

Return the :class:Theme for name (or the current default).

Source code in src/simweave/viz/themes.py 
165
166
167
168
169
170
171
172
def get_theme(name: str | None = None) -> Theme:
    """Return the :class:`Theme` for ``name`` (or the current default)."""
    key = name if name is not None else _DEFAULT_NAME
    if key not in _REGISTRY:
        raise KeyError(
            f"Unknown theme {key!r}. Available: {sorted(_REGISTRY)}."
        )
    return _REGISTRY[key]

register_theme 

register_theme(name: str, template: str, palette: tuple[str, ...] | list[str] | None = None, layout_overrides: dict[str, Any] | None = None, *, overwrite: bool = False) -> None

Register a new theme.

Parameters:

Name Type Description Default
name str

Identifier used by set_default_theme(name) and theme=name.

 required
template str

Name of a plotly built-in template ("plotly_white", "plotly_dark", "simple_white", "ggplot2", etc) or any template you have already added to plotly.io.templates.

 required
palette tuple[str, ...] | list[str] | None

Optional sequence of hex/CSS colour strings used as the colorway for traces.

 None
layout_overrides dict[str, Any] | None

Optional mapping merged into fig.layout after the template is applied. Use this for fonts, paper colours, margins, etc.

 None
overwrite bool

If False (default), raises KeyError when name already exists. Pass overwrite=True to replace.

 False
Source code in src/simweave/viz/themes.py 
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
def register_theme(
    name: str,
    template: str,
    palette: tuple[str, ...] | list[str] | None = None,
    layout_overrides: dict[str, Any] | None = None,
    *,
    overwrite: bool = False,
) -> None:
    """Register a new theme.

    Parameters
    ----------
    name:
        Identifier used by ``set_default_theme(name)`` and ``theme=name``.
    template:
        Name of a plotly built-in template (``"plotly_white"``,
        ``"plotly_dark"``, ``"simple_white"``, ``"ggplot2"``, etc) or any
        template you have already added to ``plotly.io.templates``.
    palette:
        Optional sequence of hex/CSS colour strings used as the
        ``colorway`` for traces.
    layout_overrides:
        Optional mapping merged into ``fig.layout`` after the template is
        applied. Use this for fonts, paper colours, margins, etc.
    overwrite:
        If False (default), raises ``KeyError`` when ``name`` already
        exists. Pass ``overwrite=True`` to replace.
    """
    if not overwrite and name in _REGISTRY:
        raise KeyError(
            f"Theme {name!r} already registered. Pass overwrite=True to replace."
        )
    _REGISTRY[name] = Theme(
        name=name,
        template=template,
        palette=tuple(palette) if palette else (),
        layout_overrides=dict(layout_overrides or {}),
    )

set_default_theme 

set_default_theme(name: str) -> None

Set the theme applied by every plot helper that omits theme=.

Source code in src/simweave/viz/themes.py 
114
115
116
117
118
119
120
121
122
def set_default_theme(name: str) -> None:
    """Set the theme applied by every plot helper that omits ``theme=``."""
    if name not in _REGISTRY:
        raise KeyError(
            f"Unknown theme {name!r}. Available: {sorted(_REGISTRY)}. "
            "Use register_theme(...) to add a new one."
        )
    global _DEFAULT_NAME
    _DEFAULT_NAME = name

plot_agent_path 

plot_agent_path(agent: Any, graph: Any | None = None, *, show_graph: bool = True, theme: str | None = None, title: str | None = None) -> Any

Render an agent's traversal over a 2-D graph.

Parameters:

Name Type Description Default
agent Any

A :class:~simweave.agents.agent.Agent (or any object exposing .history of (t, node) pairs and .name).

 required
graph Any | None

Optional graph to draw underneath the path. Defaults to agent.graph. Pass show_graph=False to skip drawing it.

 None
show_graph bool

If True, draws faint lines for every edge of the graph.

 True
Source code in src/simweave/viz/plots.py 
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
def plot_agent_path(
    agent: Any,
    graph: Any | None = None,
    *,
    show_graph: bool = True,
    theme: str | None = None,
    title: str | None = None,
) -> Any:
    """Render an agent's traversal over a 2-D graph.

    Parameters
    ----------
    agent:
        A :class:`~simweave.agents.agent.Agent` (or any object exposing
        ``.history`` of ``(t, node)`` pairs and ``.name``).
    graph:
        Optional graph to draw underneath the path. Defaults to
        ``agent.graph``. Pass ``show_graph=False`` to skip drawing it.
    show_graph:
        If True, draws faint lines for every edge of the graph.
    """
    go = _plotly.require_go()
    g = graph if graph is not None else getattr(agent, "graph", None)

    history: Iterable[tuple[float, Any]] = getattr(agent, "history", []) or []
    times: list[float] = []
    xs: list[float] = []
    ys: list[float] = []
    nodes: list[Any] = []
    for t, node in history:
        xy = _node_xy(node, g)
        if xy is None:
            continue
        times.append(float(t))
        xs.append(xy[0])
        ys.append(xy[1])
        nodes.append(node)

    fig = go.Figure()

    if show_graph and g is not None:
        edge_x: list[Any] = []
        edge_y: list[Any] = []
        edges_iter = (
            g.edges() if hasattr(g, "edges") and callable(getattr(g, "edges")) else []
        )
        for edge in edges_iter:
            # simweave Graph.edges() yields (u, v, data); networkx also (u, v) or 3-tup.
            u, v = edge[0], edge[1]
            uxy = _node_xy(u, g)
            vxy = _node_xy(v, g)
            if uxy is None or vxy is None:
                continue
            edge_x.extend([uxy[0], vxy[0], None])
            edge_y.extend([uxy[1], vxy[1], None])
        if edge_x:
            fig.add_trace(
                go.Scatter(
                    x=edge_x,
                    y=edge_y,
                    mode="lines",
                    line={"color": "rgba(150,150,150,0.4)", "width": 1},
                    hoverinfo="skip",
                    showlegend=False,
                    name="graph",
                )
            )

    if xs:
        fig.add_trace(
            go.Scatter(
                x=xs,
                y=ys,
                mode="lines+markers",
                marker={"size": 7},
                line={"width": 2},
                name=getattr(agent, "name", "agent"),
                hovertext=[f"t={tt:.2f}\n{n}" for tt, n in zip(times, nodes)],
                hoverinfo="text",
            )
        )
        fig.add_trace(
            go.Scatter(
                x=[xs[0]],
                y=[ys[0]],
                mode="markers",
                marker={"size": 12, "symbol": "circle"},
                name="start",
                showlegend=True,
            )
        )
        fig.add_trace(
            go.Scatter(
                x=[xs[-1]],
                y=[ys[-1]],
                mode="markers",
                marker={"size": 12, "symbol": "x"},
                name="end",
                showlegend=True,
            )
        )

    aname = getattr(agent, "name", "agent")
    fig.update_layout(
        title=title or f"agent path: {aname}",
        xaxis_title="x",
        yaxis_title="y",
        yaxis={"scaleanchor": "x", "scaleratio": 1},
    )
    return apply_theme(fig, theme)

plot_mc_fan 

plot_mc_fan(mc_or_array: Any, times: Sequence[float] | ndarray | None = None, percentiles: Sequence[float] = (5, 25, 50, 75, 95), *, time_axis: 'SimTimeAxis | None' = None, theme: str | None = None, title: str | None = None, show_mean: bool = True) -> Any

Percentile fan chart for a Monte Carlo trajectory ensemble.

Parameters:

Name Type Description Default
mc_or_array Any

MCResult (with 2-D .samples), raw (n_runs, n_time) ndarray, or a (times, samples) tuple.

 required
times Sequence[float] | ndarray | None

Optional time axis. Ignored if mc_or_array is a tuple. Defaults to arange(n_time) if not supplied.

 None
percentiles Sequence[float]

Percentiles to draw. The median (or 50th percentile if present) is rendered as a solid line; the rest form symmetric shaded bands from outside-in.

 (5, 25, 50, 75, 95)
show_mean bool

If True, overlays the per-time mean as a thin dashed line.

 True
Source code in src/simweave/viz/plots.py 
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
def plot_mc_fan(
    mc_or_array: Any,
    times: Sequence[float] | np.ndarray | None = None,
    percentiles: Sequence[float] = (5, 25, 50, 75, 95),
    *,
    time_axis: "SimTimeAxis | None" = None,
    theme: str | None = None,
    title: str | None = None,
    show_mean: bool = True,
) -> Any:
    """Percentile fan chart for a Monte Carlo trajectory ensemble.

    Parameters
    ----------
    mc_or_array:
        ``MCResult`` (with 2-D ``.samples``), raw ``(n_runs, n_time)``
        ndarray, or a ``(times, samples)`` tuple.
    times:
        Optional time axis. Ignored if ``mc_or_array`` is a tuple.
        Defaults to ``arange(n_time)`` if not supplied.
    percentiles:
        Percentiles to draw. The median (or 50th percentile if present)
        is rendered as a solid line; the rest form symmetric shaded bands
        from outside-in.
    show_mean:
        If True, overlays the per-time mean as a thin dashed line.
    """
    go = _plotly.require_go()
    t, samples = _coerce_mc_input(mc_or_array, times)

    pct = sorted(float(p) for p in percentiles)
    if not pct:
        raise ValueError("percentiles must be non-empty.")
    qs = np.percentile(samples, pct, axis=0)  # shape (len(pct), n_time)

    # Pair outside-in for shading: (lo, hi) -> band; if odd count, the middle one
    # becomes the median line.
    bands: list[tuple[int, int]] = []
    i, j = 0, len(pct) - 1
    while i < j:
        bands.append((i, j))
        i += 1
        j -= 1
    median_idx = i if (i == j) else None

    fig = go.Figure()
    n_bands = len(bands)
    for k, (lo, hi) in enumerate(bands):
        # Outer band fades the most; inner band darkest.
        opacity = 0.15 + 0.45 * (k / max(n_bands - 1, 1))
        # Lower trace (invisible line, will be filled to)
        fig.add_trace(
            go.Scatter(
                x=t,
                y=qs[lo],
                mode="lines",
                line={"width": 0},
                showlegend=False,
                hoverinfo="skip",
            )
        )
        fig.add_trace(
            go.Scatter(
                x=t,
                y=qs[hi],
                mode="lines",
                line={"width": 0},
                fill="tonexty",
                fillcolor=f"rgba(31, 119, 180, {opacity:.3f})",
                name=f"P{pct[lo]:g}-P{pct[hi]:g}",
                hoverinfo="skip",
            )
        )
    if median_idx is not None:
        fig.add_trace(
            go.Scatter(
                x=t,
                y=qs[median_idx],
                mode="lines",
                line={"width": 2},
                name=f"P{pct[median_idx]:g} (median)",
            )
        )
    if show_mean:
        fig.add_trace(
            go.Scatter(
                x=t,
                y=samples.mean(axis=0),
                mode="lines",
                line={"dash": "dash", "width": 1.5},
                name="mean",
            )
        )

    scenario = (
        getattr(mc_or_array, "scenario_name", None)
        if not isinstance(mc_or_array, (tuple, np.ndarray))
        else None
    )
    fig.update_layout(
        title=title
        or (f"Monte Carlo fan: {scenario}" if scenario else "Monte Carlo fan"),
        xaxis_title="time",
        yaxis_title="value",
    )
    return apply_theme(_apply_time_axis(fig, time_axis), theme)

plot_phase_portrait 

plot_phase_portrait(result: Any, x_idx: int = 0, y_idx: int = 1, *, theme: str | None = None, title: str | None = None) -> Any

Plot state[:, x_idx] vs state[:, y_idx] with a start marker.

Source code in src/simweave/viz/plots.py 
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
def plot_phase_portrait(
    result: Any,
    x_idx: int = 0,
    y_idx: int = 1,
    *,
    theme: str | None = None,
    title: str | None = None,
) -> Any:
    """Plot ``state[:, x_idx]`` vs ``state[:, y_idx]`` with a start marker."""
    go = _plotly.require_go()
    state = np.asarray(result.state)
    if state.shape[1] <= max(x_idx, y_idx):
        raise IndexError(
            f"phase portrait needs at least {max(x_idx, y_idx) + 1} state channels; "
            f"got {state.shape[1]}."
        )
    labels = list(getattr(result, "state_labels", ()) or [
        f"x{i}" for i in range(state.shape[1])
    ])
    xs = state[:, x_idx]
    ys = state[:, y_idx]

    fig = go.Figure()
    fig.add_trace(
        go.Scatter(
            x=xs,
            y=ys,
            mode="lines",
            name="trajectory",
        )
    )
    fig.add_trace(
        go.Scatter(
            x=[xs[0]],
            y=[ys[0]],
            mode="markers",
            marker={"size": 10, "symbol": "circle"},
            name="start",
        )
    )
    fig.add_trace(
        go.Scatter(
            x=[xs[-1]],
            y=[ys[-1]],
            mode="markers",
            marker={"size": 10, "symbol": "x"},
            name="end",
        )
    )
    sys_name = getattr(result, "system_name", "system")
    fig.update_layout(
        title=title or f"{sys_name} -- phase portrait",
        xaxis_title=labels[x_idx] if x_idx < len(labels) else f"x{x_idx}",
        yaxis_title=labels[y_idx] if y_idx < len(labels) else f"y{y_idx}",
    )
    return apply_theme(fig, theme)

plot_queue_length 

plot_queue_length(recorder: Any, *, time_axis: 'SimTimeAxis | None' = None, theme: str | None = None, title: str | None = None) -> Any

Step plot of queue length over time.

Parameters:

Name Type Description Default
recorder Any

A :class:~simweave.viz.recorders.QueueLengthRecorder (or anything exposing .times and .lengths).

 required
time_axis 'SimTimeAxis | None'

Optional :class:~simweave.core.time_axis.SimTimeAxis. When supplied, the x-axis shows calendar dates instead of numeric ticks.

 None
Source code in src/simweave/viz/plots.py 
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
def plot_queue_length(
    recorder: Any,
    *,
    time_axis: "SimTimeAxis | None" = None,
    theme: str | None = None,
    title: str | None = None,
) -> Any:
    """Step plot of queue length over time.

    Parameters
    ----------
    recorder:
        A :class:`~simweave.viz.recorders.QueueLengthRecorder` (or anything
        exposing ``.times`` and ``.lengths``).
    time_axis:
        Optional :class:`~simweave.core.time_axis.SimTimeAxis`.  When
        supplied, the x-axis shows calendar dates instead of numeric ticks.
    """
    go = _plotly.require_go()
    times = np.asarray(recorder.times)
    lengths = np.asarray(recorder.lengths)
    qname = getattr(recorder.queue, "name", "queue") if hasattr(recorder, "queue") else "queue"

    fig = go.Figure()
    fig.add_trace(
        go.Scatter(
            x=times,
            y=lengths,
            mode="lines",
            line={"shape": "hv"},
            name=qname,
        )
    )
    fig.update_layout(
        title=title or f"queue length: {qname}",
        xaxis_title="time",
        yaxis_title="length",
    )
    return apply_theme(_apply_time_axis(fig, time_axis), theme)

plot_service_utilisation 

plot_service_utilisation(recorder: Any, *, time_axis: 'SimTimeAxis | None' = None, theme: str | None = None, title: str | None = None) -> Any

Aggregate utilisation line + per-channel busy-time lines.

Parameters:

Name Type Description Default
recorder Any

A :class:~simweave.viz.recorders.ServiceUtilisationRecorder.

 required
time_axis 'SimTimeAxis | None'

Optional :class:~simweave.core.time_axis.SimTimeAxis for calendar date x-axis labels.

 None
Source code in src/simweave/viz/plots.py 
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
def plot_service_utilisation(
    recorder: Any,
    *,
    time_axis: "SimTimeAxis | None" = None,
    theme: str | None = None,
    title: str | None = None,
) -> Any:
    """Aggregate utilisation line + per-channel busy-time lines.

    Parameters
    ----------
    recorder:
        A :class:`~simweave.viz.recorders.ServiceUtilisationRecorder`.
    time_axis:
        Optional :class:`~simweave.core.time_axis.SimTimeAxis` for calendar
        date x-axis labels.
    """
    go = _plotly.require_go()
    times = np.asarray(recorder.times)
    util = np.asarray(recorder.utilisation)
    busy = np.asarray(recorder.busy_time)  # (T, n_channels)
    sname = (
        getattr(recorder.service, "name", "service")
        if hasattr(recorder, "service")
        else "service"
    )

    fig = go.Figure()
    fig.add_trace(
        go.Scatter(
            x=times,
            y=util,
            mode="lines",
            name="aggregate utilisation",
            line={"width": 3},
        )
    )
    if busy.ndim == 2:
        for ch in range(busy.shape[1]):
            fig.add_trace(
                go.Scatter(
                    x=times,
                    y=busy[:, ch],
                    mode="lines",
                    name=f"channel {ch} busy_time",
                    line={"dash": "dot"},
                    yaxis="y2",
                )
            )
    fig.update_layout(
        title=title or f"service utilisation: {sname}",
        xaxis_title="time",
        yaxis={"title": "aggregate utilisation", "range": [0, 1]},
        yaxis2={
            "title": "cumulative busy time per channel",
            "overlaying": "y",
            "side": "right",
        },
        legend={"orientation": "h", "y": -0.2},
    )
    return apply_theme(_apply_time_axis(fig, time_axis), theme)

plot_state_trajectories 

plot_state_trajectories(result: Any, channels: Sequence[int] | None = None, *, theme: str | None = None, title: str | None = None) -> Any

Line plot of each state channel vs result.time.

Parameters:

Name Type Description Default
result Any

A :class:~simweave.continuous.solver.SimulationResult or any object exposing .time, .state (shape (T, n)) and .state_labels.

 required
channels Sequence[int] | None

Optional indices of state channels to include. Default: all.

 None
theme str | None

Theme name. Default: the global default (see :func:simweave.viz.set_default_theme).

 None
title str | None

Optional figure title.

 None
Source code in src/simweave/viz/plots.py 
 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
def plot_state_trajectories(
    result: Any,
    channels: Sequence[int] | None = None,
    *,
    theme: str | None = None,
    title: str | None = None,
) -> Any:
    """Line plot of each state channel vs ``result.time``.

    Parameters
    ----------
    result:
        A :class:`~simweave.continuous.solver.SimulationResult` or any
        object exposing ``.time``, ``.state`` (shape ``(T, n)``) and
        ``.state_labels``.
    channels:
        Optional indices of state channels to include. Default: all.
    theme:
        Theme name. Default: the global default (see
        :func:`simweave.viz.set_default_theme`).
    title:
        Optional figure title.
    """
    go = _plotly.require_go()
    time = np.asarray(result.time)
    state = np.asarray(result.state)
    labels = list(getattr(result, "state_labels", ()) or [
        f"x{i}" for i in range(state.shape[1])
    ])
    idxs = list(channels) if channels is not None else list(range(state.shape[1]))

    fig = go.Figure()
    for i in idxs:
        fig.add_trace(
            go.Scatter(
                x=time,
                y=state[:, i],
                mode="lines",
                name=labels[i] if i < len(labels) else f"x{i}",
            )
        )
    sys_name = getattr(result, "system_name", "system")
    fig.update_layout(
        title=title or f"{sys_name} -- state trajectories",
        xaxis_title="time",
        yaxis_title="state",
        legend_title_text="channel",
    )
    return apply_theme(fig, theme)

plot_warehouse_stock 

plot_warehouse_stock(recorder: Any, sku_indices: Sequence[int] | None = None, *, time_axis: 'SimTimeAxis | None' = None, theme: str | None = None, title: str | None = None, show_reorder_points: bool = True) -> Any

Per-SKU stock-level lines with optional reorder-point dashes.

Parameters:

Name Type Description Default
recorder Any

A :class:~simweave.viz.recorders.WarehouseStockRecorder.

 required
sku_indices Sequence[int] | None

Optional iterable of SKU indices to include. Default: all.

 None
time_axis 'SimTimeAxis | None'

Optional :class:~simweave.core.time_axis.SimTimeAxis for calendar date x-axis labels.

 None
show_reorder_points bool

If True, draws a horizontal dashed line at each SKU's reorder point in the same colour family as its stock trace.

 True
Source code in src/simweave/viz/plots.py 
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
def plot_warehouse_stock(
    recorder: Any,
    sku_indices: Sequence[int] | None = None,
    *,
    time_axis: "SimTimeAxis | None" = None,
    theme: str | None = None,
    title: str | None = None,
    show_reorder_points: bool = True,
) -> Any:
    """Per-SKU stock-level lines with optional reorder-point dashes.

    Parameters
    ----------
    recorder:
        A :class:`~simweave.viz.recorders.WarehouseStockRecorder`.
    sku_indices:
        Optional iterable of SKU indices to include. Default: all.
    time_axis:
        Optional :class:`~simweave.core.time_axis.SimTimeAxis` for calendar
        date x-axis labels.
    show_reorder_points:
        If True, draws a horizontal dashed line at each SKU's reorder
        point in the same colour family as its stock trace.
    """
    go = _plotly.require_go()
    times = np.asarray(recorder.times)
    stock = np.asarray(recorder.stock)  # (T, n_skus)
    names = list(recorder.sku_names)
    rop = np.asarray(recorder.reorder_points)

    idxs = list(sku_indices) if sku_indices is not None else list(range(stock.shape[1]))

    fig = go.Figure()
    for i in idxs:
        sku = names[i] if i < len(names) else f"sku{i}"
        fig.add_trace(
            go.Scatter(
                x=times,
                y=stock[:, i],
                mode="lines",
                name=sku,
            )
        )
        if show_reorder_points and i < rop.size:
            fig.add_trace(
                go.Scatter(
                    x=[times[0], times[-1]],
                    y=[rop[i], rop[i]],
                    mode="lines",
                    name=f"{sku} reorder",
                    line={"dash": "dash", "width": 1},
                    showlegend=False,
                    hoverinfo="skip",
                )
            )
    wname = (
        getattr(recorder.warehouse, "name", "warehouse")
        if hasattr(recorder, "warehouse")
        else "warehouse"
    )
    fig.update_layout(
        title=title or f"warehouse stock: {wname}",
        xaxis_title="time",
        yaxis_title="stock level",
        legend_title_text="SKU",
    )
    return apply_theme(_apply_time_axis(fig, time_axis), theme)

plot_fleet_availability 

plot_fleet_availability(recorder: Any, *, normalize: bool = False, time_axis: 'SimTimeAxis | None' = None, theme: str | None = None, title: str | None = None) -> Any

Stacked area chart of fleet operational availability over time.

The three stacked layers are (bottom to top):

  • awaiting part -- entities grounded waiting for spare stock (red).
  • in repair -- parts obtained, repair in progress (amber).
  • operational -- fully mission-capable (green).

Parameters:

Name Type Description Default
recorder Any

A :class:~simweave.reliability.fleet.FleetAvailabilityRecorder (or any object exposing .times, .operational, .in_repair, .awaiting_part, and .fleet).

 required
normalize bool

If True, express each band as a fraction of fleet size (0–1) rather than an absolute vehicle count.

 False
theme str | None

Theme name.

 None
title str | None

Optional figure title.

 None
Source code in src/simweave/viz/plots.py 
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
def plot_fleet_availability(
    recorder: Any,
    *,
    normalize: bool = False,
    time_axis: "SimTimeAxis | None" = None,
    theme: str | None = None,
    title: str | None = None,
) -> Any:
    """Stacked area chart of fleet operational availability over time.

    The three stacked layers are (bottom to top):

    * **awaiting part** -- entities grounded waiting for spare stock (red).
    * **in repair** -- parts obtained, repair in progress (amber).
    * **operational** -- fully mission-capable (green).

    Parameters
    ----------
    recorder:
        A :class:`~simweave.reliability.fleet.FleetAvailabilityRecorder`
        (or any object exposing ``.times``, ``.operational``,
        ``.in_repair``, ``.awaiting_part``, and ``.fleet``).
    normalize:
        If ``True``, express each band as a fraction of fleet size (0–1)
        rather than an absolute vehicle count.
    theme:
        Theme name.
    title:
        Optional figure title.
    """
    go = _plotly.require_go()
    times = np.asarray(recorder.times)
    op = np.asarray(recorder.operational, dtype=float)
    ir = np.asarray(recorder.in_repair, dtype=float)
    ap = np.asarray(recorder.awaiting_part, dtype=float)

    fleet_name = getattr(getattr(recorder, "fleet", None), "name", "fleet")
    fleet_size = getattr(getattr(recorder, "fleet", None), "size", 1) or 1

    if normalize:
        op = op / fleet_size
        ir = ir / fleet_size
        ap = ap / fleet_size
        ylabel = "fraction of fleet"
    else:
        ylabel = "vehicles"

    fig = go.Figure()
    # Stack order: awaiting_part at bottom, then in_repair, then operational.
    fig.add_trace(
        go.Scatter(
            x=times,
            y=ap,
            mode="lines",
            stackgroup="one",
            name="awaiting part",
            line={"color": "rgba(180,30,30,0.9)", "width": 0.5},
            fillcolor="rgba(214,39,40,0.65)",
        )
    )
    fig.add_trace(
        go.Scatter(
            x=times,
            y=ir,
            mode="lines",
            stackgroup="one",
            name="in repair",
            line={"color": "rgba(200,100,0,0.9)", "width": 0.5},
            fillcolor="rgba(255,127,14,0.65)",
        )
    )
    fig.add_trace(
        go.Scatter(
            x=times,
            y=op,
            mode="lines",
            stackgroup="one",
            name="operational",
            line={"color": "rgba(30,140,30,0.9)", "width": 0.5},
            fillcolor="rgba(44,160,44,0.65)",
        )
    )
    fig.update_layout(
        title=title or f"fleet availability: {fleet_name}",
        xaxis_title="time",
        yaxis_title=ylabel,
        legend={"orientation": "h", "y": -0.2},
    )
    return apply_theme(_apply_time_axis(fig, time_axis), theme)

plot_sensitivity_surface 

plot_sensitivity_surface(result: Any, *, chart_type: str = 'surface', show_std: bool = False, theme: str | None = None, title: str | None = None) -> Any

3-D surface or grouped bar chart for a 2-D sensitivity sweep result.

Parameters:

Name Type Description Default
result Any

A :class:~simweave.reliability.sensitivity.SweepResult from a 2-D sweep (result.is_2d must be True).

 required
chart_type str

"surface" (default) -- smooth 3-D surface using go.Surface. "bar" -- grouped 2-D bar chart (p1 values as groups, p2 as series), useful when parameter values are discrete labels. "heatmap" -- 2-D colour map, ideal for dense grids.

 'surface'
show_std bool

If True and chart_type="bar", draws error bars representing ±1 standard deviation across Monte Carlo replicates.

 False
theme str | None

Theme name.

 None
title str | None

Optional figure title.

 None
Source code in src/simweave/viz/plots.py 
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
def plot_sensitivity_surface(
    result: Any,
    *,
    chart_type: str = "surface",
    show_std: bool = False,
    theme: str | None = None,
    title: str | None = None,
) -> Any:
    """3-D surface or grouped bar chart for a 2-D sensitivity sweep result.

    Parameters
    ----------
    result:
        A :class:`~simweave.reliability.sensitivity.SweepResult` from a 2-D
        sweep (``result.is_2d`` must be ``True``).
    chart_type:
        ``"surface"`` (default) -- smooth 3-D surface using ``go.Surface``.
        ``"bar"`` -- grouped 2-D bar chart (p1 values as groups, p2 as
        series), useful when parameter values are discrete labels.
        ``"heatmap"`` -- 2-D colour map, ideal for dense grids.
    show_std:
        If ``True`` and ``chart_type="bar"``, draws error bars representing
        ±1 standard deviation across Monte Carlo replicates.
    theme:
        Theme name.
    title:
        Optional figure title.
    """
    go = _plotly.require_go()

    p1 = np.asarray(result.param1_values)
    metric = np.asarray(result.metric_mean)
    std = np.asarray(result.metric_std)
    p1_name = result.param1_name
    metric_name = result.metric_name

    # 1-D fallback: line plot with optional error band.
    if not result.is_2d:
        fig = go.Figure()
        fig.add_trace(
            go.Scatter(
                x=p1,
                y=metric,
                mode="lines+markers",
                name=metric_name,
                error_y=(
                    {"type": "data", "array": std.tolist(), "visible": True}
                    if show_std
                    else None
                ),
            )
        )
        fig.update_layout(
            title=title or f"sensitivity: {metric_name} vs {p1_name}",
            xaxis_title=p1_name,
            yaxis_title=metric_name,
        )
        return apply_theme(fig, theme)

    # 2-D
    p2 = np.asarray(result.param2_values)
    p2_name = result.param2_name

    if chart_type == "surface":
        fig = go.Figure(
            go.Surface(
                x=p2,
                y=p1,
                z=metric,
                colorscale="Viridis",
                colorbar={"title": metric_name},
            )
        )
        fig.update_layout(
            title=title or f"sensitivity surface: {metric_name}",
            scene={
                "xaxis_title": p2_name,
                "yaxis_title": p1_name,
                "zaxis_title": metric_name,
            },
        )

    elif chart_type == "heatmap":
        fig = go.Figure(
            go.Heatmap(
                x=[str(v) for v in p2],
                y=[str(v) for v in p1],
                z=metric,
                colorscale="Viridis",
                colorbar={"title": metric_name},
                hoverongaps=False,
            )
        )
        fig.update_layout(
            title=title or f"sensitivity heatmap: {metric_name}",
            xaxis_title=p2_name,
            yaxis_title=p1_name,
        )

    else:  # "bar"
        fig = go.Figure()
        for j, v2 in enumerate(p2):
            ey = {"type": "data", "array": std[:, j].tolist(), "visible": True} if show_std else None
            fig.add_trace(
                go.Bar(
                    name=f"{p2_name}={v2:g}",
                    x=[f"{v:g}" for v in p1],
                    y=metric[:, j],
                    error_y=ey,
                )
            )
        fig.update_layout(
            title=title or f"sensitivity: {metric_name}",
            xaxis_title=p1_name,
            yaxis_title=metric_name,
            barmode="group",
        )

    return apply_theme(fig, theme)

plot_road_occupancy 

plot_road_occupancy(recorder: Any, *, time_axis: 'SimTimeAxis | None' = None, theme: str | None = None, title: str | None = None) -> Any

Line chart of in-transit vehicle counts for a set of roads over time.

Parameters:

Name Type Description Default
recorder Any

A :class:~simweave.roads.recorder.RoadOccupancyRecorder (or any object exposing .times, .occupancy, and .road_names).

 required
time_axis 'SimTimeAxis | None'

Optional :class:~simweave.core.time_axis.SimTimeAxis for calendar date x-axis labels.

 None
theme str | None

Standard theme/title overrides.

 None
title str | None

Standard theme/title overrides.

 None
Source code in src/simweave/viz/plots.py 
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
def plot_road_occupancy(
    recorder: Any,
    *,
    time_axis: "SimTimeAxis | None" = None,
    theme: str | None = None,
    title: str | None = None,
) -> Any:
    """Line chart of in-transit vehicle counts for a set of roads over time.

    Parameters
    ----------
    recorder:
        A :class:`~simweave.roads.recorder.RoadOccupancyRecorder` (or any
        object exposing ``.times``, ``.occupancy``, and ``.road_names``).
    time_axis:
        Optional :class:`~simweave.core.time_axis.SimTimeAxis` for calendar
        date x-axis labels.
    theme, title:
        Standard theme/title overrides.
    """
    go = _plotly.require_go()
    times = np.asarray(recorder.times)
    occ = np.asarray(recorder.occupancy)   # (n_samples, n_roads)
    road_names: Sequence[str] = recorder.road_names

    fig = go.Figure()
    for i, name in enumerate(road_names):
        col = occ[:, i] if occ.ndim == 2 else occ
        fig.add_trace(
            go.Scatter(
                x=times,
                y=col,
                mode="lines",
                name=name,
            )
        )
    fig.update_layout(
        title=title or "Road occupancy (vehicles in transit)",
        xaxis_title="time",
        yaxis_title="vehicles in transit",
        legend={"orientation": "h", "y": -0.2},
    )
    return apply_theme(_apply_time_axis(fig, time_axis), theme)

plot_intersection_queues 

plot_intersection_queues(recorder: Any, *, time_axis: 'SimTimeAxis | None' = None, theme: str | None = None, title: str | None = None) -> Any

Line chart of approach-queue lengths at one intersection over time.

The total queue (solid line) and each per-approach breakdown (dashed lines) are plotted.

Parameters:

Name Type Description Default
recorder Any

An :class:~simweave.roads.recorder.IntersectionQueueRecorder (or any object exposing .times, .total_queued, and .per_approach).

 required
time_axis 'SimTimeAxis | None'

Standard overrides.

 None
theme 'SimTimeAxis | None'

Standard overrides.

 None
title 'SimTimeAxis | None'

Standard overrides.

 None
Source code in src/simweave/viz/plots.py 
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
def plot_intersection_queues(
    recorder: Any,
    *,
    time_axis: "SimTimeAxis | None" = None,
    theme: str | None = None,
    title: str | None = None,
) -> Any:
    """Line chart of approach-queue lengths at one intersection over time.

    The total queue (solid line) and each per-approach breakdown (dashed
    lines) are plotted.

    Parameters
    ----------
    recorder:
        An :class:`~simweave.roads.recorder.IntersectionQueueRecorder` (or
        any object exposing ``.times``, ``.total_queued``, and
        ``.per_approach``).
    time_axis, theme, title:
        Standard overrides.
    """
    go = _plotly.require_go()
    times = np.asarray(recorder.times)
    total = np.asarray(recorder.total_queued, dtype=float)

    fig = go.Figure()
    fig.add_trace(
        go.Scatter(
            x=times,
            y=total,
            mode="lines",
            name="total queued",
            line={"width": 2},
        )
    )

    # Per-approach breakdown
    if recorder.per_approach:
        approach_names = list(recorder.per_approach[0].keys())
        for road_name in approach_names:
            vals = np.asarray(
                [d.get(road_name, 0) for d in recorder.per_approach], dtype=float
            )
            fig.add_trace(
                go.Scatter(
                    x=times,
                    y=vals,
                    mode="lines",
                    name=road_name,
                    line={"dash": "dot", "width": 1},
                )
            )

    fig.update_layout(
        title=title or "Intersection queue lengths",
        xaxis_title="time",
        yaxis_title="vehicles queued",
        legend={"orientation": "h", "y": -0.2},
    )
    return apply_theme(_apply_time_axis(fig, time_axis), theme)

plot_fault_signals 

plot_fault_signals(result: Any, injector: Any, channels: Sequence[int] | None = None, *, theme: str | None = None, title: str | None = None) -> Any

State trajectories with shaded regions for degraded and failed phases.

The plot overlays the simulated state channels with coloured background bands:

  • green — healthy (health index = 1).
  • amber — degrading (0 < health index < 1).
  • red — failed (health index = 0).

Parameters:

Name Type Description Default
result Any

A :class:~simweave.continuous.solver.SimulationResult from a run that used a :class:~simweave.faults.injector.FaultInjector.

 required
injector Any

The :class:~simweave.faults.injector.FaultInjector used for the run (provides fault profile timings).

 required
channels Sequence[int] | None

State channel indices to plot. Default: all.

 None
theme str | None

Standard overrides.

 None
title str | None

Standard overrides.

 None
Source code in src/simweave/viz/plots.py 
 976
 977
 978
 979
 980
 981
 982
 983
 984
 985
 986
 987
 988
 989
 990
 991
 992
 993
 994
 995
 996
 997
 998
 999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
def plot_fault_signals(
    result: Any,
    injector: Any,
    channels: Sequence[int] | None = None,
    *,
    theme: str | None = None,
    title: str | None = None,
) -> Any:
    """State trajectories with shaded regions for degraded and failed phases.

    The plot overlays the simulated state channels with coloured background
    bands:

    * **green** — healthy (health index = 1).
    * **amber** — degrading (0 < health index < 1).
    * **red** — failed (health index = 0).

    Parameters
    ----------
    result:
        A :class:`~simweave.continuous.solver.SimulationResult` from a run
        that used a :class:`~simweave.faults.injector.FaultInjector`.
    injector:
        The :class:`~simweave.faults.injector.FaultInjector` used for the run
        (provides fault profile timings).
    channels:
        State channel indices to plot.  Default: all.
    theme, title:
        Standard overrides.
    """
    go = _plotly.require_go()
    time = np.asarray(result.time)
    state = np.asarray(result.state)
    labels = list(getattr(result, "state_labels", ()) or [
        f"x{i}" for i in range(state.shape[1])
    ])
    idxs = list(channels) if channels is not None else list(range(state.shape[1]))

    fig = go.Figure()

    # Shade degradation / failure windows
    t0, tf = float(time[0]), float(time[-1])
    for f in injector.faults:
        onset = max(f.profile.onset_time, t0)
        failure = min(f.profile.failure_time, tf)
        if onset < failure:
            fig.add_vrect(
                x0=onset, x1=failure,
                fillcolor="orange", opacity=0.12, layer="below", line_width=0,
                annotation_text=f"degrading ({f.profile.mode})",
                annotation_position="top left",
            )
        if failure < tf:
            fig.add_vrect(
                x0=failure, x1=tf,
                fillcolor="red", opacity=0.12, layer="below", line_width=0,
                annotation_text="failed",
                annotation_position="top left",
            )

    for i in idxs:
        fig.add_trace(
            go.Scatter(
                x=time,
                y=state[:, i],
                mode="lines",
                name=labels[i] if i < len(labels) else f"x{i}",
            )
        )

    sys_name = getattr(result, "system_name", "system")
    fig.update_layout(
        title=title or f"{sys_name} — fault signals",
        xaxis_title="time",
        yaxis_title="state",
        legend_title_text="channel",
    )
    return apply_theme(fig, theme)

plot_health_index 

plot_health_index(dataset: Any, *, show_rul: bool = True, theme: str | None = None, title: str | None = None) -> Any

Health index (and optionally RUL) over simulation time.

Parameters:

Name Type Description Default
dataset Any

A :class:~simweave.faults.dataset.FaultDataset (or any object exposing .time, .health_index, and .rul).

 required
show_rul bool

If True (default), overlay remaining useful life on a secondary y-axis.

 True
theme str | None

Standard overrides.

 None
title str | None

Standard overrides.

 None
Source code in src/simweave/viz/plots.py 
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
def plot_health_index(
    dataset: Any,
    *,
    show_rul: bool = True,
    theme: str | None = None,
    title: str | None = None,
) -> Any:
    """Health index (and optionally RUL) over simulation time.

    Parameters
    ----------
    dataset:
        A :class:`~simweave.faults.dataset.FaultDataset` (or any object
        exposing ``.time``, ``.health_index``, and ``.rul``).
    show_rul:
        If ``True`` (default), overlay remaining useful life on a secondary
        y-axis.
    theme, title:
        Standard overrides.
    """
    go = _plotly.require_go()
    time = np.asarray(dataset.time)
    hi = np.asarray(dataset.health_index)

    fig = go.Figure()
    fig.add_trace(
        go.Scatter(
            x=time,
            y=hi,
            mode="lines",
            name="health index",
            line={"color": "royalblue", "width": 2},
        )
    )

    if show_rul:
        rul = np.asarray(dataset.rul, dtype=float)
        rul_finite = np.where(np.isinf(rul), np.nan, rul)
        if not np.all(np.isnan(rul_finite)):
            fig.add_trace(
                go.Scatter(
                    x=time,
                    y=rul_finite,
                    mode="lines",
                    name="RUL",
                    line={"color": "darkorange", "dash": "dash", "width": 1.5},
                    yaxis="y2",
                )
            )
            fig.update_layout(
                yaxis2={
                    "title": "remaining useful life",
                    "overlaying": "y",
                    "side": "right",
                    "showgrid": False,
                }
            )

    fig.update_layout(
        title=title or "Health index and RUL",
        xaxis_title="time",
        yaxis={"title": "health index", "range": [-0.05, 1.05]},
        legend={"orientation": "h", "y": -0.2},
    )
    return apply_theme(fig, theme)

plot_vehicle_metrics 

plot_vehicle_metrics(result, *, model=None, theme: str | None = None, title: str | None = None)

Plot vehicle metrics with adaptive layout and automatic units.

Source code in src/simweave/viz/vehicle_dynamics.py 
 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
136
137
138
139
140
141
142
143
144
145
146
147
148
def plot_vehicle_metrics(
    result,
    *,
    model=None,
    theme: str | None = None,
    title: str | None = None,
):
    """Plot vehicle metrics with adaptive layout and automatic units."""

    go = _plotly.require_go()

    metrics = compute_vehicle_metrics(result, model)
    t = np.asarray(result.time)

    # --- unit helpers ---
    def accel(x): return Acceleration(x).to("m/s^2")
    def angle(x): return Angle(x).to("deg")
    def dist(x): return Distance(x).to("m")
    def force(x): return Force(x).to("N")

    # --- detect signals ---
    has_pitch = metrics["pitch"] is not None
    has_roll = metrics["roll"] is not None

    # --- build subplot structure ---
    subplot_titles = ["Body acceleration (comfort)"]

    if has_pitch or has_roll:
        subplot_titles.append("Pitch / Roll")

    subplot_titles.append("Suspension travel")
    subplot_titles.append(metrics["tyre_metric"]["name"])

    n_rows = len(subplot_titles)

    fig = make_subplots(
        rows=n_rows,
        cols=1,
        shared_xaxes=True,
        vertical_spacing=0.08,
        subplot_titles=tuple(subplot_titles),
    )

    row = 1

    # --- 1. BODY ACCEL ---
    fig.add_trace(
        go.Scatter(x=t, y=accel(metrics["body_accel"]), mode="lines",
                   name="body accel [m/s²]"),
        row=row, col=1,
    )

    rms = accel(metrics["body_accel_RMS"])
    fig.add_annotation(
        text=f"RMS: {rms:.3f} m/s²",
        xref="paper", yref="paper",
        x=0.01, y=0.98,
        showarrow=False,
    )

    fig.update_yaxes(title_text="m/s²", row=row)
    row += 1

    # --- 2. PITCH / ROLL (optional) ---
    if has_pitch or has_roll:
        if has_pitch:
            fig.add_trace(
                go.Scatter(x=t, y=angle(metrics["pitch"]),
                           mode="lines", name="pitch [deg]"),
                row=row, col=1,
            )

        if has_roll:
            fig.add_trace(
                go.Scatter(x=t, y=angle(metrics["roll"]),
                           mode="lines", name="roll [deg]"),
                row=row, col=1,
            )

        fig.update_yaxes(title_text="deg", row=row)
        row += 1

    # --- 3. SUSPENSION TRAVEL ---
    for key, data in metrics["suspension_travel"].items():
        fig.add_trace(
            go.Scatter(
                x=t,
                y=dist(data),
                mode="lines",
                name=f"{key.upper()} travel [m]",
            ),
            row=row, col=1,
        )

    fig.update_yaxes(title_text="m", row=row)
    row += 1

    # --- 4. TYRE ---
    tyre_metric = metrics["tyre_metric"]

    if tyre_metric["unit"] == "N":
        conv = force
        unit_label = "N"
    else:
        conv = dist
        unit_label = "m"

    for key, data in metrics["tyre"].items():
        fig.add_trace(
            go.Scatter(
                x=t,
                y=conv(data),
                mode="lines",
                line={"dash": "dot"},
                name=f"{key.upper()} tyre [{unit_label}]",
            ),
            row=row, col=1,
        )

    fig.update_yaxes(title_text=unit_label, row=row)

    # --- layout ---
    fig.update_layout(
        title=title or "Vehicle metrics",
        xaxis_title="time",
        legend_title_text="signals",
        height=300 * n_rows,  # dynamic height
    )

    return apply_theme(fig, theme)

have_plotly 

have_plotly() -> bool

Cheap probe: does the current environment have plotly available?

Source code in src/simweave/viz/_plotly.py 
29
30
31
32
33
34
35
def have_plotly() -> bool:
    """Cheap probe: does the current environment have plotly available?"""
    try:
        import plotly  # noqa: F401
    except ImportError:
        return False
    return True