PF Simulation graphical workbench

Configuration correction in GUI1.3.1: use the canonical spacetime field. The resolved-settings summary distinguishes the configured model from an explicit run override. Legacy-only aliases migrate; conflicting duplicates fail before execution. Derived comparison fields are read-only. The raw model controls and QKD inheritance behavior are documented in RELEASE_NOTES_R16.md. Completed simulation and comparison branches retain effective_config.json with a manifest byte hash.

The complete illustrated reference is Chapter 22 of documentation/PF_Simulation_Complete_End_User_Manual.pdf; Chapter 32, ISAES: from workflow results to evidence, covers scientific reporting and optional report discussions. Both the manual and the current ISAES guides are available from Documentation. Consult the package manifest for the installed release identifier.

Choose standalone or hosted access

The desktop launcher opens the standalone workbench, with local files and local job execution. The separately deployed SaaS application requires a signed-in account and a selected organization/project before opening the shared workbench. See SAAS_USER_GUIDE.md (source package reference: SAAS_USER_GUIDE.md) and manual Chapter 27 for hosted accounts, input uploads, permissions and job behavior.

Instructions below concerning the launcher, absolute local input paths, gui_runs and stopping the local server apply to standalone use. In SaaS, replace local input paths with authorized project assets, inspect the selected project's runs, and use the deployment's account and resource policies. Hosted execution preserves the same scientific configuration and state conventions.

Open standalone without a command line

1. Extract the complete package into a writable folder.
2. Double-click PF_Simulation_GUI.pyw. On Windows, Launch_PF_GUI.vbs is the alternative launcher.
3. In the launcher, choose Check environment. If dependencies are missing, choose Install/update dependencies, read its log, then check again.
4. Choose Open GUI. Keep the launcher/server running while working in the browser.

An installed supported Python with Tkinter is required. Python 3.8 remains supported. Installation uses the package's local environment rather than upgrading the system Python. Downloading dependencies and online tracking data requires network access. The desktop launcher is a local service. Public multi-user operation uses the separate SaaS application and its deployment configuration.

When updating the application, finish or cancel active jobs and close the launcher first. Retain the existing gui_runs directory if you want its saved history in the updated installation. Copy completed job directories into the updated package's gui_runs directory when installing into a new folder; retain their contents and job identifiers together. Keep a backup before copying, and do not overwrite a different job with the same identifier. Reopening a saved result uses the updated display without rerunning its scientific calculation or rewriting its evidence files. The UTC overview also reads existing saved comparison segments; those runs do not need to be recomputed.

Configure

Choose Study purpose, Physical topology, and Starting configuration before detailed edits. Mission workflows expose a separate Quantum experiments panel; published references show Reference applicability, and standalone experiments show Apparatus scope. Available topologies reflect each workflow's scientific applicability. SatQuMA numerical references, laboratory BBM92, satellite-to-ground Jinan-1, Micius references and mission simulation are distinct analyses.

Selecting a starting configuration loads its natural topology. Incompatible topology conversions are disabled with an explanation, including Earth-orbit versus numerical-plane apparatus and conversions that remove a required common receiver or relay. All starting configurations remain available so another study can be selected explicitly. This behavior is shared by standalone and SaaS workbenches.

Current inputs identifies the active workflow and, where supplied, its integration and experiment. The starting configuration records the preset used as a starting point. After edits or an import, the workbench identifies whether the inputs still match that preset and hides its specific notes when they no longer describe the current configuration. Execution uses the current inputs; a retained preset name does not replace them. Review the complete Fields/JSON configuration before submitting.

• Run options controls the execution: scenarios, sampling, controls, live behavior and related workflow options.
• Fields edits typed nested configuration values. Search keys, expand objects, edit arrays and use optional-section templates.
• JSON exposes the complete engine configuration. Supported optional keys can be added without a special GUI release. Invalid types/ranges still fail engine validation.
• Import loads JSON; Export saves the current editable configuration.
• Validate configuration checks the request. Run simulation submits it.

Validation reports known apparatus restrictions for selected mission quantum experiments before submission, including the affected scenarios. Review these warnings before running: intentional studies of unavailable protocols may continue after confirmation, and the engine can report NOT_APPLICABLE for those cases. Editing inputs clears the old warning display and requires fresh validation. These checks do not establish numerical accuracy or live tracking connectivity.

If configuration edits, another preset selection or an account/project change occur while validation is pending, its late response cannot overwrite the current inputs or submit the old request. Validate again before running.

Relative packaged input paths resolve against the package directory. A browser upload does not reliably identify the original configuration directory. After importing a configuration from elsewhere, use the intended absolute local paths or package-relative inputs. Review the saved resolved configuration.

Launch live tracking and the orbit viewer

For live scenario calculations, choose the Simulation · quantum states, timing and QKD workflow and a Current UTC tracking starting configuration. The choices include flat SR, static GR, phase noise, and static GR and phase noise. Confirm Repeat at current UTC in Run options, inspect Live updates and the update interval, then select Run simulation. These presets already run live SGP4 predictions; they are not a separate connection waiting to be launched from the results page.

Each live simulation update evaluates one epoch at [0, 0] for its freshly captured UTC epoch. Live updates sets the number of updates; configured Steps, Time interval and the Epoch count override do not set that count. The inactive epoch-count override is disabled while live updates are enabled, and its stored value is retained for non-live simulations. Orbit comparison has its own per-update duration and scenario grid; this one-epoch rule applies to live scenario simulation.

For the satellite trajectory viewer:

1. Open the GUI from the desktop launcher, then select Orbit viewer in the header. This opens the saved model-versus-SGP4 orbit-comparison display.
2. To create a live comparison, return to Configure and select Load live orbit comparison preset. This loads a new Orbital mechanics · matched SGP4 comparison study after confirmation; it does not convert or preserve the complete current mission. It replaces topology, ground stations, satellite IDs, quantum settings, other configuration values, run options and run name. Only the effective flat-SR/static-GR choice is carried over, read from the current Fields/JSON inputs with an explicit Spacetime run override taking precedence. Export first to keep the current design. Invalid JSON, unsupported models and numerical-plane apparatus cannot silently fall back to an Earth-orbit example. Choose an Earth-orbit starting configuration explicitly when beginning that different study.
3. Review the Current UTC orbit comparison · SR or Current UTC orbit comparison · GR preset, satellite identifiers, live update count, interval, force model and tracking settings. Select Run simulation.
4. Return to Orbit viewer and use Saved session to select either an individual comparison segment or All segments — UTC overview for its live run. Use the trajectory and residual displays together; the overview keeps successive forecast windows on one UTC timeline.

The orbit viewer reads comparison-workflow outputs. A scenario-simulation run containing only quantum, timing and collection results does not automatically supply a model-versus-SGP4 trajectory comparison. An empty viewer before the first comparison run is therefore expected. The viewer is a projection of calculated trajectories, not a direct spacecraft telemetry feed. Keep the local GUI server running while using it.

Read all live comparison segments on one timeline

In Saved session, All segments — UTC overview groups the saved segment_0001…, segment_0002…, and later forecasts from the same live comparison run. Different live runs have separate overview choices. The individual segment choices remain available for their existing timeline and detailed review.

• Choose a Coordinate / spacetime subset before comparing curves. Incompatible coordinate or spacetime cases remain separate.
• Use Forecast segment to show All displayed segments or focus on one forecast, and use Satellite and Projection as needed.
• Read UTC offset · s together with the displayed UTC origin, the earliest valid initialization or sample UTC in the whole group. Each point uses its recorded epoch_utc, so a later forecast starts later on the shared axis instead of starting again at zero. Selecting a subset does not reset that origin. This is a civil UTC display coordinate, not the engine's physical propagation duration; the original elapsed_seconds remains in the saved data. Missing, invalid or unsupported UTC timestamps are reported rather than assigned invented times.
• Inspect Forecast starts and coverage for each segment's initialization UTC, first/last available sample UTC, point count and status. Vertical ticks mark forecast initialization on residual plots; circles mark the first available point of each trajectory. Open segment opens its individual saved-session view.

Each segment restarts the numerical forecast from its own SGP4-matched initial state. The supplied live comparison presets forecast 60 seconds, while the default minimum start-to-start update interval is 30 seconds. Their forecast windows can therefore overlap. Actual starts depend on calculation time and are read from the recorded UTC values. Curves from different segments remain separate, including where they predict the same UTC instant; the overview does not join them into one continuous numerical integration or an independently measured trajectory. A residual returning near zero at a segment start follows from matching the initial state.

The viewer checks for saved updates every five seconds. While the overview is selected, newly saved segments appear without switching to an individual segment. Follow newest session is disabled in the overview because the whole overview refreshes; use it when reviewing individual sessions. Refreshing the display does not request another forecast or change the saved scientific results.

Monitor and inspect

Runs shows persistent job history and the process log. Select a job, use View results, Use configuration, or Cancel run as appropriate. Cancelled/interrupted runs retain incomplete evidence; they are not completed benchmarks.

Use configuration immediately changes to Loading configuration… and is disabled while the selected run's inputs are loaded and checked. A failed load preserves the previous editable configuration. Changing the selected run or editing the configuration while a load is pending prevents its late response from replacing the newer selection or edits. A successful load opens Configure.

The main workbench refreshes active runs more frequently than idle history, slows automatic refresh while its tab is hidden, and backs off after network errors. The operator can configure these intervals in SaaS. Refresh and Cancel run remain explicit actions; a slower background refresh does not change execution or cancel a job.

Results shows available execution/validation statuses, metrics, diagnostic guidance, figures and saved files. Enlarge figures and inspect full-precision JSON before interpreting small numerical differences. Interactive charts provide series toggles and Show data. Supported text/JSON files have an Inspect dialog (15 MB limit) and Open original. Download run ZIP downloads the recorded output bundle for the selected run and attempt. Standalone jobs are stored under gui_runs, with request, configuration, logs and results.

ZIP downloads show preparation, byte progress and errors while keeping the workbench open and preserving unsaved edits. Where supported, a save-file picker streams directly to the chosen file. Other browsers use an in-memory download bounded to 64 MiB; larger archives offer an explicit Save large run ZIP link for the browser's download manager. This separate action can open an error in a new tab if the request is denied. Cancel download stops the current transfer; it does not cancel the simulation. Check the browser's downloads or the chosen file before treating a download request as a saved local copy. The unsaved-edit warning still applies when actually leaving or reloading the workbench.

For hosted runs, elapsed wall time includes preparation and result handling. PF compute accounting and the provider's reported Job runtime are separate measurements. See the timing and usage sections of SAAS_USER_GUIDE.md (source package reference: SAAS_USER_GUIDE.md) before comparing local calculation time with hosted completion time.

Figures and visual outputs groups same-stem image/PDF files in the same directory into one figure card. For example, figures/benchmark_jinan.png and figures/benchmark_jinan.pdf are one unique figure with two format files. The counts distinguish unique figures from available format files. Matching stems in different directories stay separate, including successive live snapshots. Enlarge the image preview or open the card's format links; a plot PDF is another format of the figure.

Reports and documents lists report/document artifacts separately; the heading is Documents when none is identified as a report. Known figure PDFs use Open vector PDF, and known PDF reports use Open report (PDF). Unclassified PDFs use Open PDF, without claiming they are reports. Published-reference benchmarks save their detailed reports as benchmark_suite.json and the selected profiles' satquma.json, bbm92.json, and jinan.json. These JSON files contain the numerical/empirical statuses, parameters, residuals, provenance and limitations. The workflow does not generate an additional detailed narrative PDF; graph PDFs remain figure formats. README.md summarizes status, and resolved_config.json records suite settings. Use a benchmark's Open result record (JSON) link or Inspect in Saved outputs to read the original evidence. Reports can still be available when plotting is disabled.

For a live scenario run, interactive charts combine the updates into one series per scenario using elapsed seconds from the first recorded UTC epoch. They do not place each update at its own local zero. Each saved live_0001/comparison.png, live_0002/comparison.png, and so on remains a single-update snapshot; one epoch produces a marker rather than a time-varying line. Use the interactive chart for the full live timeline and the labelled snapshot figures for individual updates.

Exactly equal scenario values overlap. Hide other series with the legend, or use Show data, to inspect each one without introducing artificial differences. Zero accepted rate is a plotted physical result, not a missing plot. Where Earth blocks all links, the displayed fidelity and purity are conditional model predictions only; there are no accepted photons from which to estimate a state. Unavailable reception, timing and PF results must remain unavailable rather than being interpreted as zero residuals.

The release repackaging tool excludes untracked gui_runs folders by default: these contain local execution state rather than application source. Share a completed experiment with Download run ZIP; it includes that job's saved inputs and outputs without the local server's connection file.

Documentation opens the end-user manual, ISAES reporting guide, ISAES report-assistant guide and related workflow/account guides, and shows the local environment. PDF and Markdown links are labeled separately; Markdown guides open as readable source text. Use the desktop launcher for dependency installation or repair. Closing a browser tab does not cancel a running job; finish or cancel work before stopping the server.

Use ISAES with a private workflow

1. Open My workflows, select a workflow, then inspect a completed run in its Run history. The ISAES scientific report section appears below the retained run outputs. The reporting worker reads those outputs; it does not repeat the simulation.
2. Inspect the report's execution, delivery, coverage, numerical, statistical and literature statuses separately. A delivered report can retain failed checks or insufficient evidence. Expand a finding's evidence details before relying on its interpretation.
3. Explore available linked figures and tables, save a view, or download the report and exact data. Change the workflow's reporting settings and regenerate a report when you need a different analysis; the earlier report remains retained. Exporting a saved view changes presentation without recalculating the scientific findings.
4. If the operator has enabled report discussions, choose Discuss report. Review any proposed changes under Refresh report proposals, then choose Approve proposal or Reject proposal. Approval does not run anything. Apply proposal to new revision creates a queued analysis or view revision; select Run report to execute it. Interpretation proposals remain separate commentary.

Classical reporting, exploration and exports work without an AI provider. Report discussion is disabled by default and requires the operator's PF_ISAES_AI_ENABLED=1 setting plus the existing provider/BYOK configuration and permissions. This optional mode is for controlled evaluation; successful protocol checks do not establish live-model scientific accuracy.

See R34_ISAES_GUIDE.md for reporting, literature, saved views and recovery, and docs/ISAES_AI.md for evidence review, pause/continue and proposal application. Literature archiving is account-wide; removing a workflow association and permanently deleting a document are separate actions.

Scientific interpretation

• Process completion, numerical validation and empirical agreement are separate statuses.
• Equal conditional fidelity/purity can be correct. Scenario 3 uses Scenario 2's physical history; a different coordinate description alone creates no additional noise or protection.
• Conditional state quality, accepted count rate and calculated secure-key budget are different outputs. A zero-key result may be physically and numerically correct.
• Live tracking uses public orbit-prediction data; it is not direct spacecraft telemetry.
• Recommendations suggest justified diagnostic actions. They do not guarantee a pass, change inputs automatically, or recommend weakening a security/validation criterion merely to get a favorable label.
• Save reference runs before changing assumptions. A different fit split, threshold, security level or apparatus parameter changes the analysis and must be reported.

Troubleshooting

Read the named error in the launcher or job log. Missing dependencies, unavailable input files, expired timing data, invalid model configuration and failed scientific checks require different remedies. A successful environment check is not an empirical validation. If a graph appears empty, check whether it is a one-epoch snapshot, whether series coincide, and whether the accepted rate is zero; use Show data and the original JSON. If no figure was produced, check whether plots were disabled or the run stopped before producing it. For a usable optical link, inspect visibility and the selected epoch/geometry; reducing phase noise does not remove an Earth obstruction.

If the orbit viewer keeps showing a new forecast beginning near zero residual, select All segments — UTC overview to see the successive initialization times and overlapping forecast windows together. Check its segment table and status messages if an expected segment or UTC sample is unavailable.

For complete configuration definitions, mathematical assumptions, result schemas and reproducibility guidance, retain the full manual alongside this guide.

Research precision

Choose Research precision · uncertainty and evidence and one of the four SR, static-GR, BBM92 or decoy presets. Edit the precision section in Fields or JSON. Each uncertainty parameter needs an explicit supported path, unit, distribution and provenance. The examples are illustrative, not measured calibrations. Nominal requirements, uncertainty completion and measurement comparison have separate result statuses. Static GR is supported for engine outputs; the optional frozen-endpoint covariance diagnostic is SR-only.

Open the result plots and tables, then inspect or download the original JSON and CSV matrices. Full configuration and interpretation are in Chapter 23 and RESEARCH_PRECISION_GUIDE.md. A completed job or a passing configured requirement does not establish empirical validation or mission qualification.

Quantum protocol and component benchmarks

Choose Quantum benchmarks · components and protocols to run all nine profiles or a selected profile: Bell states, teleportation, entanglement swapping, recurrence purification, memory, a two-link repeater, Hong–Ou–Mandel interference, QKD loss sweeps and channel characterization. Edit the resolved profile settings in Fields or JSON. This standalone component/protocol workflow does not run a satellite trajectory. For mission-coupled experiments, select a mission study and use its separate Quantum experiments controls; see MISSION_QUANTUM_GUIDE.md.

The saved evidence includes exact/model-sampled results, numerical reference checks, CSV tables, PNG/vector figures and a separate narrative quantum_benchmark_report.pdf. Read reference-check and requirement statuses separately. Simulated measurement counts are not empirical observations; a passing protocol identity does not qualify hardware or establish vendor parity. The full model, settings and interpretation reference is the manual's Quantum protocol and component benchmarks chapter. Published SatQuMA, BBM92, Jinan-1 and Micius comparisons retain their separate scientific roles.

1. Select that workflow, then choose All quantum component benchmarks or one named Starting configuration. The Quantum benchmark profile dropdown in Run options loads the same complete presets. Switching presets prompts before replacing unsaved edits.
2. Expand profiles, then the selected profile in Fields. Every scalar, nested object and sweep array is editable; use Add item for extra sweep values or Edit JSON for a whole section. The optional repeater success probabilities and cutoff accept numbers directly; leaving them blank retains null and its documented model behavior. No satellite fields are added to this component workflow.
3. Leave requirements empty for a descriptive benchmark, or add predeclared engineering requirements as objects containing id, profile, metric, aggregation, operator and value. The metric must name a numeric column in that profile's computed series. Aggregation is minimum, maximum or mean; operators are >= or <=. For example, a memory retention target must be based on its actual reported metric and intended operating interval, rather than changing a threshold after viewing the result.
4. Select Validate configuration, then Run simulation. Structural preflight runs in the GUI; the scientific engine performs the final parameter and physical-domain validation. Require engineering pass for successful exit is optional: enabling it makes an unmet configured requirement fail the job without changing its numerical result. Skip saved plot generation retains computed data, interactive data views and the narrative report.
5. Open View results. Each profile has separate numerical checks, engineering criteria and empirical evidence outcomes. These model benchmarks do not import measured observations; their empirical status is NOT_ASSESSED. Expand the series and requirement tables, toggle plotted curves or use Show data. Unavailable conditional outputs remain gaps.
6. Under Reports and documents, choose Open report (PDF) for the narrative quantum_benchmark_report.pdf. Under Figures and visual outputs, a PNG preview and Open vector PDF show alternative formats of the same figure. Download quantum_benchmark_suite.json, individual profile JSON records, *_series.csv tables and resolved_config.json from Saved outputs, or preserve the whole job with Download run ZIP. The result manifest binds configurations, source files and artifacts by hashes; hashes establish byte identity rather than experimental truth.

A numerical failure calls for inspecting the named check, equation and residual. An engineering failure calls for reviewing the declared target and physically justified apparatus changes. Neither permits weakening a security parameter or validation criterion to manufacture a pass. Rerun changed assumptions as a new job so the original evidence stays available.

Mission quantum experiments (r20)

1. Choose the Study purpose: Simulation, Orbital mechanics, Research precision, or Risk audit. Choose the Physical topology and Starting configuration.
2. Read Scenario and apparatus. Its diagram identifies physical nodes; its text distinguishes model-derived inputs from declared assumptions.
3. In Quantum experiments, opt in with Run selected experiments on this mission. Select the desired experiments and read each prerequisite.
4. Use Declare installed apparatus and the complete mission_quantum configuration to describe the equipment and protocol parameters. Checking a hardware declaration does not acquire calibration evidence or change geometry.
5. Validate, run and inspect experiment applicability and execution records alongside conditional states, success probabilities and resource rates.

The default mission experiment template is disabled and its apparatus flags are false. Selecting all nine experiments does not create the required sources, memories or joint analyzers. A module without the required apparatus remains explicitly inapplicable rather than returning a fabricated success.

Reference and standalone studies hide the mission live-tracking shortcut and orbit viewer. Their apparatus descriptions explain what actually runs. Existing saved mission outputs can still be inspected through their applicable result views. The complete operating reference is MISSION_QUANTUM_GUIDE.md and manual Chapter 26.

When an independent secondary mission is supplied, the scenario card shows both pair distributions and the required shared relay/endpoints. A source-independence declaration does not replace physical endpoint checks. In Results, inspect the per-module status/reason table and State, timing and resource provenance. The JSON download retains the exact complex matrices and detailed event records.

Research additions in r22

Select Research validation · independent acquisitions to calibrate the production Gaussian downlink count/QBER model on complete acquisitions and assess a frozen model against preassigned held-out acquisitions. The bundled Synthetic independent-pass demonstration is labeled synthetic throughout; it does not support measured accuracy or an academic/commercial qualification. Import acquisition manifest exposes the same strict manifest contract for research data. Set dataset.path and its expected SHA256; hosted users choose an input uploaded to their own project. A manifest embeds all observations and cannot reference other server files.

Run All to calibrate and validate, Calibrate to export frozen_model.json, or Validate with that frozen model to test without refitting. Hosted users upload the frozen model as a second project input. Saved result tabs show data provenance, predeclared gates, separate acquisition errors, remaining claim limitations, and downloadable predictions/configurations. Changing the model, protocol or calibration inputs invalidates its frozen identity.

The 16-draw precision presets are explicitly demonstrations. Choose Prespecified research study · 299 draws per seed for three fixed independent seeds and three nominal epoch grids. The form reports all 897 draws and 8,124 scenario-epoch evaluations before submission. These counts describe work, not a runtime quote. The risk bound applies to the first fixed-N seed under the declared simulation distribution; repeats are stability diagnostics, and larger samples cannot create missing experimental validation.

Full-state import · asymmetric phase and local channel demonstrates an explicit full complex state and a trace-preserving local quantum channel with subsystem identity and theoretical provenance. Edit these envelopes in the configuration tree or raw JSON; use measured-reconstruction provenance only for documented measured tomography. Fidelity alone is not an import format.

Two-link research · event history and heterogeneous memories enables the bounded event history, per-qubit memories, a declared proper-age admission gate and repeated seeds. It remains a two-link apparatus, with explicit unmodeled network and detector mechanisms in its reports.

A Release reference evidence status refers only to the packaged checked cases and source/evidence hashes. It does not grant empirical validation to a new custom run. Input snapshots/hashes establish byte integrity, not authenticity. The compact HF deployment reports Deployment package integrity separately: it checks shipped bytes, while scientific reference applicability remains Not assessed when the full evidence closure is not included. The complete release archive carries the named scientific reference evidence.

Acquisition-validation workload limits

The independent-acquisition workflow currently reports an unknown runtime. Its preflight does not parse an uploaded manifest to estimate fitting work, price or supported throughput. The engine permits at most 100,000 observation rows, at most 1,000 operating/range segments per row, and 3–101 integration points per segment. Validation also evaluates a refined grid of 2N-1 points. calibration.max_nfev must be a positive integer but has no dedicated upper cap; numerical Jacobian work can add model evaluations beyond the optimizer's reported function-evaluation count. Manifest byte limits also constrain hosted inputs, but are not a scientific cost estimate.

Hosted jobs reserve their selected execution-time allowance against the organization's monthly compute quota before queuing. During scientific execution, the worker checks elapsed time approximately every 0.2 seconds and terminates a job exceeding its limit; CPU, memory and artifact bounds also apply. Materialization and result transfer are separate from this scientific execution timer. A large acquisition manifest or expensive fit can therefore hit a limit before producing a complete result. A terminated execution must not be interpreted as model disagreement or successful validation. No capacity or completion-time guarantee is implied by accepting an input file.

Compare completed runs (r23)

Select Compare beside a completed run in Run history, then choose a related completed run with the same study purpose, topology and starting preset. Inspect saved configuration changes alongside numerical differences and matched series; download JSON or CSV when needed. Both standalone and hosted editions support the feature. See RUN_COMPARISON_GUIDE.md (source package reference: RUN_COMPARISON_GUIDE.md) for matching rules, unavailable values, project access and interpretation limits.

Shared classical reports

The shared core now supplies automatic scientific reporting and private literature associations. See R34_CLASSICAL_REPORTING_GUIDE.md for workbench steps, open analyzer/renderer APIs, deployment and validation scope. This pipeline operates independently of the AI research assistant.