Tilepy: Scheduling Engine for Transients

• Tilepy is a Python-based scheduling engine that converts large-uncertainty sky localizations into actionable observation plans using HEALPix maps and observatory-specific constraints.
• It employs both 2D and 3D strategies, integrating probabilistic models and galaxy catalogues to maximize localization probability coverage in multi-messenger follow-ups.
• Its layered, modular design supports coordinated campaigns across ground- and space-based observatories for rapid responses to gravitational-wave, gamma-ray burst, and neutrino alerts.

tilepy is a Python-based, open-source scheduling engine for follow-up observations of poorly localized transient events in time-domain and multi-messenger astronomy, including gravitational waves, gamma-ray bursts, and high-energy neutrinos. It ingests HEALPix sky localizations, optionally uses 3D distance information and galaxy catalogues, enforces observatory-specific constraints for ground- and space-based facilities, and produces an ordered list of pointings with times and coordinates intended to maximize covered localization probability under operational limits (Schüssler et al., 26 Jan 2026).

1. Scientific context and development

tilepy addresses a central optimization problem in transient follow-up: multi-messenger triggers often arrive with localization uncertainties spanning tens to thousands of square degrees, whereas electromagnetic facilities typically have fields of view of at most a few tens of square degrees. The practical question is therefore how to choose pointings, in what order, and at what times, so that a finite observing window captures as much event probability as possible while respecting telescope constraints.

The package was originally developed within the H.E.S.S. collaboration to support rapid follow-up of gravitational-wave alerts and was subsequently generalized to other large-uncertainty alerts, including Fermi-GBM gamma-ray bursts and high-energy neutrino candidates. Earlier descriptions emphasize its role for small and mid-field-of-view observatories, while later work extends the scope to coordinated multi-observatory campaigns and to space-based observatories (Schüssler et al., 2023). It is open source, hosted on GitHub under the GNU LGPL, exposed through a public API at https://tilepy.com, and integrated into Astro-COLIBRI.

Operationally, tilepy has been used by H.E.S.S. in gravitational-wave observing runs O2 and O3 and is used for CTAO/LST-1 planning. A notable result reported in the literature is that the tiling strategies implemented in tilepy enabled H.E.S.S. to be the first ground-based pointing instrument to observe the true position of GW170817; the cited account places this observation about 5.3 hours after the merger (Lavergne et al., 2023). The software is therefore best understood not as a single survey-specific script, but as a general scheduler intended to convert probabilistic sky localizations into actionable observing plans.

2. Architecture and software organization

The architecture is explicitly layered. The principal separation is between high-level scheduling logic and low-level geometric and pointing calculations, so that strategy decisions do not depend on the detailed representation of field-of-view geometry or on the specific visibility implementation for a given instrument (Schüssler et al., 26 Jan 2026).

At the input/configuration layer, a campaign is initialized from three primary elements: a localization map, a campaign start time, and one or more telescope configuration files. The localization is typically a 2D HEALPix probability skymap from facilities such as LIGO/Virgo/KAGRA, Fermi-GBM, or IceCube; if available, distance information is also used. Telescope configurations encode observatory location for ground-based instruments, field-of-view size and shape, horizon or airmass limits, Sun and Moon constraints, and, for satellites, orbital or attitude information relevant to Earth-limb avoidance, Sun and Moon exclusion, and South Atlantic Anomaly passages. Multi-observatory campaigns are formed by loading multiple configurations in parallel.

The core layer is subdivided into three abstraction levels. The Observation Scheduler acts as the top-level manager: it parses configurations and skymaps, selects a scheduling strategy, and executes the main scheduling loop. The Tiling Determination layer defines the geometric discretization of the search region, including HEALPix resolution choice, tile centers, and field shapes. The Pointing Tools layer performs low-level numerical work: coordinate transformations, visibility checks, probability integration, galaxy-catalog queries, and, for space-based systems, orbital propagation and occultation handling.

The output layer produces both machine-readable and diagnostic products. Schedules are returned as ordered pointings with right ascension, declination, and start times, with duration or number of exposures where relevant. Visualization products include coverage maps, visibility plots, and cumulative probability curves such as $P_{\text{covered}}(t)$, which summarize how efficiently a schedule captures the localization probability as a function of time (Schüssler et al., 26 Jan 2026). This layered design is central to tilepy’s portability across observatories and observing modes.

3. Probability models, tiling strategies, and scheduling logic

tilepy implements both 2D and 3D strategies. In the 2D case, it operates directly on a sky probability map and evaluates candidate pointings by integrating the localization probability within the instrument footprint. In the formulation used by the software,

$$P_{\text{tile}} = \int_{\Omega_{\text{FoV}}} p(\hat{n})\, d\Omega,$$

where $p(\hat{n})$ is the skymap probability density and $\Omega_{\text{FoV}}$ is the solid angle subtended by the field of view. Earlier descriptions also give the discrete HEALPix form $P_i = \sum_{k \in F_i} p_k$ for a tile $i$ covering pixel set $F_i$ (Lavergne et al., 2023).

The default scheduler is greedy. At each step it identifies, among currently visible candidate tiles, the pointing with the highest remaining probability or merit, schedules that tile at the earliest available slot, masks the covered region to avoid double counting, and repeats until the observing window closes or a predefined coverage threshold is reached. A compact expression used to summarize the logic is

$M_i(t_k) = P_{\text{tile},i}(t_k)\, C_i(t_k),$

where $C_i(t_k)$ encodes whether the tile satisfies the relevant constraints at time $t_k$ (Schüssler et al., 26 Jan 2026). For 2D maps, this procedure corresponds to iterative greedy coverage maximization on the masked skymap.

For 3D strategies, tilepy combines a sky-and-distance posterior with a galaxy catalogue. The literature describes the use of GLADE+ and host-galaxy probabilities of the form

$$P_{\text{tile}} = \int_{\Omega_{\text{FoV}}} p(\hat{n})\, d\Omega,$$0

where $$P_{\text{tile}} = \int_{\Omega_{\text{FoV}}} p(\hat{n})\, d\Omega,$$1 can encode B-band luminosity, stellar mass, or related astrophysical weights. Tile scores are then defined by summing normalized galaxy probabilities inside the field of view,

$$P_{\text{tile}} = \int_{\Omega_{\text{FoV}}} p(\hat{n})\, d\Omega,$$2

This yields either galaxy-targeted searches for small fields of view or FoV-integrated galaxy searches for mid-field instruments (Lavergne et al., 2023).

tilepy has also supported multiple tiling philosophies across its development. Earlier work distinguishes 2D pixel-targeted search, 2D FoV-targeted search, 3D galaxy-targeted search, 3D FoV-targeted search using galaxy seed points, and 3D FoV-targeted search on a coordinate grid (Schüssler et al., 2023). Later multi-observatory work formalizes candidate grids as degraded HEALPix grids, user-defined grids, or galaxy-based grids, and adds options such as altitude optimization, deep exposure mode, exclusion of previously observed pointings, and sets of exposure durations rather than a single fixed exposure (Seglar-Arroyo et al., 2024).

4. Observatory constraints and support from ground to orbit

A defining feature of tilepy is that candidate tiles are not evaluated purely geometrically; they are filtered through observability and visibility constraints. For ground-based observatories, the software computes altitude and azimuth as functions of time, applies horizon or airmass cuts, enforces Sun and Moon conditions, and can distinguish observing modes such as astronomical darkness, moonlight conditions, or daytime operation for instruments that allow it. The configuration files encode quantities such as observatory latitude, longitude, altitude, field of view, maximum zenith angle, Moon avoidance, and allowed observing windows (Seglar-Arroyo et al., 2024).

Support for field-of-view geometry has evolved. Earlier descriptions, especially in the multi-observatory paper, describe circular fields of view as the current implementation (Seglar-Arroyo et al., 2024), whereas later papers report explicit support for circular, square, hexagonal, and generic polygonal shapes, together with arbitrary rotations on the sky (Schüssler et al., 26 Jan 2026). This development is significant for instruments with asymmetric or orientation-dependent footprints, including rectangular or hex-packed detectors.

Space-based support is a major later extension. In the space-observatory workflow, tilepy first performs the same localization-dependent tile generation used for ground-based scheduling, then retrieves the spacecraft trajectory from external services, computes the spacecraft position for each observation slot, and applies visibility cuts from Earth, Sun, and Moon occultation together with South Atlantic Anomaly screening (Ashkar et al., 11 Aug 2025). For SAA identification, the software evaluates geomagnetic field strength using IGRF-13 coefficients and, by default, flags times when the field intensity falls below $$P_{\text{tile}} = \int_{\Omega_{\text{FoV}}} p(\hat{n})\, d\Omega,$$3. The cited Swift example uses a conservative Earth-limb avoidance angle of $$P_{\text{tile}} = \int_{\Omega_{\text{FoV}}} p(\hat{n})\, d\Omega,$$4, a Sun avoidance angle of $$P_{\text{tile}} = \int_{\Omega_{\text{FoV}}} p(\hat{n})\, d\Omega,$$5, and a Moon avoidance angle of $$P_{\text{tile}} = \int_{\Omega_{\text{FoV}}} p(\hat{n})\, d\Omega,$$6.

These capabilities make tilepy instrument-aware without hard-wiring the strategy to a single facility. A plausible implication is that the separation between scheduling policy and low-level constraint modules is what enables the same code base to operate across Cherenkov telescopes, optical imagers, radio facilities, and low-Earth-orbit spacecraft, provided the relevant geometry and constraints are encoded in configuration and pointing modules.

5. Interfaces, coordination, and integration with Astro-COLIBRI

tilepy is accessible in three main ways: as a Python library, through a public web API, and via Astro-COLIBRI. In direct use, the typical pattern is to install the package from GitHub, prepare a HEALPix skymap and one or more telescope configuration files, instantiate the scheduler with the skymap, campaign start time, and configuration paths, run the scheduler, and export the resulting schedule. Advanced users can override the default greedy policy, plug in custom merit functions or tiling algorithms, or extend visibility and probability modules (Schüssler et al., 26 Jan 2026).

The public API allows external services or observatories to submit an event identifier or a direct skymap URL together with observatory parameters and to receive a JSON-formatted schedule in response. This supports automated trigger chains in which an alert is received, the tilepy API is called, an optimized schedule is returned, and the observatory control system ingests the result. Earlier descriptions also note that tilepy can be used via HTTP GET/POST and that the service is hosted on AWS for high availability (Lavergne et al., 2023).

Astro-COLIBRI provides the principal interactive interface. Within the web or mobile application, a user can select an event and request a tiling plan with a single action. The platform then displays visibility plots, an overlay of tiles on the skymap, and the ordered list of pointings. Astro-COLIBRI itself aggregates alerts across a wide range of transient classes and provides web access, a RESTful API, smartphone applications, push notifications, and a dedicated helpdesk or discussion forum for tilepy support (Lavergne et al., 2023).

Cross-observatory coordination is a central use case. In the multi-observatory scheduler, each telescope begins observing when its own conditions permit; as pointings are assigned, the sky map is masked so later-observing facilities avoid redundant coverage unless overlap is explicitly requested. The result is a coordinated campaign in which different telescopes, sites, and wavelengths fill remaining high-probability regions according to their own visibility and configuration constraints (Seglar-Arroyo et al., 2024).

6. Demonstrated applications, limitations, and prospective development

The published applications span gravitational-wave, gamma-ray burst, and other poorly localized alerts. In the very poorly localized Fermi-GBM GRB 231012A scenario, four IACT subarrays at La Palma, each with a $$P_{\text{tile}} = \int_{\Omega_{\text{FoV}}} p(\hat{n})\, d\Omega,$$7 FoV radius, reached 80% coverage of the skymap in 1.5 hours when observing in parallel (Seglar-Arroyo et al., 2024). For a simulated binary-neutron-star event followed jointly by CTAO-N and CTAO-S using a 3D integrated galaxy-informed strategy, the two observatories jointly covered 86% of the galaxy probability (Seglar-Arroyo et al., 2024). A multi-optical follow-up scenario for GW190814 with seven hypothetical telescopes at six sites reached 93% of the galaxy probability (Seglar-Arroyo et al., 2024). These examples document tilepy’s role as a coordination engine, not merely as a single-telescope tiler.

The space-based case study for Swift-XRT on the gravitational-wave candidate S250328ae illustrates both capability and limitation. For a 90-minute campaign beginning at 2025-07-28 10:00:10 UTC, with 30 observations of 3 minutes each and a $$P_{\text{tile}} = \int_{\Omega_{\text{FoV}}} p(\hat{n})\, d\Omega,$$8 Swift-XRT FoV, the 2D strategy produced 22 pointings covering 74% of the total gravitational-wave probability within the time window and geometric constraints. For the same event, with distance $$P_{\text{tile}} = \int_{\Omega_{\text{FoV}}} p(\hat{n})\, d\Omega,$$9 Mpc, the 3D galaxy strategy achieved only $p(\hat{n})$0 total coverage, and only 4 pointings remained visible during the entire 90-minute campaign window once Sun, Moon, and Earth occultation were applied (Ashkar et al., 11 Aug 2025). The same paper reports that field shape and orientation affect per-pointing efficiency: for the first five pointings on S250328ae, square and hexagonal footprints yielded different $p(\hat{n})$1 values, with the hexagonal case reaching $p(\hat{n})$2 for the leading tiles.

Several limitations are explicit in the literature. The scheduler is largely greedy and does not guarantee a globally optimal solution; traveling-salesman-style slew minimization and more global path optimization are described as future work rather than current capability (Schüssler et al., 26 Jan 2026). Localization handling is presently centered on HEALPix products, although later papers note plans to support non-HEALPix formats. For 3D galaxy strategies, effectiveness depends strongly on catalogue completeness and on the event distance; the literature repeatedly states that galaxy-guided scheduling is most effective only up to a few hundred Mpc, beyond which incompleteness degrades performance (Lavergne et al., 2023). Weather, full multi-night scheduling, long-term cadence optimization, and dynamic re-planning based on partial results are also not described as core present features.

Planned or ongoing developments include expanded support for space-based missions and orbital models, additional constraint types, non-HEALPix localization formats, and scheduling strategies that incorporate slew minimization or artificial-intelligence tools such as agglomerative clustering (Ashkar et al., 11 Aug 2025). This suggests an evolutionary trajectory from rapid gravitational-wave tiling for small and mid-field instruments toward a broader, community-maintained scheduling framework for heterogeneous transient-response networks.