quantcore_circuits.track

Live run state for the dashboard (reviewer/, served by qcc review): build/<design>/state.json.

A 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 quantcore_circuits.plots), the circuit, the Hamiltonian, the estimator consensus, simulation jobs, optimiser history and a log. Every mutation rewrites state.json atomically (inside 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

Classes

Run

Functions

default_root() → pathlib.Path

<repo>/build: the folder with the pyproject.toml above the working directory (notebooks run from

emit(event, **kw) → None

Library hook: report event to the tracking session (no-op when tracking is off; never raises).

job_alive(d, job) → bool

A job whose job.json says "solving" / "rendering": is the AEDT process still there? (<log>.pid, written

job_progress(d, job) → dict | None

Solve progress of the job directory d from the files the solve leaves behind: job.json (status, start

pid_alive(pid) → bool

Whether process pid exists (never signals it: a query only).

quiet()

Suspend the automatic fill/LOM/DRC hooks (a caller that records those results itself, e.g. loop.analyse).

run_dir_for(design_name[, root]) → pathlib.Path

run_for([design, model_name])

The tracking session's Run for design (None when tracking is off): what loop.analyse records into.

scan_jobs(names[, jobs_root, keep_root]) → list[dict]

Jobs (job.json) of designs names under jobs_root; with keep_root ("auto": the tutorials'

session()

The active tracking session or None (QCC_TRACK=1 / QCC_TRACK=<run name> starts one on first use).

stage(step[, label])

Mark dashboard step step running, then done (or failed on an exception / handle.fail(msg)) when the

start([name, reset, snapshots, root, dashboard, port, ...])

Record the library's calls (builds, DRC, LOM, FEM jobs, feedback) into build/<name>/state.json.

stop() → None

Module Contents

class quantcore_circuits.track.Run(design_source=None, run_dir: str | pathlib.Path | None = None, reset: bool = False, name: str | None = None)
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).

done(step_id: str, summary: str = '', **metrics) → None
fail(step_id: str, message: str) → None
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.

iteration(entry: dict) → None
log(msg: str, level: str = 'info') → None
plot(spec: dict) → None

Add or replace a PlotSpec (id is the key).

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 (job_progress()). Returns the jobs and stores them.

reset_from(step_id: str) → None

Mark step_id and every later step pending again (a new loop iteration).

save(force: bool = False) → pathlib.Path
screenshot(png: str | pathlib.Path, title: str, step: str | None = None, caption: str = '', source: str = 'headless', ident: str | None = None) → dict

Copy png into <run>/shots/ and register it (same ident replaces the earlier one).

set(**fields) → None

Set top-level fields: targets, goal, circuit, hamiltonian, consensus, jobs, cmatrix, history.

skip(step_id: str, reason: str) → None
start(step_id: str, summary: str | None = None) → None
design_source = None
dir
path
quantcore_circuits.track.default_root() → pathlib.Path

<repo>/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.

quantcore_circuits.track.emit(event: str, **kw) → None

Library hook: report event to the tracking session (no-op when tracking is off; never raises).

quantcore_circuits.track.job_alive(d: pathlib.Path, job: dict) → bool

A job whose job.json says “solving” / “rendering”: is the AEDT process still there? (<log>.pid, written by hfss.run_aedt). Without a pid file a job that started under a minute ago counts as alive.

quantcore_circuits.track.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).

quantcore_circuits.track.pid_alive(pid: int) → bool

Whether process pid exists (never signals it: a query only).

quantcore_circuits.track.quiet()

Suspend the automatic fill/LOM/DRC hooks (a caller that records those results itself, e.g. loop.analyse).

quantcore_circuits.track.run_dir_for(design_name: str, root: str | pathlib.Path = 'build') → pathlib.Path
quantcore_circuits.track.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.

quantcore_circuits.track.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").

quantcore_circuits.track.session()

The active tracking session or None (QCC_TRACK=1 / QCC_TRACK=<run name> starts one on first use).

quantcore_circuits.track.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.

quantcore_circuits.track.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/<name>/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).

quantcore_circuits.track.stop() → None
quantcore_circuits.track.STATE_SCHEMA = 'qcc-state/0.1'
quantcore_circuits.track.STEPS = [('synthesis', 'LOM synthesis'), ('layout', 'Layout'), ('render', 'HFSS render'), ('simulate',...