Add docs to RTD, changes to readme, logo update (#10)

* Substitute logo for new one * WIP change badges in README.rst * WIP docs * fixup! WIP docs * docs fixes
aimclub · Dec 20, 2022 · 0efa8fb · 0efa8fb
1 parent ee3f8e5
commit 0efa8fb
Show file tree

Hide file tree

Showing 25 changed files with 224 additions and 103 deletions.
diff --git a/README.rst b/README.rst
@@ -1,28 +1,15 @@
-
-.. image:: docs/img/golem_logo.png
+.. image:: docs/source/img/golem_logo-02.png
    :alt: Logo of GOLEM framework
-   :scale: 70 %
+   :align: center
+   :width: 500
 
-.. start-badges
-.. list-table::
-   :stub-columns: 1
+.. class:: center
 
-   * - package
-     - | |pypi| |py_7| |py_8| |py_9|
-   * - tests
-     - | |build|
-   * - coverage
-     - | |coverage|
-   * - docs
-     - |docs|
-   * - license
-     - | |license|
-   * - support
-     - | |tg|
+    |python| |pypi| |build| |docs| |license| |tg|
 
-.. end-badges
 
-**GOLEM**: Graph Optimization and Learning by Evolutionary Methods
+Graph Optimization and Learning by Evolutionary Methods
+-------------------------------------------------------
 
 GOLEM is an open-source AI framework for optimization and learning of structured graph-based models with meta-heuristic methods. It is centered around 2 ideas:
 
@@ -69,16 +56,15 @@ Examples of GOLEM applications:
 
 As GOLEM is a general-purpose, it's easy to imagine fore potential applications, for example, finite state automata search for robotics control or molecular graph learning for drug discovery, and more.
 
-..
-    TODO:
-    Installation
-    ============
 
-    GOLEM can be installed with ``pip``:
+Installation
+============
+
+GOLEM can be installed with ``pip``:
 
-    .. code-block::
+.. code-block::
 
-      $ pip install golem
+  $ pip install golem
 
 
 Project Structure
@@ -155,37 +141,33 @@ Other papers - in `ResearchGate <https://www.researchgate.net/project/Evolutiona
     :target: https://thegolem.readthedocs.io/en/latest/?badge=latest
     :alt: Documentation Status
 
-.. |build| image:: https://github.com/ITMO-NSS-team/GOLEM/actions/workflows/unit-build.yml/badge.svg?branch=main
+.. |build| image:: https://github.com/aimclub/GOLEM/actions/workflows/unit-build.yml/badge.svg?branch=main
    :alt: Build Status
-   :target: https://github.com/ITMO-NSS-team/GOLEM/actions/workflows/unit-build.yml
+   :target: https://github.com/aimclub/GOLEM/actions/workflows/unit-build.yml
 
-.. |coverage| image:: https://codecov.io/gh/ITMO-NSS-team/GOLEM/branch/main/graph/badge.svg
+.. |coverage| image:: https://codecov.io/gh/aimclub/GOLEM/branch/main/graph/badge.svg
    :alt: Coverage Status
-   :target: https://codecov.io/gh/ITMO-NSS-team/GOLEM
+   :target: https://codecov.io/gh/aimclub/GOLEM
 
-.. |pypi| image:: https://badge.fury.io/py/fedot.svg
-   :alt: Supported Python Versions
-   :target: https://badge.fury.io/py/fedot
+.. |pypi| image:: https://img.shields.io/pypi/v/golem.svg
+   :alt: PyPI Package Version
+   :target: https://img.shields.io/pypi/v/golem
 
-.. |py_7| image:: https://img.shields.io/badge/python_3.7-passing-success
+.. |python| image:: https://img.shields.io/pypi/pyversions/fedot.svg
    :alt: Supported Python Versions
-   :target: https://img.shields.io/badge/python_3.7-passing-success
+   :target: https://img.shields.io/pypi/pyversions/fedot
 
-.. |py_8| image:: https://img.shields.io/badge/python_3.8-passing-success
+.. |license| image:: https://img.shields.io/github/license/aimclub/GOLEM
    :alt: Supported Python Versions
-   :target: https://img.shields.io/badge/python_3.8-passing-success
+   :target: https://github.com/aimclub/GOLEM/blob/main/LICENSE.md
 
-.. |py_9| image:: https://img.shields.io/badge/python_3.9-passing-success
-   :alt: Supported Python Versions
-   :target: https://img.shields.io/badge/python_3.9-passing-success
-
-.. |license| image:: https://img.shields.io/github/license/nccr-itmo/FEDOT
-   :alt: Supported Python Versions
-   :target: https://github.com/nccr-itmo/FEDOT/blob/master/LICENSE.md
-
-.. |downloads_stats| image:: https://static.pepy.tech/personalized-badge/fedot?period=total&units=international_system&left_color=grey&right_color=brightgreen&left_text=Downloads
-   :target: https://pepy.tech/project/fedot
+.. |downloads_stats| image:: https://static.pepy.tech/personalized-badge/golem?period=total&units=international_system&left_color=grey&right_color=brightgreen&left_text=Downloads
+   :target: https://pepy.tech/project/golem
 
 .. |tg| image:: https://img.shields.io/badge/Telegram-Group-blue.svg
-          :target: https://t.me/FEDOT_helpdesk
-          :alt: Telegram Chat
+   :alt: Telegram Chat
+   :target: https://t.me/FEDOT_helpdesk
+
+.. |by-golem| image:: http://img.shields.io/badge/powered%20by-GOLEM-orange.svg?style=flat
+   :target: http://github.com/aimclub/GOLEM
+   :alt: Powered by GOLEM
diff --git a/docs/img/__init__.py b/docs/img/__init__.py
diff --git a/docs/img/golem_logo.png b/docs/img/golem_logo.png
diff --git a/docs/source/advanced/adaptation.rst b/docs/source/advanced/adaptation.rst
@@ -1,4 +1,41 @@
-Adaptation of Domain Graphs
-===========================
+Adaptation of Graphs
+====================
 
-There's info..
+Domain Graphs & Optimization Graphs
+************************************
+
+Problem domains usually work with their own graph representations that are suitable for specific needs. For example, in the case of AutoML problem (as in FEDOT framework) this is a pipeline of ML operations (a tree or a directed acyclic graph);
+in Bayesian optimization this is a graph of variables and their conditional dependencies (as in BAMT framework), in the task of neural architecture search (NAS) the domain graph is a neural network implemented in some deep learning framework, and so on.
+
+Universal graph optimizer abstracts from these details and works with internal graph representation (also called *optimization graph*). This design brings the following benefits:
+
+* **Generality**: graph optimizer is isolated from domain specifics and can be used for a wide range of domains.
+* **Domain nativeness**: at the same time isolation enables opaque domain-specific operators and rules, that domain experts can define. Graph fitness is also defined in domain terms.
+* **Effectiveness**: optimization works with suitable light-weight structure.
+* **Flexibility**: the only requirement for domain structure is convertibility to a graph form. This conversion is the task of the Adapter subsystem.
+
+Adapter Subsystem
+*****************
+
+.. image:: ../img/adapter-structure-v1.png
+
+**Adapter** provides automatic 2-way transformation between domain graphs and optimization graphs. Adapter transforms graphs on 2 levels, as schematically represented by the diagram.
+
+* First, on the initial input and the output of the optimizer.
+
+  Initial domain graphs provided by the user are transformed to optimization graphs, and the resulting optimization graphs are transformed back to domain graphs. This the the outer border on the scheme between problem domain and graph optimizer.
+
+* Second, when graph optimizer calls verification rules and graph operators (e.g. evolutionary operators) defined for domain graphs.
+
+  For example, in optimization of 3D structures we could define a domain crossover operator, that merges 3D meshes only along specific planes. To apply this opertor, optimizer first restores the domain graphs from the optimization graphs, then applies the operator, and then adapts the resulting domain graph back into internal representation.
+
+Framework users need to explicitly use the Adapter subsystem in two cases:
+
+* When they instantiate the framework for the new problem domain.
+
+  In this case they must implement their own Adapter, inheriting from the base Adapter (see :py:class:`golem.core.adapter.adapter.BaseOptimizationAdapter`).
+
+* When they define custom rules or operators *that work on internal optimization graphs*.
+
+  These can be graph verification rules (see :py:class:`golem.core.dag.graph_verifier.GraphVerifier` class) or custom operators for the evolutionary optimizer. This use-case is less common, because external users usually define rules or operators that work with the domain graphs.
+  In this case users should mark these functions with ``@register_native`` decorator. This decorator tells the Adapter that the decorated function works directly on optimization graphs and does not require transformation of its arguments and/or return values.
diff --git a/docs/source/advanced/index.rst b/docs/source/advanced/index.rst
@@ -11,5 +11,4 @@ Advanced Topics
    narrow_search
    multi_obj_search
    serialization
-   interpolation
-
+   nx-interop
diff --git a/docs/source/advanced/interpolation.rst b/docs/source/advanced/interpolation.rst
diff --git a/docs/source/advanced/nx-interop.rst b/docs/source/advanced/nx-interop.rst
@@ -0,0 +1,4 @@
+Interoperation with NetworkX 
+============================
+
+NetworkX adapter provides a two-way transformation between directed `networkx.DiGraph <https://networkx.org/documentation/stable/reference/classes/digraph.html>`_ and internal GOLEM Graph.
diff --git a/docs/source/api/adapter.rst b/docs/source/api/adapter.rst
@@ -0,0 +1,10 @@
+Adapter Subsystem
+=================
+
+.. automodule:: golem.core.adapter.adapt_registry
+   :members:
+   :no-undoc-members:
+
+.. automodule:: golem.core.adapter.adapter
+   :members:
+   :no-undoc-members:
diff --git a/docs/source/api/graph.rst b/docs/source/api/graph.rst
@@ -0,0 +1,9 @@
+Graph
+=====
+
+.. autoclass:: golem.core.dag.graph.Graph
+   :members:
+   :no-undoc-members:
+
+.. autoclass:: golem.core.dag.graph_node.GraphNode
+   :members:
diff --git a/docs/source/api/index.rst b/docs/source/api/index.rst
@@ -1,19 +1,16 @@
 API Reference
 =============
 
-There are links to ``.rst`` files. Every file has to consist modules that have been built automaticaly...
+This is automatically generated API reference.
 
-Example:
-
-.. code::
-
-    .. automodule:: fedot.core.composer.composer
-       :members:
-       :no-undoc-members:
-
-    .. autoclass:: fedot.core.composer.composer.Composer
-       :members:
-       :no-undoc-members:
-
-    
+.. toctree::
+   :glob:
+   :maxdepth: 1
 
+   adapter
+   graph
+   optimizer
+   objective
+   parameters
+   profiler
+   logging
diff --git a/docs/source/api/logging.rst b/docs/source/api/logging.rst
@@ -0,0 +1,6 @@
+Logging
+=======
+
+.. automodule:: golem.core.log
+   :members:
+   :no-undoc-members:
diff --git a/docs/source/api/objective.rst b/docs/source/api/objective.rst
@@ -0,0 +1,5 @@
+Objective
+=========
+
+.. autoclass:: golem.core.optimisers.objective.objective.Objective
+   :members:
diff --git a/docs/source/api/optimizer.rst b/docs/source/api/optimizer.rst
@@ -0,0 +1,5 @@
+GraphOptimizer
+==============
+
+.. autoclass:: golem.core.optimisers.optimizer.GraphOptimizer
+   :members:
diff --git a/docs/source/api/parameters.rst b/docs/source/api/parameters.rst
@@ -0,0 +1,14 @@
+Parameter classes
+=================
+
+.. autoclass:: golem.core.optimisers.optimizer.AlgorithmParameters
+   :members:
+
+.. autoclass:: golem.core.optimisers.optimization_parameters.OptimizationParameters
+   :members:
+
+.. autoclass:: golem.core.optimisers.optimization_parameters.GraphRequirements
+   :members:
+
+.. autoclass:: golem.core.optimisers.optimizer.GraphGenerationParams
+   :members:
diff --git a/docs/source/api/profiler.rst b/docs/source/api/profiler.rst
@@ -0,0 +1,16 @@
+Profiler
+========
+
+MemoryProfiler
+--------------
+
+.. automodule:: golem.utilities.profiler.memory_profiler
+   :members:
+   :no-undoc-members:
+
+TimeProfiler
+------------
+
+.. automodule:: golem.utilities.profiler.time_profiler
+   :members:
+   :no-undoc-members:
diff --git a/docs/source/examples/abstract.rst b/docs/source/examples/abstract.rst
@@ -1,4 +1,10 @@
 Abstract Graph Search
 =====================
 
-There's info and links to notebooks and examples...
+This example is about the search for graphs that are closest to a target graph by some distance metric.
+
+Target graphs are generated using `networkx`. Both ordered and random graphs are used.
+
+For objective are used graph theoretic metrics defined on features of the graph and graph matrices. In particular, distance between spectres of graph matrices are used. Spectre of the graph defines its characteristic features (like number of components, clustering, and more). For details see the `this publication <https://api.semanticscholar.org/CorpusID:118711105>`_ about graph similarity.
+
+Full code of the example can be found `in this python file <https://github.com/aimclub/GOLEM/blob/main/examples/synthetic_graph_evolution/abstract_graph_search.py>`_.
diff --git a/docs/source/faq.rst b/docs/source/faq.rst
@@ -8,6 +8,14 @@ Frequently asked questions and answers
 
     *GOLEM is an open-source AI framework for optimization and learning of structured graph-based models with meta-heuristic methods.*
 
+.. topic:: Why not just use Deep Learning?
+
+    ...
+
+.. topic:: How graphs are useful in AI?
+
+    ...
+
 .. topic:: Another question?
 
-    *Your beautifull answer*
+    *Your beautiful answer*
diff --git a/docs/source/img/adapter-structure-v1.png b/docs/source/img/adapter-structure-v1.png
diff --git a/docs/source/img/golem_logo-02.png b/docs/source/img/golem_logo-02.png
diff --git a/docs/source/img/golem_logo-03.png b/docs/source/img/golem_logo-03.png
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -23,4 +23,4 @@ Content:
    faq
    about
 
-.. |logo| image:: ../img/golem_logo.png
+.. |logo| image:: /img/golem_logo-02.png
diff --git a/docs/source/introduction.rst b/docs/source/introduction.rst
@@ -1,4 +1,16 @@
 Introduction
 ============
 
-There's your super intro!
+GOLEM is an open-source AI framework for optimization and learning of structured graph-based models with meta-heuristic methods. It is centered around 2 ideas:
+
+1. Potential of meta-heuristic methods in complex problem spaces.
+
+Focus on meta-heuristics allows approaching kinds of problems where gradient-based learning methods (notably, neural networks) can't be easily applied, like optimization problems with multiple conflicting objectives or having combinatorial character.
+
+2. Importance of structured models in many problem domains.
+
+Graph-based learning enables solutions in the form of structured and hybrid probabilistic models, not to mention that a wide range of domain-specific problems have a natural formulation in the form of graphs.
+
+Together this constitutes an approach to AI that potentially leads to structured, intuitive, interpretable methods and solutions for a wide range of tasks.
+
+To see how you can use GOLEM go to the :doc:`Quick Start Guide </quick_start>`.
diff --git a/docs/source/quick_start.rst b/docs/source/quick_start.rst
@@ -5,7 +5,7 @@ GOLEM Framework quick start guide
 
 Installation from GitHub
 ------------------------
-  | git clone https://github.com/ITMO-NSS-team/GOLEM.git
+  | git clone https://github.com/aimclub/GOLEM.git
   | cd GOLEM
   | pip install -r requirements.txt
   | pytest -s test/
@@ -14,8 +14,26 @@ How to install with pip
 -----------------------
 .. code::
 
- pip install https://github.com/ITMO-NSS-team/GOLEM/archive/master.zip
+ pip install https://github.com/aimclub/GOLEM/archive/main.zip
 
 
+Task definition
+------------------
 
- 
+The core notions of the framework are *Graph*, *Optimizer*, *Objective* and *Fitness*. GOLEM runs the optimizer, which searches for the graphs that have better fitness by the given objective.
+
+The usual workflow for solving the task with GOLEM includes these steps:
+
+1. Define the available nodes from which the graph will be built.
+2. Import the optimizer and define the settings for it.
+3. Define the objective, that is a function which for a given graph computes fitness score.
+4. Run the optimizer with given objective and get the best graphs.
+
+For a code example you can look into the `simple example <https://github.com/aimclub/GOLEM/blob/main/examples/graph_model_optimization.py>`_.
+
+Adapter for domain structures
+-----------------------------
+
+Commonly your domain task works with specific structures. These can be some special graph models, 3D models, etc. Before running GOLEM for such tasks you need to define the *graph adapter* that will transform your domain graphs to universal graph representation, that GOLEM uses internally.
+For this you either need to subclass the :py:class:`golem.core.adapter.adapter.BaseOptimizationAdapter` or use one of the existing adapters. Currently there's one non-trivial adapter for `NetworkX <https://networkx.org/>`_ directed graphs. You can read more about it in :doc:`this document </advanced/nx-interop>`.
+You can also find example using this adapter in this example on :doc:`synthetic graph search </examples/abstract>`.
-Original file line number
+Diff line change
@@ Expand Up / @@ -23,4 +23,4 @@ Content: @@
        faq
        about
-    .. |logo| image:: ../img/golem_logo.png
+    .. |logo| image:: /img/golem_logo-02.png