update install instructions (#705)

* update install instructions * fix up install instructions * documentation build breaking, lets try auto * double notebook timeout * dont execute cattsunami tutorial in docs * no logo for now * final edits --------- Co-authored-by: lbluque <[email protected]>
FAIR-Chem · May 17, 2024 · f5e1ad8 · f5e1ad8
1 parent bcb3cf5
commit f5e1ad8
Show file tree

Hide file tree

Showing 4 changed files with 65 additions and 35 deletions.
diff --git a/docs/_config.yml b/docs/_config.yml
@@ -1,20 +1,20 @@
 #######################################################################################
 # A default configuration that will be loaded for all jupyter books
-# See the documentation for help and more options: 
+# See the documentation for help and more options:
 # https://jupyterbook.org/customize/config.html
 
 #######################################################################################
 # Book settings
-title                       : FAIR Chemistry Documentation  # The title of the book. Will be placed in the left navbar.
+title                       : "" # FAIR Chemistry Documentation  # The title of the book. Will be placed in the left navbar.
 author                      : FAIR Chemistry & Collaborators  # The author of the book
 copyright                   : "2024"  # Copyright year to be placed in the footer
-logo                        : logo.png  # A path to the book logo
+# logo                        : logo.png  # A path to the book logo - no logo looks better than old logo
 
 # Force re-execution of notebooks on each build.
 # See https://jupyterbook.org/content/execute.html
 execute:
-  execute_notebooks: force
-  timeout: 1800
+  execute_notebooks: 'off' # auto
+  timeout: 3600
 
 # Define the name of the latex output file for PDF builds
 latex:
@@ -30,7 +30,7 @@ repository:
   url: https://github.com/FAIR-Chem/fairchem  # Online location of your book
   path_to_book: docs  # Optional path to your book, relative to the repository root
   branch: main  # Which branch of the repository should be used when creating links (optional)
-  
+
 # Add GitHub buttons to your book
 # See https://jupyterbook.org/customize/config.html#add-a-link-to-your-repository
 html:
@@ -43,7 +43,7 @@ parse:
     # including those that are enabled by default!
     - amsmath
     - dollarmath
-    
+
 sphinx:
   extra_extensions:
   - 'sphinx.ext.napoleon'

diff --git a/docs/core/install.md b/docs/core/install.md
@@ -1,33 +1,40 @@
 # Installation
 
-### conda or better yet [mamba](https://mamba.readthedocs.io/en/latest/user_guide/mamba.html) - easy
+To install `fairchem-core` you will need to setup the `fairchem-core` environment (using [conda](#Conda) or [pip](#PyPi))
+and then either install `fairchem-core` package [directly](#Install-fairchem-core) or install a [development version](#Development-install) from our git repository.
+
+## Environment
+
+You can install the environment using either conda or pip
+
+### Conda
 
 We do not have official conda recipes (yet!); in the meantime you can use the
-following environment yaml files for CPU [env.cpu.yml](https://raw.githubusercontent.com/FAIR-Chem/fairchem/main/packages/env.cpu.yml)
-or GPU [env.gpu.yml](https://raw.githubusercontent.com/FAIR-Chem/fairchem/main/packages/env.gpu.yml) to easily set up a
-working environment and install `fairchem-core`.
+following environment yaml files to setup on CPU or GPU. If conda is too slow for you, please consider using [mamba](https://mamba.readthedocs.io/en/latest/user_guide/mamba.html)
 
 1. Create an environment to install *fairchem*
-   1. **GPU**
+
+   a. **GPU**
 
       The default environment uses cuda 11.8, if you need a different version you will have to edit *pytorch-cuda* version
       accordingly.
       ```bash
+      wget https://raw.githubusercontent.com/FAIR-Chem/fairchem/main/packages/env.gpu.yml
       conda env create -f env.gpu.yml
       ```
 
-   2. **CPU**
+   b. **CPU**
       ```bash
+      wget https://raw.githubusercontent.com/FAIR-Chem/fairchem/main/packages/env.cpu.yml
       conda env create -f env.cpu.yml
       ```
 
-2. Activate the environment and install `fairchem-core` from PyPi
+2. Activate the environment
    ```bash
    conda activate fair-chem
-   pip install fairchem-core
    ```
 
-### PyPi - flexible
+### PyPi
 You can also install `pytorch` and `torch_geometric` dependencies from PyPI to select specific CPU or CUDA versions.
 
 1. Install `pytorch` by selecting your installer, OS and CPU or CUDA version following the official
@@ -37,11 +44,11 @@ You can also install `pytorch` and `torch_geometric` dependencies from PyPI to s
    similarly by selecting the appropriate versions in the official
    [PyG docs](https://pytorch-geometric.readthedocs.io/en/latest/notes/installation.html)
 
-3. Install `fairchem-core` from PyPi
-   ```bash
-   pip install fairchem-core
-   ```
-
+## Install fairchem-core
+Install `fairchem-core` from PyPi
+```bash
+pip install fairchem-core
+```
 
 ## Additional packages
 
@@ -51,12 +58,13 @@ to install other packages you can do so by:
 pip install fairchem-{package-to-install}
 ```
 
-## Dev install
+## Development install
 
-If you plan to make contributions you will need to clone (for windows user please see next section) the repo and install
-`fairchem-core` in editable mode with dev
-dependencies,
+If you plan to make contributions you will need to fork and clone (for windows user please see next section) the repo,
+set up the environment, and install fairchem-core from source in editable mode with dev dependencies,
 ```bash
+git clone https://github.com/FAIR-Chem/fairchem.git
+cd fairchem
 pip install -e packages/fairchem-core[dev]
 ```
 
@@ -69,9 +77,7 @@ pip install -e packages/fairchem-{package-to-install}
 
 Our build system requires the use of symlinks which are not available by default on windows. To properly build fairchem packages you must enable symlinks and clone the repository with them enabled.
 
-1) When installing git on your machine make sure "enable symbolic links" is checked  ([download git installer](https://git-scm.com/download/win))
-
-![Enable symlinks on git install](https://i.stack.imgur.com/kZmPI.png)
+1) When installing git on your machine make sure "enable symbolic links" is checked  ([download git installer](https://git-scm.com/download/win)) ([see here](https://stackoverflow.com/a/65563980) for detailed instructions )
 
 2) Enable developer mode ([instructions](https://learn.microsoft.com/en-us/windows/apps/get-started/enable-your-device-for-development)) or run the following commands as administrator
 

diff --git a/docs/index.md b/docs/index.md
@@ -1,4 +1,5 @@
-<h1 align="center"> <code>fairchem</code> by FAIR Chemistry </h1>
+
+<h2 align="center"> <code>fairchem</code> by FAIR Chemistry </h2>
 
 <p align="center">
   <img width="559" height="200" src="https://github.com/FAIR-Chem/fairchem/assets/45150244/5872c21c-8f39-41af-b703-af9817f0affe"?
@@ -11,6 +12,8 @@
 
 </h4>
 
+#### FAIR-Chem overview
+
 `fairchem` is the [FAIR](https://ai.meta.com/research/) Chemistry's centralized repository of all its data, models, demos, and application efforts
 for materials science and quantum chemistry. Collaborative projects that contribute or use the models and approaches in
 this repo:
@@ -22,7 +25,7 @@ We re-organized and rebranded the repository in 2024 (previously the `fairchem`
 general usability of these models beyond catalysis, including things like direct air capture.
 ```
 
-### Datasets in `fairchem`:
+#### Datasets in `fairchem`:
 `fairchem` provides training and evaluation code for tasks and models that take arbitrary
 chemical structures as input to predict energies / forces / positions / stresses,
 and can be used as a base scaffold for research projects. For an overview of
@@ -33,7 +36,7 @@ tasks, data, and metrics, please read the documentations and respective papers:
  - [OC20Dense](core/datasets/oc20dense)
  - [OC20NEB](core/datasets/oc20neb)
 
-### Projects and models built on `fairchem`:
+#### Projects and models built on `fairchem`:
 
 - SchNet [[`arXiv`](https://arxiv.org/abs/1706.08566)] [[`code`](https://github.com/FAIR-Chem/fairchem/blob/main/src/fairchem/core/models/schnet.py)]
 - DimeNet++ [[`arXiv`](https://arxiv.org/abs/2011.14115)] [[`code`](https://github.com/FAIR-Chem/fairchem/blob/main/src/fairchem/core/models/dimenet_plus_plus.py)]
@@ -53,15 +56,15 @@ Older model implementations that are no longer supported:
 - SpinConv [[`arXiv`](https://arxiv.org/abs/2106.09575)] [[`code`](https://github.com/FAIR-Chem/fairchem/blob/e7a8745eb307e8a681a1aa9d30c36e8c41e9457e/ocpmodels/models/spinconv.py)]
 - ForceNet [[`arXiv`](https://arxiv.org/abs/2103.01436)] [[`code`](https://github.com/FAIR-Chem/fairchem/blob/e7a8745eb307e8a681a1aa9d30c36e8c41e9457e/ocpmodels/models/forcenet.py)]
 
-## Discussion
+### Discussion
 
 For all non-codebase related questions and to keep up-to-date with the latest OCP
 announcements, please join the [discussion board](https://discuss.opencatalystproject.org/).
 
 All code-related questions and issues should be posted directly on our
 [issues page](https://github.com/FAIR-Chem/fairchem/issues).
 
-## Acknowledgements
+### Acknowledgements
 
 - This codebase was initially forked from [CGCNN](https://github.com/txie-93/cgcnn)
 by [Tian Xie](http://txie.me), but has undergone significant changes since.
@@ -70,11 +73,11 @@ by [Tian Xie](http://txie.me), but has undergone significant changes since.
 - It was then developed as the OCP repo, and includes many contributions from the community and collaborators.
 - Much of the documentation was developed for various papers or as part of a comprehensive tutorial for the 2023 ACS Fall Chemistry conference.
 
-## License
+### License
 
 `fairchem` is released under the [MIT](https://github.com/FAIR-Chem/fairchem/blob/main/LICENSE.md) license.
 
-## Citing `fairchem`
+### Citing `fairchem`
 
 If you use this codebase in your work, please consider citing:
 

diff --git a/docs/tutorials/cattsunami_walkthrough.md b/docs/tutorials/cattsunami_walkthrough.md
@@ -14,6 +14,9 @@ kernelspec:
 # CatTSunami tutorial
 
 ```{code-cell} ipython3
+---
+tags: ["skip-execution"]
+---
 from fairchem.applications.cattsunami.core import Reaction
 from fairchem.data.oc.core import Slab, Adsorbate, Bulk, AdsorbateSlabConfig
 from fairchem.core.common.relaxation.ase_utils import OCPCalculator
@@ -40,6 +43,9 @@ To start, we generate placements for the reactant and product species on the sur
 
 
 ```{code-cell} ipython3
+---
+tags: ["skip-execution"]
+---
 # Instantiate the reaction class for the reaction of interest
 reaction = Reaction(reaction_str_from_db="*CH -> *C + *H",
                     reaction_db_path=DISSOCIATION_REACTION_DB_PATH,
@@ -68,6 +74,9 @@ product2_configs = AdsorbateSlabConfig(slab = slab[0], adsorbate = product2,
 ```
 
 ```{code-cell} ipython3
+---
+tags: ["skip-execution"]
+---
 # Instantiate the calculator
 # NOTE: If you have a GPU, use cpu = False
 # NOTE: Change the checkpoint path to locally downloaded files as needed
@@ -87,6 +96,9 @@ There are 2 options for how to do this.
 You need to provide the calculator with a path to a model checkpoint file. That can be downloaded [here](../core/model_checkpoints)
 
 ```{code-cell} ipython3
+---
+tags: ["skip-execution"]
+---
 # Relax the reactant systems
 reactant_energies = []
 for config in reactant_configs:
@@ -116,6 +128,9 @@ Here we use the class we created to handle automatic generation of NEB frames to
 ![dissociation_scheme](https://github.com/FAIR-Chem/fairchem/blob/main/src/fairchem/applications/cattsunami/tutorial/dissociation_scheme.png)
 
 ```{code-cell} ipython3
+---
+tags: ["skip-execution"]
+---
 af = AutoFrameDissociation(
             reaction = reaction,
             reactant_system = reactant_configs[reactant_energies.index(min(reactant_energies))],
@@ -140,6 +155,9 @@ frame_sets, mapping_idxs = af.get_neb_frames(calc,
 Here we use the custom child class we created to run NEB relaxations using ML. The class we created allows the frame relaxations to be batched, improving efficiency.
 
 ```{code-cell} ipython3
+---
+tags: ["skip-execution"]
+---
 ## This will run all NEBs enumerated - to just run one, run the code cell below.
 # On GPU, each NEB takes an average of ~1 minute so this could take around a half hour on GPU
 # But much longer on CPU
@@ -172,6 +190,9 @@ Here we use the custom child class we created to run NEB relaxations using ML. T
 ```
 
 ```{code-cell} ipython3
+---
+tags: ["skip-execution"]
+---
 # If you run the above cell -- dont run this one
 fmax = 0.05 # [eV / ang**2]
 delta_fmax_climb = 0.4