alexhernandezgarcia · engmubarak48 · Sep 23, 2024 · Sep 25, 2024 · Sep 25, 2024 · Oct 24, 2024
diff --git a/.gitignore b/.gitignore
@@ -15,3 +15,4 @@ playground/
 !docs/requirements-docs.txt
 .DS_Store
 docs/_build/
+logs
diff --git a/README.md b/README.md
@@ -5,15 +5,15 @@ gflownet is a library built upon [PyTorch](https://pytorch.org/) to easily train
 In a nutshell, GFlowNets can be regarded as a generative model designed to sample objects $x \in \mathcal{X}$ proportionally to a reward function $R(x)$. This results in the potential of sampling diverse objects with high rewards. For example, given the reward landscape depicted below, defined over a two-dimensional space, a well-trained GFlowNet will be able to sample from the four high-reward corners with high probability.
 
 <p align="center">
-  <img width="400" src="docs/images/reward_landscape.png" />
+  <img width="400" src="docs/source/figures/reward_landscape.png" />
 </p>
 
 GFlowNets rely on the principle of **compositionality** to generate samples. A meaningful decomposition of samples $x$ into multiple intermediate states $s_0\rightarrow s_1 \rightarrow \dots \rightarrow x$ can yield generalisable patterns. These patterns can then be learned by neural networks trained to model the value of transitions $F_{\theta}(s_t \rightarrow s_{t+1})$.
 
 Consider the problem of generating [Tetris](https://en.wikipedia.org/wiki/Tetris)-like boards. A natural decomposition of the sample generation process would be to add one piece at a time, starting from an empty board. For any state representing a board with pieces, we could identify its valid parents and children, as illustrated in the figure below.
 
 <p align="center">
-  <img width="400" src="docs/images/tetris_flows.png" />
+  <img width="400" src="docs/source/figures/tetris_flows.png" />
 </p>
 
 We could define a reward function $R(x)$ as the number of cells occupied by pieces, for instance. The goal of training a GFlowNet on this task would be to discover (sample) diverse solutions (boards with pieces) with high rewards. This represents an intuitive yet complex problem where GFlowNets can be used, which is [implemented in this library](https://github.com/alexhernandezgarcia/gflownet/blob/ahg/313-update-readme-components/gflownet/envs/tetris.py). Many problems in scientific discoveries, such as the inverse design of proteins, molecules, or crystals share similarties with this intuitive task.

diff --git a/docs/Makefile b/docs/Makefile
@@ -5,7 +5,7 @@
 # from the environment for the first two.
 SPHINXOPTS    ?=
 SPHINXBUILD   ?= sphinx-build
-SOURCEDIR     = .
+SOURCEDIR     = source
 BUILDDIR      = _build
 
 # Put it first so that "make" without argument is like "make help".

diff --git a/docs/_static/css/custom.css b/docs/_static/css/custom.css
diff --git a/docs/index.rst b/docs/index.rst
diff --git a/docs/source/.gitignore b/docs/source/.gitignore
@@ -0,0 +1 @@
+generated/
diff --git a/docs/source/_static/css/custom.css b/docs/source/_static/css/custom.css
@@ -0,0 +1,22 @@
+.sidebar-container {
+  width: 20em !important;
+}
+
+.sidebar-brand img {
+  display: block;
+  margin: 0 auto 0.5rem auto;
+  padding-top: 1rem;
+  width: 80%;
+  height: auto;
+}
+
+/* To make toctree captions bold */
+.caption .caption-text {
+  font-weight: bold;
+}
+
+/* To change the color of the first title on the page */
+.article-container>article>section>h1 {
+  color: #904e3d;
+  /* Example: Google blue */
+}
diff --git a/docs/_static/images/gflownet-logo-32.png → ...ource/_static/images/gflownet-logo-32.png b/docs/_static/images/gflownet-logo-32.png → ...ource/_static/images/gflownet-logo-32.png
diff --git a/docs/_static/images/gflownet-logo.png → docs/source/_static/images/gflownet-logo.png b/docs/_static/images/gflownet-logo.png → docs/source/_static/images/gflownet-logo.png
diff --git a/docs/_static/images/github-pr.png → docs/source/_static/images/github-pr.png b/docs/_static/images/github-pr.png → docs/source/_static/images/github-pr.png
diff --git a/docs/_templates/autoapi/index.rst → docs/source/_templates/autoapi/index.rst b/docs/_templates/autoapi/index.rst → docs/source/_templates/autoapi/index.rst
@@ -1,4 +1,4 @@
-API Reference
+Package Reference
 =============
 
 This page contains auto-generated API reference documentation [#f1]_ for the ``gflownet`` package.

diff --git a/docs/_templates/autoapi/python/attribute.rst → ...e/_templates/autoapi/python/attribute.rst b/docs/_templates/autoapi/python/attribute.rst → ...e/_templates/autoapi/python/attribute.rst
diff --git a/docs/_templates/autoapi/python/class.rst → ...ource/_templates/autoapi/python/class.rst b/docs/_templates/autoapi/python/class.rst → ...ource/_templates/autoapi/python/class.rst
diff --git a/docs/_templates/autoapi/python/data.rst → ...source/_templates/autoapi/python/data.rst b/docs/_templates/autoapi/python/data.rst → ...source/_templates/autoapi/python/data.rst
diff --git a/docs/_templates/autoapi/python/exception.rst → ...e/_templates/autoapi/python/exception.rst b/docs/_templates/autoapi/python/exception.rst → ...e/_templates/autoapi/python/exception.rst
diff --git a/docs/_templates/autoapi/python/function.rst → ...ce/_templates/autoapi/python/function.rst b/docs/_templates/autoapi/python/function.rst → ...ce/_templates/autoapi/python/function.rst
diff --git a/docs/_templates/autoapi/python/method.rst → ...urce/_templates/autoapi/python/method.rst b/docs/_templates/autoapi/python/method.rst → ...urce/_templates/autoapi/python/method.rst
diff --git a/docs/_templates/autoapi/python/module.rst → ...urce/_templates/autoapi/python/module.rst b/docs/_templates/autoapi/python/module.rst → ...urce/_templates/autoapi/python/module.rst
diff --git a/docs/_templates/autoapi/python/package.rst → ...rce/_templates/autoapi/python/package.rst b/docs/_templates/autoapi/python/package.rst → ...rce/_templates/autoapi/python/package.rst
diff --git a/docs/_templates/autoapi/python/property.rst → ...ce/_templates/autoapi/python/property.rst b/docs/_templates/autoapi/python/property.rst → ...ce/_templates/autoapi/python/property.rst
diff --git a/docs/source/advanced/stack_enviroments.rst b/docs/source/advanced/stack_enviroments.rst
@@ -0,0 +1,3 @@
+Stacked Enviroment
+===================
+This tutorial demonstrates how to use more than one enviroments one time or what we call stacked enviroments...
diff --git a/docs/conf.py → docs/source/conf.py b/docs/conf.py → docs/source/conf.py
@@ -17,7 +17,7 @@
 import sys
 from pathlib import Path
 
-ROOT = Path(__file__).resolve().parent.parent
+ROOT = Path(__file__).resolve().parent.parent.parent
 sys.path.insert(0, str(ROOT))
 
 # -- Project information -----------------------------------------------------
@@ -70,8 +70,8 @@
 html_css_files = [
     "css/custom.css",
 ]
-html_favicon = "./_static/images/gflownet-logo-32.png"
-
+html_favicon = "./_static/images/gflownet-logo.png"
+html_logo = "./figures/reward_landscape.png"
 # -----------------------------
 # -----  Plugins configs  -----
 # -----------------------------

diff --git a/docs/images/reward_landscape.png → docs/source/figures/reward_landscape.png b/docs/images/reward_landscape.png → docs/source/figures/reward_landscape.png
diff --git a/docs/images/tetris_flows.png → docs/source/figures/tetris_flows.png b/docs/images/tetris_flows.png → docs/source/figures/tetris_flows.png
diff --git a/docs/source/get_started/colabs.rst b/docs/source/get_started/colabs.rst
@@ -0,0 +1,5 @@
+Colab Notebooks and Video Tutorials
+============
+
+List of tutorials
+-----------------
diff --git a/docs/source/get_started/introduction.rst b/docs/source/get_started/introduction.rst
@@ -0,0 +1,39 @@
+Introduction by Example
+=======================
+
+Welcome to the introduction of **gflownet**, a library designed to facilitate training and extending Generative Flow Networks (GFlowNets) for a wide range of applications, especially in scientific discovery. GFlowNets provide a framework for probabilistic and generative modeling.
+
+What are GFlowNets?
+-------------------
+
+Generative Flow Networks, or GFlowNets, are a type of generative model that sample objects $x \in \mathcal{X}$ proportionally to a reward function $R(x)$. This framework is particularly suited for applications where the goal is to generate diverse high-reward samples, such as in scientific discovery.
+
+.. image:: ../figures/reward_landscape.png
+   :align: center
+   :width: 400
+   :alt: Reward landscape
+
+The model learns to transition between states in a way that the frequency of generating any given state is proportional to its reward. For instance, a GFlowNet trained on a 2D space with four high-reward areas would learn to sample those areas more frequently.
+
+Compositionality and Sampling
+------------------------------
+
+GFlowNets utilize compositionality by decomposing samples $x$ into sequences of intermediate states, such as:
+
+.. image:: ../figures/tetris_flows.png
+   :align: center
+   :width: 400
+   :alt: Tetris flows
+
+In the example of generating Tetris-like boards, each board configuration is built by adding one piece at a time, starting from an empty board. Each intermediate state has potential "parents" and "children," forming a directed graph over states, where each edge (transition from one state to another) is modeled and learned.
+
+
+Key Components
+--------------
+
+**gflownet** comprises several core components essential for its operation:
+
+- **Environment**: Defines the state and action spaces for tasks, such as the Tetris or Scrabble environments.
+- **Proxy**: Manages the reward function logic, essential for evaluating states.
+- **Policy Models**: Neural networks that model the transitions between states.
+- **GFlowNet Agent**: Orchestrates interactions between the environment, policies, and proxy, among other functions.
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -0,0 +1,30 @@
+GFlowNets Documentation
+======================
+
+Welcome to the documentation for **gflownet**, a library built upon `PyTorch <https://pytorch.org>`_ to facilitate training and extending Generative Flow Networks (GFlowNets) for a wide range of applications, particularly in scientific discovery problems.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Install gflownet
+
+   install/installation
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Get Started
+
+   get_started/introduction
+   get_started/colabs
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Tutorials
+
+   tutorials/grid_enviroment
+   tutorials/add_enviroment
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Advanced Concepts
+
+   advanced/stack_enviroments
diff --git a/docs/source/install/installation.rst b/docs/source/install/installation.rst
@@ -0,0 +1,75 @@
+Installation
+============
+
+This section provides detailed instructions on how to install **gflownet**. Ensure your system meets the following requirements before proceeding with the installation.
+
+Requirements
+------------
+
+* **Python Version:** Python 3.10 is required.
+* **CUDA Version:** CUDA 11.8 is needed for GPU acceleration.
+* **Operating System:** The setup is primarily supported on Ubuntu. The installation may work on OSX with manual handling of package dependencies.
+
+Quick Installation
+------------------
+
+For a quick installation, clone the repository and execute the setup script:
+
+.. code-block:: bash
+
+    git clone [email protected]:alexhernandezgarcia/gflownet.git
+    cd gflownet
+    ./setup_all.sh
+
+Detailed Installation
+---------------------
+
+If you prefer a more controlled installation or need to customize the environment, follow these steps:
+
+1. **Create a Virtual Environment:**
+
+   .. code-block:: bash
+
+       python3.10 -m venv ~/envs/gflownet  # Initialize your virtual environment.
+
+2. **Activate the Virtual Environment:**
+
+   .. code-block:: bash
+
+       source ~/envs/gflownet/bin/activate  # Activate your environment.
+
+3. **Install Ubuntu Prerequisites:**
+
+   .. code-block:: bash
+
+       ./prereq_ubuntu.sh  # Installs some packages required by dependencies.
+
+4. **Install Python Prerequisites:**
+
+   .. code-block:: bash
+
+       ./prereq_python.sh  # Installs Python packages with specific wheels.
+
+5. **Optional: Install Geometric Dependencies:**
+
+   .. code-block:: bash
+
+       ./prereq_geometric.sh  # OPTIONAL - for the molecule environment.
+
+6. **Install gflownet:**
+
+   .. code-block:: bash
+
+       pip install .[all]  # Install the remaining elements of this package.
+
+Optional Packages
+-----------------
+
+You can also install additional optional packages tailored for specific functionalities:
+
+* **Development Tools:** Install with `dev` tag.
+* **Materials Science Dependencies:** Install with `materials` tag.
+* **Molecular Environment Packages:** Install with `molecules` tag.
+
+The `all` tag installs all dependencies, which is the simplest and recommended option if you require full functionality.
+
diff --git a/docs/source/tutorials/add_enviroment.rst b/docs/source/tutorials/add_enviroment.rst
@@ -0,0 +1,2 @@
+How to add custom enviroment
+============
diff --git a/docs/source/tutorials/grid_enviroment.rst b/docs/source/tutorials/grid_enviroment.rst
@@ -0,0 +1,2 @@
+Grid Enviroment tutorial
+============
diff --git a/docs/tutorial.rst b/docs/tutorial.rst
diff --git a/prereq_ci.sh b/prereq_ci.sh
@@ -4,4 +4,4 @@ python -m pip install --ignore-installed six appdirs
 python -m pip install torch==2.0.1
 python -m pip install dgl==1.1.3+cu118
 python -m pip install dglgo==0.0.2
-python -m pip install pyg_lib==0.3.1 torch_scatter==2.1.2 torch_sparse==0.6.18 torch_geometric==2.4.0 torch_cluster==1.6.3 torch_spline_conv==1.2.2 -f https://data.pyg.org/whl/torch-2.0.0+cpu.html
+python -m pip install pyg_lib==0.3.1 torch_scatter==2.1.2 torch_sparse==0.6.18 torch_geometric==2.4.0 torch_cluster==1.6.3 torch_spline_conv==1.2.2 -f https://data.pyg.org/whl/torch-2.0.0+cpu.html