astro-observation-planner

Astronomical Observation Planner

Produces a four-part observation plan: twilight window, Moon summary, planetary visibility, and a deep-sky object table. Display each part to the user as soon as it is computed — do not wait for all four parts before showing anything. The DSO query in Part 4 can take a minute or more.

Step 0 — Confirm location and date

Location

• If the user gives a location explicitly, use it and proceed.
• If not, you may have an approximate location from context. Always tell the user what location you are using and note that inferred locations may not be precise — ask if they'd like to specify a city or coordinates. Never silently use an inferred location; precision matters for rise/set times.

Date

• Default to today if the user says "tonight" or gives no date.
• Use the date the user specifies for future or past nights.

Display timezone

Sunrise/Sunset embed the kernel's UTC offset in returned times. Ask the user: "What timezone are you in?" (or infer it from the observation location if they are observing from where they are). Then set:

$AstroDisplayTZ = "America/New_York"  (* IANA name — handles DST automatically *)
(* or a numeric UTC offset: $AstroDisplayTZ = -4 *)

If the user's timezone matches the kernel's, leave it as None. All time formatting functions read this variable automatically. Note: WL's built-in $TimeZone takes a numeric offset and is unrelated — setting it does not reformat times already returned by Sunrise/Sunset.

Parameters

Part 4 (deep-sky objects) is optional. The DSO query takes 1–2 minutes and can return hundreds of results, which may consume significant tokens on lower-tier plans. Ask the user whether they want it — Parts 1–3 (twilight, Moon, planets) run quickly and may be sufficient.

If the user wants Part 4, confirm:

• Equipment / sky conditions (sets the magnitude limit):
  • Naked eye, dark skies: ~6 | Naked eye, suburban: ~4
  • Binoculars: ~9 | Small telescope (4–6"): ~11 | Large telescope (8"+): ~13
• Minimum altitude: default 10° — adjust if the user has a specific horizon constraint.

Object types are fixed: galaxies, star clusters, nebulae.

Output format

All function results return Associations with string keys and plain string/number values. Choose format before computing:

• Wolfram Notebook / Desktop — Dataset[rows] renders natively
• Chat interface — ExportString[Dataset[rows], "Markdown"] produces a clean Markdown table (all values are already plain strings — no conversion needed)
• HTML report — build a styled HTML string and CloudDeploy it

Step 1 — Load the implementation

First, determine kernel persistence. Run this probe as a single evaluator call:

$testPersistence = "alive"; $testPersistence

Then immediately run a second call:

$testPersistence

• If the second call returns "alive" → kernel is persistent. Load once at the start; definitions persist for all subsequent calls.
• If the second call returns $testPersistence unevaluated or raises an undefined-symbol warning → kernel is stateless. Prepend the relevant Get call(s) to the top of every evaluator call that uses them.

Load the core file (shared helpers + Parts 1–3) with:

Get["https://raw.githubusercontent.com/WolframResearch/skills/main/skills/astro-observation-planner/references/astro-observation-core.wl"]

If the user confirmed they want Part 4 (deep-sky objects) in Step 0, also load:

Get["https://raw.githubusercontent.com/WolframResearch/skills/main/skills/astro-observation-planner/references/astro-observation-dso.wl"]

No internet access: if the kernel cannot reach the URLs, read references/astro-observation-core.wl (and references/astro-observation-dso.wl if Part 4 is needed) from this skill's directory and evaluate their contents instead.

astro-observation-core.wl defines: $AstroDisplayTZ, AstroTimeStr, AstroDateTimeStr, AstroAltStr, AstroMagStr, AstroDurStr, AstroInWindow, AstroTwilightSummary, AstroMoonSummary, AstroPlanetTable.
astro-observation-dso.wl defines: AstroDSOTable and its internal helpers iAstroDSONormalize, iAstroDSOVisibleQ, iAstroDSOClassify.

In a stateless kernel, prepend the relevant Get[...] call(s) to each evaluator call below.

Step 2 — Run each part in sequence

Call these functions in order. After each part, paste the Markdown string returned by ExportString directly into your response — do not leave it as WL kernel output. Pass part["Rows"] directly to Dataset; do not unpack or reconstruct rows manually.

Part 1: Twilight summary

part1 = AstroTwilightSummary[loc, observeDate];
ExportString[Dataset[part1["Rows"]], "Markdown"]

Paste the result into your response. If part1["NoAstroDark"] is True, tell the user there is no astronomical darkness tonight (common at high latitudes in summer) and offer to continue with nautical twilight as the dark window. Do not proceed with Parts 2–4 using Missing["NoAstronomicalDark"] as the dusk/dawn values — ask the user if they want to continue.

Part 2: Moon summary

part2 = AstroMoonSummary[loc, observeDate, part1["AstroDusk"], part1["AstroDawn"]];
ExportString[Dataset[part2["Rows"]], "Markdown"]

Paste the result into your response. Note whether the Moon sets during the session (part2["MoonSet"] is a DateObject) or is up all night (Missing). If the Moon is >50% illuminated and up during prime hours, mention the impact on deep-sky visibility.

Part 3: Planetary visibility

part3 = AstroPlanetTable[loc, observeDate, part1["AstroDusk"], part1["AstroDawn"]];
ExportString[Dataset[part3], "Markdown"]

Paste the result into your response. Call out any bright planets (mag < 0) or planets visible for most of the session.

Part 4: Deep-sky objects

Only run Part 4 if the user confirmed they want deep-sky objects in Step 0. If they did not, skip this section entirely.

part4 = AstroDSOTable[loc, observeDate, part1["AstroDusk"], part1["AstroDawn"]];

This query takes 1–2 minutes. Tell the user it's running. When complete, paste each table into your response:

(* Top 25 by set time — catch them before they set *)
ExportString[Dataset[Take[part4["Rows"], 25]], "Markdown"]
(* Up-all-night highlights — brightest objects with Set = "Up until dawn" *)
upAllNight = Select[part4["Rows"], #["Set"] === "Up until dawn" &];
ExportString[Dataset[Take[SortBy[upAllNight, #["Mag"] &], 15]], "Markdown"]

Also report: total visible objects, breakdown by type, how many set during the session vs up all night.

Notes

Resolving locations. Always use \[FreeformPrompt]["city name"] to obtain the correct entity — never write Entity[...] by hand. If the result is ambiguous or fails with Sunrise/Sunset, fall back to GeoPosition[{lat, lon}] — all functions accept either form.

Times display in kernel timezone unless $AstroDisplayTZ is set in Step 0. Sunrise/Sunset return times in the kernel's timezone; setting $AstroDisplayTZ to the user's timezone string (e.g. "Europe/London") causes all AstroTimeStr/AstroDateTimeStr calls to convert automatically.

Rise/set label meanings in the DSO table (times are LST-derived, session-relative):

• "Already up" — object was above the horizon when astronomical dark began
• "Up until dawn" — object does not set before astronomical dawn
• A clock time — the object rises or sets during the session window

Planet table shows actual M/D HH:MM (24h) rise and set times regardless of whether they fall inside the dark window. Planets are sorted by session set time so in-window planets appear first; planets that set before dark or rise after dawn appear at the bottom with their real times.

Optional: Shareable output

After generating the plan, offer the user one of the following depending on their preference:

Recomputable cloud notebook — build a Notebook[{cells...}] expression with a Get cell to load the functions and one cell per part, then deploy:

CloudDeploy[
  Notebook[{
    Cell["Observation Plan — <location> — <date>", "Title"],
    Cell[BoxData["Get[\"https://raw.githubusercontent.com/WolframResearch/skills/main/skills/astro-observation-planner/references/astro-observation-core.wl\"]"], "Input"],
    (* Include the DSO Get cell only if Part 4 was requested *)
    Cell[BoxData["Get[\"https://raw.githubusercontent.com/WolframResearch/skills/main/skills/astro-observation-planner/references/astro-observation-dso.wl\"]"], "Input"],
    Cell[BoxData["part1 = AstroTwilightSummary[loc, observeDate]"], "Input"],
    (* ... one Input cell per part ... *)
  }],
  Permissions -> "Public"
]

Returns a URL anyone can open and re-evaluate.

Shareable HTML report — build a styled HTML string and deploy:

CloudDeploy[ExportForm[htmlString, "HTML"], Permissions -> "Public"]

Returns a URL to a static page — no WL kernel required to view.

Local file — if cloud deployment is unavailable, offer to produce a Markdown summary or notebook file the user can save or deploy themselves.