API for creating planets and launching missiles. More...

Classes
struct	GrvxTrajectory
	Sequence of spatial and velocity data of a missile. More...

struct	GrvxConfig
	Static configurations. More...

Typedefs
typedef struct GrvxPlanets *	GrvxPlanetsHandle
	Handle to a set of planets forming a closed universe. More...

typedef struct GrvxTrajectory *	GrvxTrajectoryBatch
	Handle to a batch of trajectories. More...

Functions
GRVX_EXPORT const char *	grvx_version (void)
	Returns the version of the library. More...

GRVX_EXPORT GrvxPlanetsHandle	grvx_new_planets (uint32_t n)
	Creates a new planets handle. More...

GRVX_EXPORT void	grvx_delete_planets (GrvxPlanetsHandle handle)
	Deletes all planets of the associated handle and frees the allocated memory. More...

GRVX_EXPORT uint32_t	grvx_count_planets (GrvxPlanetsHandle handle)
	Counts the planets. More...

GRVX_EXPORT int32_t	grvx_set_planet (GrvxPlanetsHandle handle, uint32_t i, double lat, double lon)
	Initializes or overwrites the spatial position of a planet. More...

GRVX_EXPORT int32_t	grvx_get_planet (GrvxPlanetsHandle handle, uint32_t i, double lat, double lon)
	Retrieves the spatial position of a planet. More...

GRVX_EXPORT uint32_t	grvx_pop_planet (GrvxPlanetsHandle handle)
	Removes the last planet from the universe. More...

GRVX_EXPORT GrvxTrajectoryBatch	grvx_new_missiles (uint32_t n)
	Creates a new batch of uninitialized missiles. More...

GRVX_EXPORT void	grvx_delete_missiles (GrvxTrajectoryBatch batch)
	Deletes a batch of missiles and frees the allocated memory. More...

GRVX_EXPORT struct GrvxTrajectory *	grvx_get_trajectory (GrvxTrajectoryBatch batch, uint32_t i)
	Extracts a missile by ID from the given missile batch. More...

GRVX_EXPORT int32_t	grvx_init_missile (struct GrvxTrajectory *trj, double lat, double lon, double v, double dlat, double dlon)
	Initializes the position and velocity of a missile on the sphere. More...

GRVX_EXPORT int32_t	grvx_launch_missile (struct GrvxTrajectory *trj, GrvxPlanetsHandle planets_handle, uint32_t planet_id, double v_abs, double psi)
	Initializes a missile on the rim of a given planet. More...

GRVX_EXPORT uint32_t	grvx_propagate_missile (struct GrvxTrajectory trj, GrvxPlanetsHandle planets, double h, int32_t premature)
	Propagates a missile in the gravitational force field of planets. More...

GRVX_EXPORT double	grvx_lat (double z)
	Computes the latitudinal position, \(\phi\), from Cartesian coordinates. More...

GRVX_EXPORT double	grvx_lon (double x, double y)
	Computes the longitudinal position, \(\lambda\), from Cartesian coordinates. More...

GRVX_EXPORT double	grvx_vlat (double vx, double vy, double vz, double lat, double lon)
	Computes the latitudinal speed, \(\dot\phi\), from Cartesian coordinates. More...

GRVX_EXPORT double	grvx_vlon (double vx, double vy, double vz, double lon)
	Computes the (scaled) longitudinal speed, \(\dot\lambda \cos\phi\), from Cartesian coordinates. More...

GRVX_EXPORT double	grvx_v_esc (void)
	Escape velocity \(p_\pi\) for isolated planets. More...

GRVX_EXPORT double	grvx_v_scrcl (double r)
	Velocity of a missile on a small circle for isolated planets. More...

GRVX_EXPORT double	grvx_orb_period (double v0, double h)
	Orbital period for isolated planets. More...

GRVX_EXPORT void	grvx_perturb_measurement (GrvxPlanetsHandle planets_handle, uint32_t planet_id, double angular_error, double lat, double lon)
	Perturbs measurement by assuming finite angular resolution. More...

GRVX_EXPORT struct GrvxConfig *	grvx_get_config (void)
	Returns static configuration. More...

GRVX_EXPORT void	grvx_free_config (struct GrvxConfig *cfg)
	Frees GrvxConfig instance. More...

Detailed Description

API for creating planets and launching missiles.

The API of gravix2's physics engine should be used to create planets and launch missiles. Upon calling grvx_propagate_missile(), missiles move on the surface of a unit sphere and in a conservative gravitational force field generated by static planets.

In order to simulate the propagation of missiles, planets have to be defined. Use grvx_new_planets() and grvx_set_planet() to create and initialize new planets and pass the handle returned by the former when required by other functions. It is the obligation of the caller to free allocated memory when necessary by calling grvx_delete_planets() for planets and grvx_delete_missiles() for missiles.

Missiles are created via grvx_new_missiles(). Note that grvx_new_planets() should be used to craft separate universes, whereas multiple calls to grvx_new_missiles() can be used in the same universe (referred to by the same planet handle.) However, each call to grvx_new_missiles() will dynamically allocate memory and thus comes with a computational overhead during runtime.

Each missile is represented by a GrvxTrajectory parametrized by a sequence of spatial and velocity data, represented in Cartesian coordinates. In order to transform this parametrization back into a spherical parametrization using latitude and longitude pairs, the helper functions grvx_lat(), grvx_lon(), grvx_vlat(), and grvx_vlon() can be used. Note that all spherical coordinates, such as the latitude and longitude, are always given in radians. Simply scale those values with \(180^\circ / \pi \approx 57.296^\circ\) to obtain the corresponding values in units of degrees.

For universes with a single planet, missiles launched at this planet will always come back. If launched with a sufficiently large momentum, missiles propagate on a great circle of the unit sphere and eventually hit the planet on the opposite side. We refer to this critical momentum as the escape velocity, grvx_v_esc(), and to the integrated time between launching the missile and its collision with the planet as the orbital period, grvx_orb_period().

Although not necessarily needed for dealing with the API, the static configurations set during compilation of the library can be readout via grvx_get_config().

Typedef Documentation

◆ GrvxPlanetsHandle

typedef struct GrvxPlanets* GrvxPlanetsHandle

Handle to a set of planets forming a closed universe.

Planets are kept intentionally opaque in the API and should only be referred to by their respective handle. Internals are subjects to change.

◆ GrvxTrajectoryBatch

typedef struct GrvxTrajectory* GrvxTrajectoryBatch

Handle to a batch of trajectories.

For the sake of minimizing the number of memory allocation, trajectories can be allocated in batches. A batch is referred to as a handle to trajectories.

Function Documentation

◆ grvx_count_planets()

GRVX_EXPORT uint32_t grvx_count_planets ( GrvxPlanetsHandle handle )

Counts the planets.

Parameters

handle The planets handle.

Returns: Number of planets.

Here is the caller graph for this function:

◆ grvx_delete_missiles()

GRVX_EXPORT void grvx_delete_missiles ( GrvxTrajectoryBatch batch )

Deletes a batch of missiles and frees the allocated memory.

Parameters

batch The handle to the batch.

Here is the caller graph for this function:

◆ grvx_delete_planets()

GRVX_EXPORT void grvx_delete_planets ( GrvxPlanetsHandle handle )

Deletes all planets of the associated handle and frees the allocated memory.

Parameters

handle The planets handle.

◆ grvx_free_config()

GRVX_EXPORT void grvx_free_config ( struct GrvxConfig * cfg )

Frees GrvxConfig instance.

Deletes an existing GrvxConfig instance. Reading from an already freed GrvxConfig instance is undefined.

Parameters

cfg	The GrvxConfig instance.

◆ grvx_get_config()

GRVX_EXPORT struct GrvxConfig* grvx_get_config ( void )

Returns static configuration.

A new GrvxConfig instance is allocated and returned. It is the obligation of the caller to free the object after use via grvx_free_config().

Returns: Static configuration.

◆ grvx_get_planet()

GRVX_EXPORT int32_t grvx_get_planet	(	GrvxPlanetsHandle	handle,
		uint32_t	i,
		double *	lat,
		double *	lon
	)

Retrieves the spatial position of a planet.

Retrieves the spatial position of a planet. See grvx_set_planet() for how to set these values.

Parameters

handle	The planets handle.
i	ID of the planet to be initialized.
lat	Latitude.
lon	Longitude.

Returns: Zero on success.

◆ grvx_get_trajectory()

GRVX_EXPORT struct GrvxTrajectory* grvx_get_trajectory	(	GrvxTrajectoryBatch	batch,
		uint32_t	i
	)

Extracts a missile by ID from the given missile batch.

Missiles are referred to by unique and static IDs within a batch. For a batch of size \(n\) (cf. grvx_new_missiles()) the IDs are the integer values \([0, 1, 2, \ldots, n-1]\).

Parameters

batch	The handle to the missile batch.
i	The missile ID. The behavior of requesting invalid IDs is undefined.

Returns: The trajectory handle of the requested missile.

◆ grvx_init_missile()

GRVX_EXPORT int32_t grvx_init_missile	(	struct GrvxTrajectory *	trj,
		double	lat,
		double	lon,
		double	v,
		double	dlat,
		double	dlon
	)

Initializes the position and velocity of a missile on the sphere.

The missile is aligned on the surface of the sphere s.t. it is pointing towards \(\Delta \phi\) and \(\Delta \lambda \, \cos \phi\) where the former (latter) is the difference in latitude (longitude). The magnitude of the vector is given separately by v.

For convenience, this function will also write the initial values into the first slot of the trajectory (index 0) where they can be read out safely. This value is overwritten by calling grvx_propagate_missile().

Note that even if the initial velocity is set to zero, either dlat or dlon has to be set to a non-zero value. In fact, the magnitude of the orientation is never taken into account (only the orientation matters). Hence, for the sake of numerical stability, an orientation of unit length is always preferable.

Parameters

trj	The trajectory handle as obtained from grvx_get_trajectory().
lat	The initial latitude, \(\phi\).
lon	The initial longitude, \(\lambda\).
v	The intitial velocity, \(\sqrt{\dot\phi^2 + (\dot\lambda \, \cos\phi)^2}\).
dlat	The intitial latitudinal orientation, \(\Delta \phi\).
dlon	The intitial longitudinal orientation, \(\Delta \lambda \, \cos\phi\).

Returns: Zero on success.

◆ grvx_lat()

GRVX_EXPORT double grvx_lat ( double z )

Computes the latitudinal position, \(\phi\), from Cartesian coordinates.

Parameters

z	(Third) \(z\)-coordinate of Cartesian representation.

Returns: Latitude, \(\phi\).

Here is the caller graph for this function:

◆ grvx_launch_missile()

GRVX_EXPORT int32_t grvx_launch_missile	(	struct GrvxTrajectory *	trj,
		GrvxPlanetsHandle	planets_handle,
		uint32_t	planet_id,
		double	v_abs,
		double	psi
	)

Initializes a missile on the rim of a given planet.

The missile is placed on the rim of the planet with a radial bearing pointing away from the planet center if the initial velocity is positive. The rim is defined as a circle centered at the planet. Propagation of missiles that fall inside this circle is stopped, cf. grvx_propagate_missile().

For convenience, this function will also write the initial values into the first slot of the trajectory (index 0) where they can be read out safely. Note that this value is overwritten by calling grvx_propagate_missile().

Parameters

trj	The trajectory handle as obtained from grvx_get_trajectory().
planets_handle	The planets handle.
planet_id	The planet ID.
v_abs	Magnitude of the initial velocity, \(\sqrt{\dot\phi^2 + (\dot\lambda \cos\phi)^2}\), where \(\phi\) and \(\lambda\) are the latitudinal and longitudinal position on the rim, respectively, and the dot indicates temporal derivatives.
psi	The azimuthal position on the rim.

Returns: Zero on success.

◆ grvx_lon()

GRVX_EXPORT double grvx_lon	(	double	x,
		double	y
	)

Computes the longitudinal position, \(\lambda\), from Cartesian coordinates.

Parameters

x	(First) \(x\)-coordinate of Cartesian representation.
y	(Second) \(y\)-coordinate of Cartesian representation.

Returns: Longitude, \(\lambda\).

Here is the caller graph for this function:

◆ grvx_new_missiles()

GRVX_EXPORT GrvxTrajectoryBatch grvx_new_missiles ( uint32_t n )

Creates a new batch of uninitialized missiles.

Use grvx_get_trajectory() and either grvx_init_missile() or grvx_launch_missile() to initialize missiles. The behavior of propagating uninitialized missiles is undefined.

Parameters

n	Number of missiles to be bundled into a batch.

Returns: The handle to the batch.

Here is the caller graph for this function:

◆ grvx_new_planets()

GRVX_EXPORT GrvxPlanetsHandle grvx_new_planets ( uint32_t n )

Creates a new planets handle.

Allocates a new set of planets and returns a handle. It is the obligation of the caller to initialize all planets before propagating missiles and to prevent memory leakage by deleting all planets with grvx_delete_planets().

Parameters

n	Number of planets.

Returns: Planets handle to yet uninitialized planets.

◆ grvx_orb_period()

GRVX_EXPORT double grvx_orb_period	(	double	v0,
		double	h
	)

Orbital period for isolated planets.

For isolated planets: Integrated time between launching and touching the rim of the planet for the first time. If v0 > grvx_v_esc() the missile propagates on a great circle of the unit sphere and collides with the planet after an integrated path length of \(2(\pi - \delta)\) where \(\delta\) is the radius of the planet's rim.

This method returns a more precise value than one would get by calling grvx_propagate_missile() until the premature flag is set.

Parameters

v0	Initial speed.
h	The step size of the integrator. Typically, this value should be \(\ll 1\).

Returns: Orbital period.

Here is the call graph for this function:

◆ grvx_perturb_measurement()

GRVX_EXPORT void grvx_perturb_measurement	(	GrvxPlanetsHandle	planets_handle,
		uint32_t	planet_id,
		double	angular_error,
		double *	lat,
		double *	lon
	)

Perturbs measurement by assuming finite angular resolution.

An observation of an event at a given planet is measured with a finite angular resolution. The given latitude and longitude pair is moved on a small circle centered at the planet by angular_error. The (ground truth) position of the event is read from lat and lon, and eventually updated with the new perturbed values.

Parameters

planets_handle	The planets handle.
planet_id	The planet ID.
angular_error	The angular error that shifts the event position.
lat	Latitudinal position of the event.
lon	Longitudinal position of the event.

Here is the call graph for this function:

◆ grvx_pop_planet()

GRVX_EXPORT uint32_t grvx_pop_planet ( GrvxPlanetsHandle handle )

Removes the last planet from the universe.

The last planet in the universe is the one with the largest ID. If called \(k\) times for a universe with \(n\) planets, \(n-k\) planets remain. If \(k > n\) the behavior is undefined.

Parameters

handle The planets handle.

Returns: Number of remaining planets in the universe.

◆ grvx_propagate_missile()

GRVX_EXPORT uint32_t grvx_propagate_missile	(	struct GrvxTrajectory *	trj,
		GrvxPlanetsHandle	planets,
		double	h,
		int32_t *	premature
	)

Propagates a missile in the gravitational force field of planets.

Before calling this method for the first time each missile has to be initialized by either using grvx_init_missile() or grvx_launch_missile(). Afterwards, multiple calls to this method can be chained until the premature flag is set. The behavior of any subsequent calls is undefined until a missile is reinitialized using either grvx_init_missile() or grvx_launch_missile().

Consider a trajectory sequence [x, x+1, x+2, ..., x+N] where x refers to some point in phase space and x+1 to its immediate successor. Let 2 be the return value of this function, then the updated sequence corresponds to [x+N+1, x+N+2, x+2, ..., x+N], i.e., the first two values were updated by the integrator. In particular, initial values at the first position are overwritten upon calling.

If a missile propagates inside the rim of a planet, cf. grvx_launch_missile(), the premature flag is set to a non-zero value and propagation is stopped.

Parameters

trj	The trajectory handle as obtained from grvx_get_trajectory().
planets	The planets handle.
h	The step size of the integrator. Typically, this value should be \(\ll 1\).
premature	Set to non-zero values if propagation was stopped prematurely. If set this also indicates that the last time interval between consecutive steps of the trajectory is shorter than those of the other consecutive steps.

Returns: Number of simulated steps stored into the trajectory sequence. This value should be used to safely readout the data from GrvxTrajectory, i.e., let \(n\) be the returned value, then the first \(n\) points of trj were updated by the integrator. Note that this value does not change if the missile passes a planet rim within the last integration step! (The premature flag is still set in this case.)

◆ grvx_set_planet()

GRVX_EXPORT int32_t grvx_set_planet	(	GrvxPlanetsHandle	handle,
		uint32_t	i,
		double	lat,
		double	lon
	)

Initializes or overwrites the spatial position of a planet.

Planets are referred to by unique IDs. For \(n\) planets (see grvx_new_planets()) the IDs are the integer values \([0, 1, 2, \ldots, n-1]\). Note that all planets of a universe have to be initialized before missiles are propagated.

Parameters

handle	The planets handle.
i	ID of the planet to be initialized.
lat	Latitude.
lon	Longitude.

Returns: Zero on success.

Here is the caller graph for this function:

◆ grvx_v_esc()

GRVX_EXPORT double grvx_v_esc ( void )

Escape velocity \(p_\pi\) for isolated planets.

For isolated planets: Minimal initial momentum necessary to asymptotically reach a distance of \(\pi\) to the center of the planet if launched on its rim.

Returns: Escape velocity, \(p_\pi\).

Here is the caller graph for this function:

◆ grvx_v_scrcl()

GRVX_EXPORT double grvx_v_scrcl ( double r )

Velocity of a missile on a small circle for isolated planets.

For isolated planets: Velocity of a missile on a small circle with radius r and centered at the isolated planet.

Parameters

r	Radius of small circle.

Returns: Constant velocity for the given small circle.

◆ grvx_version()

GRVX_EXPORT const char* grvx_version ( void )

Returns the version of the library.

Returns: Version of the library.

◆ grvx_vlat()

GRVX_EXPORT double grvx_vlat	(	double	vx,
		double	vy,
		double	vz,
		double	lat,
		double	lon
	)

Computes the latitudinal speed, \(\dot\phi\), from Cartesian coordinates.

Parameters

vx	(First) \(x\)-component of velocity in Cartesian representation.
vy	(Second) \(y\)-component of velocity in Cartesian representation.
vz	(Third) \(z\)-component of velocity in Cartesian representation.
lat	Latitude, \(\phi\) as obtained from lat().
lon	Longitude, \(\lambda\) as obtained from lon().

Returns: Latitudinal speed, \(\dot\phi\).

Here is the call graph for this function:

◆ grvx_vlon()

GRVX_EXPORT double grvx_vlon	(	double	vx,
		double	vy,
		double	vz,
		double	lon
	)

Computes the (scaled) longitudinal speed, \(\dot\lambda \cos\phi\), from Cartesian coordinates.

Parameters

vx	(First) \(x\)-component of velocity in Cartesian representation.
vy	(Second) \(y\)-component of velocity in Cartesian representation.
vz	(Third) \(z\)-component of velocity in Cartesian representation.
lon	Longitude, \(\lambda\) as obtained from grvx_lon().

Returns: (Scaled) longitudinal speed, \(\dot\lambda \cos\phi\).

Here is the call graph for this function:

Classes

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ GrvxPlanetsHandle

◆ GrvxTrajectoryBatch

Function Documentation

◆ grvx_count_planets()

◆ grvx_delete_missiles()

◆ grvx_delete_planets()

◆ grvx_free_config()

◆ grvx_get_config()

◆ grvx_get_planet()

◆ grvx_get_trajectory()

◆ grvx_init_missile()

◆ grvx_lat()

◆ grvx_launch_missile()

◆ grvx_lon()

◆ grvx_new_missiles()

◆ grvx_new_planets()

◆ grvx_orb_period()

◆ grvx_perturb_measurement()

◆ grvx_pop_planet()

◆ grvx_propagate_missile()

◆ grvx_set_planet()

◆ grvx_v_esc()

◆ grvx_v_scrcl()

◆ grvx_version()

◆ grvx_vlat()

◆ grvx_vlon()