# First steps¶

The purpose of this guide is to illustrate the possible uses of geomstats.

**INSTALL GEOMSTATS WITH PIP3**

From a terminal (OS X & Linux), you can install geomstats and its requirements with `pip3`

as follows:

```
pip3 install geomstats
```

This method installs the latest version of geomstats that is uploaded on PyPi.

**INSTALL GEOMSTATS FROM GITHUB**

From a terminal (OS X & Linux), you can install geomstats and its requirements via Git as follows:

```
git clone https://github.com/geomstats/geomstats.git
pip3 install -r requirements.txt
```

This methods installs the latest GitHub version. Developers should install this version, together with the development requirements and the optional requirements to enable `tensorflow`

and `pytorch`

backends:

```
pip3 install -r dev-requirements.txt -r opt-requirements.txt
```

**CHOOSE THE BACKEND**

Geomstats can run seemlessly with `numpy`

, `tensorflow`

or `pytorch`

. Note that `pytorch`

and `tensorflow`

requirements are optional, as geomstats can be used with `numpy`

only. By default, the `numpy`

backend is used. The visualizations are only available with this backend.

To get the `tensorflow`

and `pytorch`

versions compatible with geomstats, install the optional requirements:

```
pip3 install -r opt-requirements.txt
```

You can choose your backend by setting the environment variable `GEOMSTATS_BACKEND`

to `numpy`

, `tensorflow`

or `pytorch`

, and importing the `backend`

module. From the command line:

```
export GEOMSTATS_BACKEND=pytorch
```

and in the Python3 code:

```
import geomstats.backend as gs
```

**FIRST EXAMPLES**

To use geomstats for learning
algorithms on Riemannian manifolds, you need to follow three steps:
- instantiate the manifold of interest,
- instantiate the learning algorithm of interest,
- run the algorithm.
The data should be represented by the structure `gs.array`

, which represents numpy arrays, tensorflow or pytorch tensors, depending on the choice of backend.

As an example, the following code snippet illustrates the use of K-means on simulated data on the 5-dimensional hypersphere.

```
from geomstats.geometry.hypersphere import Hypersphere
from geomstats.learning.online_kmeans import OnlineKMeans
sphere = Hypersphere(dim=5)
data = sphere.random_uniform(n_samples=10)
clustering = OnlineKMeans(metric=sphere.metric, n_clusters=4)
clustering = clustering.fit(data)
```

The following code snippet shows the use of tangent Principal Component Analysis on simulated data on the space of 3D rotations.

```
from geomstats.geometry.special_orthogonal import SpecialOrthogonal
from geomstats.learning.pca import TangentPCA
so3 = SpecialOrthogonal(n=3, point_type='vector')
metric = so3.bi_invariant_metric
data = so3.random_uniform(n_samples=10)
tpca = TangentPCA(metric=metric, n_components=2)
tpca = tpca.fit(data)
tangent_projected_data = tpca.transform(data)
```

All geometric computations are performed behind the scenes. The user only needs a high-level understanding of Riemannian geometry. Each algorithm can be used with any of the manifolds and metric implemented in the package.

To see additional examples, visit the page examples.