API Reference

spacetimelib.norm_s(vec_s)

Calculate the norm of a space-vector. This is simply the Euclidean norm, or more formally, the L-2 norm.

Given an N-dimensional space-vector a = (a1, ..., aN), the norm is norm_s(a) = sqrt(a1^2 + ... + aN^2).

For instance, if the space-vector is the difference between the coordinates of two positions in space, then its norm is the distance between the events.

Parameters:

vec_s (array_like) –

Any space-vector

Shape: (…, N)

spacetimelib.norm2_st(vec_st)

Calculate the square of the norm of a spacetime-vector.

Given an N+1-dimensional spacetime-vector a = (a0, a1, ..., aN), the square norm is norm2_st(a) = - a0^2 + a1^2 + ... + aN^2.

This is traditionally called the squared norm of a four-vector

For instance, if the spacetime-vector is the difference between the coordinates of two events, then its squared norm is the square of proper distance (or the space-like interval) between the events. The negative of the squared norm is the proper time (or the time-like interval) between the events.

Parameters:

vec_st (array_like) –

Any spacetime-vector

Shape: (…, N+1)

spacetimelib.velocity_st(vel_s, light_speed=1)

Calculates the spacetime-velocity vector from a space-velocity vector.

Given a space-velocity v = (v1, ..., vN), the spacetime-velocity is calculated by (1 , v1, ..., vN) / sqrt(1 - |v|**2).

Spacetime-velocity is traditionally called four-velocity in the context of 3+1 Minkowski spacetime.

This is the reverse of spacetimelib.velocity_s().

Parameters:

• vel_s (array_like) –

  Space-velocity of a particle, given by the derivative of each space dimension with respect to coordinate time. If the norm of the space-velocity is equal to or greater than the speed of light, then the spacetime-velocity is undefined and an error will raise.

  Shape: (…, N)

• light_speed (array_like, optional) –

  Scalar Speed of light.

  Default: 1

spacetimelib.velocity_s(vel_st)

Calculates the space-velocity vector from a spacetime-velocity vector.

This is the reverse of spacetimelib.velocity_st().

Parameters:

vel_st (array_like) –

Spacetime-velocity of a particle, given by the derivative of each dimension of spacetime (coordinate time dimension comes first) with respect to proper time.

Shape: (…, N+1)

spacetimelib.boost(vec_st, boost_vel_s, light_speed=1, _old=False)

Boost a spacetime-vector by a specified space-velocity.

This operation uses the Lorentz vector transformations as described here: Lorentz Transformation: Vector transformations - Wikipedia

Batched inputs are supported, to allow boosting multiple spacetime-vectors or space-velocities by multiple boost space-velocities in one call.

A single spacetime-vector is given by a 1-D array of N+1 elements, where N is the number of spatial dimensions. The first element is the time coordinate, and the remaining elements are spatial coordinates. For example, if the spacetime-vector represents an event (t, x, y, z) in 3+1 spacetime, t is the time coordinate and x, y, and z are spatial coordinates in a three dimensional space.

A single space-velocity is given by a 1-D array of N elements, derivatives of the spatial dimensions with respect to coordinate time. For example, the space-velocity (v_x, v_y, v_z) can also be written (dx/dt, dy/dt, dz/dt).

Parameters:

• vec_st (array_like) –

  Spacetime-vectors to be boosted.

  Shape: (…, N+1)

• boost_vel_s (array_like) –

  Space-velocity to use as the boost velocity of the Lorentz transformation.

  Shape: (…, N)

• light_speed (array_like, optional) –

  Scalar speed of light.

  Default: 1

Returns:

The boosted spacetime-vector

Return type:

ndarray

spacetimelib.boost_velocity_s(vel_s, boost_vel_s, light_speed=1)

Boost a space-velocity by a specified space-velocity.

This operation uses the Lorentz vector transformations as described here: Lorentz Transformation: Transformation of velocities - Wikipedia

Batched inputs are supported, to allow boosting multiple space-velocities by multiple boost space-velocities in one call.

A single space-velocity is given by a 1-D array of N elements, derivatives of the spatial dimensions with respect to coordinate time. For example, the space-velocity (v_x, v_y, v_z) can also be written (dx/dt, dy/dt, dz/dt).

Parameters:

• vel_s (array_like, optional) –

  Space-velocities to be boosted.

  Shape: (…, N)

  Default: None

• boost_vel_s (array_like) –

  Space-velocity to use as the boost velocity of the Lorentz transformation.

  Shape: (…, N)

• light_speed (array_like, optional) –

  Scalar speed of light.

  Default: 1

Returns:

The boosted space-velocity

Return type:

ndarray

spacetimelib.proper_time_delta(event0, event1)

Calculate the proper time between two events.

The result preserves the sign of the difference between the time coordinates of the two events. So if event1 is in the future with respect to event0, the result is positive; otherwise, the result is negative.

Parameters:

• event0 (array_like) – First event Shape: (…, N+1)

• event1 (array_like) – Second event Shape: (…, N+1)

Returns:

The proper time between the two events. Shape: (…)

Return type:

ndarray

class spacetimelib.Worldline(vertices, ends_vel_s=None, *, past_vel_s=None, future_vel_s=None, proper_time_origin=None, proper_time_offset=0)

The worldline of a particle is represented as a finite list of events, called “vertices”, through which the particle passes in an inertial reference frame. The particle moves in straight lines between the vertices.

Continuous worldlines can only be approximated, with accuracy proportional to the density of vertices.

We can evaluate events along the worldline at any time between the vertices with Worldline.eval().

We can also boost an entire worldline into a different reference frame with Worldline.boost().

Parameters:

• vertices (array_like) –

  A list of spacetime-vectors to use as the vertices of the worldline.

  Events must be sorted by increasing time coordinate.

  Adjacent vertices must be separated by time-like or light-like intervals, since particles are limited by the speed of light. In other words, st.norm2_st(vertices[i+1] - vertices[i]) <= 0 for all i.

  By default, the first and last vertices are treated as end point boundaries, past which events simply cannot be evaluated. The ends_vel_s, past_vel_s, or future_vel_s arguments can be specified to enable linear extrapolation of events that fall outside of these boundaries.

  Size: (M, N+1) for M vertices that each have N+1 dimensions

• ends_vel_s (array_like, optional) –

  Space-velocity of the worldline before and after the first and last vertices. This enables the extrapolation of events that occur before and after the first and last vertices.

  If specified, past_vel_s and future_vel_s must be None.

  Size: (N+1)

  Default: None

Keyword Arguments:

• past_vel_s (array_like, optional) –

  Space-velocity of the worldline before the first vertex. If specified, ends_vel_s must be None.

  Size: (N+1)

  Default: None

• future_vel_s (array_like, optional) –

  Space-velocity of the worldline after the last vertex. If specified, ends_vel_s must be None.

  Size: (N+1)

  Default: None

• proper_time_origin (number, optional) –

  The proper time origin for the worldline. This is the coordinate time at which a stopwatch traveling along the worldline has the value proper_time_offset. By default, the coordinate time of the first vertex in the worldline is chosen.

  Default: vertices[0][0]

• proper_time_offset (number, optional) –

  The value that a stopwatch traveling along the worldline has at the coordinate time proper_time_origin.

  Default: 0

__len__()

Get the number of vertices in the worldline.

Return type:

int

__add__(event_delta)

Add a displacement to all events in the worldline.

Parameters:

event_delta (array_like) – Displacements to add to each dimension.

Return type:

spacetimelib.Worldline

__sub__(event_delta)

Subtract a displacement from all events in the worldline.

Parameters:

event_delta (array_like) – Displacements to subtract from each dimension.

Return type:

spacetimelib.Worldline

__eq__(other)

Check if two worldlines are equal. This checks every property of the two worldlines. If any one of them differs, they are not equal.

Parameters:

other (spacetimelib.Worldline) – Other worldline

Return type:

bool

boost(boost_vel_s)

Boost the worldline to a different inertial reference frame. The vertices, past and future velocities, and :attr:Worldline.proper_time_origin are all boosted.

Parameters:

boost_vel_s (array_like) – Space-velocity to boost the worldline by.

Return type:

spacetimelib.Worldline

eval(time, return_indices=False)

Calculates the event at a specified time on the worldline. The particle travels in straight lines between vertices, so we use simple linear interpolation for this.

To evaluate times that are before or after all of the vertices, ends_vel_s, past_vel_s, or future_vel_s must have been specified in Worldline().

Parameters:

• time (number) – Time at which to evaluate the worldline.

• return_indices (bool, optional) –

  Whether to return the indices of vertices surrounding the specified time.

  Default: False

Returns:

If return_indices == False, just the evaluated event is returned. If return_indices == True, returns a 2-tuple containing the event combined with a 2-tuple of ints for the indices of vertices surrounding the specified time.

Return type:

ndarray or tuple(ndarray, tuple(int, int))

eval_proper_time(time, proper_time_delta)

Calculates the coordinates of the event located at the specified proper time displacement away from a specified time coordinate along the worldline.

Parameters:

• time (number) – Time coordinate

• proper_time_delta (number) – Proper time displacement away from the time coordinate

Return type:

ndarray or tuple(ndarray, tuple(int, int))

eval_vel_s(time)

Calculates the space-velocity at a specified time on the worldline. If the time coincides with a vertex, the future velocity after the vertex is returned.

Parameters:

time (number) – Time at which to evaluate the worldline.

Return type:

ndarray

property future_vel_s

Space-velocity of the worldline after the last vertex.

Returns:

Size: (N)

Return type:

None or array_like

property future_vel_st

Spacetime-velocity of the worldline after the last vertex.

Returns:

Size: (N+1)

Return type:

None or array_like

property ndim

Get the number of spatial plus time dimensions, N+1, for this worldline.

Returns:

N+1

Return type:

int

property past_vel_s

Space-velocity of the worldline before the first vertex.

Returns:

Size: (N)

Return type:

None or array_like

property past_vel_st

Spacetime-velocity of the worldline before the first vertex.

Returns:

Size: (N+1)

Return type:

None or array_like

plot(dim0=1, dim1=0, *, end_extension_time=None)

Get an array that can be given directly to matplotlib.pyplot.plot(), to generate a 2D plot of the worldline in two of its N+1 dimensions.

You will need to expand the array with *, like so: matplotlib.pyplot.plot(*worldline.plot())

Parameters:

• dim0 (int) –

  First dimension to plot

  Default: 1

• dim1 (int) –

  Second dimension to plot

  Default: 0

Keyword Arguments:

end_extension_time (float, optional) –

If not None, add an extra vertex to the past and future if the worldline has a past and future velocity. This is to make it possible to show the past and future sections of the worldline on a Matplotlib plot, since we cannot plot infinitely long rays in Matplotlib.

Default: None

Returns:

Size: (2, M) for M vertices

Return type:

ndarray

proper_time(time)

Calculate the proper time along a section of the worldline between :attr:Worldline.proper_time_origin and a specified time coordinate, plus the :attr:Worldline.proper_time_offset. This is equivalent to reading the value, at coordinate time time, on a stopwatch which is traveling along the worldline, and the stopwatch’s value was set to :attr:Worldline.proper_time_offset at coordinate time :attr:Worldline.proper_time_origin.

Parameters:

time (number) – Time coordinate along the worldline

Return type:

number

proper_time_delta(time0, time1)

Measure the proper time along a section of the worldline between two specified time coordinates. Note that if time1 < time0, result is negative.

Parameters:

• time0 (number) – First time coordinate along the worldline

• time1 (number) – Second time coordinate along the worldline

Return type:

number

property proper_time_offset

Get the proper time offset of the worldline.

Return type:

int or float

property proper_time_origin

Get the proper time origin of the worldline.

Return type:

int or float

vertex(idx)

Get the vertex at the specified index.

Parameters:

idx (int) – The index of the vertex to get.

Returns:

Size: (N+1,)

Return type:

ndarray

class spacetimelib.Frame(worldlines=None, names=None)

An inertial reference frame is represented as a set of Worldline s, all in the same coordinate system. All worldlines in the same frame must have the same number of N+1 dimensions.

Worldline s can be accessed either by name or by index. Index values correspond with the order in which worldlines were added to the frame.

When a Worldline is appended to the frame, it can be given a name. If no name is given, a default name of the format “wl<number>” is automatically assigned to it.

__len__()

__getitem__(key)

__setitem__(key, value)

__add__(event_delta)

Add a displacement to all worldlines in the frame.

Parameters:

event_delta (array_like) – Displacements to add to each dimension.

Return type:

Frame

boost(boost_vel_s, event_delta_pre=None, event_delta_post=None, _batched=True)

Boost each worldline in the frame by the specified velocity.

The event_delta_pre and event_delta_post arguments can be used to add optional spacetime-vector offsets to the frame before and after boosting. This performs the same calculation as calling Frame.__add__() before and after boosting, but it is usually significantly faster to use this combined operation.

Parameters:

• boost_vel_s (array_like) – Space-velocity to boost the frame by.

• event_delta_pre (optional, array_like) –

  Displacement to add to each worldline before boosting.

  Default: None

• event_delta_post (optional, array_like) –

  Displacement to add to each worldline after boosting.

  Default: None

Return type:

Frame

eval(time)

Calculates the event coordinates and proper times for all worldlines at a specified time.

Parameters:

time (number) – Time at which to evaluate the frame.

Returns:

A list containing an entry corresponding to each worldline in the frame, in the same order that worldlines are stored in the Frame. Each entry contains the name, event, and proper time, in that order, for one of the worldlines at the specified time.

Return type:

list[3-tuple(str, ndarray, float)]