geomstats package#

Subpackages#

Submodules#

geomstats.algebra_utils module#

Utility module of reusable algebra routines.

geomstats.algebra_utils.flip_determinant(matrix, det)[source]#

Change sign of the determinant if it is negative.

For a batch of matrices, multiply the matrices which have negative determinant by a diagonal matrix :math:`diag(1,…,1,-1) from the right. This changes the sign of the last column of the matrix.

Parameters:

matrix (array-like, shape=[…,n ,m]) – Matrix to transform.
det (array-like, shape=[…]) – Determinant of matrix, or any other scalar to use as threshold to determine whether to change the sign of the last column of matrix.

Returns:

matrix_flipped (array-like, shape=[…, n, m]) – Matrix with the sign of last column changed if det < 0.

geomstats.algebra_utils.from_vector_to_diagonal_matrix(vector, num_diag=0)[source]#

Create diagonal matrices from rows of a matrix.

Parameters:

vector (array-like, shape=[m, n])
num_diag (int) – number of diagonal in result matrix. If 0, the result matrix is a diagonal matrix; if positive, the result matrix has an upper-right non-zero diagonal; if negative, the result matrix has a lower-left non-zero diagonal. Optional, Default: 0.

Returns:

diagonals (array-like, shape=[m, n, n]) – 3-dimensional array where the i-th n-by-n array diagonals[i, :, :] is a diagonal matrix containing the i-th row of vector.

geomstats.algebra_utils.rotate_points(points, end_point)[source]#

Apply to points the rotation from north_pole to end_point.

A QR decomposition is used to find the rotation that maps the north pole (1, 0,…,0) to the end_point, then this rotation is applied to the input points.

Parameters:

points (array-like, shape=[…, n]) – Points to rotate.
end_point (array-like, shape=[n, ]) – Point to parametrise the rotation.

Returns:

rotated_points (array-like, shape=[…, n]) – Points after the rotation.

geomstats.algebra_utils.taylor_exp_even_func(point, taylor_function, order=5, tol=1e-06)[source]#

Taylor Approximation of an even function around zero.

Parameters:

point (array-like) – Argument of the function to approximate.
taylor_function (dict with following keys) –

functioncallable
Even function to approximate around zero.

coefficientslist
Taylor coefficients of even order at zero.
order (int) – Order of the Taylor approximation. Optional, Default: 5.
tol (float) – Threshold to use the approximation instead of the function’s value. Where abs(point) <= tol, the approximation is returned.

Returns:

function_value (array-like) – Value of the function at point.

geomstats.errors module#

Checks and associated errors.

exception geomstats.errors.ShapeError[source]#

Bases: ValueError

Raised when there is an incompatibility between shapes.

geomstats.errors.check_belongs(point, manifold, **kwargs)[source]#

Raise an error if point does not belong to the input manifold.

Parameters:

point (array-like) – Point to be tested.
manifold (Manifold) – Manifold to which the point should belong.
manifold_name (string) – Name of the manifold for the error message.

geomstats.errors.check_integer(n, n_name)[source]#

Raise an error if n is not a > 0 integer.

Parameters:

n (unspecified) – Parameter to be tested.
n_name (string) – Name of the parameter.

geomstats.errors.check_parameter_accepted_values(param, param_name, accepted_values)[source]#

Raise an error if parameter does not belong to a set of values.

Parameters:

param (unspecified) – Parameter to be tested.
param_name (string) – Name of the parameter.
accepted_values (list) – Accepted values that the parameter can take.

geomstats.errors.check_point_shape(point, manifold, suppress_error=False)[source]#

Check if the shape of point does not match the shape of a manifold or metric.

If the final elements of the shape of point do not match the shape of manifold (which may be any object with a shape attribute, such as a Riemannian metric) then point cannot be an array of points on the manifold (or similar) and a ValueError is raised. The error can be suppressed by setting suppress_error to True.

Parameters:

point (array-like) – The point to check the shape of.
manifold ({Manifold, RiemannianMetric}) – The object to check the point against
suppress_error (bool) – Whether to suppress the ShapeError if the shapes do not match. Optional, default is False.

Returns:

shapes_match (bool) – Whether the shape of the point matches the shape of the manifold or metric.

Raises:

ValueError – If the final dimensions of point are not equal to the final dimensions of manifold.

geomstats.errors.check_positive(param, param_name)[source]#

Raise an error if param is not a > 0 number.

Parameters:

param (unspecified) – Parameter to be tested.
param_name (string) – Name of the parameter.

geomstats.exceptions module#

Geomstats custom exceptions.

exception geomstats.exceptions.AutodiffNotImplementedError[source]#

Bases: RuntimeError

Raised when autodiff is not implemented.

geomstats.integrator module#

Integrator functions used when no closed forms are available.

Lead author: Nicolas Guigui.

These are designed for first order ODE written of a variable x and a time variable t:

\[\frac{dx}{dt} = force(x, t)\]

where \(x\) is called the state variable. It may represent many variables by stacking arrays, e.g. position and velocity in a geodesic equation.

geomstats.integrator.euler_step(force, state, time, dt)[source]#

Compute one step of the euler approximation.

Parameters:

force (callable) – Vector field that is being integrated.
state (array-like, shape=[2, dim]) – State at time t, corresponds to position and velocity variables at time t.
time (float) – Time variable.
dt (float) – Time-step in the integration.

Returns:

point_new (array-like, shape=[…, {dim, [n, n]}]) – First variable at time t + dt.
vector_new (array-like, shape=[…, {dim, [n, n]}]) – Second variable at time t + dt.

geomstats.integrator.integrate(function, initial_state, end_time=1.0, n_steps=10, step='euler')[source]#

Compute the flow under the vector field using symplectic euler.

Integration function to compute flows of vector fields on a regular grid between 0 and a finite time from an initial state.

Parameters:

function (callable) – Vector field to integrate.
initial_state (tuple of arrays) – Initial position and speed.
end_time (float) – Final integration time. Optional, default : 1.
n_steps (int) – Number of integration steps to use. Optional, default : 10.
step (str, {‘euler’, ‘rk4’, ‘group_rk2’, ‘group_rk4’}) – Numerical scheme to use for elementary integration steps. Optional, default : ‘euler’.

Returns:

final_state (tuple) – sequences of solutions every end_time / n_steps. The shape of each element of the sequence is the same as the vectors passed in initial_state.

geomstats.integrator.leapfrog_step(force, state, time, dt)[source]#

Compute one step of the leapfrog approximation.

Parameters:

state (array-like, shape=[2, dim]) – State at time t, corresponds to position and velocity variables at time t.
force (callable) – Vector field that is being integrated.
time (float) – Time variable.
dt (float) – Time-step in the integration.

Returns:

point_new (array-like, shape=[…, {dim, [n, n]}]) – First variable at time t + dt.
vector_new (array-like, shape=[…, {dim, [n, n]}]) – Second variable at time t + dt.

geomstats.integrator.rk2_step(force, state, time, dt)[source]#

Compute one step of the rk2 approximation.

Parameters:

force (callable) – Vector field that is being integrated.
state (array-like, shape=[2, dim]) – State at time t, corresponds to position and velocity variables at time t.
time (float) – Time variable.
dt (float) – Time-step in the integration.

Returns:

point_new (array-like, shape=[…, {dim, [n, n]}]) – First variable at time t + dt.
vector_new (array-like, shape=[…, {dim, [n, n]}]) – Second variable at time t + dt.

geomstats.vectorization module#

Decorator to handle vectorization.

This abstracts the backend type.

geomstats.vectorization.adapt_result(result, initial_shapes, args_kwargs_types, is_scal)[source]#

Adapt shape of output.

This function squeezes the dim 0 or 1 of the output, depending on:

the type of the output: scalar vs else,
the initial shapes or args and kwargs provided by the user.

Parameters:

result (unspecified) – Output of the function.
initial_shapes (list) – Shapes of args and kwargs provided by the user.
args_kwargs_types (list) – Types of args and kwargs.
is_scal (bool) – Boolean determining if the output ‘result’ is a scalar.

Returns:

result (unspecified) – Output of the function, with adapted shape.

geomstats.vectorization.adapt_types(args_types, kwargs_types, opt_kwargs_types, args, kwargs)[source]#

Adapt the list of input input_types.

Some functions are implemented with array-like arguments that can be either ‘vector’ or ‘matrix’ depending on the value of the ‘point_type’ argument.

This function reads the ‘point_type’ argument, and adapt the actual type of the input array-like arguments.

Parameters:

args_types (list) – Types of args.
kwargs_types (list) – Types of kwargs.
opt_kwargs_types (list) – Types of optional kwargs.
args (tuple) – Args of a function.
kwargs (dict) – Kwargs of a function.

Returns:

args_types (list) – Adapted types of args.
kwargs_types (list) – Adapted types of kwargs.

geomstats.vectorization.broadcast_to_multibatch(batch_shape_a, batch_shape_b, array_a, *array_b)[source]#

Broadcast to multibatch.

Gives to both arrays batch shape batch_shape_b + batch_shape_a.

Does nothing if one of the batch shapes is empty.

Parameters:

batch_shape_a (tuple) – Batch shape of array_a.
batch_shape_b (tuple) – Batch shape of array_b.
array_a (array)
array_b (array)

geomstats.vectorization.check_is_batch(point_ndim, *point)[source]#

Check if inputs are batch.

Parameters:

point_ndim (int) – Point number of array dimensions.
point (array-like) – Point belonging to the space.

Returns:

is_batch (bool) – Returns True if point contains several points.

geomstats.vectorization.get_batch_shape(point_ndim, *point)[source]#

Get batch shape.

Parameters:

point_ndim (int) – Point number of array dimensions.
point (array-like or None) – Point belonging to the space.

Returns:

batch_shape (tuple) – Returns the shape related with batch. () if only one point.

geomstats.vectorization.get_initial_shapes(input_types, args)[source]#

Extract shapes and ndims of input args or kwargs values.

Store the shapes of the input args, or kwargs values, that are array-like, store None otherwise.

Parameters:

input_types (list) – Point types corresponding to the args, or kwargs values.
args (tuple or dict_values) – Args, or kwargs values, of a function.

Returns:

in_shapes (list) – Shapes of array-like input args, or kwargs values.

geomstats.vectorization.get_n_points(point_ndim, *point)[source]#

Compute the number of points.

Parameters:

point_ndim (int) – Point number of array dimensions.
point (array-like) – Point belonging to the space.

Returns:

n_points (int) – Number of points.

geomstats.vectorization.get_types(input_types, args, kwargs)[source]#

Extract the types of args, kwargs, optional kwargs and output.

Parameters:

input_types (list) – List of inputs’ input_types, including for optional inputs.
args (tuple) – Args of a function.
kwargs (dict) – Kwargs of a function.

Returns:

args_types (list) – Types of args.
kwargs_types (list) – Types of kwargs.
opt_kwargs_types (list) – Types of optional kwargs.
is_scal (bool) – Boolean determining if the output is a scalar.

geomstats.vectorization.is_scalar(vect_array)[source]#

Test if a “fully-vectorized” array represents a scalar.

Parameters:: vect_array (array-like) – Array to be tested.
Returns:: is_scalar (bool) – Boolean determining if vect_array is a fully-vectorized scalar.

geomstats.vectorization.repeat_out(point_ndim, out, *point, out_shape=())[source]#

Repeat out shape after finding batch shape.

Parameters:

point_ndim (int) – Point number of array dimensions.
out (array-like) – Output to be repeated
point (array-like or None) – Point belonging to the space.
out_shape (tuple) – Indicates out shape for no batch computations.

Returns:

out (array-like) – If no batch, then input is returned. Otherwise it is broadcasted.

geomstats.vectorization.repeat_point(point, n_reps=2, expand=False)[source]#

Repeat point.

Parameters:

point (array-like) – Point of a space.
n_reps (int) – Number of times the point should be repeated.
expand (bool) – Repeat even if n_reps == 1.

Returns:

rep_point (array-like) – point repeated n_reps times.

geomstats.vectorization.squeeze_output_dim_0(result, in_shapes, input_types)[source]#

Determine if the output needs to be squeezed on dim 0.

The dimension 0 is squeezed iff all input parameters:

contain one sample,
have the corresponding dimension 0 squeezed, i.e. if all input parameters have ndim strictly less than the ndim corresponding to their vectorized shape.

Parameters:

in_ndims (list) – Initial ndims of input parameters, as entered by the user.
input_types (list) – Associated list of input_type of input parameters.

Returns:

squeeze (bool) – Boolean deciding whether to squeeze dim 0 of the output.

geomstats.vectorization.squeeze_output_dim_1(result, in_shapes, input_types, is_scal=True)[source]#

Determine if the output needs to be squeezed on dim 1.

This happens if the user represents scalars as array of shapes: [n_samples,] instead of [n_samples, 1] Dimension 1 is squeezed by default if input_type is ‘scalar’. Dimension 1 is not squeezed if the user inputs at least one scalar with a singleton in dimension 1.

Parameters:

result (array-like) – Result output by the function, before reshaping.
in_shapes (list) – Initial shapes of input parameters, as entered by the user.
input_types (list) – Associated list of input_type of input parameters.

Returns:

squeeze (bool) – Boolean deciding whether to squeeze dim 1 of the output.

geomstats.vectorization.vectorize_args(input_types, args)[source]#

Vectorize input args.

Transform input array-like args into their fully-vectorized form, where “fully-vectorized” means that:

one scalar has shape [1, 1],
n scalars have shape [n, 1],
one d-D vector has shape [1, d],
n d-D vectors have shape [n, d],

etc.

Parameters:

input_types (list) – Point types corresponding to the args.
args (tuple) – Args of a function.

Returns:

vect_args (tuple) – Args of the function in their fully-vectorized form.

geomstats.vectorization.vectorize_kwargs(input_types, kwargs)[source]#

Vectorize input kwargs.

Transform input array-like kwargs into their fully-vectorized form, where “fully-vectorized” means that:

one scalar has shape [1, 1],
n scalars have shape [n, 1],
one d-D vector has shape [1, d],
n d-D vectors have shape [n, d],

etc.

Parameters:

input_types (list) – Point types corresponding to the args.
kwargs (dict) – Kwargs of a function.

Returns:

vect_kwargs (dict) – Kwargs of the function in their fully-vectorized form.

Module contents#

Import main modules.