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 which path changes. 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 .bak is overwritten) unless backup is false — the autosave snapshot is itself a backup, so it keeps none of its own. The .bak is 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 leave path missing. A failure after the .bak is 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 .asymp file path.

asymmetry.core.project.prepare_project(state, *, checkpoint=<function <lambda>>)[source]

Migrate/retry once, then prepare detached canonical project owners.

checkpoint may 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

asymmetry.core.project.schema.validate(data)[source]

Validate canonical owned declarations without resolving external inputs.

asymmetry.core.project.schema.migrate_to_current(data)[source]

Apply each version transition once, returning a current-schema copy.

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_numbers

Ordered 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_run

Map from synthetic group key → source run number ("groups" series only).

param_roles

Per-parameter classification: "global", "local", or "fixed".

nuisance_params

List of per-(run, group) nuisance parameter names excluded from trending ("groups" series only).

results_by_run

Per-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
available(index)[source]

Whether this input may be consumed by the current operation.

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.

dataset_paths()[source]

Accepted candidate targets, keyed by the existing current dataset owner.

check_constituents(index, datasets)[source]

Verify consumed constituent captures; preserve their ordered selections.

report()[source]

Publish statuses and owner addresses without locators or private diagnostics.

__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 full run.grouping payload. 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_resolver resolves the reference_run background mode’s reference histograms + good-frame scale (the caller supplies one backed by a loaded-dataset registry). It is only consulted by a per_run_estimate alpha policy paired with reference_run background, 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.