quantcore_circuits.track ======================== .. py:module:: quantcore_circuits.track .. autoapi-nested-parse:: Live run state for the dashboard (``reviewer/``, served by ``qcc review``): ``build//state.json``. A :class:`Run` records the design loop as it happens — which step is running, targets vs current values, KLayout screenshots, plots (as data, rendered by the dashboard and by :mod:`quantcore_circuits.plots`), the circuit, the Hamiltonian, the estimator consensus, simulation jobs, optimiser history and a log. Every mutation rewrites ``state.json`` atomically (inside :meth:`Run.deferred`: step starts / ends and the end of the block only); the server pushes a Server-Sent Event and the browser refetches. The JSON follows the contract in ``reviewer/contract/state.ts``. Attributes ---------- .. autoapisummary:: quantcore_circuits.track.STATE_SCHEMA quantcore_circuits.track.STEPS Classes ------- .. autoapisummary:: quantcore_circuits.track.Run Functions --------- .. autoapisummary:: quantcore_circuits.track.default_root quantcore_circuits.track.emit quantcore_circuits.track.job_alive quantcore_circuits.track.job_progress quantcore_circuits.track.pid_alive quantcore_circuits.track.quiet quantcore_circuits.track.run_dir_for quantcore_circuits.track.run_for quantcore_circuits.track.scan_jobs quantcore_circuits.track.session quantcore_circuits.track.stage quantcore_circuits.track.start quantcore_circuits.track.stop Module Contents --------------- .. py:class:: Run(design_source=None, run_dir: str | pathlib.Path | None = None, reset: bool = False, name: str | None = None) .. py:method:: deferred() Within this block ``state.json`` is written when a step starts, ends or fails and once at the end, not on every log line, plot or field (an analysis of many qubit pairs adds dozens of them; each write encodes the whole state). .. py:method:: done(step_id: str, summary: str = '', **metrics) -> None .. py:method:: fail(step_id: str, message: str) -> None .. py:method:: follow(design, design_source=None, name: str | None = None, save: bool = True) -> None Point the run's ``design`` block at ``design`` (a revision of the same run). ``None``: a model-only run. .. py:method:: iteration(entry: dict) -> None .. py:method:: log(msg: str, level: str = 'info') -> None .. py:method:: plot(spec: dict) -> None Add or replace a PlotSpec (``id`` is the key). .. py:method:: refresh_jobs(jobs_root: str | pathlib.Path | None = None, keep_root: str | pathlib.Path | None = 'auto') -> list[dict] Scan ``jobs_root`` (and the tutorials' kept FEM results) for the job directories of this run's design(s): status, results, and the solve progress (:func:`job_progress`). Returns the jobs and stores them. .. py:method:: reset_from(step_id: str) -> None Mark ``step_id`` and every later step pending again (a new loop iteration). .. py:method:: save(force: bool = False) -> pathlib.Path .. py:method:: screenshot(png: str | pathlib.Path, title: str, step: str | None = None, caption: str = '', source: str = 'headless', ident: str | None = None) -> dict Copy ``png`` into ``/shots/`` and register it (same ``ident`` replaces the earlier one). .. py:method:: set(**fields) -> None Set top-level fields: targets, goal, circuit, hamiltonian, consensus, jobs, cmatrix, history. .. py:method:: skip(step_id: str, reason: str) -> None .. py:method:: start(step_id: str, summary: str | None = None) -> None .. py:attribute:: design_source :value: None .. py:attribute:: dir .. py:attribute:: path .. py:function:: default_root() -> pathlib.Path ``/build``: the folder with the pyproject.toml above the working directory (notebooks run from ``examples/``, ``examples/tutorials/`` or the root all share one set of runs), else ``./build``. .. py:function:: emit(event: str, **kw) -> None Library hook: report ``event`` to the tracking session (no-op when tracking is off; never raises). .. py:function:: job_alive(d: pathlib.Path, job: dict) -> bool A job whose ``job.json`` says "solving" / "rendering": is the AEDT process still there? (``.pid``, written by ``hfss.run_aedt``). Without a pid file a job that started under a minute ago counts as alive. .. py:function:: job_progress(d: pathlib.Path, job: dict) -> dict | None Solve progress of the job directory ``d`` from the files the solve leaves behind: ``job.json`` (status, start time, settings), ``qcc_solve_status.txt`` / ``solve.log`` (last lines), ``*_convergence.txt`` (adaptive passes, mesh, criterion), ``results/results.json``. None when there is nothing to show (an exported job). .. py:function:: pid_alive(pid: int) -> bool Whether process ``pid`` exists (never signals it: a query only). .. py:function:: quiet() Suspend the automatic fill/LOM/DRC hooks (a caller that records those results itself, e.g. ``loop.analyse``). .. py:function:: run_dir_for(design_name: str, root: str | pathlib.Path = 'build') -> pathlib.Path .. py:function:: run_for(design=None, model_name: str | None = None) The tracking session's Run for ``design`` (None when tracking is off): what ``loop.analyse`` records into. .. py:function:: scan_jobs(names, jobs_root: str | pathlib.Path = 'build/jobs', keep_root: str | pathlib.Path | None = 'auto') -> list[dict] Jobs (``job.json``) of designs ``names`` under ``jobs_root``; with ``keep_root`` ("auto": the tutorials' ``examples/tutorials/fem``) kept results of a job count when the build copy has none (``source: "kept"``). .. py:function:: session() The active tracking session or None (``QCC_TRACK=1`` / ``QCC_TRACK=`` starts one on first use). .. py:function:: stage(step: str, label: str = '') Mark dashboard step ``step`` running, then done (or failed on an exception / ``handle.fail(msg)``) when the block ends. Nested stages of one step (``hfss.render`` exporting its job) mark only the outermost. No-op when tracking is off; never raises on its own. .. py:function:: start(name: str | None = None, *, reset: bool = True, snapshots: bool = True, root: str | pathlib.Path | None = None, dashboard: bool = False, port: int = 8765, open_browser: bool = True, watch: bool = True) Record the library's calls (builds, DRC, LOM, FEM jobs, feedback) into ``build//state.json``. ``name``: one run for everything (e.g. a tutorial's revisions); None: one run per design name. ``reset``: start the run(s) fresh. ``dashboard=True`` also serves the dashboard from this process (background thread) following the run. Returns the session (``.flush()`` waits for the background snapshots). .. py:function:: stop() -> None .. py:data:: STATE_SCHEMA :value: 'qcc-state/0.1' .. py:data:: STEPS :value: [('synthesis', 'LOM synthesis'), ('layout', 'Layout'), ('render', 'HFSS render'), ('simulate',...