Projects, Lattices, and Revisions

简体中文 · Previous: Interface · Next: Physics inputs

Choosing a project format

Format	Use
.vmaproj	Native working file containing the authoritative project, recoverable draft, Cell layout, study drafts, and attached evidence
studio-project/0.1 JSON	Canonical interchange project for linear optics and generic CPU tracking
studio-project/0.2 JSON	Extended project for equilibrium, matched distribution, LMA, Touschek, nonlinear, and orbit workflows

Opening JSON is an import. Save creates a .vmaproj and never overwrites that JSON. Use Export Project JSON to explicitly emit current canonical interchange data.

A .vmaproj is integrity-checked when opened. Do not rename plain JSON to .vmaproj or edit the container with an archive utility.

Building a lattice

New projects start with one START marker. In Design → Lattice:

1. Select an insertion position.
2. Click Add Element.
3. Choose type, occurrence name, Family name, and physical length.
4. Select a parameter in Properties, enter its SI value, and apply it to the draft.

Supported authoring choices are Marker/diagnostic, Drift, Quadrupole, Sextupole, Bend, RF cavity, Corrector, and rectangular/elliptical aperture. Initial values are placeholders, not matched designs: a new Quadrupole has k1=0 m⁻², and a new Bend has zero angle until configured.

Existing v0.2 authoring is deliberately bounded. Direct Bend/RF insertion or duplication is disabled because it would change ring closure or RF topology. Other lattice edits withdraw stale supplied radiation slices so that a new equilibrium run regenerates revision-bound evidence.

Sequence operations

• Up/Down moves a selected occurrence in the root line.
• Duplicate creates a new stable occurrence ID and keeps its Family reference.
• Delete removes the occurrence and is undoable; v0.2 also reconciles unused Family/aperture metadata.
• Undo/Redo operates on project edits.

Physical edits create a new content and/or physics identity. Relevant edits are blocked while an equilibrium calculation is active so changing input cannot cross an in-flight result.

Families

Select an occurrence and choose Edit Family. Studio allows a batch edit only when Family members share element type and parameter. For example, a QF k1 change is applied atomically to all members.

A Family is a design-data relationship; it is not evidence of shared power supplies, calibration, installation tolerances, or correction channels.

Cells

Shift- or Ctrl/Cmd-select at least two contiguous, ungrouped occurrences, then choose Define Cell. You can rename or ungroup it without changing physics, or duplicate/mirror-copy the whole block to create new occurrence IDs.

Mirror-copy reverses occurrence order only. It does not transform bend angles, multipole signs, corrector kicks, RF phase, hardware polarity, or alignment conventions. A v0.2 Cell containing a Bend or RF cavity cannot be copied.

Linear and circular views

The linear canvas derives position and length from authoritative SI data. Zoom affects display only. Circular Lattice projects the ordered path into a ring and can export PDF, SVG, or PNG. It is topology, not surveyed tunnel or magnet geometry.

Reviewing a revision

After a v0.2 edit, use Project → Review to compare the current state with the previous undo point: hashes, occurrence count, circumference, synchronous RF, radiation model, Cells, and all added/removed/reordered/parameter/metadata changes.

• PHYSICS REVISION CHANGED: old calculations do not identify current physics.
• PROJECT CONTENT CHANGED · PHYSICS IDENTITY UNCHANGED: explicit evidence reconciliation is still required.
• STUDIO LAYOUT ONLY: Cell layout changed; physics results remain valid.

Hands-on FODO edit

Open protocol/v0_3/fixtures/fodo-ring.studio-project.json, select a Quadrupole, make a small documented Family k1 change, and open Review Current Revision. Confirm the parameter, content, and physics identities changed; the prior result should be STALE, not deleted. Undo and confirm the original identity returns. This demonstrates revision behavior, not optics matching.