You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
- 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/).
- Search for [sbryngelson/mfc](https://hub.docker.com/r/sbryngelson/mfc) repository where all the MFC images are stored then pull a release tag (e.g., `latest-cpu`).
10
+
### Docker Desktop GUI
9
11
10
-
Read through the **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.
12
+
- Search for the [sbryngelson/mfc](https://hub.docker.com/r/sbryngelson/mfc) repository. All the MFC containers are stored here.
11
13
12
-
-Start a container by clicking the Run button in the Images tab.
14
+
-Find and pull a release tag (e.g., `latest-cpu`).
13
15
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 to display resource usage.
16
+
* Read through the **Tag Details** below to distinguish between them. Docker Desktop's left sidebar has two key tabs: **Images** stores your program copies, and **Containers** shows instances of those images. You can launch multiple containers from a single image.
15
17
16
-
Or via Docker CLI,
18
+
- Start a container by navigating to the `Images` tab and clicking the `Run` button.
17
19
18
-
- Pull from [sbryngelson/mfc](https://hub.docker.com/r/sbryngelson/mfc) repository and run the latest MFC container.
20
+
* 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 to display resource usage.
19
21
22
+
### Docker CLI
23
+
24
+
You can navigate Docker entirely from the command line.
25
+
From a bash-like shell, pull from the [sbryngelson/mfc](https://hub.docker.com/r/sbryngelson/mfc) repository and run the latest MFC container:
20
26
```bash
21
27
docker run -it --rm --entrypoint bash sbryngelson/mfc:latest-cpu
22
28
```
23
-
<br>
24
-
25
-
**Selecting OS/ARCH:**
26
29
27
-
Docker by default selects the compatible architecture when pulling and running a container. However, you can manually specify your platform (i.e., `linux/amd64` for most devices or `linux/arm64` for Apple Silicon).
30
+
**Selecting OS/ARCH:** Docker selects the compatible architecture by default when pulling and running a container.
31
+
You can manually specify your platform if something seems to go wrong, as Docker may suggest doing so.
32
+
For example, `linux/amd64` handles many *nix-based x86 architectures, and `linux/arm64` handles Apple Silicon and Arm-based *nix devices.
33
+
You can specify it like this:
28
34
```bash
29
35
docker run -it --rm --entrypoint bash --platform linux/amd64 sbryngelson/mfc:latest-cpu
30
36
```
31
-
<br>
32
-
33
-
**What is Next:**
34
37
35
-
After starting a container, the primary working directory is `/opt/MFC`, where all necessary files are located. Read through [Example Cases](https://mflowcode.github.io/documentation/md_examples.html) to get familiar with running cases, then review [Case Files](https://mflowcode.github.io/documentation/md_case.html) to write a custom case file.
38
+
**What's Next?**
36
39
40
+
Once a container has started, the primary working directory is `/opt/MFC`, and all necessary files are located there.
41
+
You can check out the usual MFC documentation, such as the [Example Cases](https://mflowcode.github.io/documentation/md_examples.html), to get familiar with running cases.
42
+
Then, review the [Case Files](https://mflowcode.github.io/documentation/md_case.html) to write a custom case file.
37
43
38
-
<br>
44
+
## Details on Running Containers
39
45
40
-
## Running Containers
41
-
42
-
Start a CPU container.
46
+
Let's take a closer look at running MFC within a container.
47
+
Kick off a CPU container:
43
48
```bash
44
49
docker run -it --rm --entrypoint bash sbryngelson/mfc:latest-cpu
45
50
```
46
-
Start a GPU container.
51
+
Or, start a GPU container.
47
52
```bash
48
53
docker run -it --rm --gpus all --entrypoint bash sbryngelson/mfc:latest-gpu
49
54
```
50
-
**Note:**`--gpus all` exposes the container to available GPUs, and only NVIDIA GPUs are currently supported. Make sure your device's CUDA version is at least 12.3 to avoid backward compatibility issues.
51
55
52
-
<br>
53
-
<br>
56
+
**Note:**`--gpus all` exposes the container to available GPUs, and _only NVIDIA GPUs are currently supported_.
57
+
[Ensure your device's CUDA version is at least 12.3](https://stackoverflow.com/questions/9727688/how-to-get-the-cuda-version) to avoid backward compatibility issues.
54
58
55
-
**Mounting Directory:**
59
+
**Mounting Directory**
56
60
57
-
Mount a directory to `mnt` inside the container to easily transfer files between the host and the container, e.g. `cp -r <source> /mnt/destination>`.
61
+
Mount a directory to `mnt` inside the container to easily transfer files between your host computer and the separate container.
62
+
For example, `cp -r <source> /mnt/destination>` moves something from your source computer to the container (reverse the order for the reverse to happen!).
58
63
```bash
59
64
docker run -it --rm --entrypoint bash -v "$PWD":/mnt sbryngelson/mfc:latest-cpu
60
65
```
61
-
<br>
62
66
63
-
**Shared Memory:**
67
+
**Shared Memory**
64
68
65
-
When encountering MPI memory binding errors resulting in failed tests and cases, increase the shared memory size or disable MPI inside the container (`./mfc.sh --no-mpi`).
69
+
If you run a job with multiple MPI ranks, you could run into _MPI memory binding errors_.
70
+
This can manifest as a failed test (launched via `./mfc.sh test`) and running cases with `./mfc.sh run -n X <path/to/case.py>` where `X > 1`.
71
+
To avoid this issue, you can increase the shared memory size (to keep MPI working):
66
72
```bash
67
73
docker run -it --rm --entrypoint bash --shm-size=<e.g., 4gb> sbryngelson/mfc:latest-cpu
68
74
```
75
+
or avoid MPI altogether via `./mfc.sh <your commands> --no-mpi`.
69
76
70
77
78
+
### Portability
71
79
72
-
73
-
### **For Portability,**
74
-
75
-
On the source machine,
76
-
- Pull and save the image.
80
+
On the source machine, pull and save the image:
77
81
```bash
78
82
docker pull sbryngelson/mfc:latest-cpu
79
83
docker save -o mfc:latest-cpu.tar sbryngelson/mfc:latest-cpu
80
84
```
81
-
On the target machine,
82
-
- Load and run the image.
85
+
On the target machine, load and run the image:
83
86
```bash
84
87
docker load -i mfc:latest-cpu.tar
85
88
docker run -it --rm mfc:latest-cpu
86
89
```
87
90
88
-
<br>
91
+
## Using Supercomputers/Clusters via Apptainer/Singularity
`/sim` directory should all the simulation files, including the case setup (`case.py`).
142
-
143
-
`--nv --fakeroot --writable-tmpfs`, these flags are critical to:
144
-
- Grant access to the host system's NVIDIA GPUs and its CUDA libraries.
145
-
- Enable root-like permissions inside the container without actual root access.
146
-
- Allow temporary write access to the container filesystem.
147
-
148
140
141
+
In the above,
142
+
* The `/sim` directory should have all the simulation files, including the case setup (`case.py`).
143
+
* The `--nv --fakeroot --writable-tmpfs` set of flags are needed to
144
+
- Grant access to the host system's NVIDIA GPUs and its CUDA libraries.
145
+
- Enable root-like permissions inside the container without actual root access.
146
+
- Allow temporary write access to the container filesystem.
149
147
150
148
## Tag Details
149
+
151
150
### Base Images
152
151
- CPU images (v4.3.0-latest releases) are built on **Ubuntu 22.04**.
153
152
- GPU images (v4.3.0-latest releases) are built on **NVHPC SDK 23.11 (CUDA 12.3) & Ubuntu 22.04**.
@@ -157,16 +156,21 @@ Where,
157
156
-**`cpu/gpu`** - Build configurations for CPU or GPU acceleration.
158
157
-**`ubuntu-xx.xx`** - Base Ubuntu version (standard = `amd64`, `-arm` = `arm64`)
159
158
160
-
### Available Tags
161
-
```
159
+
### Example Tags
160
+
161
+
```shell
162
162
mfc:latest-xxx # Latest version (amd64 & arm64)
163
163
mfc:vx.x.x-cpu # CPU version (amd64 & arm64)
164
164
mfc:vx.x.x-gpu # GPU version (amd64 & arm64)
165
165
mfc:vx.x.x-xxx-ubuntu-xx.xx # amd64 natively-supported version
166
166
mfc:vx.x.x-xxx-ubuntu-xx.xx-arm # arm64 natively-supported version
167
167
```
168
-
### **Architecture Support**
169
-
You can specify the desired architecture with `--platform <os>/<arch>` - either `linux/amd64` or `linux/arm64`. If unsure, Docker automatically selects the compatible image with your system architecture. If native support isn't available, QEMU emulation is enabled for the following architectures albeit with degraded performance.
168
+
169
+
### Architecture Support
170
+
171
+
You can specify your architecture with `--platform <os>/<arch>`, typically either `linux/amd64` or `linux/arm64`.
172
+
If you are unsure, Docker automatically selects the compatible image with your system architecture.
173
+
If native support isn't available, QEMU emulation is enabled for the following architectures, albeit with degraded performance.
0 commit comments