Re-organize the documentation

docs/src/conf.py

@@ -6,6 +6,7 @@
 
 import toml
 
+
 ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", ".."))
 
 sys.path.append(os.path.join(ROOT, "python", "src"))
@@ -86,8 +87,8 @@ def setup(app):
  "gallery_dirs": ["examples"],
  "min_reported_time": 60,
  # Make the code snippet for equistore functions clickable
- #"reference_url": {"equistore": None},
- #"prefer_full_module": ["equistore"],
+ "reference_url": {"equistore": None},
+ "prefer_full_module": ["equistore"],
 }
 
 breathe_projects = {

docs/src/explanations/data.rst

@@ -1,10 +1,12 @@
 Where does the actual data come from?
 =====================================
 
-Equistore manages the metadata, where does the data come from. How does
-equistore deal with it and how to register new data origins in the python
-wrapper 
+TBD
 
-(Python automagically transforms data to numpy.ndarray or a torch.tensor)
-Equistore has no idea about the data itself (only knows the pointer to data
-and operations you can perform on it - create, destroy move and reshape data)
+.. Equistore manages the metadata, where does the data come from. How does
+.. equistore deal with it and how to register new data origins in the python
+.. wrapper
+
+.. (Python automagically transforms data to numpy.ndarray or a torch.tensor)
+.. Equistore has no idea about the data itself (only knows the pointer to data
+.. and operations you can perform on it - create, destroy move and reshape data)

docs/src/explanations/gradients.rst

@@ -1,14 +1,17 @@
 Gradients and how we manage them
 ================================
 
-Gradient samples - "special" format
+TBD
 
-first sample of gradients is "sample" that refers to the row in block.values
-that we are taking the gradient of.
-the other samples - what we are taking the gradient with respect to.
-Write what this entails -- block.gradients.sample (i A j) (pair feature i j A k)
 
-Cell gradients - Sample (i)
-components [[x y z ] [x y z]] (displacement matrix)
+.. Gradient samples - "special" format
 
-Gradient wrt hypers
+.. first sample of gradients is "sample" that refers to the row in block.values
+.. that we are taking the gradient of.
+.. the other samples - what we are taking the gradient with respect to.
+.. Write what this entails -- block.gradients.sample (i A j) (pair feature i j A k)
+
+.. Cell gradients - Sample (i)
+.. components [[x y z ] [x y z]] (displacement matrix)
+
+.. Gradient wrt hypers

docs/src/explanations/index.rst

@@ -3,10 +3,11 @@
 Explanations
 ============
 
-The explanation section discusses topics that broaden your knowledge of
-equistore. The theory behind the calculators and additional useful information
-are found here to give you more clarity and understanding of what equistore is
-all about.
+The explanation section discusses key topics and concepts at a fairly high level
+and provides useful explanations to expand your knowledge of equistore. It
+requires at least basic to intermediate knowledge of equistore If you are an
+absolute beginner, we recommend you start from the :ref:`userdoc-get-started`
+section of the documentation.
 
 .. toctree::
  :maxdepth: 2

docs/src/get-started/index.rst

@@ -8,7 +8,5 @@ The following sections describes how to install and start with using equistore.
 .. toctree::
  :maxdepth: 2
 
- equistore
  concepts
  installation
- tutorials/index

docs/src/index.rst

@@ -1,65 +1,50 @@
-Overview of Equistore's Documentation
-=====================================
-
-This documentation covers everything you need to know about equistore.
-It comprises of the following five broad sections:
-
-- :ref:`userdoc-get-started`
-- :ref:`userdoc-how-to`
-- :ref:`userdoc-references`
-- :ref:`userdoc-explanations`
-- :ref:`devdoc`
-
-If you are new to equistore we recommend starting with the
-:ref:`userdoc-get-started` section. If you want to contribute to the development
-of the library please have a look at our :ref:`developer documentation
-<devdoc>`.
+Equistore: data storage for atomistic machine learning
+======================================================
 
+Equistore is a specialized data storage format suited to all your atomistic
+machine learning needs and more. You can think of it like ``numpy.ndarray`` or
+``torch.Tensor``, but carrying extra metadata together with the data.
 
-Getting started
----------------
+This metadata can be about the nature of the **objects** being described, about
+**how** this object is being described, about **symmetry** properties of the
+data (this is especially relevant for equivariant machine learning), different
+**sparsity** linked to one-hot encoding of species or **components** of
+gradients of the above with respect to various parameters.
 
-If you are an absolute beginner, we recommend you to start with the get started
-pages to familiarize yourself with equistore and the equistore ecosystem.
+For example, the object being described could be "one atom in a structure", or
+"a pair of atoms", while the how could be "using SOAP power spectrum features"
+or "Hamiltonian matrix elements".
 
-How-to guides
--------------
+Equistore main concern is about representing and manipulating this metadata,
+while using other well established library handle the data itself. We currently
+support using arbitrary CPU arrays created by any language (including numpy
+arrays), as well as PyTorch Tensor --- including full support for GPU and
+automatic differentiation.
 
-This section comprises of guides that will take you through series of steps
-involved in addressing key problems and use-cases in equistore. It requires
-intermediate to advanced knowledge of how equistore works. If you are an
-absolute beginner, it is recommended you start from the
-:ref:`userdoc-get-started` section before going to the How to Guides.
+.. TODO: the end goal is to create an ecosystem of inter-operable libraries for atomistic ML
+.. TODO: equistore does not create data, other libraries do
+.. TODO: add a figure
 
-Reference guides
-----------------
+--------------------------------------------------------------------------------
 
-The Reference Guide contains technical references for equistore's APIs.
-It describes the various functionalities
-provided by equistore. You can always refer to this section to learn more about
-classes, functions, modules, and other aspects of equistore's machinery you come
-across.
-
-Explanations
-------------
-
-The explanation section discusses key topics and concepts at a fairly high level
-and provides useful explanations to expand your knowledge of equistore. It
-requires at least basic to intermediate knowledge of equistore If you are an
-absolute beginner, we recommend you start from the :ref:`userdoc-get-started`
-section of the documentation.
-
-Developer documentation
------------------------
+This documentation covers everything you need to know about equistore.
+It comprises of the following five broad sections:
 
-The developer guide introduces the aspects of how contributing to the code base
-or the documentation of equistore.
+- :ref:`userdoc-get-started`: familiarize yourself with equistore and it's
+ ecosystem;
+- :ref:`userdoc-tutorials`: step-by-step tutorials addressing key problems and
+ use-cases for equistore;
+- :ref:`userdoc-references`: technical description of all the functionalities
+ provided by equistore;
+- :ref:`userdoc-explanations`: high-level explanation of more advanced
+ functionalities;
+- :ref:`devdoc`: how to contribute to the code or the documentation of equistore.
 
 .. toctree::
  :hidden:
 
  get-started/index
- how-to/index
+ tutorials/index
  reference/index
  explanations/index
  devdoc/index

docs/src/reference/index.rst

@@ -3,8 +3,10 @@
 Reference guides
 ----------------
 
-The reference guides describe how the equistore API 
-can be used from each language.
+The reference guides contains technical references for equistore's APIs. They
+describes the various functionalities provided by equistore. You can always
+refer to this section to learn more about classes, functions, modules, and other
+aspects of equistore's machinery you come across.
 
 
 .. toctree::

docs/src/tutorials/first-tensormap.rst

@@ -0,0 +1,17 @@
+Creating TensorMap manually
+===========================
+
+.. container:: sphx-glr-footer sphx-glr-footer-example
+
+ .. container:: sphx-glr-download sphx-glr-download-python
+
+ :download:`Download Python source code for this example: first-tensormap.py <../examples/first-tensormap.py>`
+
+ .. container:: sphx-glr-download sphx-glr-download-jupyter
+
+ :download:`Download Jupyter notebook for this example: first-tensormap.ipynb <../examples/first-tensormap.ipynb>`
+
+
+.. include:: ../examples/first-tensormap.rst
+ :start-after: start-body
+ :end-before: end-body

docs/src/tutorials/index.rst

@@ -0,0 +1,18 @@
+.. _userdoc-tutorials:
+
+Tutorials
+=========
+
+This section comprises of guides that will take you through series of steps
+involved in addressing key problems and use-cases in equistore. It requires
+intermediate to advanced knowledge of how equistore works. If you are an
+absolute beginner, it is recommended you start from the
+:ref:`userdoc-get-started` section before going to the How to Guides.
+
+.. toctree::
+ :maxdepth: 2
+
+ first-tensormap
+ linear-model
+ operations
+ torch

docs/src/tutorials/operations.rst

@@ -0,0 +1,4 @@
+Operating on equistore data
+---------------------------
+
+TBD

docs/src/tutorials/torch.rst

@@ -0,0 +1,6 @@
+Integration with PyTorch
+------------------------
+
+TBD
+
+.. Using torch tensors as data (gpus, autograd)