Add docs as ipynb, and reduce time for adsorption example (#1304)

zulissimeta · web-flow · commit 9793d997bc5b · 2025-06-26T09:28:21.000-07:00
* small changes

* update github codespaces install

* clean up install content for consistency across tutorials

* make sure ipynb works for uma tutorial

* long timeout
diff --git a/.devcontainer/postCreateCommand.sh b/.devcontainer/postCreateCommand.sh
@@ -1,11 +1,5 @@
 #!/bin/bash
-if [ -f packages/requirements.txt ]; then pip install -r packages/requirements.txt; fi
-if [ -f packages/requirements-optional.txt ]; then pip install -r packages/requirements-optional.txt; fi
-pip install -e packages/fairchem-core[dev,docs,adsorbml]
-pip install -e packages/fairchem-data-oc[dev]
-pip install -e packages/fairchem-demo-ocpapi[dev]
-pip install -e packages/fairchem-applications-cattsunami
-pip install jupytext
+pip install -e packages/fairchem-core[docs,adsorbml,quacc] -e packages/fairchem-data-oc[dev] -e packages/fairchem-applications-cattsunami jupytext
 
 # Convert all .md docs to ipynb for easy viewing in vscode later!
 find ./docs -name '*.md' -exec jupytext --to ipynb {} \;
diff --git a/.github/workflows/build_docs.yml b/.github/workflows/build_docs.yml
@@ -41,6 +41,9 @@ jobs:
         # Set FAST_DOCS only if not a push to main
         FAST_DOCS: ${{ (github.event_name != 'push' || github.ref != 'refs/heads/main') && 'true' || '' }}
       run: |
+        # Convert MyST markdown files to Jupyter notebooks if needed to get download as ipynb buttons
+        jupytext --to ipynb ./docs/uma_tutorials/uma_tutorial.md
+        # find ./docs/ -name "*.md" -exec grep -q "format_name: myst" {} \; -print0 | xargs -0 jupytext --to ipynb
         jupyter-book build docs
 
     - name: Upload documentation artifact
diff --git a/docs/_config.yml b/docs/_config.yml
@@ -14,7 +14,7 @@ copyright                   : "2024"  # Copyright year to be placed in the foote
 # See https://jupyterbook.org/content/execute.html
 execute:
   execute_notebooks: cache
-  timeout: 7200
+  timeout: 14400
   allow_errors: false
 
 # Define the name of the latex output file for PDF builds
diff --git a/docs/catalysts/examples_tutorials/OCP-introduction.md b/docs/catalysts/examples_tutorials/OCP-introduction.md
@@ -56,12 +56,41 @@ Based on https://atct.anl.gov/Thermochemical%20Data/version%201.118/species/?spe
 
 The first step is getting a checkpoint for the model we want to use. UMA is currently the state-of-the-art model and will provide total energy estimates at the RPBE level of theory if you use the "OC20" task. 
 
-This next cell will automatically download the checkpoint from huggingface and load it. 
-1. You need to first request access to the UMA model here: https://huggingface.co/facebook/UMA
-2. You also need to run `huggingface-cli login` and follow the instructions to get a token from huggingface to authenticate to the servers. 
+
+````{admonition} Need to install fairchem-core or get UMA access or getting permissions/401 errors?
+:class: dropdown
+
+
+1. Install the necessary packages using pip, uv etc
+```{code}
+:tags: [skip-execution]
+
+! pip install fairchem-core fairchem-data-oc fairchem-applications-cattsunami
+```
+
+2. Get access to any necessary huggingface gated models 
+    * Get and login to your Huggingface account
+    * Request access to https://huggingface.co/facebook/UMA
+    * Create a Huggingface token at https://huggingface.co/settings/tokens/ with the permission "Permissions: Read access to contents of all public gated repos you can access"
+    * Add the token as an environment variable using `huggingface-cli login` or by setting the HF_TOKEN environment variable. 
+
+```{code}
+:tags: [skip-execution]
+
+# Login using the huggingface-cli utility
+# ! huggingface-cli login
+
+# alternatively,
+import os
+os.environ['HF_TOKEN'] = 'MY_TOKEN'
+```
+
+````
 
 If you find your kernel is crashing, it probably means you have exceeded the allowed amount of memory. This checkpoint works fine in this example, but it may crash your kernel if you use it in the NRR example.
 
+This next cell will automatically download the checkpoint from huggingface and load it. 
+
 ```{code-cell}
 from __future__ import annotations
 
diff --git a/docs/catalysts/examples_tutorials/adsorbml_walkthrough.md b/docs/catalysts/examples_tutorials/adsorbml_walkthrough.md
@@ -17,6 +17,14 @@ The [AdsorbML](https://arxiv.org/abs/2211.16486) paper showed that pre-trained m
 
 The latest UMA models are now total-energy models, and the results for the adsorption energy are even more impressive ([see the paper for details and benchmarks](https://ai.meta.com/research/publications/uma-a-family-of-universal-models-for-atoms/)). The AdsorbML package helps you with automated multi-adsorbate placement, and will automatically run calculations using the ML models to find the best sites to sample. 
 
+:::{note} Need to install fairchem-core or get UMA access or getting permissions/401 errors?
+:class: dropdown
+
+```{include} ../../core/simplified_install.md
+```
+
+:::
+
 ## Define desired adsorbate+slab system
 
 ```{code-cell} ipython3
diff --git a/docs/catalysts/examples_tutorials/adsorption_energies/adsorption_energies.md b/docs/catalysts/examples_tutorials/adsorption_energies/adsorption_energies.md
@@ -17,6 +17,14 @@ Expert adsorption energies
 
 One of the most common tasks in computational catalysis is calculating the binding energies or adsorption energies of small molecules on catalyst surfaces.
 
+:::{note} Need to install fairchem-core or get UMA access or getting permissions/401 errors?
+:class: dropdown
+
+```{include} ../../core/simplified_install.md
+```
+
+:::
+
 ```{code-cell} ipython3
 from __future__ import annotations
 
@@ -189,7 +197,7 @@ if fast_docs:
     relaxation_steps = 20
 else:
     num_bulks = -1
-    num_sites = 100
+    num_sites = 20
     relaxation_steps = 300
 ```
 
diff --git a/docs/catalysts/examples_tutorials/cattsunami_tutorial.md b/docs/catalysts/examples_tutorials/cattsunami_tutorial.md
@@ -30,6 +30,14 @@ else:
     optimization_steps = 300
 ```
 
+:::{note} Need to install fairchem-core or get UMA access or getting permissions/401 errors?
+:class: dropdown
+
+```{include} ../../core/simplified_install.md
+```
+
+:::
+
 ## Do enumerations in an AdsorbML style
 
 ```{code-cell} ipython3
diff --git a/docs/catalysts/examples_tutorials/ocpapi.md b/docs/catalysts/examples_tutorials/ocpapi.md
@@ -16,15 +16,14 @@ Python library for programmatic use of the [Open Catalyst Demo](https://open-cat
 
 ## Installation
 
-Ensure you have Python 3.9.1 or newer, and install `ocpapi` using:
+:::{note} Need to install fairchem-core or get UMA access or getting permissions/401 errors?
+:class: dropdown
 
-```{code-cell} ipython3
----
-tags: ["skip-execution"]
----
-! pip install -q ocpapi
+```{include} ../../core/simplified_install.md
 ```
 
+:::
+
 ## Quickstart
 
 The following examples are used to search for *OH binding sites on Pt surfaces. They use the `find_adsorbate_binding_sites` function, which is a high-level workflow on top of other methods included in this library. Once familiar with this routine, users are encouraged to learn about lower-level methods and features that support more advanced use cases.
diff --git a/docs/core/common_tasks/ase_calculator.md b/docs/core/common_tasks/ase_calculator.md
@@ -27,6 +27,13 @@ predictor = pretrained_mlip.get_predict_unit("uma-s-1", device="cuda")
 calc = FAIRChemCalculator(predictor, task_name="oc20")
 ```
 
+:::{note} Need to install fairchem-core or get UMA access or getting permissions/401 errors?
+:class: dropdown
+
+```{include} ../../core/simplified_install.md
+```
+:::
+
 ## Default mode
 
 UMA is designed for both general-purpose usage (single or batched systems) and single-system long rollout (MD simulations, relaxations, etc.). For general-purpose use, we suggest using the [default settings](https://github.com/facebookresearch/fairchem/blob/main/src/fairchem/core/units/mlip_unit/api/inference.py#L92). This is a good trade-off between accuracy, speed, and memory consumption and should suffice for most applications. In this setting, on a single 80GB H100 GPU, we expect a user should be able to compute on systems as large as 50k-100k neighbors (depending on their atomic density). Batching is also supported in this mode.
diff --git a/docs/core/common_tasks/batch_inference.md b/docs/core/common_tasks/batch_inference.md
@@ -1,5 +1,12 @@
 # Batch inference with UMA models
 
+:::{note} Need to install fairchem-core or get UMA access or getting permissions/401 errors?
+:class: dropdown
+
+```{include} ../../core/simplified_install.md
+```
+:::
+
 If your application requires predictions over many systems you can run batch inference using
 UMA models to use compute more efficiently and improve GPU utilization. Below we show some easy ways to run batch
 inference over batches created at runtime or loading from a dataset. If you want to learn more about the different
@@ -39,8 +46,7 @@ preds["energy"][0]
 preds["forces"][batch.batch == 0]
 ```
 
-Batch inference using a dataset and a dataloader
-------------------------------------------------
+## Batch inference using a dataset and a dataloader
 
 If you are running predictions over more structures than you can fit in memory, you can run inference using
 a torch Dataloader,
@@ -60,8 +66,8 @@ for batch in loader:
     preds = predictor.predict(batch)
 ```
 
-Inference over heterogenous batches
------------------------------------
+## Inference over heterogenous batches
+
 For the odd cases where you want to batch systems to be computed with different task predictions
 (ie molecules and materials), you can take advantage of UMA models and do it in a single batch
 as follows,
diff --git a/docs/core/install.md b/docs/core/install.md
@@ -21,6 +21,21 @@ pip install fairchem-core
 
 In V2, we removed all dependencies on 3rd party libraries such as torch-geometric, pyg, torch-scatter, torch-sparse etc that made installation difficult. So no additional steps are required!
 
+## Subpackages
+
+In addition to `fairchem-core`, there are related packages for specialized tasks or applications. Each can be installed with `pip` or `uv` just like `fairchem-core`:
+* `fairchem-data-oc`
+* `fairchem-applications-cattsunami`
+* `fairchem-demo-ocpapi`
+
+## Access to gated models on huggingface
+
+To access gated models like UMA, you need to get a HuggingFace account and request access to the UMA models.
+
+1. Get and login to your Huggingface account
+2. Request access to https://huggingface.co/facebook/UMA
+3. Create a Huggingface token at https://huggingface.co/settings/tokens/ with the permission "Permissions: Read access to contents of all public gated repos you can access"
+4. Add the token as an environment variable (using `huggingface-cli login` or by setting the HF_TOKEN environment variable. 
 
 ## License
 
diff --git a/docs/core/quickstart.md b/docs/core/quickstart.md
@@ -25,6 +25,13 @@ appropriate task name for domain specific prediction.
 - **odac:** use this for MOFs
 - **omc:** use this for molecular crystals
 
+:::{note} Need to install fairchem-core or get UMA access or getting permissions/401 errors?
+:class: dropdown
+
+```{include} ../../core/simplified_install.md
+```
+:::
+
 ## Relax an adsorbate on a catalytic surface
 ```python
 from ase.build import fcc100, add_adsorbate, molecule
diff --git a/docs/core/simplified_install.md b/docs/core/simplified_install.md
@@ -0,0 +1,24 @@
+
+1. Install the necessary packages using pip, uv etc
+```{code}
+:tags: [skip-execution]
+
+! pip install fairchem-core fairchem-data-oc fairchem-applications-cattsunami
+```
+
+2. Get access to any necessary huggingface gated models 
+    * Get and login to your Huggingface account
+    * Request access to https://huggingface.co/facebook/UMA
+    * Create a Huggingface token at https://huggingface.co/settings/tokens/ with the permission "Permissions: Read access to contents of all public gated repos you can access"
+    * Add the token as an environment variable using `huggingface-cli login` or by setting the HF_TOKEN environment variable. 
+
+```{code}
+:tags: [skip-execution]
+
+# Login using the huggingface-cli utility
+# ! huggingface-cli login
+
+# alternatively,
+import os
+os.environ['HF_TOKEN'] = 'MY_TOKEN'
+```
diff --git a/docs/dac/examples_tutorials/adsorption_energy.md b/docs/dac/examples_tutorials/adsorption_energy.md
@@ -24,15 +24,15 @@ Each term on the right-hand side represents the energy of the relaxed state of t
 
 ## Loading Pre-trained Models
 
-To leverage the ODAC pre-trained models, ensure you have fairchem version 2 installed; more details are available [here](../../core/fairchemv1_v2.html). You can install the required version using pip if you haven't already:
+:::{note} Need to install fairchem-core or get UMA access or getting permissions/401 errors?
 
-```{code-cell}
-:tags: [skip-execution]
-
-!pip install fairchem-core
+```{include} ../../core/simplified_install.md
 ```
 
-Once installed, a pre-trained model can be loaded using `FAIRChemCalculator`. In this example, we'll employ UMA to determine the CO<sub>2</sub> adsorption energies.
+:::
+
+
+A pre-trained model can be loaded using `FAIRChemCalculator`. In this example, we'll employ UMA to determine the CO<sub>2</sub> adsorption energies.
 
 ```{code-cell}
 from fairchem.core import FAIRChemCalculator, pretrained_mlip
diff --git a/docs/index.md b/docs/index.md
@@ -35,10 +35,11 @@ If you want to explore model capabilities check out our
 
 [![Educational Demo](https://github.com/user-attachments/assets/7005d1bb-4459-403d-b299-d41fdd8c48ec)](https://facebook-fairchem-uma-demo.hf.space/)
 
-## Installation
-Although not required, we highly recommend installing using a package manager and virtualenv such as [uv](https://docs.astral.sh/uv/getting-started/installation/#standalone-installer), it is much faster and better at resolving dependencies than standalone pip.
 
-Install fairchem-core using pip
-```bash
-pip install fairchem-core
+:::{note} Need to install fairchem-core or get UMA access or getting permissions/401 errors?
+:class: dropdown
+
+```{include} ../../core/simplified_install.md
 ```
+
+:::
diff --git a/docs/inorganic_materials/examples_tutorials/bulk_stability.md b/docs/inorganic_materials/examples_tutorials/bulk_stability.md
@@ -18,7 +18,12 @@ We're going to start simple here - let's run a local relaxation (optimize the un
 1. It's a relatively small (31M) parameter model
 2. It was pre-trained on the OMat24 dataset, and then fine-tuned on the MPtrj and Alexandria datasets, so it should emit energies and forces that are consistent with the MP GGA (PBE/PBE+U) level of theory
 
-This code will download the appropriate checkpoint from huggingface_hub automatically; if you don't have the right access token specified, you'll hit an permission or 401 error.
+:::{note} Need to install fairchem-core or get UMA access or getting permissions/401 errors?
+:class: dropdown
+
+```{include} ../../core/simplified_install.md
+```
+:::
 
 ```{code-cell} ipython3
 from __future__ import annotations
diff --git a/docs/inorganic_materials/examples_tutorials/elastic.md b/docs/inorganic_materials/examples_tutorials/elastic.md
@@ -24,6 +24,13 @@ We don't have to change much code from above, we just use a built-in recipe to c
 
 For more documentation, see the quacc docs for [quacc.recipes.mlp.elastic_tensor_flow](https://quantum-accelerators.github.io/quacc/reference/quacc/recipes/mlp/elastic.html#quacc.recipes.mlp.elastic.elastic_tensor_flow)
 
+:::{note} Need to install fairchem-core or get UMA access or getting permissions/401 errors?
+:class: dropdown
+
+```{include} ../../core/simplified_install.md
+```
+:::
+
 ```{code-cell} ipython3
 from __future__ import annotations
 
diff --git a/docs/inorganic_materials/examples_tutorials/phonons.md b/docs/inorganic_materials/examples_tutorials/phonons.md
@@ -60,3 +60,10 @@ print(
 ```
 
 Congratulations, you ran your first phonon calculation!
+
+:::{note} Need to install fairchem-core or get UMA access or getting permissions/401 errors?
+:class: dropdown
+
+```{include} ../../core/simplified_install.md
+```
+:::
diff --git a/docs/uma_tutorials/uma_tutorial.md b/docs/uma_tutorials/uma_tutorial.md
