adam_core.dynamics.plots module

adam_core.dynamics.plots.prepare_propagated_variants(propagated_variants: Orbits, impacts: CollisionEvent) → dict[str, Orbits][source]

Sets variants propagated after their impact time to their impact coordinates on the surface of the colliding body for stopping collision events. Non-stopping close-approach events are preserved as propagated.

Note: Due to the nature of the collision detection code, some variants may already be inside the sphere of the colliding body when a stopping event is detected. In these cases, the variants’ distance from the body center is set to the body radius. Results are intended for visualization, not high-fidelity impact prediction.

Parameters:

  • propagated_variants (Orbits) – The propagated variants to cleanse.

  • impacts (CollisionEvent) – The impacts detected within the variants.

Returns:

A dictionary containing the prepared variants, with keys:

  • ”Non-Impacting”: Variants with no collision events

  • ”{BODY} Impacting”: Variants with stopping collisions for that body

  • ”{BODY} Close-Approaching”: Variants with non-stopping collisions for that body

Return type:

dict[str, Orbits]

adam_core.dynamics.plots.generate_impact_visualization_data(orbit: Orbits, variant_orbits: VariantOrbits, impacts: CollisionEvent, propagator: Propagator, time_step: float = 5, time_range: float = 60, window_mode: Literal['event_range', 'closest_approach'] = 'event_range', focus_body: Literal['EARTH', 'MOON'] | None = None, window_percentiles: Tuple[float, float] = (10.0, 90.0), window_padding: float = 10.0, target_frames: int | None = 180, min_time_step: float = 1.0, max_processes: int | None = None) → Tuple[Timestamp, Orbits, dict[str, Orbits]][source]

Generates the data for collision-event visualization animation (impacts and/or close-approaches) for supported planetary bodies.

CollisionEvents visualizations are currently supported for the Earth and Moon.

Parameters:

  • orbit (Orbits) – The nominal best-fit orbit to propagate.

  • variant_orbits (VariantOrbits) – The variants to propagate.

  • impacts (CollisionEvent) – The impacts detected within the variants.

  • propagator (Propagator) – The propagator to use to propagate the orbit.

  • time_step (float) – The time step to use for the propagation.

  • time_range (float) – The time range to use for the propagation.

  • window_mode (Literal["event_range", "closest_approach"]) – Time window selection mode. “event_range” uses full first/last event range with time_range padding. “closest_approach” focuses on closest events.

  • focus_body (Optional[Literal["EARTH", "MOON"]]) – Body used by closest_approach window mode. Defaults to a body with stopping impacts, then MOON if present, then the first body with events; a warning is logged when multiple bodies have events and no focus_body is given.

  • window_percentiles (Tuple[float, float]) – Percentiles used to bracket closest-event times in closest_approach mode.

  • window_padding (float) – Padding (minutes) added to both sides of closest_approach window.

  • target_frames (Optional[int]) – Target frame count for closest_approach mode; time_step may be increased to keep frame count near this value.

  • min_time_step (float) – Minimum time step (minutes) allowed for closest_approach auto-scaling.

  • max_processes (Optional[int]) – The maximum number of processes to use for the propagation.

Returns:

The propagation times, the propagated nominal best-fit orbit and the propagated variants.

Return type:

Tuple[Timestamp, Orbits, dict[str, Orbits]]

adam_core.dynamics.plots.create_sphere(radius, offset=None)[source]

Create a set of points that form a sphere.

Parameters:

  • radius (float) – The radius of the sphere.

  • offset (array-like, optional) – The offset of the sphere from the origin.

adam_core.dynamics.plots.add_earth(time, coastlines: bool = True, origin: OriginCodes = OriginCodes.EARTH, frame: str = 'ecliptic', show: bool = True) → Tuple[Surface, List[Scatter3d]][source]

Add the Earth to the plot.

Parameters:

  • time (Timestamp) – The time of the plot.

  • coastlines (bool, optional) – Whether to add the coastlines to the plot.

  • origin (Origin, optional) – The origin of the plot.

  • frame (str, optional) – The frame of the plot.

  • show (bool, optional) – Whether to show the Earth by default.

Returns:

The Earth rendered as a sphere and the traces for the coastlines.

Return type:

Tuple[go.Surface, List[go.Scatter3d]]

adam_core.dynamics.plots.add_moon(time: Timestamp, origin: OriginCodes = OriginCodes.EARTH, frame: Literal['ecliptic', 'equatorial', 'itrf93'] = 'ecliptic', show: bool = True) → Surface[source]

Add the Moon to the plot.

Parameters:

  • time (Timestamp) – The time of the snapshot.

  • origin (OriginCodes) – The origin of the plot.

  • frame (Literal["ecliptic", "equatorial", "itrf93"]) – The frame of the plot.

Returns:

The Moon rendered as a sphere.

Return type:

go.Surface

adam_core.dynamics.plots.plot_impact_simulation(propagation_times: Timestamp, propagated_best_fit_orbit: Orbits, propagated_variants: dict[str, Orbits], impacts: CollisionEvent, grid: bool = True, title: str = None, logo: bool = True, show_impacting: bool = True, show_close_approaching: bool = True, show_non_impacting: bool = True, show_best_fit: bool = True, show_earth: bool = True, show_moon: bool = True, sample_impactors: float | None = None, sample_non_impactors: float | None = None, height: int | None = None, width: int | None = None) → Figure[source]

Plot the impact simulation.

Parameters:

  • propagated_best_fit_orbit (Orbits) – The propagated best-fit orbit.

  • propagated_variants (Orbits) – The propagated variants.

  • impacts (CollisionEvent) – The impacts detected within the variants.

  • grid (bool, optional) – Whether to add the grid to the plot.

  • title (str, optional) – The title of the plot.

  • logo (bool, optional) – Whether to add the Asteroid Institute logo to the plot.

  • show_impacting (bool, optional) – Whether to show the impacting variants.

  • show_close_approaching (bool, optional) – Whether to show variants with non-stopping close-approach events.

  • show_non_impacting (bool, optional) – Whether to show the non-impacting variants.

  • show_best_fit (bool, optional) – Whether to show the best-fit orbit.

  • show_earth (bool, optional) – Whether to show the Earth.

  • show_moon (bool, optional) – Whether to show the Moon.

  • sample_impactors (Optional[float], optional) – Randomly sample the impactors for plotting. Should be between 0 and 1.

  • sample_non_impactors (Optional[float], optional) – Randomly sample the non-impactors for plotting. Should be between 0 and 1.

  • height (int, optional) – The height of the plot.

  • width (int, optional) – The width of the plot.

Returns:

The impact simulation plot.

Return type:

go.Figure

adam_core.dynamics.plots.plot_risk_corridor(impacts: CollisionEvent, title: str | None = None, logo: bool = True, height: int | None = None, width: int | None = None, map_style: Literal['carto-positron', 'open-street-map', 'white-bg'] = 'carto-positron') → Figure[source]

Plot the risk corridor with toggleable globe/map views. Points colored by time with a linear scale and animated sequence.

Parameters:

  • impacts (Impact data containing coordinates)

  • title (str, optional) – Plot title

  • logo (bool, optional) – Whether to add the Asteroid Institute logo to the plot.

  • height (int, optional) – The height of the plot.

  • width (int, optional) – The width of the plot.

  • map_style ({"carto-positron", "open-street-map", "white-bg"}, optional) – Basemap style used by Plotly map tiles. Defaults to "carto-positron" to avoid OpenStreetMap tile-rate errors in shared/public viewing contexts.

Returns:

The risk corridor plot.

Return type:

go.Figure