KOPR

KOPR documentation

WPlanner source roles, two-stage dynamics and Generate maps

R255 remains the source-role/two-stage Planner foundation. Theta-20 and Theta-26–38 supersede its COBS and finding-chart workflow as described below.

R515 structural note: This page preserves feature/release contracts, but any flat-root Python filenames cited as implementation evidence are historical pre-convergence names. Current implementation ownership is canonical under src/kopr/; use the current package/API policy for imports and extension work.
Current authority: R255 changes no R254 production algorithm, but it supersedes older documentation that treated CometData as general current-catalogue membership or N-body as part of Planner search/filtering.

Qualified comet-element source roles

FileRoleMeaning
Elements.txtCURRENT_MPCCurrent MPC catalogue / current osculating elements.
CustomElements.datUSER_BASE_OR_OVERRIDEExplicit user-supplied elements.
CometData.datAUXILIARY_APPARITION_HISTORYMultiple-return/apparition history for legitimate periodic or lost-periodic targets.

CometData.dat is not a generic current-catalogue layer.

Epoch-aware apparition and source resolver

The resolver first determines the physically relevant apparition. Within that same apparition the approved source precedence is:

Custom > Elements > CometData

This preserves historical periodic-target calculations while preventing auxiliary historical data from silently expanding the present-day catalogue.

WPlanner current membership

current Planner targets = Elements.txt + CustomElements.dat

A CometData-only designation cannot enlarge the current Planner selector. R217 custom-element mutation/reconciliation still applies to the user layer; R255 defines how that layer participates in current membership and epoch-aware selection.

R251/R255 two-stage Planner dynamics

Phase A — legacy 2-body search

Current candidates go through cheap filters/delta-T, schedule construction, best-time search, magnitude/phase correction, altitude and all row-membership filters. Accepted rows freeze the exact UTC epochs and selected element identities.

Phase B — final cached N-body

Only frozen accepted rows request persistent cached N-body refinement. The refined values become the final displayed values and final frozen ICRS/J2000 map positions.

N-body search epochs    = 0
N-body rejected epochs  = 0
N-body requested epochs = final accepted legacy-row count

No magnitude or altitude membership filter is re-applied after N-body refinement, and silent final fallback to a non-N-body model is rejected.

Documented single-target map architecture

fresh final Planner rows
→ select exactly one map-eligible comet
→ freeze immutable document
→ deferred authoritative N-body physical-track refinement
→ overview/index + landscape detail sheets
→ Preview
→ atomic PDF export

Existing final Planner rows are reused, but Generate maps may compute missing dense epochs. The current physical-track contract probes every drawable segment at quarter, half and three-quarter times and refines until measured projected error is ≤0.25 mm or the bounded operation fails closed.

Current catalogue and rendering policy

  • Fixed local roots: ./koprtyc2 and ./koprybsc5.
  • Detail fusion priority: Yale > TYC2 > GSC1.1.
  • Overview: independent TYC2+Yale acquisition to 6.5 mag, no GSC completeness dependency.
  • B−V is provenance only; output is monochrome.
  • Overview square TAN starts at 30° and expands by 1° to a hard 60° maximum.
  • Overview lines are clipped to frame; D labels are outside footprints.
  • Mixed-version component preflight fails before expensive N-body/catalogue work.

R247 WCCD repair authority

R247 simultaneously qualifies the current WCCD repair boundary:

  • validate complete requested background geometry before sampling; a one-pixel overflow is a typed hard failure;
  • zero or negative ring medians do not disable valid upper-only ACF clipping;
  • raw and filtered annular flux remain signed;
  • degenerate sigma and invalid angular coverage have explicit typed states;
  • None means unhydrated reference state, while [] is an authoritative empty state;
  • Clear all stars atomically clears canonical/legacy/diagnostic/image-slot/measured-artist reference state while preserving the comet, catalogue overlays and frozen ACF context.

Current qualification evidence

Source-reported Theta-38 status: PASS_HEADLESS / ARCHIVE QUALIFIED; focused affected set 68/68 PASS; current Planner maps 198 = 197 PASS + 1 allowed PyQt5 skip; re-extracted smoke 68/68 PASS. These figures are inherited from the supplied Theta-38 report and were not rerun by this documentation package.

Supersession and retained historical contracts

  • R130 remains the background-operation, interval/persistence performance foundation for the final N-body refinement phase, but not the authority for which Planner rows receive N-body work.
  • R121 modal-ephemeris documentation is historical where it says N-body participates in Planner visibility/best-time search; R255 supersedes that Planner-specific statement.
  • R217 remains the custom-element mutation/repository/selector-repair authority; R255 defines source roles and current membership.
  • R239 remains the exact-designation MPC/Generate maps integration baseline; R247 hardens it; R255 defines the final workflow and source/dynamics semantics.

R239 report · R247 report · R255 report