From f5e1ad8305c74c645ceff8617d564181b038557e Mon Sep 17 00:00:00 2001 From: Misko Date: Fri, 17 May 2024 10:36:20 -0700 Subject: [PATCH] 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 --- docs/_config.yml | 14 +++---- docs/core/install.md | 48 +++++++++++++----------- docs/index.md | 17 +++++---- docs/tutorials/cattsunami_walkthrough.md | 21 +++++++++++ 4 files changed, 65 insertions(+), 35 deletions(-) diff --git a/docs/_config.yml b/docs/_config.yml index 758503391..03f4283ec 100644 --- 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 index d48265a65..8ad523f32 100644 --- 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 index 2ebb90111..7e279abd3 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,4 +1,5 @@ -

fairchem by FAIR Chemistry

+ +

fairchem by FAIR Chemistry

+#### 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,7 +56,7 @@ 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/). @@ -61,7 +64,7 @@ announcements, please join the [discussion board](https://discuss.opencatalystpr 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 index 648ab4c3b..5d70a38ff 100644 --- 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