tardis.visualization.tools.rpacket_plot module

class tardis.visualization.tools.rpacket_plot.RPacketPlotter(sim, no_of_packets: int)

Bases: object

Animated plotting interface for Monte Carlo packet trajectories.

This class creates an animated plot using Plotly to visualize the trajectories of real packets as they travel through the ejecta starting from the photosphere. The visualization shows packet interactions and shell structures in 2D space.

Parameters:

simSimulation

TARDIS simulation object containing transport state and configuration.

no_of_packetsint

Number of packets to include in the visualization.

Attributes:

no_of_packetsint

Number of packets being visualized.

simSimulation

Reference to the TARDIS simulation object.

interaction_from_numdict[int, dict[str, str | float]]

Mapping from interaction type integers to display properties.

theme_colorsdict[str, dict[str, str]]

Color schemes for light and dark themes.

play_buttondict

Plotly button configuration for animation play control.

pause_buttondict

Plotly button configuration for animation pause control.

figgo.Figure, optional

The generated Plotly figure object.

Initialize the RPacket Plotter.

Parameters:

simSimulation

TARDIS simulation object generated using the run_tardis function.

no_of_packetsint

Number of packets to be used for plotting. Must be positive.

Raises:

ValueError

If no_of_packets is not positive.

create_packet_scatter(packet_no: int, rpacket_x: ndarray, rpacket_y: ndarray, interactions: ndarray, theme: str, frame: int | None = None) → Scatter

Create a scatter plot object for a single packet trajectory.

Generates a Plotly scatter plot with interaction-based styling for visualizing packet trajectories with optional frame-based slicing.

Parameters:

packet_noint

Index of the packet to create scatter plot for.

rpacket_xnp.ndarray

Array of x coordinate arrays for different packets.

rpacket_ynp.ndarray

Array of y coordinate arrays for different packets.

interactionsnp.ndarray

Array of interaction type arrays for different packets.

themestr

Theme name for plot styling.

frameint, optional

Frame number for trajectory slicing. If None, shows full trajectory.

Returns:

go.Scatter

Plotly scatter object with styled trajectory and interaction markers.

Notes

Marker colors and opacity are determined by interaction types. Hover information includes coordinates and last interaction type.

classmethod from_simulation(sim, no_of_packets: int = 15) → RPacketPlotter

Create an RPacketPlotter instance from a TARDIS simulation.

This factory method creates a plotter instance with validation to ensure the simulation has the necessary tracker data.

Parameters:

simSimulation

TARDIS simulation object generated using run_tardis function. Must have rpacket tracking enabled.

no_of_packetsint, optional

Number of packets to visualize, by default 15. If greater than available packets, all available packets are used.

Returns:

RPacketPlotter

Configured plotter instance ready for visualization.

Raises:

AttributeError

If the simulation does not have rpacket tracking enabled.

Warns:

UserWarning

If requested no_of_packets exceeds available packets.

generate_plot(theme: str = 'light') → Figure

Create an animated plotly plot showing Monte Carlo packet trajectories.

This method generates a comprehensive visualization showing packet paths, interaction types, shell boundaries, and photosphere. The plot includes animation controls and customizable themes.

Parameters:

themestr, optional

Visual theme for the plot, by default “light”. Must be either “light” or “dark”.

Returns:

go.Figure

Plotly figure object containing the animated packet trajectory plot with shells, photosphere, and interaction visualization.

Raises:

ValueError

If theme is not “light” or “dark”.

get_coordinates_multiple_packets(r_packet_tracker: DataFrame) → Tuple[ndarray, ndarray, ndarray]

Generate coordinates for multiple packet trajectories.

Creates uniformly distributed launch angles and calculates coordinates for multiple packets to visualize their collective behavior.

Parameters:

r_packet_trackerpd.DataFrame

DataFrame containing packet tracking data with columns for radius, direction cosine, and interaction types.

Returns:

tuple[np.ndarray, np.ndarray, np.ndarray]

Three-element tuple containing: - Array of x coordinate arrays for multiple packets (object dtype) - Array of y coordinate arrays for multiple packets (object dtype) - Array of interaction type arrays for multiple packets (object dtype)

Notes

Launch angles are distributed uniformly around the photosphere to provide representative coverage of packet trajectories.

get_coordinates_with_theta_init(r_track: Series, mu_track: Series, time: float, last_interaction_type: Series, theta_initial: float = 0) → Tuple[ndarray, ndarray, List[int]]

Generate 2D coordinates for a single packet trajectory.

Calculates x, y coordinates from radial position and direction cosine data, converting from spherical to Cartesian coordinates for visualization.

Parameters:

r_trackpd.Series

Radial position of packet at each step (in cm).

mu_trackpd.Series

Cosine of radial angle of the packet at each step.

timefloat

Time since explosion occurrence (in seconds).

last_interaction_typepd.Series

Interaction type of the packet at each step.

theta_initialfloat, optional

Initial launch angle from x-axis at photosphere, by default 0.

Returns:

tuple[np.ndarray, np.ndarray, list[int]]

Three-element tuple containing: - x coordinates of the packet at different steps (km/s) - y coordinates of the packet at different steps (km/s) - interaction types occurring at different points

Notes

Coordinates are converted to velocity units (km/s) by dividing by time and applying unit conversion. The trajectory calculation follows the spherical geometry described in the TARDIS documentation.

get_equal_array_size(rpacket_x: ndarray, rpacket_y: ndarray, interactions: ndarray) → Tuple[ndarray, ndarray, ndarray, int]

Normalize coordinate arrays to equal size for animation frames.

Pads shorter trajectories with their final values to match the longest trajectory length, enabling synchronized animation across all packets.

Parameters:

rpacket_xnp.ndarray

Array of x coordinate arrays for different packets.

rpacket_ynp.ndarray

Array of y coordinate arrays for different packets.

interactionsnp.ndarray

Array of interaction type arrays for different packets.

Returns:

tuple[np.ndarray, np.ndarray, np.ndarray, int]

Four-element tuple containing: - Normalized x coordinate array (all sub-arrays same length) - Normalized y coordinate array (all sub-arrays same length) - Normalized interaction types array (all sub-arrays same length) - Maximum array size among all packets

Notes

Padding uses the final coordinate values to maintain trajectory continuity in the animation visualization.

get_frames(frame: int, rpacket_x: ndarray, rpacket_y: ndarray, interactions: ndarray, theme: str) → List[Scatter]

Create individual animation frames with scatter plot objects.

Generates a list of scatter plot objects for each packet trajectory up to the specified frame number for animation visualization.

Parameters:

frameint

Current frame number for trajectory slicing.

rpacket_xnp.ndarray

Array of x coordinate arrays for different packets.

rpacket_ynp.ndarray

Array of y coordinate arrays for different packets.

interactionsnp.ndarray

Array of interaction type arrays for different packets.

themestr

Theme name for plot styling.

Returns:

list[go.Scatter]

List of Plotly scatter objects for the current frame.

Notes

Each scatter object represents one packet’s trajectory up to the current frame, enabling smooth animation transitions.

get_slider_steps(rpacket_max_array_size: int) → List[Dict]

Generate timeline slider steps for animated plot frames.

Creates slider step configurations for frame-by-frame animation control with consistent transition timing.

Parameters:

rpacket_max_array_sizeint

Maximum size of coordinate array among all packets.

Returns:

list[dict]

List of slider step dictionaries with frame animation arguments.

Notes

Each step includes frame duration, transition settings, and label for user interaction with the animation timeline.