leaspy.utils.linalg
===================

.. py:module:: leaspy.utils.linalg


Functions
---------

.. autoapisummary::

   leaspy.utils.linalg.compute_orthonormal_basis


Module Contents
---------------

.. py:function:: compute_orthonormal_basis(dgamma_t0, G_metric, *, strip_col = 0)

   
   Householder decomposition, adapted for a non-Euclidean inner product defined by:
   (1) :math:`< x, y >Metric(p) = < x, G(p) y >Eucl = xT G(p) y`, where:
   :math:`G(p)` is the symmetric positive-definite (SPD) matrix defining the metric at point `p`.

   The Euclidean case is the special case where `G` is the identity matrix.
   Product-metric is a special case where `G(p)` is a diagonal matrix (identified to a vector)
   whose components are all > 0.

   It is used to compute and set in-place the ``orthonormal_basis`` attribute
   given the time-derivative of the geodesic at initial time and the `G_metric`.
   The first component of the full orthonormal basis is a vector collinear `G_metric x dgamma_t0` that we get rid of.

   The orthonormal basis we construct is always orthonormal for the Euclidean canonical inner product.
   But all (but first) vectors of it lie in the sub-space orthogonal (for canonical inner product) to `G_metric * dgamma_t0`
   which is the same thing that being orthogonal to `dgamma_t0` for the inner product implied by the metric.

   [We could do otherwise if we'd like a full orthonormal basis, w.r.t. the non-Euclidean inner product.
   But it'd imply to compute G^(-1/2) & G^(1/2) which may be computationally costly in case we don't have direct access to them
   (for the special case of product-metric it is easy - just the component-wise inverse (sqrt'ed) of diagonal)
   TODO are there any advantages/drawbacks of one method over the other except this one?
   TODO are there any biases between features when only considering Euclidean orthonormal basis?]

   :Parameters:

       **dgamma_t0** : :class:`torch.FloatTensor` 1D
           Time-derivative of the geodesic at initial time.
           It may also be a vector collinear to it without any change to the result.

       **G_metric** : scalar, `torch.FloatTensor` 0D, 1D or 2D-square
           The `G(p)` defining the metric as referred in equation (1) just before :
               * If 0D (scalar): `G` is proportional to the identity matrix
               * If 1D (vector): `G` is a diagonal matrix (diagonal components > 0)
               * If 2D (square matrix): `G` is general (SPD)

       **strip_col** : :obj:`int` in 0..model_dimension-1 (default 0)
           Which column of the basis should be the one collinear to `dgamma_t0` (that we get rid of)



   :Returns:

       torch.Tensor of shape (dimension, dimension - 1)
           ..




   :Raises:

       :exc:`.LeaspyModelInputError`
           if incoherent metric `G_metric`







   ..
       !! processed by numpydoc !!