Skip to content

Commit 987a04b

Browse files
author
Malmahrouqi3
committed
docs updated
1 parent bea47ca commit 987a04b

File tree

3 files changed

+187
-1
lines changed

3 files changed

+187
-1
lines changed

‎README.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -84,8 +84,11 @@ And here is a high amplitude acoustic wave reflecting and emerging through a cir
8484

8585

8686
## Getting started
87+
for a quick start, open a GitHub Codespace to load a pre-configured docker container to get familiar with MFC. Click <kbd> <> Code</kbd> (green button at top right) → <kbd>Codespaces</kbd> (right tab) → <kbd>+</kbd> (create a codespace).
8788

88-
You can navigate [to this webpage](https://mflowcode.github.io/documentation/md_getting-started.html) to get started using MFC!
89+
****Notes:**** Codespaces is a free service with a monthly quota of compute time and storage usage. It is commended for testing commands, troubleshooting, and running simple case files without the need to install dependencies and build MFC on your device. Remember to save any important files locally before closing your codespace. To learn more, read through [docker](https://mflowcode.github.io/documentation/docker.html).
90+
91+
Otherwise, you can navigate [to this webpage](https://mflowcode.github.io/documentation/md_getting-started.html) to get started using MFC!
8992
It's rather straightforward.
9093
We'll give a brief intro. here for MacOS.
9194
Using [brew](https://brew.sh), install MFC's dependencies:

‎docs/documentation/docker.md‎

Lines changed: 173 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,173 @@
1+
# Docker
2+
3+
## Navigating Docker Desktop/CLI
4+
5+
- Install Docker on [Mac](https://docs.docker.com/desktop/setup/install/mac-install/), [Windows](https://docs.docker.com/desktop/setup/install/windows-install/), or [Linux](https://docs.docker.com/desktop/setup/install/linux/).
6+
7+
Via Docker Desktop GUI,
8+
- Search for [sbryngelson/mfc](https://hub.docker.com/r/sbryngelson/mfc) repository where all MFC images are stored then pull a release tag (e.g. `lastest-cpu`).
9+
10+
Read through **Tag Details** below to distinguish between them. Docker Desktop's left sidebar has two key tabs: **Images** stores your program copies, while **Containers** shows instances of those images. You can launch multiple containers from a single image.
11+
12+
- Start a container by clicking the Run button in the Images tab.
13+
14+
Use the *Exec* section to interact with MFC directly via terminal, the *Files* section to transfer files between your device and container, and the *Stats* section displays resource usage of it.
15+
16+
Or via Docker CLI,
17+
18+
- Pull from [sbryngelson/mfc](https://hub.docker.com/r/sbryngelson/mfc) repository and run the latest MFC container.
19+
20+
```bash
21+
docker run -it --rm --entrypoint bash sbryngelson/mfc:latest-cpu
22+
```
23+
24+
## Running Containers
25+
26+
Start a CPU container
27+
```bash
28+
docker run -it --rm --entrypoint bash sbryngelson/mfc:latest-cpu
29+
```
30+
Start a GPU container
31+
```bash
32+
docker run -it --rm --entrypoint bash --gpus all sbryngelson/mfc:latest-gpu
33+
```
34+
**Note:** `--gpus all` exposes the container to available GPUs, and only Nvidia GPUs are currently supported. Make sure your device CUDA version is at least 12.3 to avoid backward compatibility issues.
35+
36+
*⚠️ Append the `--debug` option to the `./mfc.sh` command inside the container with **Apple Silicon** (ARM-based Architecture) to bypass any potential errors or run `./mfc.sh clean && ./mfc.sh build` if needed.*
37+
<br>
38+
<br>
39+
40+
**Mounting Directory:**
41+
42+
Mount a directory to `mnt` inside the container to easily transfer files between the host and the container, e.g. `cp -r <source> /mnt/`.
43+
```bash
44+
docker run -it --rm --entrypoint bash -v "$PWD":/mnt sbryngelson/mfc:latest-cpu
45+
```
46+
<br>
47+
48+
**Shared Memory:**
49+
50+
Increase the shared memory size to prevent MPI memory binding errors which may fail some tests and cases. Otherwie, you can disable MPI inside the container `--no-mpi`.
51+
```bash
52+
docker run -it --rm --entrypoint bash --shm-size=<e.g. 4gb> sbryngelson/mfc:latest-cpu
53+
```
54+
55+
56+
57+
58+
### **For Portability,**
59+
60+
On the source machine,
61+
- Pull and save the image
62+
```bash
63+
docker pull sbryngelson/mfc:latest-cpu
64+
docker save -o mfc:latest-cpu.tar sbryngelson/mfc:latest-cpu
65+
```
66+
On the target machine,
67+
- Load and run the image
68+
```bash
69+
docker load -i mfc:latest-cpu.tar
70+
docker run -it --rm mfc:latest-cpu
71+
```
72+
73+
<br>
74+
75+
## HPC Cluster Usage (Apptainer/Singularity)
76+
77+
### **Interactive Shell**
78+
```bash
79+
apptainer exec --fakeroot --writable-tmpfs --bind "$PWD":/mnt docker://sbryngelson/mfc:latest-gpu bash -c "cd /opt/MFC && bash"
80+
```
81+
or
82+
```bash
83+
apptainer shell --fakeroot --writable-tmpfs --bind "$PWD":/mnt docker://sbryngelson/mfc:latest-gpu
84+
Apptainer>cd /opt/MFC
85+
```
86+
87+
### **For Portability,**
88+
On the source machine,
89+
- Pull and translate the image into `.sif` format
90+
```bash
91+
apptainer build mfc:latest-gpu.sif docker://sbryngelson/mfc:latest-gpu
92+
```
93+
On the target machine,
94+
- Load and start an interactive shell
95+
```bash
96+
apptainer shell --fakeroot --writable-tmpfs --bind "$PWD":/mnt mfc:latest-gpu.sif
97+
```
98+
99+
100+
101+
### Slurm Job
102+
```bash
103+
#!/bin/bash
104+
#SBATCH --job-name=mfc-sim
105+
#SBATCH --nodes=2
106+
#SBATCH --ntasks-per-node=12
107+
#SBATCH --time=06:00:00
108+
#SBATCH --partition=
109+
#SBATCH --output=mfc-sim-%j.out
110+
#SBATCH --error=mfc-sim-%j.err
111+
112+
# Load required modules
113+
module load apptainer
114+
115+
cd $SLURM_SUBMIT_DIR
116+
117+
# Define container image
118+
CONTAINER="mfc:latest-gpu.sif"
119+
120+
apptainer exec --fakeroot --writable-tmpfs \
121+
--bind "$PWD":/mnt \
122+
$CONTAINER \
123+
bash -c "cd /opt/MFC && ./mfc.sh run sim/case.py -c <computer>"
124+
```
125+
Where
126+
127+
`/sim` directory contains all simulation files including case setup (`case.py`).
128+
129+
`--fakeroot --writable-tmpfs` are critical to:
130+
- Enable root-like permissions inside the container without actual root access
131+
- Allow temporary write access to the container filesystem
132+
133+
134+
135+
## Tag Details
136+
### Base Images
137+
- CPU images (v4.3.0-latest releases) are built on **Ubuntu 22.04**.
138+
- GPU images (v4.3.0-latest releases) are built on **NVHPC SDK 23.11 (CUDA 12.3) & Ubuntu 22.04**.
139+
140+
### Tag Structure
141+
- **`vx.x.x`** - Official MFC release versions (recommended: use `latest` release)
142+
- **`cpu/gpu`** - Build configurations for CPU or GPU acceleration.
143+
- **`ubuntu-xx.xx`** - Base Ubuntu version (standard = `amd64`, `-arm` = `arm64`)
144+
145+
### Available Tags
146+
```
147+
mfc:latest-xxx # Latest version (amd64 & arm64)
148+
mfc:vx.x.x-cpu # CPU version (amd64 & arm64)
149+
mfc:vx.x.x-gpu # GPU version (amd64 & arm64)
150+
mfc:vx.x.x-xxx-ubuntu-xx.xx # amd64 natively-supported version
151+
mfc:vx.x.x-xxx-ubuntu-xx.xx-arm # arm64 natively-supported version
152+
```
153+
### **Architecture Support**
154+
You can specify the desired architecture with `--platform <os>/<arch>` - either `linux/amd64` or `linux/arm64`. If not sure, Docker automatically selects the available image compatible with your system architecture. If native support isn't available, QEMU emulation is enabled for the following architectures albeit with degraded performance.
155+
```
156+
linux/amd64
157+
linux/amd64/v2
158+
linux/amd64/v3
159+
linux/arm64
160+
linux/riscv64
161+
linux/ppc64le
162+
linux/s390x
163+
linux/386
164+
linux/mips64le
165+
linux/mips64
166+
linux/loong64
167+
linux/arm/v7
168+
linux/arm/v6
169+
```
170+
171+
172+
<br>
173+
<br>

‎docs/documentation/getting-started.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -145,6 +145,16 @@ Examples:
145145
- Build MFC using a single thread without MPI, GPU, and Debug support: `./mfc.sh build --no-mpi`.
146146
- Build MFC's `simulation` code in Debug mode with MPI and GPU support: `./mfc.sh build --debug --gpu -t simulation`.
147147

148+
## Using Containers
149+
As an alternative to building MFC from scratch, use containers to quickly access pre-built MFC with all its dependencies.
150+
151+
Run the latest MFC container.
152+
```bash
153+
docker run -it --rm --entrypoint bash sbryngelson/mfc:latest-cpu
154+
```
155+
Please refer to the [Docker](https://mflowcode.github.io/documentation/docker.html) document for more information.
156+
157+
148158
## Running the Test Suite
149159

150160
Run MFC's test suite with 8 threads:

0 commit comments

Comments
 (0)