Observation Planner

Generate observing candidates with a cheap legacy two-body search, refine only the accepted rows with the persistent cached N-body engine, and reuse those frozen final positions for finding charts.

Calculation model: Planner first filters candidate epochs with the fast two-body path. Accepted rows are then refined with the cached DE440s N-body model. COBS brightness uses the observer-aware model when suitable observations are available. Finding-chart generation can request additional N-body epochs for the selected comet track.

Data and active configuration

Opening Planner triggers an update of the local COBS summary data when possible. The current Planner selector is built from Elements.txt (current MPC elements) plus CustomElements.dat (user base/override). CometData.dat is auxiliary apparition history and cannot by itself enlarge the current Planner catalogue.

Planner uses the active longitude, latitude, elevation and GMT offset; change the active KOPR location 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	Dimensionless dust-to-gas light ratio normalized at a 90° phase angle; it is not an angular value in degrees.

Select comets

The current selector membership is Elements.txt + CustomElements.dat. CometData.dat is not a generic current-catalogue source. Active and inactive lists can be searched and reconciled through the shared selector; custom-element mutations preserve use_all or the explicit subset.

For epoch-aware calculation, KOPR first resolves the physically relevant apparition and then applies same-apparition precedence Custom > Elements > CometData.

Execution, progress and worker ownership

Expensive Planner work uses immutable operations, bounded process ownership, signal-routed progress and deferred validated-segment persistence. The accepted-row-only Planner N-body boundary remains current; Generate maps may later request additional dense epochs for its selected single target.

Search and rejected candidates create zero N-body epochs.
Final accepted epochs reuse persistent validated N-body segments where possible.
A process worker never creates a nested process scheduler.
Persistence failure cannot invalidate a successfully completed final ephemeris.
Stale operations cannot replace newer settings or catalogue generations.

Generate an ephemeris

Select current targets.
Set date, interval, steps, limiting magnitude and limiting altitude.
Select twilight reference and optional phase correction.
Click Generate ephemeris.
Review the final N-body-refined rows and any warning about skipped comets.

Planner isolates failures per comet. If any interval/apparition job for one comet fails, that comet is omitted as a whole: KOPR does not publish a partial ephemeris for it. Other comets that completed successfully remain published and usable, and the warning identifies the skipped targets and their errors.

If every requested comet fails, Planner remains fail-closed and preserves the previous table instead of replacing it with an empty or partially invalid result. Generate maps offers only comets that are actually present in the successfully published ephemeris rows.

The normal table does not need to expose internal technical provenance strings; structured provenance remains available internally for diagnostics and prepared map snapshots.

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.

COBS photometry and update lifecycle

When eligible COBS observations exist, Planner uses the authoritative observer_robust_v1 brightness model with precedence eligible robust COBS → Custom photometric parameters → catalogue/element H,n.

Negative/faint/upper-limit, inaccurate, missing-observer and unsupported-method rows are excluded from the fit.
A missing preference defaults COBS ON; an explicitly saved OFF remains OFF.
Planner checks COBS freshness on each real activation. A stale/missing/corrupt snapshot prompts at most once per session, but a snapshot that ages past 24 hours during the same session can become prompt-eligible again.
Update COBS… runs a manual refresh.
For predictions more than 42 days ahead while COBS is enabled, choose Continue with COBS, Disable COBS and continue, or Cancel.

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.

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.
One comet is listed as skipped after generation	Planner isolated a failure for that target. Successful comets remain valid. Read the warning/error for the skipped comet; it is intentionally not published as a partial ephemeris.
All selected comets fail	The operation fails closed and keeps the previous table. Resolve the reported ephemeris/runtime problems and retry.
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 suitable COBS photometry	Refresh online data, review COBS eligibility, or use custom/catalogue photometric parameters.
Unrealistic brightness prediction	Review stored magnitude parameters, COBS source status and whether Marcus phase correction is appropriate.
N-body preflight fails before calculation	Check the reported DE440s path and the exact missing runtime dependency. The failure is not cached permanently; after installing the dependency, retry in the same session.
COBS keeps prompting	One stale/missing/corrupt state should auto-prompt at most once per session. Use Update COBS… for an explicit retry.

Custom elements and catalogue refresh

The shared selector exposes the explicit custom-elements action. After an mutation, Planner reconciles the stable supported catalogue while preserving use_all or the explicit subset. New apparitions, rename and deletion are handled through the same catalogue transaction.

Selector state uses PREPARE → COMMIT and rolls back on a commit fault. A successful nested editor Save remains durable even if the outer selector is cancelled. See Custom comet elements.

Generate maps

After a fresh final ephemeris, Generate maps offers map-eligible comets in a single-target selector. Choose exactly one comet. KOPR freezes one immutable document and performs deferred authoritative N-body refinement for the physical track, reusing existing Planner rows and shared cache where possible.

Fallback two-body geometry is not accepted for the physical track. Preview and PDF use a compatible map-component stack and mixed installations fail early before expensive N-body/catalogue work. See Planner finding charts.

Related chapters

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