quantcore_circuits.plots ======================== .. py:module:: quantcore_circuits.plots .. autoapi-nested-parse:: Plot helpers following the project plot style (thesis style), plus PlotSpec builders shared with the dashboard. Style: the Quantcore palette, inward ticks with minor ticks on all sides (:func:`thesis_axes`), serif LaTeX text when a TeX install works (checked once in a subprocess, cached), PDF fonts embedded. Sizes: figure width = fraction of \textwidth × 6.0 in, so the matplotlib font size is the printed size; pick a layout from :data:`FIGSIZES` and its font tier with :func:`figure`. Data is passed around as *PlotSpecs* (``reviewer/contract/state.ts``): the same dict is drawn by the React dashboard and by :func:`plot_spec` here. Builders: :func:`xy_spec`, :func:`bar_spec`, :func:`levels_spec`, :func:`heatmap_spec`. Attributes ---------- .. autoapisummary:: quantcore_circuits.plots.COLORS quantcore_circuits.plots.FIGSIZES quantcore_circuits.plots.TIERS Functions --------- .. autoapisummary:: quantcore_circuits.plots.bar_spec quantcore_circuits.plots.convergence_data quantcore_circuits.plots.convergence_specs quantcore_circuits.plots.epr_specs quantcore_circuits.plots.fem_specs quantcore_circuits.plots.figure quantcore_circuits.plots.heatmap_spec quantcore_circuits.plots.latex_available quantcore_circuits.plots.levels_spec quantcore_circuits.plots.plot_convergence quantcore_circuits.plots.plot_epr quantcore_circuits.plots.plot_s21_fit quantcore_circuits.plots.plot_spec quantcore_circuits.plots.s21_specs quantcore_circuits.plots.save quantcore_circuits.plots.tex quantcore_circuits.plots.thesis_axes quantcore_circuits.plots.use_style quantcore_circuits.plots.use_tier quantcore_circuits.plots.xy_spec Module Contents --------------- .. py:function:: bar_spec(ident, title, tab, bars, y_label=None, caption=None) ``bars``: list of {label, values: {series: value}}. .. py:function:: convergence_data(x, label: str | None = None) -> dict | None One job's adaptive-pass convergence as plain lists: ``label``, ``analysis``, ``criterion``, ``target``, ``converged``, ``passes``, ``elements`` (solved tets per pass), ``delta`` (None on pass 1), ``mode_GHz`` (eigenmode jobs: mode -> frequency per pass). None when the job has no convergence data. .. py:function:: convergence_specs(results_or_job, label: str | None = None, tab: str = 'plots') -> list[dict] Dashboard specs of a job's convergence: delta per pass with the criterion line, delta against the tet count and, for eigenmode jobs, each mode's frequency per pass. .. py:function:: epr_specs(epr_result: dict, tab: str = 'plots', prefix: str = 'epr') -> list[dict] Dashboard specs of an EPR result: participation bars (mode -> junction) and the chi matrix (diagonal alpha). .. py:function:: fem_specs(jobs, tab: str = 'plots') -> list[dict] All FEM-result plot specs for the dashboard. ``jobs``: results dicts or ``FilledCircuit.jobs`` entries (which hold ``results``). Per job: its convergence set, the S21 notches of a driven job and the EPR of an eigenmode job that recorded it. .. py:function:: figure(layout: str = 'single', nrows: int = 1, ncols: int = 1, **kw) ``plt.subplots`` with the guideline figsize and font tier for ``layout`` (see :data:`FIGSIZES`). .. py:function:: heatmap_spec(ident, title, tab, rows, cols, values, unit, caption=None) .. py:function:: latex_available(timeout: float = 120.0) -> bool Whether matplotlib ``text.usetex`` works here (tested once in a subprocess so a TeX prompt can't hang us). .. py:function:: levels_spec(ident, title, tab, levels, caption=None) .. py:function:: plot_convergence(results_or_job, ax=None, label: str | None = None) Adaptive-pass convergence of one job (a ``results.json`` dict / path, a job folder, a convergence text file) or of several (``{label: ...}`` or a list). Returns the first axis (``ax.figure.axes`` has the rest). With ``ax`` only that panel is drawn: the criterion (delta %, max delta f %, max \|delta S\|) against the pass, a dotted criterion line, and the mesh size (solved tets) on a secondary top axis for a single job; jobs with different criteria are drawn as delta / target so the line at 1 is the criterion. Without ``ax`` a figure with the pass panel, the same delta against the tet count (log), and, for an eigenmode job, each mode's frequency relative to its last pass. .. py:function:: plot_epr(epr_result: dict, ax=None) Energy participation of an EPR result (:mod:`analysis.epr_lumped`): bars of p per mode, one colour per junction (log scale: resonator modes sit near 1e-3), and without ``ax`` also the chi matrix of the modes that touch a junction (signed, symmetric-log colour, values printed). Returns the first axis. .. py:function:: plot_s21_fit(results, ax=None, f_GHz=None, s21=None, job_dir=None, notch: str | None = None) \|S21\| of a driven job with its notch fit, the fitted f0, kappa_ext and Q_i written on the panel. ``results``: the ``results.json`` dict (``sparams.notch`` holds the fits), a path to it, or a job folder with an ``*_SMatrix.s2p`` (the trace is read and re-fitted with :func:`analysis.results.fit_notches`). The trace itself is not stored in ``results.json``: pass ``f_GHz`` / ``s21`` or ``job_dir`` to draw the data, otherwise only the fitted model curve (normalised to 1 off resonance) is shown and the title says so. ``notch``: one fit's key; default all fits, one panel each (up to 4) when ``ax`` is not given, the first when it is. Returns the first axis. .. py:function:: plot_spec(spec: dict, ax=None, legend: bool = True) Draw a PlotSpec on ``ax`` (a new guideline-sized figure if omitted). Returns the axis. .. py:function:: s21_specs(results, f_GHz=None, s21=None, job_dir=None, tab: str = 'plots', max_points: int = 400) -> list[dict] Dashboard spec per \|S21\| notch: the data when a trace is available (decimated to ``max_points``), the fit curve, and the fitted f0 / kappa_ext in the caption. .. py:function:: save(fig, path, formats=('pdf', 'png')) -> list[pathlib.Path] Save ``fig`` next to ``path`` in each format (PDF for LaTeX, PNG for the dashboard/notebook). .. py:function:: tex(s: str | None) -> str | None Unicode label → mathtext/LaTeX label: ``f_q``/``C_Σ`` (single-letter base) become subscripts, Greek and kets become math, and text-mode specials are escaped under usetex (``metal_lom`` stays literal). .. py:function:: thesis_axes(ax, xminor: int = 5, yminor: int = 5) Minor ticks and consistent spine widths (project plot style). Call once per axis. .. py:function:: use_style(usetex: bool | None = None) -> bool Apply the guideline style; returns whether LaTeX text is on (falls back to Computer Modern mathtext). .. py:function:: use_tier(n: int) -> None .. py:function:: xy_spec(ident, title, tab, series, x_label=None, y_label=None, ref_lines=None, log_y=False, caption=None) ``series``: list of dicts {name, x, y, kind?, dashed?}. .. py:data:: COLORS :value: ['#185adb', '#f9813a', '#da0037', '#206a5d', '#444444', '#c4fb6d', '#e84a5f', '#3edbf0',... .. py:data:: FIGSIZES .. py:data:: TIERS