Skip to content

Commit 2e8db2b

Browse files
xylarxylar
committed
Flesh out documentation
Some pages are still skeletons or empty placeholders for now.
1 parent 15a408e commit 2e8db2b

File tree

10 files changed

+400
-5
lines changed

10 files changed

+400
-5
lines changed

‎docs/contributing.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
# Contributing & Community
2+
3+
We welcome contributions and feedback from all users and developers of
4+
E3SM-Unified. Whether you're updating packages, improving documentation, or
5+
reporting issues, your input helps strengthen the environment and its
6+
community.
7+
8+
---
9+
10+
## Ways to Contribute
11+
12+
### ✏️ Documentation
13+
14+
* Suggest improvements to the user guide or technical docs.
15+
* Fix typos or clarify instructions.
16+
* Add usage examples for tools you use regularly.
17+
18+
### 🚀 Suggest or Update Packages
19+
20+
* Request new tools or features by opening a GitHub Issue.
21+
* Propose version updates by:
22+
* Editing the E3SM Confluence pages defining the next E3SM-Unified version
23+
(if you have access)
24+
* Or editing the `meta.yaml` (for conda package) or `defaults.cfg` (for spack
25+
pacakges) and making a pull request (if you don't have access to E3SM's
26+
Confluence pages).
27+
28+
### ⚙️ Development & Testing
29+
30+
* Help test release candidates on supported platforms.
31+
* Report issues you encounter.
32+
* Contribute improvements to tools in the E3SM ecosystem (e.g., `mache`,
33+
`mpas-analysis`, `zppy`, `e3sm_diags`).
34+
35+
---
36+
37+
## Getting Started
38+
39+
1. Fork the [e3sm-unified GitHub repository](https://github.com/E3SM-Project/e3sm-unified).
40+
2. Create a new branch for your changes.
41+
3. Submit a pull request (PR).
42+
4. Tag reviewers as needed (e.g., `@xylar`).
43+
44+
We recommend following our naming conventions for release branches (e.g.,
45+
`update-to-1.12.0`).
46+
47+
---
48+
49+
## Communication
50+
51+
* GitHub Issues: [E3SM-Unified GitHub](https://github.com/E3SM-Project/e3sm-unified/issues)
52+
* Slack: `#e3sm-help-postproc`
53+
* Email: [[email protected]](mailto:[email protected])
54+
55+
Have questions about where to start? Just ask on Slack or open an issue!

‎docs/deployment.md‎

Whitespace-only changes.

‎docs/index.md‎

Lines changed: 44 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,50 @@
1+
# Welcome to E3SM-Unified Documentation
2+
13
```{image} logo/e3sm_unified_logo_200.png
24
:align: center
35
:width: 200 px
46
```
57

6-
# E3SM-Unfied
8+
E3SM-Unified is a unified conda + Spack environment developed to support pre-
9+
and post-processing workflows for the Energy Exascale Earth System Model
10+
(E3SM). It bundles commonly used analysis, visualization, and workflow tools
11+
into a single portable environment.
12+
13+
This documentation is for both **users** of the E3SM-Unified environment and
14+
**developers** who build, test, and deploy it on supported platforms.
15+
16+
---
17+
18+
## 🚀 Start Here
19+
20+
* 📖 [Introduction](introduction.md): What E3SM-Unified is and why you should
21+
use it
22+
* 🧪 [Quickstart Guide](quickstart.md): Load the environment and start using
23+
tools
24+
25+
---
26+
27+
## 📚 Contents
28+
29+
* 💠 [Using E3SM-Unified Tools](using-tools.md)
30+
* 🧪 [Testing Release Candidates](testing-release-candidates.md)
31+
* 🦠 [Release Engineering](release-engineering.md)
32+
* 🚚 [Deployment on HPCs](deployment.md)
33+
* 📦 [Package Catalog](packages.md)
34+
* ❓ [Troubleshooting & FAQs](troubleshooting.md)
35+
* 🤝 [Contributing & Community](contributing.md)
36+
37+
---
38+
39+
## 💬 Get Help
40+
41+
```{admonition} Support
42+
- Slack: #e3sm-help-postproc
43+
- GitHub Issues: [E3SM-Unified on GitHub](https://github.com/E3SM-Project/e3sm-unified/issues)
44+
- Maintainer contact: [email protected]
45+
```
46+
47+
---
748

8-
A metapackage for a unified
9-
[conda environment](https://conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html)
10-
for analysis and other pre- and post-processing for the Energy Exascale Earth
11-
System Model (E3SM).
49+
This documentation is maintained by the E3SM Infrastructure Team and
50+
contributors across the community.

‎docs/introduction.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
# Introduction to E3SM-Unified
2+
3+
```{image} logo/e3sm_unified_logo_200.png
4+
:align: center
5+
:width: 200 px
6+
```
7+
8+
## What is E3SM-Unified?
9+
10+
E3SM-Unified is a unified conda-based environment that provides pre- and
11+
post-processing tools for the Energy Exascale Earth System Model (E3SM). It is
12+
designed to streamline the analysis, visualization, and transformation of model
13+
output for scientists and developers.
14+
15+
This environment bundles together a curated set of Python and compiled tools
16+
that work well across supported platforms, particularly on E3SM-managed
17+
high-performance computing (HPC) systems.
18+
19+
## Key Features
20+
21+
* Combines dozens of packages into one environment, eliminating setup friction.
22+
* Maintains consistency across HPC platforms (Anvil, Chrysalis, Compy, etc.).
23+
* Offers both Conda and Spack-installed components for MPI performance.
24+
* Fully open source and community-maintained via GitHub.
25+
26+
## Common Use Cases
27+
28+
* Diagnostics and evaluation (e.g., `e3sm_diags`, `MPAS-Analysis`)
29+
* CMIP output conversion (`e3sm_to_cmip`)
30+
* Time series generation, viewer creation, and archiving (`zppy`, `zstash`)
31+
* Domain generation and mesh visualization (`cime_gen_domain`, `mosaic`)
32+
33+
## Supported Platforms
34+
35+
E3SM-Unified is available on many E3SM-supported systems:
36+
37+
* Andes
38+
* Anvil
39+
* Chrysalis
40+
* Compy
41+
* Dane
42+
* Frontier
43+
* Perlmutter
44+
* Polaris (ALCF)
45+
* Ruby
46+
47+
It can also be installed on Linux or macOS laptops for limited use (see
48+
[Quickstart Guide](quickstart.md)). Windows is not supported.
49+
50+
## Getting Help
51+
52+
* [Quickstart Guide](quickstart.md)
53+
* GitHub: [E3SM-Unified repository](https://github.com/E3SM-Project/e3sm-unified)
54+
* Slack: `#e3sm-help-postproc`
55+
* Issues/questions: GitHub Issues or contact [[email protected]](mailto:[email protected])

‎docs/packages.md‎

Whitespace-only changes.

‎docs/quickstart.md‎

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
# Quickstart Guide
2+
3+
```{note}
4+
E3SM-Unified is supported only on Linux, OSX and HPC platforms. It is **not**
5+
supported on Windows.
6+
```
7+
8+
## Accessing E3SM-Unified on Supported Machines
9+
10+
On most E3SM-supported HPC systems, E3SM-Unified is already installed and
11+
ready to use via an activation script.
12+
13+
### Example Activation Commands
14+
15+
```bash
16+
# Andes
17+
source /ccs/proj/cli115/software/e3sm-unified/load_latest_e3sm_unified_andes.sh
18+
19+
# Anvil
20+
source /lcrc/soft/climate/e3sm-unified/load_latest_e3sm_unified_anvil.sh
21+
22+
# Chrysalis
23+
source /lcrc/soft/climate/e3sm-unified/load_latest_e3sm_unified_chrysalis.sh
24+
25+
# Compy
26+
source /share/apps/E3SM/conda_envs/load_latest_e3sm_unified_compy.sh
27+
28+
# Dane
29+
source /usr/workspace/e3sm/apps/e3sm-unified/load_latest_e3sm_unified_dane.sh
30+
31+
# Frontier
32+
source /ccs/proj/cli115/software/e3sm-unified/load_latest_e3sm_unified_frontier.sh
33+
34+
# Perlmutter
35+
source /global/common/software/e3sm/anaconda_envs/load_latest_e3sm_unified_pm-cpu.sh
36+
37+
# Polaris (ALCF)
38+
source /lus/grand/projects/E3SMinput/soft/e3sm-unified/load_latest_e3sm_unified_polaris.sh
39+
40+
# Ruby
41+
source /usr/workspace/e3sm/apps/e3sm-unified/load_latest_e3sm_unified_ruby.sh
42+
```
43+
44+
Once the script is sourced, you'll have access to all the tools provided by
45+
E3SM-Unified in your environment.
46+
47+
## Verifying Installation
48+
49+
After activation, you can verify that the environment is correctly loaded by
50+
testing if major packages are importable:
51+
52+
```python
53+
python -c "import xarray, e3sm_diags, mpas_analysis, zppy"
54+
```
55+
56+
## Running on Compute Nodes (Optional but Recommended)
57+
58+
Many E3SM-Unified tools (e.g., MOAB, MPAS-Analysis, NCO, TempestRemap) benefit
59+
from running on compute nodes using MPI-enabled system builds.
60+
61+
Check your system documentation for how to launch interactive compute sessions
62+
(e.g., `srun`, `salloc`, or `qsub`).
63+
64+
## Installing E3SM-Unified on an Unsupported System
65+
66+
E3SM-Unified is not officially supported on Linux or Mac laptops or
67+
workstations, but users can install it using `miniforge3`.
68+
69+
### Step-by-Step (Linux/macOS):
70+
71+
```bash
72+
# Install miniforge3
73+
wget "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh"
74+
bash "Miniforge3-$(uname)-$(uname -m).sh"
75+
76+
# Create a new environment
77+
conda create -n esm-unified -c conda-forge e3sm-unified
78+
79+
# Activate it
80+
conda activate e3sm-unified
81+
```
82+
83+
Note: On macOS with M1/M2 chips, install the x86\_64 version and use Rosetta 2
84+
for compatibility.
85+
86+
---
87+
88+
## Related Pages
89+
90+
* [Introduction to E3SM-Unified](introduction.md)
91+
* [Using E3SM-Unified Tools](using-tools.md)
92+
* [Troubleshooting](troubleshooting.md)
93+
94+
```{admonition} Need Help?
95+
- Slack: #e3sm-help-postproc
96+
- GitHub Issues: https://github.com/E3SM-Project/e3sm-unified/issues
97+
- Email: [email protected]
98+
```

‎docs/release-engineering.md‎

Whitespace-only changes.

‎docs/testing-release-candidates.md‎

Whitespace-only changes.

‎docs/troubleshooting.md‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
# Troubleshooting & FAQs
2+
3+
This page collects common problems users encounter when working with
4+
E3SM-Unified and how to resolve them. If you encounter an issue not listed
5+
here, please reach out via Slack or GitHub.
6+
7+
---
8+
9+
## Common Issues
10+
11+
### "Permission Denied" When Installing E3SM-Unified
12+
13+
**Symptom:**
14+
15+
```
16+
OSError(13, 'Permission denied')
17+
```
18+
19+
**Cause:** You're likely trying to install E3SM-Unified into a system-wide
20+
Python or Conda environment you don't have write access to.
21+
22+
**Solution:**
23+
Install Miniforge3 in your home directory and create an environment locally,
24+
see [Quickstart Guide](quickstart.md).
25+
26+
---
27+
28+
### "Module Not Found" When Importing Packages
29+
30+
**Symptom:**
31+
32+
```python
33+
ModuleNotFoundError: No module named 'e3sm_diags'
34+
```
35+
36+
**Cause:** E3SM-Unified may not be activated correctly, or you're in a
37+
different shell/session.
38+
39+
**Solution:**
40+
Re-source the appropriate `load_latest_e3sm_unified_<machine>.sh` script and
41+
retry.
42+
43+
---
44+
45+
### MPI-based Tools Fail on Login Nodes
46+
47+
**Symptom:** Tools like `mpas_analysis` or `nco` crash with MPI errors.
48+
49+
**Cause:** These tools are compiled with system MPI (or launch other tools
50+
that use system MPI) and require execution on compute nodes.
51+
52+
**Solution:** Launch a batch job or an interactive compute session with
53+
`srun`, `salloc` or `qsub`, depending on your machine.
54+
55+
---
56+
57+
## Tips & Best Practices
58+
59+
* Always check you're in the correct conda environment.
60+
* On HPC systems, prefer running MPI-enabled tools on compute nodes.
61+
* If installing locally, make sure have create a clean environment with the
62+
latest version of E3SM-Unified.
63+
* Refer to the [Quickstart Guide](quickstart.md) for environment setup
64+
instructions.
65+
66+
---
67+
68+
## Still Need Help?
69+
70+
```{admonition} Support
71+
- Slack: #e3sm-help-postproc
72+
- GitHub Issues: [E3SM-Unified on GitHub](https://github.com/E3SM-Project/e3sm-unified/issues)
73+
- Email: [email protected]
74+
```

0 commit comments

Comments
 (0)