Physics Inputs

简体中文 · Previous: Projects and lattices · Next: Engine connection

Physics Inputs places editable values, read-only derived values, missing data, and the physical consequence of each absence on one page. It is not merely a form-completeness check: Engine validation of the exact project remains the final calculation gate.

v0.1 and v0.2

For a v0.1 project, Studio creates a deterministic v0.2 authoring draft and lists fields that cannot be derived. Exporting the draft preserves every absence; it does not fill zeros or use generic machine defaults.

For a reviewed v0.2 project, RF/equilibrium inputs can be edited and applied as one atomic revision.

Editable fields

Field	Rule	Meaning
Main harmonic h	Positive integer	Main RF harmonic
Total RF voltage [V]	Positive finite value	Authoritative total voltage
RF reference phase [rad]	Finite value	Reference phase
Synchronism tolerance	0 < value ≤ 1e-3	Relative RF synchronism tolerance
Longitudinal range [σ]	≥ 3	Equilibrium screening range

fRF is derived from h, reference-particle velocity, and circumference. It is read-only. When you click Apply as new v0.2 revision, the inputs and linked cavity values update together.

Reading the readiness table

Rows show a path, state, and consequence. Common states include Present, Absent, Blocked, Preserved, Screening only, and Available after negotiation.

Important dependencies:

• no synchronous RF blocks longitudinal equilibrium;
• no radiation model blocks radiation integrals and damping;
• no equilibrium model blocks equilibrium evaluation;
• bunch population/fill pattern may not block single-particle equilibrium, but they block credible intensity, collective, or lifetime work;
• missing geometric vertical emittance is not guessed from the horizontal plane; matched and Touschek workflows can require it explicitly;
• physical-aperture provenance is not DA or local momentum acceptance;
• RF bucket height is never substituted for local momentum acceptance.

Two equilibrium-input routes

Studio chooses automatically:

1. Supplied-model v0.2: the project already carries complete, consistent radiation slices; evaluate equilibrium-result/0.1.
2. Lattice-derived v0.3: generate project-bound 8/32/128 converged radiation slices, then evaluate equilibrium-result/0.2.

The lattice-derived result is the standard prerequisite for matched distribution and LMA. A non-RF lattice edit withdraws supplied slices rather than reusing old optics.

Example: update RF without editing frequency

Open protocol/v0_3/fixtures/fodo-ring.studio-project.json, enter Design → Physics Inputs, and note Derived fRF. Change the main harmonic or voltage within reviewed limits, apply the new revision, and inspect Project → Review. If harmonic changed, confirm fRF was recomputed; do not edit cavity frequency independently. Rerun equilibrium because the previous result is stale.

Values must come from an RF design review. Do not enter arbitrary data merely to enable a button.

Exporting a v0.2 draft

For an eligible v0.1 project, Export deterministic v0.2 draft… preserves deterministic content/physics identities, known inputs, every unresolved input and its reason, and original aperture/acceptance provenance. It is an authoring artifact, not an equilibrium result.