Xsuite Import and Historical Experiment Migration

简体中文 · Previous: Results and evidence · Next: Engine capabilities

Structural Xsuite Line import

vm-accelerator-studio-import-xsuite projects a resolved Xsuite Line JSON into .vmaproj and packages a canonical v0.2 structural project, import evidence, exact source bytes, and a read-only native Xsuite binding. The binding cross-checks the source entry, byte count, SHA-256, Xtrack version, element inventory, and project identity. A separately reviewed expected SHA-256 is mandatory; mismatch produces no output.

./build/dev/vm-accelerator-studio-import-xsuite \
  --input resolved-line.json \
  --output imported-ring.vmaproj \
  --project-id imported-ring \
  --display-name "Imported ring structural projection" \
  --expected-sha256 <reviewed-source-sha256> \
  --project-json imported-ring.studio-project.json \
  --evidence-json imported-ring.import-evidence.json \
  --native-binding-json imported-ring.native-xsuite-binding.json

The bounded projection accepts Marker, Drift, FirstOrderTaylorMap (length only; matrix retained in source evidence), Quadrupole, Sextupole, Bend (including optional k1), LimitRect, LimitEllipse, and active or inactive Cavity. A dipole-only Multipole becomes a physical corrector using the Xsuite convention dpx=-knl[0], dpy=ksl[0]; higher-order strengths remain only in the embedded source. Multiple cavities become separate RF systems with unspecified roles instead of invented main/harmonic ownership. Other serializable Xsuite classes appear as labelled length-preserving drifts or zero-length markers while their exact definitions remain authoritative in the read-only source. Nonzero relative multipoles use the same source-only rule instead of blocking packaging. Degenerate rectangle bounds and cavity fields outside the portable RF vocabulary also become native-only. Inconsistent ellipse axes and malformed maps are rejected.

This is structural browsing/editing, not Xsuite calculation equivalence. A FirstOrderTaylorMap is represented geometrically as a drift, while nonzero bend edge angles and higher-order Multipoles remain source-only, so calculationEquivalentToXsuiteSource=false remains mandatory. Studio shows a Native Xsuite · read-only source badge and marks the projection detached after any portable edit. Exact Engine loading must use the three-way hash-bound project, descriptor, and original source; the projected lattice must never be submitted as an equivalent replacement.

The Screening Study Validate project stage selects Studio–Engine v0.11 for an attached native package. It negotiates ValidateNativeXsuite, uploads all three exact entries on framed stdin, and checks canonical load evidence, every returned identity, ordered occurrence count, and source/runtime Xtrack versions. Studio automatically selects a compatible exact-source route where one exists; portable-only routes remain blocked instead of silently calculating from the non-equivalent projection. A successful v0.11 gate is an input-load result, not a physics result or machine prediction.

For an attached, unedited native package, Equilibrium uses the separate v0.12 original-Line operation. Distribution uses v0.13: after you choose the occurrence and bounded draw settings, one operation rechecks the package binding, recomputes native equilibrium, derives local optics from the same authoritative original Line, and opens the verified particle result. Studio retains both returned artifacts. This is linear, planar, uncoupled screening; its longitudinal Gaussian is not RF-separatrix conditioned and it is not a machine prediction.

Radiation slices uses v0.15. It rechecks the three-way package binding, reconstructs the authoritative original Line, evaluates planar 4D optics at thick radiating-element midpoints, and requires the frozen 8/32/128 I1–I5 convergence gate before retaining radiation-slice-model/0.2. This is an independent diagnostic; Studio does not claim that v0.12 equilibrium consumes it. Thin radiating kicks, skew/strong coupling, unsupported fields, and machine-prediction claims fail closed.

Optics uses v0.14 and evaluates conventional 4D x/y Twiss on the exact original Line. It returns one entrance row per authoritative occurrence plus the root-line exit, rejects coupling at or above c_minus=1e-6, and remains ideal-lattice SCREENING.

Local momentum acceptance uses v0.16 to track sparse positive/negative boundaries at twelve deterministic observation locations on the exact Line. It is coordinate-space screening, not a complete machine acceptance map.

CPU tracking, Nonlinear Dynamics, and Errors & Orbit Correction use the automatic v0.17 exact-source route. Tracking uses an explicitly synthetic fixed coordinate-space Gaussian ensemble because the package does not contain an authoritative bunch distribution. Nonlinear dynamics returns 256/512-turn boundary, FFT tune and diffusion evidence, not machine dynamic aperture. Orbit correction uses deterministic VIRTUAL BPM and corrector locations; it makes no claim about installed devices or commissioning performance. The user never chooses a protocol or Engine version.

Historical Experiment Migration

Open an audited historical-studio-migration-audit/0.2 catalog from File → Import → Open historical migration catalog…. The workspace can filter by tier/status/ feature/duplicate/text, switch unique contents versus all file instances, map logical roots, verify exact size/SHA, show YAML read-only, attach evidence to .vmaproj, start manual reconstruction, or send historical intent/evidence to the Screening Study banner.

Mapping and attaching example

For catalog paths under ssmb-new-steps/... and local root /data/ssmb-new-steps:

1. Open the catalog and choose Map Sources.
2. Map logical ssmb-new-steps to /data/ssmb-new-steps.
3. Select a record and Verify Selected.
4. Only an exact verified size/hash becomes attachable.
5. Open or save the active project as .vmaproj, then Attach Evidence.
6. Studio atomically saves, reopens, and verifies the package; physics revision does not change.

Mappings stay in local settings. Absolute/traversing paths, .., symlink escape, missing files, or hash mismatch fail closed.

Migration tiers

• Bounded migration: the reviewed catalog proves a narrow safe mapping.
• Structural project + external experiment: structure is retained while experiment semantics remain external.
• Evidence/manual reconstruction: exact source is attached and the user explicitly rebuilds a current project.

Studio never infers circumference, harmonic, beam, RF, or lattice from filenames or old scalars; renames historical GPU work as CPU; relabels DA/FMA as generic tracking; or promotes historical results to the current revision.

The catalog's Import Xsuite action remains disabled when only a logical path exists without an independent expected SHA. A hash computed from the same local file is not independent review; after obtaining one, use the standalone structural importer.