GeodesicEngine

The main object in PyGRO to perform numerical integrations of the geodesic equations is the GeodesicEngine class.

class pygro.geodesic_engine.GeodesicEngine(metric: Metric | None = None, backend: Literal['autowrap', 'lambdify'] = 'autowrap', integrator: Literal['rkf45', 'dp45', 'ck45', 'rkf78', 'dp853'] = 'rkf45')[source]View on GitHub

The main numerical class in PyGRO. It deals with performing the numerical operations to integrate a Geodesic object.

After linking a Metric to the GeodesicEngine, the latter will have the following attributes:

Variables:

  • motion_eq (Iterable[Callable]) – A callable of the coordinates and their derivatives which returns the right-hand-side of the geodesic equations (casted to a first-order system of ODEs). For example, given the coordinates ["t", "x", "y", "z"], the motion_eq will be of type (t, x, y, z, u_t, u_x, u_y, u_z) -> Iterable[float] of dimension 8.

  • u[i]_f_timelike (Callable[Iterable[float], float]) – a helper function that returns the numerical value of the i-th component of the 4-velocity of a massive test particle as a function of the others, which normalizes the 4-velocity to \(g_{\mu\nu}\dot{x}^\mu\dot{x}^\nu = -1\)

  • u[i]_f_null (Callable[Iterable[float], float]) – a helper function that returns the numerical value of the i-th component of the 4-velocity of a null test particle as a function of the others, which normalizes the 4-velocity to \(g_{\mu\nu}\dot{x}^\mu\dot{x}^\nu = 0\)

  • stopping_criterion (StoppingCriterionList) – a StoppingCriterionList representing the list of conditions to check at each integration step to determine whether to stop the integration or not.

__init__(metric: Metric | None = None, backend: Literal['autowrap', 'lambdify'] = 'autowrap', integrator: Literal['rkf45', 'dp45', 'ck45', 'rkf78', 'dp853'] = 'rkf45')[source]View on GitHub

The GeodesicEngine constructor accepts the following arguments:

Parameters:

  • metric (Metric) – The Metric object to link to the GeodesicEngine and from which the geodesic equations and all the related symbolic quantities are retrieved. If not provided, the GeodesicEngine will be linked to the last initialized Metric.

  • backend (Literal["autowrap", "lambdify"]) – The symbolic backend to use. If autowrap (defaul option) the symbolic expression will be converted, upon linking the Metric to the GeodesicEngine, in pre-compiled C low-level callable with a consitent gain in performance of single function-calls. If lambdify the geodesic equations will not be compiled as C callables and will be converted to Python callables, with a loss in performances. The GeodesicEngine will fallback to a lambdify whenever auxiliary py-functions are used to define the Metric object (see Define your own space-time for an example).

  • integrator (Literal['rkf45', 'dp45', 'ck45', 'rkf78']) – Specifies the numerical integration schemes used to carry out the geodesic integration. See Integrators. Default is rkf45 correspoding to the RungeKuttaFehlberg45 integrator.

add_stopping_criterion(expr: str, exit_str: str = 'none')[source]View on GitHub

Adds a StoppingCriterion to the StoppingCriterionList of the GeodesicEngine. Has the same parameters as set_stopping_criterion()

integrate(geo: Geodesic, tauf: float, initial_step: float, verbose: bool = False, direction: Literal['fw', 'bw'] = 'fw', **integrator_kwargs) → None[source]View on GitHub

The main function for the numerical integration. Accepts an initialized Geodesic (i.e. with appropriately set initial space-time position and 4-velocity), performs the numerical integration of the geodesic equations up to the provided final value of the affine parameter tauf or until a stopping condition is met, and returns to the input Geodesic object the integrated numerical array.

See Integrate a geodesic in PyGRO for a complete tutorials.

Parameters:

  • geo (Geodesic) – the Geodesic to be integrated.

  • tauf (float) – the value of the final proper time at which to stop the numerical integration.

  • initial_step (float) – the value of the initial proper time step.

  • verbose (bool) – whether to log the integration progress to the standard output or not.

  • direction (Literal["fw", "bw"]) – if “fw” the integration is carried on forward in proper time; if “bw” the integration is carried on backward in proper time. The correct signs for tauf and initial_step will be assigned automatically.

  • integrator_kwargs – the kwargs to be passed to the integrator.

set_stopping_criterion(expr: str, exit_str: str = 'none')[source]View on GitHub

Creates a StoppingCriterion given the symbolic expression contained in the expr argument and sets is as the sole stopping criterion for the GeodesicEngine.

Parameters:

  • expr (str) – a string to be sympy-parsed containing the expression that will be evaluated at each integration time-step.

  • exit_str (str) – the exit message that will be attached to the Geodesic when the stopping condition is met (i.e. when the condition in expr return False).

class pygro.geodesic_engine.StoppingCriterion(stopping_criterion: Callable[[ArrayLike], bool], expr: str, exit_str: str)[source]View on GitHub

An helper class to deal with stopping criterion. Requires as input the lambdified callable (stopping_criterion) built from a sympy symboic expression (expr) and can be called on a given geodesic step to return either True if the condition in the expression is verified or False when it is not, stopping the integration. It also requires an exit message (exit_str), useful to flag a geodesic that fires the stopping criterion (i.e. a geodesic that ends in an horizon).

class pygro.geodesic_engine.StoppingCriterionList(stopping_criterions: list[StoppingCriterion])[source]View on GitHub

An aggregator of multiple StoppingCriterion objects. When called on a geodesic it tests multiple stopping criterions on the last step and returns False if at least one of the stopping_criterions is falsy. In that case stores the exit of the stopping criterion that fired the condition.