Observation Planner

Generate ephemerides and visibility diagrams with the R121 N-body planner profile and the completed R125–R130 bounded interval, persistent-segment and background-execution pipeline.

R130 final Planner contract: heavy work runs through immutable operations on the shared background QThread runner. One comet/apparition interval is one job, automatic process work is bounded, and persistent fitting or writing cannot invalidate an already completed ephemeris.

Data and active configuration

Opening Planner triggers an update of the local COBS summary data when possible. Ephemerides are calculated from KOPR’s local comet elements for the active longitude, latitude, elevation and GMT offset.

Planner does not ask for a separate observing site. Change the active location in KOPR before generating results.

Planner controls

Control	Default	Meaning
Start date	Current date	First date of the ephemeris or diagram.
Interval (days)	7	Days between generated epochs.
Steps	4	Number of generated epochs.
Limit mag.	15	Faintest predicted magnitude accepted.
Limit alt.	10°	Minimum comet altitude used for filtering.
Twilight reference	Astronomical	End of astronomical (−18°), nautical (−12°) or civil (−6°) twilight.
Apply Marcus Phase Correction	Off	Apply the dust phase correction to magnitude prediction or plotting.
d_90	10	Parameter used by the phase function.

Select comets

The selection dialog is built from available standard and custom comet records. Active and inactive lists can be searched, selected in bulk and moved between sides. Stored photometric parameters are used when present; otherwise Planner uses the element-file defaults.

Execution, progress and worker ownership

EphemGen() and PlotGen() execute through immutable operations on the shared background QThread runner.
The GUI does not use QApplication.processEvents() and does not call heavy computation directly.
Progress is signal-routed; elapsed time is updated by QTimer.
One operation owns at most one spawn process pool. Pool workers never create nested pools.
One job owns one comet/apparition interval and performs at most one forward and one backward integration.
Element batches use one vector Astropy frame transformation.

Cancel follows the shared cooperative cancellation path. A finished result is committed transactionally; stale operations cannot replace newer settings or data.

Developer WPlanner performance contract

Generate an ephemeris

Select the comet list.
Set date, interval, steps, limiting magnitude and limiting altitude.
Select twilight reference and optional phase correction.
Click Generate ephemeris.
Review the text in the output panel.

KOPR refuses the operation when start date, interval or step count is blank. The exact columns are produced by the current ephemeris generator and should be read or saved as plain text.

Plot a night visibility diagram

Plot diagram calculates one night from the selected start date and active location. The background represents night and twilight geometry; accepted comets are drawn as labelled curves. Geometric altitude does not include local trees, buildings or terrain.

Actual COBS data and quick analysis

The dropdown contains comets present in the local COBS summary. Selecting one opens observed magnitudes against days from now with an internally calculated quick trend. This is a rapid context view, not the full Comet Analyzer workflow.

Validated persistent segments

A cold interval integrates the N-body trajectory. Validated segments can then be compressed and written atomically for reuse in later sessions. A matching warm interval can be served without a new integration.

Fitting, validation, compression and writing are deferred through a bounded single-worker persistence service. Persistence failure, queue saturation or shutdown timeout may prevent cache reuse, but cannot invalidate an ephemeris that has already completed successfully.

Cache identity, schema, polynomial degree, validation tolerances and disk limits remain protected. Invalid or mismatched segments are not trusted.

Deterministic reference scenarios

Scenario	Interval jobs	Automatic workers
One comet × four midnights	1	1
One comet × 500 epochs	1	1
Four comets × 300 epochs	4	4
300 comets × four epochs	300	4

The synthetic persistent-cache probe requires one cold integration, zero warm integrations for a covered interval and successful background-persistence draining. Wall time, CPU utilisation and RSS are diagnostics, not portable pass/fail thresholds.

Target-system validation

The release environment did not contain the complete production PyQt5, Astropy, jplephem, DE440s and representative 300-comet runtime. On the target installation record cold and warm times for the four reference scenarios, worker utilisation with 1/2/4 workers, Cancel during integration and deferred persistence, peak RSS, cache size and numerical comparison with R129.

Save ephemeris output

Use the Planner save control to write the generated text output. Save only after the current operation completes and inspect the destination file before using it in an observing plan.

Common problems

Symptom	Check
Required fields are rejected	Enter start date, interval and steps.
Expected comet is absent	Check spelling/elements, magnitude limit, altitude limit, observing location and date.
Progress appears stationary	Review terminal diagnostics and target-runtime dependencies. Do not interpret a long cold N-body integration as proof that the GUI thread is executing it.
Persistence warning after a valid result	The ephemeris remains valid; only later warm-cache reuse may be unavailable.
No COBS quick curve	Refresh online data or use Analyzer after loading observations.
Unrealistic brightness prediction	Review stored magnitude parameters and whether phase correction is appropriate.

Related chapters

Active observing location · Comet Analyzer · Comet elements and observation data · Performance limits