Equilibrium, Matched Distribution, and Local Momentum Acceptance

简体中文 · Previous: Optics and tracking · Next: Screening Study

These are the main calculation chain for v0.2 projects. Screening Study is the recommended way to follow dependencies, although each workflow can also be started from Calculate.

flowchart TD
    A[Validate exact v0.2 project] --> B[Generate 8/32/128 radiation slices]
    B --> C[Evaluate radiation–RF equilibrium]
    C --> D[Matched distribution v0.4]
    C --> E[Local momentum acceptance v0.5]

Matched distribution and LMA are independent siblings. Matched particles are not LMA input.

1. Radiation–RF equilibrium

Open a v0.2 project, select a target, and run the action from Physics Inputs or Calculate.

• With qualified supplied slices, Studio chooses the supplied-model route.
• Otherwise Engine first produces 8/32/128 converged radiation-slice evidence and computes equilibrium from I1–I5.

The result shows energy loss, natural horizontal emittance, energy spread, bunch length, synchrotron tune/frequency, RF bucket height, damping partitions/times, and model/input/Engine evidence. valid_with_warnings remains a warning state.

RF bucket height is an RF longitudinal boundary, not local momentum acceptance.

2. Generate a matched distribution

The exact target/project/content/physics revision must have a locally verified, warning-free valid, lattice-derived equilibrium-result/0.2. Supplied-model result/0.1 is ineligible.

Choose Generate Matched Distribution…:

Field	Default/choice
Generation occurrence	An occurrence in the current ordered lattice
Position	Center, or Entrance/Exit
Macro-particle count	1,024; allowed 128–8,192
Deterministic seed	20,260,817; at most 2^53−1
Missing geometric εy	Shown only if absent; example default 2e-11 m
Missing bunch population	Shown only if absent; example default 6.24e9

Engine computes local Twiss, εx, dispersion, and closed orbit; Studio does not accept client overrides for them. The result shows x–px, y–py, and ζ–δ, target covariance, finite-sample statistics, and RF-separatrix conditioning.

It remains SCREENING · LINEAR · PLANAR · UNCOUPLED. εy and population must come from controlled inputs; dialog defaults are examples, not machine parameters.

3. Evaluate local momentum acceptance

Choose Evaluate Local Momentum Acceptance. Studio selects qualified lattice-derived equilibrium evidence for the exact route/revision and starts a one-shot CPU workflow with a maximum 1,800-second deadline.

The plot defaults to positive and negative local kickDelta at occurrence entrances. Optional absolute δ and δsync sawtooth overlays are coordinate evidence. RF bucket height is a dashed search/comparison boundary only. Click a point for uncertainty, limiting loss, turn/location, and convergence evidence.

Permanent boundaries include SPARSE APERTURE, PHYSICAL APERTURE INCOMPLETE, NOT DESIGN QUALIFIED, and NOT A LIFETIME RESULT.

End-to-end example

1. Open protocol/v0_3/fixtures/fodo-ring.studio-project.json.
2. Select an accepted target supporting v0.3–v0.5.
3. Generate lattice slices and evaluate equilibrium.
4. Confirm schema 0.2, lattice-derived provenance, current revision, and validity.
5. Generate 1,024 particles at Center with a fixed seed.
6. Run LMA and click a limiting positive-branch point.
7. Open Screening Results and inspect radiation, equilibrium, matched, and LMA groups.

If a prerequisite is absent, Studio fails closed instead of selecting a similar older result.