vibe-sketcherDocumentation

vibesketcher.document.diffraction_store

Measured and calculated powder patterns stored in a document, with undo (#207).

store_measured() keeps a pattern read by vibesketcher.document.measured_patterns.read_measured() (digest of the original bytes, stated axis, intensity unit and wavelength, instrument fields and header lines as given, and the points); store_calculated() keeps a vibesketcher.document.diffraction.calculate() result with its structure’s digest. Both are one edit checked against the document revision; undo() removes the last stored pattern and remove() any one. The records live in the document’s diffraction_patterns list (vibesketcher.document.diffraction_model.DiffractionPattern), so they travel in the .vsk file and the QVF document section; the QVF writers also add a non-critical vendor section x_vibesketch.diffraction (QVF_KIND), because QVF has no diffraction contract, and from_qvf() reads it.

A calculated pattern is stale once its structure changed or was removed. stored() marks it; overlays, comparisons and CSV exports refuse it (re-calculate and store again). Overlays and comparisons of stored patterns use the same wavelength rule as vibesketcher.render.diffraction: a measured 2theta axis is compared in 2theta only at the calculated wavelength. Nothing here fits or refines; the display scale is not a fit.

Functions

as_calculated(document, identifier)

A current stored calculated pattern in the shape calculate() returns.

as_measured(pattern)

A stored measured pattern in the shape read_measured() returns.

comparison(document, measured, calculated[, ...])

Which reflections fall in the measured range, on one axis, with both provenances.

fresh(document, identifier)

A stored pattern that still matches its structure; a stale one is refused.

from_qvf(data)

The stored patterns of a QVF's x_vibesketch.diffraction section ([] when absent).

get(document, identifier)

The stored pattern identifier; KeyError when there is none.

overlay(document, calculated[, measured, ...])

The overlay figure of stored patterns (no re-upload).

pattern_csv(document, identifier)

A stored pattern as CSV with a provenance header; a stale calculated one is refused.

qvf_members(document[, structures])

The x_vibesketch.diffraction members, or None when nothing is stored.

record(document, identifier)

One stored pattern in full (points, reflections), marked stale or current.

remove(document, identifier, *[, revision])

The document without the stored pattern identifier (stale or not).

store_calculated(document, result, *[, ...])

Keep a calculated pattern of one of the document's structures, with its digest.

store_measured(document, measured, *[, ...])

Keep a read_measured() result in the document; returns (document, summary).

stored(document)

Summaries of every stored pattern, oldest first.

summary(document, pattern)

A stored pattern without its points or reflections, marked stale or current.

undo(document, *[, revision])

Remove the last stored pattern; refused for a calculated one gone stale since.

Exceptions

DiffractionStoreRefused(code, message)

A stored-pattern edit or read cannot be done faithfully; code says why.

exception vibesketcher.document.diffraction_store.DiffractionStoreRefused(code, message)[source]

Bases: ValueError

A stored-pattern edit or read cannot be done faithfully; code says why.

Parameters:
Return type:

None

vibesketcher.document.diffraction_store.store_measured(document, measured, *, revision=None, identifier=None, label=None)[source]

Keep a read_measured() result in the document; returns (document, summary).

Parameters:
Return type:

tuple[Document, dict[str, Any]]

vibesketcher.document.diffraction_store.store_calculated(document, result, *, revision=None, identifier=None, label=None)[source]

Keep a calculated pattern of one of the document’s structures, with its digest.

Parameters:
Return type:

tuple[Document, dict[str, Any]]

vibesketcher.document.diffraction_store.summary(document, pattern)[source]

A stored pattern without its points or reflections, marked stale or current.

Parameters:
Return type:

dict[str, Any]

vibesketcher.document.diffraction_store.stored(document)[source]

Summaries of every stored pattern, oldest first.

Parameters:

document (Document)

Return type:

list[dict[str, Any]]

vibesketcher.document.diffraction_store.get(document, identifier)[source]

The stored pattern identifier; KeyError when there is none.

Parameters:
Return type:

DiffractionPattern

vibesketcher.document.diffraction_store.record(document, identifier)[source]

One stored pattern in full (points, reflections), marked stale or current.

Parameters:
Return type:

dict[str, Any]

vibesketcher.document.diffraction_store.fresh(document, identifier)[source]

A stored pattern that still matches its structure; a stale one is refused.

Parameters:
Return type:

DiffractionPattern

vibesketcher.document.diffraction_store.remove(document, identifier, *, revision=None)[source]

The document without the stored pattern identifier (stale or not).

Parameters:
Return type:

Document

vibesketcher.document.diffraction_store.undo(document, *, revision=None)[source]

Remove the last stored pattern; refused for a calculated one gone stale since.

Parameters:
Return type:

Document

vibesketcher.document.diffraction_store.as_measured(pattern)[source]

A stored measured pattern in the shape read_measured() returns.

Parameters:

pattern (DiffractionPattern)

Return type:

dict[str, Any]

vibesketcher.document.diffraction_store.as_calculated(document, identifier)[source]

A current stored calculated pattern in the shape calculate() returns.

Parameters:
Return type:

dict[str, Any]

vibesketcher.document.diffraction_store.overlay(document, calculated, measured=None, options=None, fmt='svg', *, dpi=300)[source]

The overlay figure of stored patterns (no re-upload).

calculated is a stored calculated pattern id or a fresh calculate() result; measured a stored measured pattern id. The wavelength rule and the formats are those of vibesketcher.render.diffraction.overlay_figure().

Parameters:
Return type:

bytes

vibesketcher.document.diffraction_store.comparison(document, measured, calculated, axis='two_theta_deg')[source]

Which reflections fall in the measured range, on one axis, with both provenances.

A pairing record, not a fit: no agreement factor is computed, and agreement would not show the structure is unique. Refused like the overlay when a 2theta comparison has a mismatched or unstated measured wavelength.

Parameters:
Return type:

dict[str, Any]

vibesketcher.document.diffraction_store.pattern_csv(document, identifier)[source]

A stored pattern as CSV with a provenance header; a stale calculated one is refused.

A measured pattern writes its points (x, intensity and esd when present); a calculated one its profile curve when stored with one, else its reflection list.

Parameters:
Return type:

str

vibesketcher.document.diffraction_store.qvf_members(document, structures=None)[source]

The x_vibesketch.diffraction members, or None when nothing is stored.

structures limits the section to the calculated patterns of those structures (a single-structure QVF); measured patterns then stay out.

Parameters:
Return type:

dict[str, Any] | None

vibesketcher.document.diffraction_store.from_qvf(data)[source]

The stored patterns of a QVF’s x_vibesketch.diffraction section ([] when absent).

Parameters:

data (bytes)

Return type:

list[DiffractionPattern]