vibesketch.document.qvf

QVF, the vibyverse’s file format, as vibe-sketch’s document format.

Every program of the vibe family keeps its files as QVF (the qvf repository’s spec/qvf-format-spec.md, toolkit release 0.6). A vibe-sketch QVF holds:

• a vendor section x_vibesketch.document, not critical, its namespace declared in the manifest’s extensions, with the members document (the vibe-sketch document, schema vibe-sketch/1, drawing included), species (each species’ identifiers, including those without a 3D structure) and sdf (the species as an SD file);

• a preview (spec § 5.15): a PNG of the species as the thumbnail, at most 1024 pixels on its longest side, and the scheme as SVG;

• one structure section per species that has a 3D conformer, named structure_<species id>, with its bonds and its identity (§ 5.1): charge, multiplicity, SMILES, InChI, InChIKey, a checked name and the compound number as label;

• a reaction.scheme (§ 5.14) with the steps whose reactants and products all have a structure section;

• a job.spec (§ 5.9) for each calculation on such a species, a job set whose jobs name their structure.

So any QVF reader shows the molecules, knows which is which and what the scheme and its calculations are, without knowing vibe-sketch.

A vibe-qc calculation is submitted as a QVF job container (§ 5.9, job_container()): one structure, one job.spec in the names vibe-qc’s run_job takes, the x_vibesketch.document vendor section with the whole document, and provenance.run_status: "pending". vibeqc run job.qvf updates that file in place, so the result keeps the drawing that asked for it.

Reading takes the document from x_vibesketch.document when there is one. A finished container (run_status stated) also gives back its result: the runner’s structure becomes a new conformer of the job’s species, and result says what happened: job, species, status (pending, running, converged or failed), program, program_version, method, tasks, energy (provenance.scf_energy as written, {value, units}), energy_hartree (the same in hartree when the units say so), conformer (the index of the new conformer, or None), exit_status, started_utc, finished_utc and wall_seconds. A QVF from another program, such as a vibe-qc result, contributes its structure sections as species: bonds perceived from the 3D coordinates with the charge the section states (or its SMILES implies), a 2D layout for the drawing, the coordinates kept as the conformer, and the section’s multiplicity, label and name. qvf-writer, which provides the qvf_writer and qvf_reader modules, is an optional dependency installed from the qvf checkout.

Module Attributes

EXTENSION_VERSION	The version of the x_vibesketch extension this module writes.
QVF_WRITER_MINIMUM	the qvf extra's floor and CI's QVF_TAG name the same one (tests/test_qvf.py holds them together).
MEDIA_TYPE	QVF's registered media type (the qvf repository's spec/file-type).

Functions

from_qvf(data)	The document a QVF archive holds; raises QvfError.
job_container(document, job, *[, preview])	A pending QVF job container for one vibe-qc job: what vibeqc run executes.
overwrite_refusal(data)	Why replacing this archive would lose data, or None for a native sketch.
qvf_available()	Whether qvf-writer is installed, so QVF can be read and written.
species_qvf(document, species_id, *[, ...])	One species as a QVF of its own: one structure with its identity.
stage_container(document, recipe_id, ...[, ...])	A pending QVF job container for one stage of a recipe, for one species.
to_qvf(document, *[, preview, result_selection])	The document as a QVF archive; raises QvfUnavailable.

Exceptions

QvfError	A QVF that vibe-sketch cannot read, or cannot write.
QvfUnavailable([found])	qvf-writer is not installed, or is older than the supported toolkit release.

vibesketch.document.qvf.stage_container(document, recipe_id, stage_id, species_id, *, preview=False)

A pending QVF job container for one stage of a recipe, for one species.

Like job_container(), with the job.spec spelled from the stage’s resolved run_job keywords (vibesketch.inputs.recipe): the typed fields, the runner’s tasks for the stage’s kind, and every other keyword under options by name. The structure is the species’ first conformer: the campaign’s stage driver replaces its coordinates with the accepted geometry it is staged, so the template never runs on the sketch’s coordinates where a parent stage exists. Raises QvfError for a stage the resolver refuses or a species without a conformer.

Parameters:

• document (Document)

• recipe_id (str)

• stage_id (str)

• species_id (str)

• preview (bool)

Return type:

bytes

vibesketch.document.qvf.MEDIA_TYPE = 'application/vnd.vibe-qc.qvf+zip'

QVF’s registered media type (the qvf repository’s spec/file-type).

exception vibesketch.document.qvf.QvfError

Bases: ValueError

A QVF that vibe-sketch cannot read, or cannot write.

exception vibesketch.document.qvf.QvfUnavailable(found='QVF needs qvf-writer')

Bases: QvfError

qvf-writer is not installed, or is older than the supported toolkit release.

Parameters:

found (str)

Return type:

None

vibesketch.document.qvf.from_qvf(data)

The document a QVF archive holds; raises QvfError.

A job container gives back its result too (Derivation.result, the module docstring says what it holds).

Parameters:

data (bytes)

Return type:

Derivation

vibesketch.document.qvf.job_container(document, job, *, preview=True)

A pending QVF job container for one vibe-qc job: what vibeqc run executes.

The archive holds the job’s species as its one structure (the first conformer, with its identity), one job.spec in run_job’s names (the vibeqc writer’s translation, which refuses what it cannot express), the whole document in the x_vibesketch.document vendor section, a preview of the scheme, and provenance.run_status: "pending". The runner updates the same file in place and keeps the vendor section, so the result opens back with its drawing (from_qvf()). document should already list job, so the result names it. Raises KeyError for an unknown species, QvfError for one without a conformer, the writer’s WriterRefusal for a specification it cannot express, and QvfUnavailable without qvf-writer.

Parameters:

• document (Document)

• job (Job)

• preview (bool)

Return type:

bytes

vibesketch.document.qvf.overwrite_refusal(data)

Why replacing this archive would lose data, or None for a native sketch.

Results are imported as structures, not retained as opaque payloads. Only archives reproducible from their stored sketch may be overwritten. Preview images are allowed to change; calculation data, additional metadata and unknown members require Save As. Invalid archives fail closed too.

Parameters:

data (bytes)

Return type:

str | None

vibesketch.document.qvf.qvf_available()

Whether qvf-writer is installed, so QVF can be read and written.

Return type:

bool

vibesketch.document.qvf.species_qvf(document, species_id, *, document_id=None)

One species as a QVF of its own: one structure with its identity.

This is the file a 3D viewer opens. The charge and multiplicity are on the structure section and, as the spec asks of a single structure, in provenance too. Raises KeyError for an unknown species, QvfError for one without a conformer.

Parameters:

• document (Document)

• species_id (str)

• document_id (str | None)

Return type:

bytes

vibesketch.document.qvf.to_qvf(document, *, preview=True, result_selection=None)

The document as a QVF archive; raises QvfUnavailable.

Parameters:

• document (Document)

• preview (bool)

• result_selection (Selection | None)

Return type:

bytes