Metric

The main symbolic object in PyGRO is the pygro.Metric class which is used to describe the space-time metric and contains a variety of helper function to perform the symbolic calculations and obtain the geodesic equations.

class pygro.metric_engine.MetricView on GitHub

This is the main symbolic tool within PyGRO to perform tensorial calculations starting from the space-time metric. PyGRO uses the signature convention $(-,+,+,+)$.

After successful initialization (Metric.__init__()), the Metric instance has the following attributes:

Variables:

• g (sympy.Matrix) – The symbolic representation of the $4\times 4$ metric tensor.

• g_inv (sympy.Matrix) – The symbolic representation of the $4\times 4$ inverse metric tensor.

• x (list[sympy.Symbol]) – The symbolic representation of the space-time coordinates.

• dx (list[sympy.Symbol]) – The symbolic representation of the space-time coordinate differential.

• u (list[sympy.Symbol]) – The symbolic representation of the components 4-velocity (derivatives of the coordinates w.r.t. an affine parameter).

• eq_u (list[sympy.Basic]) – The computed geodesic equations, i.e. the right-hand-side of the equation ${\ddot{x}}^{\mu }=-{\mathrm{\Gamma }}_{\nu \rho }^{\mu }{\dot{x}}^{\nu }{\dot{x}}^{\rho }$ where ${\mathrm{\Gamma }}_{\nu \rho }^{\mu }$ are the Metric.Christoffel() symbols of the metric.

• u[i]_null (sympy.Basic) – The expression 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$

• u[i]_timelike (sympy.Basic) – The expression 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$

• transform_functions (list[sympy.Basic]) – The expressions transform functions to pseudo-cartesian coordinates that can be either passed as arguments of the Metric constructor or set with the Metric.set_coordinate_transformation() method.

__init__(name: str, coordinates: list[str], line_element: str | None = None, tensor: MutableDenseMatrix | None = None, transform: list[str] | None = None, load: str | None = None, **params)View on GitHub

To instantiate a new Metric object call

>>> spacetime_metric = pygro.Metric(name, coordinates, line_element)

or

>>> spacetime_metric = pygro.Metric(name, coordinates, tensor)

with:

Parameters:

• name (str) – The name of the metric to initialize.

• coordinates (list[str]) – Four-dimensional list containing the symbolic expression of the space-time coordinates in which the line_element argument is written.

• line_element (Optional[str]) – A string containing the symbolic expression of the line element (that will be parsed using sympy) expressed in the space-time coordinates defined in the coordinates argument.

• tensor (Optional[sp.Matrix]) – A sympy matrix containing the symbolic expression of the matrix rappresentation of the metric tensor in the given space-time coordinets.

• transform (list[str]) – Symbolic expressions containing the transformations between the chosen system of coordinates and a pseud-cartesian coordinate system, useful to Visualize the results using the Metric.transform() function.

see Define your own space-time for a detailed documentation on how to correctly define a space-time metric.

Christoffel(mu: int, nu: int, rho: int)View on GitHub

The symbolic representation of the mu-nu-rho Christoffel symbol, ${\mathrm{\Gamma }}_{\mu \nu }^{\rho }$ related to the metric tensor.

Lagrangian()View on GitHub

The symbolic representation of the test particle Lagrangian related to the metric tensor.

add_parameter(symbol: str, value: float = None)View on GitHub

Manually adds a constant parameter to the Metric object. The value of this parameter must be specified

Parameters:

• symbol (str) – The symbolic name of the parameter.

• value (float) – The value of the parameter.

evaluate_parameters(expr: Basic)View on GitHub

Returns:

The input sympy symbolic expression expr where the all the constant parameters have been evalueated with their corrispodning values.

Parameters:

expr (sp.Basic) – The sympy symbolic expression in which to substitute funcitons.

Raises:

ValueError: if the value of the parameter has not been previously set.

get_constant(param: str)View on GitHub

Returns the value of the constant parameter, if defined.

Parameters:

param (str) – The symbolic name of the parameter to retrieve.

Raises:

ValueError: if parameter not defined.

get_evaluable_function(expr: str | Basic)View on GitHub

Returns:

A python callable from a sympy expressions, where all auxiliary functions and parameters from the metric have been evaluated.

Parameters:

expr (str | sp.Basic) – The sympy symbolic expression to evaluate or a string containing the symbolic expression.

get_parameters_constants()View on GitHub

Returns:

All the elements in pygro.Metric.parameters of type "constant".

get_parameters_expressions()View on GitHub

Returns:

All the elements in pygro.Metric.parameters of type "epxression" (auxiliary expressions).

get_parameters_functions()View on GitHub

Returns:

All the elements in pygro.Metric.parameters of type "pyfunc" (auxiliary functions).

get_parameters_symb()View on GitHub

Returns:

The symbolic representation of all the elements in pygro.Metric.parameters.

get_parameters_val()View on GitHub

Returns:

The numerical value of all the elements in pygro.Metric.parameters of type "constant".

load_metric(filename, **params)View on GitHub

Loads the metric from a .metric file which has been saved through the Metric.save_metric() method.

Parameters:

filename (str) – The name of the .metric file from which to load the metric.

norm(point: Iterable[float], vec: Iterable[float]) → floatView on GitHub

Returns:

The norm of the 4-vector vec computed at the given point in space-time. Uses the currently set values of the constant parameters.

Parameters:

• point (Iterbale[float]) – 4-dimensional array of numbers representing the position in space-time at which to compute the norm of the 4-vector.

• vec (Iterbale[float]) – 4-dimensional array of numbers representing the components of the 4-vector.

Raises:

ValueError: if the input arrays are not 4-dimensional.

save_metric(filename)View on GitHub

Saves the metric into a .metric file which can later be loaded with the Metric.load_metric() method.

Parameters:

filename (str) – The name of the .metric file in which to save the metric.

set_constant(**params)View on GitHub

Sets the value of a given parameter in the Metric. Useful to change the value of an existing paramter. The parameter and its value to be set should be passed as a keyword argument to the set_constant function.

Example:

>>> metric.set_constant(M = 1)

set_coordinate_transformation(transform_functions: list[str])View on GitHub

Sets the coordinate transforamtion to a pseduo-cartesian system of coordinates.

Example:

transform_functions = [
    "t",
    "r*sin(theta)*cos(phi)",
    "r*sin(theta)*sin(phi)",
    "r*cos(theta)"
]

metric.set_coordinate_transformation(transform_functions = transform_functions)

Parameters:

transform_functions (list[str]) – A list of strings containing the symbolic expressions of the transformation functions

set_expression_to_parameter(param, expr_str)View on GitHub

Selects the param element from the metric.parameters dictionary, sets its kind to "expr" and assignes to it a value which is the sybolic parsed expression in the expr_str argument.

Parameters:

• param (str) – The symbolic name of the parameter to modify.

• expr_str (str) – The symbolic expresison to assign to this parameter.

set_function_to_parameter(param: str, function: Callable, **derivatives: list[Callable])View on GitHub

Selects the param element from the metric.parameters dictionary, sets its kind to "py" and assignes as its value the function method that is passed as argument.

Note

The function argument must be a method which admits four floats and returns a single float as results. However, in the line_element argument, upon initialization of the Metric, only explicit coordinate dependences of the functional parameter must be indicated. Moreover, for each of the explicit coordinate dependence of the function its derivative should also be passed in argument (see Define your own space-time for a tutorial on how to do this).

Example:

line_element = "-A(r)*dt**2+1/A(r)*dr**2+(r**2)*(dtheta**2+sin(theta)**2*dphi**2)"

def A(t, r, theta, phi):
    M = metric.get_constant("M")
    return 1-2*M/r

def dAdr(t, r, theta, phi):
    M = metric.get_constant("M")
    return 2*M/r**2

metric = pygro.Metric(..., A = A, dAdr = dAdr)

Parameters:

• param (str) – The symbolic name of the parameter to modify.

• function (Callable) – The method to be called as the auxiliary function in the Metric.

• derivatives (list[Callable]) – methods to be called as the derivatives of the auxiliary function in the Metric with respect to the variables on which it depends. The argument keyword must be d[function]d[variable]. For example, if A(r, theta) is the auxiliary function, the derivatives (..., dAdr = [...], dAdtheta = [...]) must be provided.

subs_functions(expr: Basic)View on GitHub

Returns:

The input sympy symbolic expression expr where the all the occurences of symbolic expressions have beem substituted by their representation.

Parameters:

expr (sp.Basic) – The sympy symbolic expression in which to substitute funcitons.

transform(X: Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes])View on GitHub

A function to apply the transformation defined in transform_functions to the given point.

Parameters:

X – the point(s) to transform. This can either be a 4-dimensional array or a $4\times n$ np.array (i.e. a collection of points).

Returns:

The transformed values of the coordinates of the point(s).