Skip to content

Commit 04b9299

Browse files
joaanderjoaander
committed
Rewrite docs in mdbook.
1 parent 528064a commit 04b9299

File tree

11 files changed

+631
-3
lines changed

11 files changed

+631
-3
lines changed

‎README.md

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,10 @@
22

33
**glotzerlab-software** deploys software developed by the [Glotzer group] at the
44
[University of Michigan] to HPC resources via conda packages. Use
5-
**glotzerlab-software** to install an MPI and GPU enabled build of HOOMD-blue on a *HPC
6-
resource*. Use the standard conda-forge provided HOOMD-blue (`mamba install hoomd` with
5+
**glotzerlab-software** to install an MPI and GPU enabled build of HOOMD-blue
6+
and related packages on a *HPC resource*.
7+
8+
Use the standard conda-forge provided HOOMD-blue (`mamba install hoomd` with
79
no special configuration) for serial execution on individual workstations.
810

911
[Glotzer group]: http://glotzerlab.engin.umich.edu

‎doc/.gitignore

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
build
1+
book

‎doc/book.toml

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
[book]
2+
language = "en"
3+
multilingual = false
4+
src = "src"
5+
title = "Glotzerlab-software documentation"
6+
7+
[output.html]
8+
git-repository-url = "https://github.com/glotzerlab/software"
9+
10+
[build]
11+
create-missing = false
12+
13+
# Uncomment to enable link checking in docs. Normally these checks are only performed in CI.
14+
# You also need to install https://github.com/Michael-F-Bryan/mdbook-linkcheck.
15+
# [output.linkcheck]
16+
# follow-web-links = true

‎doc/src/SUMMARY.md

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
# Summary
2+
3+
[Introduction](index.md)
4+
5+
- [Conda packages](conda.md)
6+
- [Glotzer lab members](glotzer.md)
7+
- [Building packages](build.md)
8+
- [Installing packages](install.md)

‎doc/src/build.md

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# Building packages
2+
3+
If you are not a Glotzer Lab member, or you would like to build these packages on a new
4+
resource:
5+
6+
> Note: Replace `{{ package-manager }}` with the name of your preferred conda compatible
7+
> package manager executable.
8+
9+
1. Install `conda-build` and `boa` into your environment:
10+
11+
{{ package-manager }} install conda-build boa
12+
13+
2. Obtain the **glotzerlab-software** source code:
14+
15+
git clone https://github.com/glotzerlab/software
16+
17+
3. Change to the `conda` directory:
18+
19+
cd software/conda
20+
21+
4. Load any modules needed to provide compilers, *MPI*, and *CUDA*
22+
(optional). For example:
23+
24+
module load gcc openmpi cuda
25+
26+
5. Build the packages:
27+
28+
./build.sh hoomd mpi4py \
29+
--skip-existing \
30+
--variants "{'cluster': ['{{ cluster-name }}'], 'device': ['gpu'], 'gpu_platform': ['CUDA']}" \
31+
--output-folder {{ channel-path }}
32+
33+
> Note: The `output-folder` is the directory where `conda build` will write the
34+
> packages. Set the channel path `file:/{{ channel-path }}` in `.condarc` to match (see
35+
> [install](install.md)).

‎doc/src/conda.md

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
# Conda packages
2+
3+
**glotzerlab-software** provides [conda] formatted packages built with cluster-specific
4+
*MPI* and *CUDA* libraries. Use it to add *MPI-* and *GPU-enabled* builds of the
5+
following software packages to your conda compatible environments on HPC resources:
6+
7+
- hoomd
8+
- mpi4py
9+
10+
[conda]: https://docs.conda.io
11+
12+
> Important: These packages are built for ABI compatibility with packages on the
13+
> **conda-forge** channel. Ensure that you have **no** packages installed
14+
> from the **default** channel before proceeding.
15+
16+
[miniforge] provides a conda compatible environment pre-configured to install packages
17+
only from **conda-forge**. When you install [miniforge] with default options, replace:
18+
19+
- `{{ package-manager }}` with `mamba`
20+
- `{{ environment-path }}` with `$HOME/miniforge3`
21+
22+
[miniforge]: https://github.com/conda-forge/miniforge
23+
24+
If you are using a different conda compatible package manager, use the appropriate
25+
`{{ package-manager }}` and `{{ environment-path }}`.
26+
27+
<div class="warning">Do not install any <i>MPI</i> or <i>GPU</i> enabled packages
28+
from the <b>conda-forge</b> channel. The generic <i>MPI</i> and <i>CUDA</i> libraries
29+
provided by <b>conda-forge</b> will take precedence and prevent the cluster-specific
30+
libraries from operating correctly.</d>

‎doc/src/glotzer.md

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
# Glotzer lab members
2+
3+
Members of the **Glotzer lab** can install *precompiled* packages. Follow the
4+
instructions in [on the installation page](install.md) to install the latest stable
5+
release using the following channel paths and module versions:
6+
7+
| HPC resource | Channel location | Module versions |
8+
|--------------------|-----------------------|-----------------------|
9+
| UMich Great Lakes | `file://nfs/turbo/glotzer/software/conda` | `module load gcc/10.3.0 openmpi/4.1.6 cuda/12.3.0` |
10+
| Purdue ANVIL | `file://anvil/projects/x-dmr140129/software/conda` | `module load gcc/11.2.0 openmpi/4.1.6` |
11+
| NCSA Delta | `file://projects/bbgw/software/conda` | `module load openmpi/4.1.6 cuda/12.3.0` |
12+
| OLCF Frontier | `file://ccs/proj/mat110/software/frontier/conda` | `module load PrgEnv-gnu rocm/5.4.3; module unload darshan-runtime` |
13+
| OLCF Andes | `file://ccs/proj/mat110/software/andes/conda` | `module load gcc/10.3.0 openmpi/4.1.2` |
14+
15+
## Frontier
16+
17+
Individual users should install conda compatible environments in their **home
18+
directory** on Frontier. Importing Python packages from this environment will be *very*
19+
slow with large node count jobs. To improve performance, generate a **tar** file from
20+
the environment and store it on Orion.
21+
22+
```shell
23+
$ tar --directory {{ environment-path }} -cf ${MEMBERWORK}/mat110/conda-env.tar .
24+
```
25+
26+
> Important: Repeat this step after you install or update packages with
27+
> `{{ package-manager }}`.
28+
29+
30+
> Note: Collaborative projects may maintain a single copy of the software in the
31+
> shared project directory:
32+
> `/ccs/proj/mat110/software/frontier/{{ subproject-name }}`.
33+
>
34+
> Collaborative projects may also utilize a single cached `conda-env.tar`:
35+
>
36+
> $ tar --directory /ccs/proj/mat110/software/frontier/{{ subproject-name }} \
37+
> -cf ${PROJWORK}/mat110/software/{{ subproject-name} }/conda-env.tar .
38+
39+
Use the following lines in your job scripts (or interactively with `salloc`) to load the
40+
environment into NVME and execute software from there:
41+
42+
#SBATCH -C nvme
43+
44+
module load PrgEnv-gnu rocm/5.4.3
45+
module unload darshan-runtime
46+
47+
export CONDA_ENV_ROOT=/mnt/bb/${USER}/conda-env
48+
srun --ntasks-per-node 1 mkdir ${CONDA_ENV_ROOT}
49+
srun --ntasks-per-node 1 tar --directory ${CONDA_ENV_ROOT} -xpf \
50+
${MEMBERWORK}/mat110/conda-env.tar
51+
# ${PROJWORK}/mat110/software/{{ subproject-name }}/conda-env.tar # For use with shared projects.
52+
53+
export PATH=${CONDA_ENV_ROOT}/bin:$PATH
54+
55+
srun {srun options} command arguments
56+
57+
> Note: The above script has been tested on environments with all packages installed
58+
> into *base*. You may need to set additional environment variables or source activation
59+
> scripts to activate conda environments within this directory.

‎doc/src/images/umich-block-M.svg

Lines changed: 79 additions & 0 deletions
Loading

‎doc/src/index.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
{{#include ../../README.md}}

‎doc/src/install.md

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# Installing packages
2+
3+
1. **Configure condarc** to use the local HPC resource channel and
4+
**conda-forge**.
5+
6+
Replace `{{ environment-path }}/.condarc` with:
7+
8+
```yaml
9+
channel_priority: strict
10+
channels:
11+
- file:/{{ channel-path }}
12+
- conda-forge
13+
disallow:
14+
- openmpi
15+
- mpich
16+
- cuda-cudart-dev
17+
```
18+
and keep any custom configuration options you would like.
19+
20+
> Note: The `disallow` section prevents you from accidentally installing *MPI* and
21+
> *GPU* packages from conda-forge.
22+
23+
2. **Install the packages**:
24+
25+
{{ package-manager }} install hoomd mpi4py
26+
27+
3. **Load the module versions** that match those used to build the
28+
package. For example:
29+
30+
module load openmpi/X.Y.Z cuda/I.J.K
31+
32+
4. **Execute Python scripts**. Use your HPC resource scheduler to
33+
request compute nodes and use the resources\'s MPI launcher. For
34+
example:
35+
36+
srun -n 8 python3 script.py
37+
38+
> Tip: After initial installation and setup is complete, you can update packages to
39+
> their latest versions with `{{package-manager}} update --all`.

0 commit comments

Comments
 (0)