Project persistence
The asymmetry.core.project module provides versioned JSON project files
(.asymp) that capture the full GUI session — loaded datasets, panel
settings, fit configuration, and Fourier settings — so you can close the
application and resume exactly where you left off.
Raw data arrays are not embedded in the project file; instead, source file paths are stored and the files are reloaded on open. This keeps project files small and avoids duplicating data.
The schema version embedded in every .asymp file is independent of the
package version, so project files survive package upgrades as long as the
schema version is supported.
Public API
- asymmetry.core.project.load_project(path)[source]
Load, migrate, and prepare project content without resolving external inputs.
- asymmetry.core.project.save_project(state, path, *, backup=True)[source]
Write a project state dict to a JSON file, atomically (D9).
The JSON is serialised to a temporary file in the destination’s directory, flushed and
fsync``ed, then swapped into place with ``os.replace— the single moment at whichpathchanges. A crash or exception at any point before it leaves the previous file byte-for-byte intact and removes the temp file.If a file already exists at
path, its previous contents are kept alongside the new one as<path>.bak(one generation: an older.bakis overwritten) unless backup is false — the autosave snapshot is itself a backup, so it keeps none of its own. The.bakis made by hard-linking the existing target (copying it where the filesystem refuses links), never by moving it: the target must stay in place until the replace, so a failure in between can never leavepathmissing. A failure after the.bakis written leaves it holding the previous contents, which is exactly what the still-intact target holds.- Parameters:
state (dict) – Project state as returned by
MainWindow.collect_project_state().path (str or Path) – Destination
.asympfile path.
- asymmetry.core.project.prepare_project(state, *, checkpoint=<function <lambda>>)[source]
Migrate/retry once, then prepare detached canonical project owners.
checkpointmay raise cancellation between declarations. No source file is opened and no execution attribution is changed by preparation.
- asymmetry.core.project.load_prepared_project(path, *, checkpoint=<function <lambda>>)[source]
Read project JSON and prepare its owned declarations without acquisition I/O.
- class asymmetry.core.project.PreparedProject(state, profiles, model, studies, groupings, sources=())[source]
Detached canonical JSON and its existing domain owners, ready to apply.
Applying transfers ownership to the session; the objects are not a reusable snapshot of widgets or a certification of external source contents.
- state
- profiles
- model
- studies
- groupings
- sources = ()
- __init__(state, profiles, model, studies, groupings, sources=())
- exception asymmetry.core.project.ProjectValidationError[source]
Malformed owned project content, with its serialized field location.
- exception asymmetry.core.project.UnsupportedSchemaVersion[source]
Raised when a project file uses an unsupported schema version.
- asymmetry.core.project.CURRENT_SCHEMA_VERSION = 40
int([x]) -> integer int(x, base=10) -> integer
Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.__int__(). For floating-point numbers, this truncates towards zero.
If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by ‘+’ or ‘-’ and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer literal. >>> int(‘0b100’, base=0) 4
The storage schema is
40. Wizard payload, workdir, effective-recipe, and scientific computation versions are separate authorities.
Preparation and application
load_project returns canonical JSON-compatible state. prepare_project
accepts a complete versioned state dictionary; load_prepared_project reads a
file and returns the same prepared form. Each performs the owning migrations and
pending-model retry, then constructs existing grouping profiles, representations,
series, joint fits, and parameter studies. Caller input remains unchanged. A
checkpoint callback can raise cancellation between declarations.
PreparedProject holds the detached canonical dictionary and existing domain
owners. Application transfers these objects to the receiving session; it is not
a reusable widget snapshot. No runtime object is inserted into the serialised
JSON. ProjectModel.from_project_state uses this same project boundary.
Standalone ProjectModel.from_dict reads the model-only codec rather than a
complete project file.
Malformed owned containers, duplicate identities, and required live links raise
ProjectValidationError with a field location before GUI state changes. External
file/model availability, stale historical membership, draft fit forms, and original
constraint/uncertainty archives remain separate from structural validity. No load,
save, or preparation assigns current execution to an old or unknown result.
The GUI prepares before replacing the active session. Acquisition restoration can still be cancelled after application begins, retaining a marked partial load with a save confirmation. See Project files for the exact UI contract.
Canonical file contents
A UTF-8 JSON object contains schema_version and a datasets array. Dataset
rows have integer run_number identities and string source locators. Optional
combined_datasets rows name their integer identity and ordered declared
sources. Project-level grouping_profiles retain grouping and calibration policy
owners; runs name a profile or retain released per-run overrides.
The optional registries are batches (fit series), data_groups,
joint_fits, global_fit_studies, and active_series. A dataset’s
representations map is keyed by RepresentationType values, including
time_fb_asymmetry, time_groups, time_maxent_recon, freq_fft, and
freq_maxent. Each representation retains its recipe, result metadata, trend
state, and single_fits sets keyed by projection ("" for the default).
Each set contains fits and an open_id selecting a saved fit.
fit_states holds the time and frequency editor forms separately. Browser,
plot, Fourier, MaxEnt, and analysis-window containers retain presentation state.
Unknown user metadata is preserved. A future storage schema is rejected, rather
than interpreted as a known format.
Schema utilities
FitSeries (batches)
The top-level batches list stores
FitSeries objects that
accumulate results across multiple members.
Key fields:
member_kind"runs"for F-B asymmetry / FFT batch fits;"groups"for multi-run grouped time-domain fits.member_run_numbersOrdered list of member keys. For
"runs"series these are real run numbers; for"groups"series they are synthetic negative keys of the form-(source_run * 1000 + group_index).member_source_runMap from synthetic group key → source run number (
"groups"series only).param_rolesPer-parameter classification:
"global","local", or"fixed".nuisance_paramsList of per-(run, group) nuisance parameter names excluded from trending (
"groups"series only).results_by_runPer-member fit result summaries (parameter values, uncertainties, χ²) used to drive the Fit Parameters trending panel.
Acquisition declarations
PreparedProject.sources is an ordered immutable inventory assembled at the
same preparation boundary as dataset, grouping, profile, calibration, and result
owners. It does not read acquisitions. Optional source_binding fields preserve
expected and observed content facts independently; their absence is unknown.
Core verify_sources consumes these declarations and caller-resolved candidates
without applying state. See Input/output and Project files for
outcomes and the limits of current project reopening.
Verified source application
- asymmetry.core.project.verify_project_sources(prepared, project_path, *, candidates=None, checkpoint=<function <lambda>>, progress=<function <lambda>>)[source]
Verify bytes and bind following-profile requests to actual acquired fingerprints.
Profile selection uses the existing loader only when following inputs need it. Decoded facts remain detached, and a capture mismatch aborts before application.
- asymmetry.core.project.apply_source_decisions(verification, *, replacements=(), checkpoint=<function <lambda>>)[source]
Accept only explicitly selected current owners from this verification request.
Unselected changed inputs remain unavailable (history only). Matched locators may move, legacy expectations remain unknown, and historical records stay intact. Callers must compare actual acquisition capture before using accepted inputs. No reduction, model fitting, calibration, or file writes occur here.
- class asymmetry.core.project.ProjectSourceApplication(prepared, verification, replacements)[source]
Detached decisions and accepted read facts for one deliberate project application.
- prepared
- verification
- replacements
- input_for(address)[source]
Return the verification index for a current owner, or None for absent provenance.
- capture_matches(index, observed)[source]
Legacy unknown capture stays unverified; accepted known content must match.
- check_capture(index, observed)[source]
Reject changed captures and unknown capture for accepted known inputs.
- reference_inputs(payload)[source]
Carry the exact prepared reference owners through mutable legacy restoration.
- check_reference_capture(indices, reference)[source]
Compare actual reference counts against the pre-resolution accepted request.
- checked_samples(loaded)[source]
Exclude changed captures before any acquired facts can heal project policies.
- check_constituents(index, datasets)[source]
Verify consumed constituent captures; preserve their ordered selections.
- __init__(prepared, verification, replacements)
SourceDeclaration.owner carries its prepared address and whether it represents
an active input. Verification remains read-only. Explicit replacements name source
indices from that complete request, not filenames or equal digest values.
Historical owners cannot accept replacements. Unselected changed inputs remain
unavailable, while matched and legitimate legacy-unknown inputs continue normally.
The operation returns detached project owners; it does not mutate the supplied
project, fit a model, or write a file.
from asymmetry.core.project import (
load_prepared_project, verify_project_sources,
apply_source_decisions, save_project,
)
project = "session.asymp"
prepared = load_prepared_project(project)
verified = verify_project_sources(prepared, project)
# Inspect verified.facts and explicitly choose the current owner indices to replace.
application = apply_source_decisions(verified, replacements=[0])
print(application.report())
save_project(application.prepared.state, "accepted.asymp")
report() omits source/candidate locators and private diagnostic text. Local
verification facts retain those fields for meaningful source selection. A caller
that consumes acquisitions must read candidate_file and use check_capture
to compare the actual loader capture with the accepted observation. GUI restoration
uses this guard before applying acquired timing or reductions. Number-only legacy
reference requests retain their existing live-input resolution.
The API/CLI action updates source expectations; recomputation is performed through the receiving operation’s existing reduction workflow. It is not a general project fitting engine, an old-code replay, or a raw-data archive.
verify_project_sources returns ProjectSourceVerification with the rebound
prepared owners and ordered facts. Following-profile reference requests
are classified using the actual instrument and histogram count through the normal
loader on the cancellable verification worker. Authoritative per-run overrides
leave their base profiles historical. Unused or disabled reference settings do not
request replacement. Capture disagreement aborts before project application.
Profiles
- class asymmetry.core.project.profiles.GroupingProfile(name, fingerprint, active=True, color=None, groups=<factory>, group_names=<factory>, included_groups=<factory>, forward_group=1, backward_group=2, projections=<factory>, excluded_detectors=<factory>, alpha_policy=<factory>, deadtime_policy=<factory>, background_policy=<factory>, t0_policy=<factory>, good_window_policy=<factory>, beta_policy=<factory>, calibration_records=(), projection_alpha_policies=<factory>, binning=<factory>, period_mode=None, extra=<factory>)[source]
A named, shareable set of grouping settings for one fingerprint.
Holds only the shareable settings (see the module docstring’s classification table). It is applied to a run via
resolve_effective_grouping(), which merges these settings with the run’s file-derived facts to produce a fullrun.groupingpayload. The binning spec records base bins (merge=1); CLI and display merges are applied to those bins as separate operations.
- asymmetry.core.project.profiles.resolve_effective_grouping(profile, run, *, reference_resolver=None, timing_search=None)[source]
Merge profile with run’s file-derived facts into a grouping payload.
The returned reduction payload combines shareable settings with this run’s timing, window, exposure, detector tables and selected period. Computed policies use these effective inputs without modifying the acquired run.
reference_resolverresolves thereference_runbackground mode’s reference histograms + good-frame scale (the caller supplies one backed by a loaded-dataset registry). It is only consulted by aper_run_estimatealpha policy paired withreference_runbackground, so the estimate balances the same background-subtracted counts the reduction will; an unresolved requested reference makes the estimate unavailable.Authored membership is preserved; reduction rejects invalid or absent channels.