Troubleshooting and Glossary¶
简体中文 · Previous: CLI and build · Back to introduction
Common issues¶
Why can’t a new project calculate?¶
A new project intentionally has only a START marker. RF, beam, aperture, acceptance, and closed
lattice are absent. Build a positive-length lattice that passes structure and closure.
.vmaproj can save the incomplete draft; JSON export, optics, and tracking require a current
strict snapshot.
Test SSH passes, but Engine fails¶
SSH proves authentication and remote commands only. Inspect Output for executable path, protocol, source/build, permissions, CPU, and limits. Specialized pages reject an Engine that only passes the v0.1 probe.
A calculation button is disabled¶
Check, in order: correct project schema; selected target; current non-stale draft; exact target/
project/content/physics prerequisite; validity/warning gate; no conflicting one-shot calculation
or pending submission; exact v0.8/v0.9 runtime gate; and whether --offline suppressed automatic
capability negotiation.
Equilibrium/downstream results disappeared after a lattice edit¶
They were not deleted; they became old-revision evidence. A non-RF lattice edit also withdraws supplied slices. Regenerate lattice-derived slices/equilibrium and rerun downstream work.
A result vanishes after Refresh¶
Refresh reverifies files. Modified, incomplete, sidecar-less, hash-mismatched, or crossed records
are withheld as UNVERIFIED. Check the summary tooltip and Output. Do not patch records by hand.
Reconnect says credential missing¶
The bookmark exists but the OS credential token is unavailable—possibly a different OS user or host, or a locked Keychain/Secret Service. Use the original account and target. The token cannot be recovered from the project because it was never stored there.
Cancel was clicked but the job is still Running¶
Durable cancellation is cooperative: request accepted, worker confirmed, then terminal cancelled. Continued observation is correct. Detach is not Cancel.
Why can’t v0.6 Touschek submit?¶
It has a confirmed formula bug. New Submit and replay are permanently disabled. Recover old jobs only for quarantined raw evidence; use corrected v0.7 for new work.
v0.8/v0.9 reports source revision mismatch¶
Use the exact accepted builds: v0.8 5253d675…, v0.9 3b14dbcc…. Create separate targets and
configure v0.9 state/source/build fields together.
Why is some text still English in Chinese mode?¶
Protocol/schema names, formulas, units, hashes, Engine evidence, and fixed qualification values are intentionally not localized. Report an untranslated ordinary button/instruction with a screenshot and exact text if it should be added.
Can Circular Lattice or Mirror Cell drive engineering layout?¶
No. Circular Lattice is path-length topology. Mirror reverses occurrence order without field sign, polarity, RF phase, or alignment transformations.
Can RF bucket height be used as LMA?¶
No. It is a longitudinal RF search/comparison boundary. Formal LMA comes from the v0.5 local kickDelta route and remains sparse-aperture screening.
Collecting a useful issue report¶
Include Studio commit/version and OS, project schema/ID, content and physics identities, target display label plus Engine build/source (never keys or tokens), exact action/error, relevant Output lines, job/artifact IDs and hash, offline-mode status, and minimal reproduction steps.
Never include SSH private keys, passwords, reconnect tokens, or unredacted sensitive paths.
Glossary¶
| Term | Meaning |
|---|---|
| content SHA | Identity of the entire canonical project content |
| physics revision | Stable identity of physics-affecting content |
| artifact | Engine-produced result object strictly validated by Studio |
| evidence | Project, Engine, artifact, qualification, and check relationships |
| CURRENT / STALE | Whether evidence belongs to the exact open revision |
| SCREENING | Design-screening evidence below machine prediction/validation |
| one-shot | No durable reconnect guarantee after client interruption |
| durable | Remote job with stable identity, state, and reconnect path |
| target route | Local Studio SSH route label, not signed Engine identity |
| Family | Design objects eligible for an atomic shared-parameter edit |
| Cell | Named contiguous occurrence structure for Studio layout/reuse |
| RF bucket | RF longitudinal stable region, not LMA |
| DA / LMA | Transverse dynamic aperture / local momentum acceptance; not interchangeable |