Documentation

Module contents

We alias import gravix2.gravix2.Gravix2 as load_library for convenience, such that loading and interacting with libgravix2.so becomes straightforward:

Example:

import gravix2

lib = gravix2.load_library('path_to_libgravix2.so')
lat = lib.get_lat(z=45)
...

Gravix2

class gravix2.gravix2.Gravix2(lib: str | Path | CDLL)

Bases: object

Proxy class for libgravix2

Parameters:: lib – Library path to libgravix2.so

property config: Config

Wraps libgravix2’s GrvxConfig object

Returns:: Static configuration as a gravix2.config.Config instance

estimate_orb_period(*, v0: float, h: float) → float

Wraps call to libgravix2’s helper function grvx_orb_period()

Parameters:

v0 – Initial velocity
h – Step size

Returns:

Orbital period

Reimplements libgravix2’s helper function grvx_lat() for NumPy arrays

Parameters:

z – (Batch of) First parameter of grvx_lat()
fwd – Bypass reimplementation and forward call to libgravix2 (does not work for NumPy arrays)

Returns:

(Batch of) Latitude

Reimplements libgravix2’s helper function grvx_lon() for NumPy arrays

Parameters:

x – (Batch of) First parameter of grvx_lon()
y – (Batch of) Second parameter of grvx_lon()
fwd – Bypass reimplementation and forward call to libgravix2 (does not work for NumPy arrays)

Returns:

(Batch of) Longitude

Reimplements libgravix2’s helper function grvx_v_lat() for NumPy arrays

Parameters:

v – Tuple of first three parameters of grvx_v_lat() or NumPy array of shape (*, 3)
lat – (Batch of) Fourth parameter of grvx_v_lat()
lon – (Batch of) Fifth parameter of grvx_v_lat()
fwd – Bypass reimplementation and forward call to libgravix2 (does not work for NumPy arrays)

Returns:

(Batch of) Latitudinal speed

Reimplements libgravix2’s helper function grvx_v_lat() for NumPy arrays

Parameters:

v – (Batch of) Tuple of first three parameters of grvx_v_lon()
lon – (Batch of) Fourth parameter of grvx_v_lat()
fwd – Bypass reimplementation and forward call to libgravix2 (does not work for NumPy arrays)

Returns:

(Batch of) Scaled longitudinal speed

new_missiles(missiles: int) → Missiles

Creates a new set of uninitialized missiles

Parameters:: missiles – Number of missiles
Returns:: A new set of missiles

new_planets(planets: int | Sequence[Tuple[float, float]], *, seed: int | None = None, min_dist: float | None = None) → Planets

Creates a new set of planets

Planets are either initialized explicitly or randomly via libgravix2’s grvx_rnd_init_planets() (from the game extension.)

If initialized randomly, a min. distance between planets has to be given.

Parameters:

planets – Number of planets (random initialization) or list of latitude and longitude pairs (explicit initialization.) If the parameter is an integer, this many planets are initialized randomly. Otherwise, the latitude/longitude pairs are used for (explicit) initialization.
seed – If planets are initialized randomly, a seed can be passed to make the sampling result consistent. If set to None, a random seed will be generated internally.
min_dist – If planets are initialized randomly, a min. distance is required. See libgravix2’s grvx_rnd_init_planets() for details (from the game extensions.)

Returns:

A new set of planets

property v_esc: float

Returns the escape velocity

Calls libgravix2’s helper function grvx_v_esc() on first call. The result is saved and returned on this and all subsequent calls.

Returns:: Escape velocity

v_scrcl(r) → float

Wraps call to libgravix2’s helper function grvx_v_scrcl()

Parameters:: r – Radius of small circle
Returns:: Small circle velocity

Planets

class gravix2.planet.Planets(planets: int | Sequence[Tuple[float, float]], *, seed: int | None = None, min_dist: float | None = None, lib: CDLL)

Bases: object

Proxy class for operations on libgravix2’s Planets

New planets are allocated and initialized either at the provided coordinates or randomly. Planets can be accessed and removed by referring to them by their respective indices. Removing planets can rearrange the internal representation and indices associations might change. Use gravix2.planet.Planets.planet_id() to get a static and unique identification (ID) for each planet. Initially, indices and IDs are identically.

Use gravix2.gravix2.Gravix2.new_planets() to create a new instance.

Parameters:

planets – Number of planets or list of latitude and longitude pairs. If this parameter is an integer, this many planets are initialized randomly.
seed – If planets are initialized randomly a seed can be passed. If None a random seed will be generated.
min_dist – If planets are initialized randomly, a min. distance is required.
lib – libgravix2 library

new_game(*, dt: float) → Game

Creates a new game instance

Creates a new game instance from libgravix2’s game extension.

Parameters:: dt – Step size of simulation
Returns:: A new game

perturb_measurement(idx: int, *, lat: float, lon: float, angular_error: float) → Tuple[float, float]

Shifts measurement by an angular offset.

Shifts a measurement taken on the given planet by an angular offset. See libgravix’s grvx_perturb_measurement() for details.

Parameters:

idx – Planet index
lat – Latitudinal position of measurement
lon – Longitudinal position of measurement
angular_error – Angular offset.

Returns:

Perturbed measurement

property planet_id: List[int]

Mapping between planet indices and their unique IDs

Returns:: List of IDs sorted by index

property planet_pos: List[Tuple[float, float]]

List of planet positions

Returns:: List of planet positions ordered by index

remove_planet(idx: int) → None

Removes a planet by index

Removal of planets changes the mapping of indices and planet IDs. These changes are reflected in gravix2.planet.Planets.planet_id().

Parameters:: idx – Planet index
Returns:: None

Missiles

class gravix2.missile.Missile(*, missile: c_void_p, lib: CDLL)

Bases: object

Proxy class for operations on libgravix2’s Missile

Note that missiles have to be initialized via gravix2.missile.Missile.set() or gravix2.missile.Missile.launch() before they can be propagated.

Use gravix2.missile.Missiles to create a new instance.

Parameters:

missile – Missile
lib – libgravix2 library

launch(*, planets: Planets, planet_idx: int, v: float, psi: float) → None

Wrapper for libgravix2’s grvx_launch_missile() function

Parameters:

planets – The planets
planet_idx – The planet index (not ID)
v – Initial velocity
psi – Initial azimuthal position

Returns:

None

propagate(planets: Planets, *, h: float) → bool

Wrapper for libgravix2’s grvx_propagate_missile() function

On success the gravix2.missile.Missile.propagate() is filled.

Parameters:

planets – The planets
h – The step size

Returns:

Flag indicating whether propagation was stopped prematurely

set(*, pos: Sequence[float], orientation: Sequence[float], v: float) → None

Wrapper for libgravix2’s grvx_init_missile() function

The initial position and orientation can either be passed as 2D tuples of latitudinal and longitudinal components or as 3D tuples in their respective Cartesian representation. If passed as 2D tuples libgravix2’s helper functions grvx_lat(), grvx_lon(), grvx_v_lat() and grvx_v_lon() are used for conversions.

Parameters:

pos – Initial position
orientation – Initial orientation
v – Initial velocity

Returns:

None

property trajectory: Trajectory

Trajectory as generated by gravix2.missile.Missile.propagate()

Returns:: The trajectory

class gravix2.missile.Missiles(n: int, *, lib: CDLL)

Bases: object

A sequence of gravix2.missile.Missile corresponding to libgravix’s Missiles.

This proxy covers all necessary (de)allocations of libgravix’s GrvxTrajectoryBatch from the user and should behave like a tuple of gravix2.missile.Missile:

Example

planets = lib.new_planets([...])
...
missiles = lib.new_missiles(3)
[m.set(pos=(0., 0.), vel=(0., 0.)) for m in missiles]
m[0].propagate(planets, h=1e-3)
...

Use gravix2.Gravix2.new_missiles() to create a new sequence of instances.

Parameters:

n – Number of missiles
lib – libgravix2 library

Bases: object

A sequence of positional and velocity data in Cartesian coordinates

Parameters:

x – Position
v – Velocity

v: _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]

x: _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]

Helper

class gravix2.helper.Helper(*, lib: CDLL): Bases: object

Config

class gravix2.config.Config(pot_type: str, n_pot: int | None, trajectory_size: int, int_steps: int, min_dist: float, composition_scheme: str, n_stages: int)

Bases: object

libgravix2 static configuration

Parameters:

pot_type – Same as GRVX_POT_TYPE
n_pot – Same as GRVX_N_POT
trajectory_size – Same as GRVX_TRAJECTORY_SIZE
int_steps – Same as GRVX_INT_STEPS
min_dist – Same as GRVX_MIN_DIST
composition_scheme – Same as GRVX_COMPOSITION_SCHEME
n_stages – Number of stages of the composition method

composition_scheme: str

int_steps: int

min_dist: float

n_pot: int | None

n_stages: int

pot_type: str

trajectory_size: int

gravix2.config.get_config(*, lib: CDLL) → Config

Returns libgravix2’s static GrvxConfig

Parameters:: lib – libgravix2 library
Returns:: The static configuration

Game Extension

class gravix2.extensions.game.Game(*, planets: c_void_p, dt: float, lib: CDLL)

Bases: object

Proxy class for libgravix2’s game extension

A new game is created. The functions gravix2.extensions.game.Game.request_launch() and gravix2.extensions.game.Game.tick() map (almost) directly to their counterparts grvx_request_launch() and grvx_observe_or_tick(), respectively.

Use gravix2.planet.Planet.new_game() to create a new instance.

Parameters:

planets – Planet handel
dt – Step size of simulation
lib – libgravix2 library

request_launch(*, planet_idx: int, t_start: float, dt_ping: float, dt_end: float, v: float, psi: float) → None

Requests a missile launch

Requests a missile launch via libgravix2’s grvx_request_launch().

Parameters:

planet_idx – The planet index
t_start – Requested launch time
dt_ping – Requested time to send a ping after launch
dt_end – Requested time of self-destruction
v – Requested initial velocity
psi – Orientation during launch

tick() → List[Detonation | Ping]

Advances time

Advances time via libgravix2’s grvx_observe_or_tick() and bundles observations in a list. Note that this behavior is different from the C-API and a single call to this function will always advance time.

An observable event is either a gravix2.extensions.observation.Ping or a gravix2.extensions.observation.Detonation.

Returns:: List of observables

Observable events

class gravix2.extensions.observation.Detonation(planet_idx: int, t: float)

Bases: object

Parameters:

planet_idx – The planet index
t – Tick

planet_idx: int

t: float

class gravix2.extensions.observation.Ping(t: float, lat: float, lon: float)

Bases: object

Parameters:

t – Tick
lat – Latitude
lon – Longitude

lat: float

lon: float

t: float