<html xmlns="http://www.w3.org/1999/xhtml">

<script async src="https://www.googletagmanager.com/gtag/js?id=G-SY496B9L99"></script>

window.dataLayer = window.dataLayer || [];

function gtag(){dataLayer.push(arguments);}

gtag('js', new Date());

gtag('config', 'G-SY496B9L99');

<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>

<meta http-equiv="X-UA-Compatible" content="IE=9"/>

<meta name="generator" content="Doxygen 1.16.1"/>

<meta name="viewport" content="width=device-width, initial-scale=1"/>

<title>MFC: Containers</title>

<meta name="description" content="Containers — MFC documentation. Open-source exascale multiphase flow solver." />

<meta name="keywords" content="exascale, fluid dynamics, cfd, computational fluid dynamics, compressible, hpc, bryngelson, colonius, subgrid, multiphase, frontier, summit, el capitan, aurora, amd gpu, gpu, nvidia"/>

<link href="tabs.css" rel="stylesheet" type="text/css"/>

<script type="text/javascript" src="jquery.js"></script>

<script type="text/javascript" src="dynsections.js"></script>

<link href="navtree.css" rel="stylesheet" type="text/css"/>

<script type="text/javascript" src="navtreedata.js"></script>

<script type="text/javascript" src="navtree.js"></script>

<script type="text/javascript" src="cookie.js"></script>

<link href="search/search.css" rel="stylesheet" type="text/css"/>

<script type="text/javascript" src="search/searchdata.js"></script>

<script type="text/javascript" src="search/search.js"></script>

<script type="text/x-mathjax-config">

extensions: ["tex2jax.js", "TeX/AMSmath.js", "TeX/AMSsymbols.js"],

jax: ["input/TeX","output/HTML-CSS"],

extensions: ["tex2jax.js"],

jax: ["input/TeX", "output/HTML-CSS"],

tex2jax: {

inlineMath: [ ['$', '$'], ["\\(","\\)"] ],

displayMath: [ ['$$','$$'], ["\\[","\\]"] ],

processEscapes: true,

ignoreClass: "line" // Ignore code blocks: https://web.archive.org/web/20120430100225/http://www.mathjax.org/docs/1.1/options/tex2jax.html

},

"HTML-CSS": {

fonts: ["TeX"]

}

<script type="text/javascript" async="async" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/MathJax.js"></script>

<link href="doxygen.css" rel="stylesheet" type="text/css" />

<link rel="shortcut icon" href="icon.ico" type="image/x-icon" />

<link href="doxygen-awesome.css" rel="stylesheet" type="text/css"/>

<link href="doxygen-awesome-sidebar-only.css" rel="stylesheet" type="text/css"/>

<link href="custom.css" rel="stylesheet" type="text/css"/>

<div id="top"><!-- do not remove this div, it is closed by doxygen! -->

<div id="titlearea">

<table cellspacing="0" cellpadding="0">

<tbody>

<tr style="height: 56px;">

<td id="projectlogo"><img alt="Logo" src="icon.ico"/></td>

<td id="projectalign" style="padding-left: 0.5em;">

<div id="projectname">MFC

</div>

<div id="projectbrief">Exascale flow solver</div>

</td>

</tr>

</tbody>

document.addEventListener('DOMContentLoaded', function() {

var nav = document.createElement('div');

nav.id = 'mfc-nav';

var items = [

['../documentation/index.html', 'documentation', 'User Guide'],

['../api/index.html', 'api', 'API Documentation']

];

var path = window.location.pathname;

var apiPaths = ['/api/', '/pre_process/', '/simulation/', '/post_process/'];

for (var i = 0; i < items.length; i++) {

var a = document.createElement('a');

a.href = items[i][0];

a.textContent = items[i][2];

if (items[i][1] === 'api') {

for (var j = 0; j < apiPaths.length; j++) {

if (path.indexOf(apiPaths[j]) !== -1) { a.className = 'active'; break; }

}

} else {

if (path.indexOf('/' + items[i][1] + '/') !== -1) a.className = 'active';

}

nav.appendChild(a);

}

var sideNav = document.getElementById('side-nav');

if (sideNav) sideNav.insertBefore(nav, sideNav.firstChild);

<script type="text/javascript">

var searchBox = new SearchBox("searchBox", "search/",'.html');

<script type="text/javascript">

$(function() { codefold.init(); });

<script type="text/javascript" src="menudata.js"></script>

<script type="text/javascript" src="menu.js"></script>

<script type="text/javascript">

$(function() {

initMenu('',true,false,'search.php','Search',true);

$(function() { init_search(); });

<div id="main-nav"></div>

<div id="side-nav" class="ui-resizable side-nav-resizable">

<div id="nav-tree">

<div id="nav-tree-contents">

<div id="nav-sync" class="sync"></div>

</div>

</div>

<div id="splitbar" style="-moz-user-select:none;"

class="ui-resizable-handle">

</div>

<script type="text/javascript">

$(function(){initNavTree('docker.html','',''); });

<div id="container">

<div id="doc-content">

<div id="MSearchSelectWindow"

onmouseover="return searchBox.OnSearchSelectShow()"

onmouseout="return searchBox.OnSearchSelectHide()"

onkeydown="return searchBox.OnSearchSelectKey(event)">

<div id="MSearchResultsWindow">

<div id="MSearchResults">

<div class="SRPage">

<div id="SRIndex">

<div id="SRResults"></div>

<div class="SRStatus" id="Loading">Loading...</div>

<div class="SRStatus" id="Searching">Searching...</div>

<div class="SRStatus" id="NoMatches">No Matches</div>

<div><div class="header">

<div class="headertitle"><div class="title">Containers </div></div>

<div class="contents">

<div class="textblock"><h1 class="doxsection"><a class="anchor" id="autotoc_md129"></a>

Containers</h1>

<h2 class="doxsection"><a class="anchor" id="autotoc_md130"></a>

Navigating Docker</h2>

<p>Install Docker on</p><ul>

<li><a href="https://docs.docker.com/desktop/setup/install/mac-install/">MacOS</a></li>

<li><a href="https://docs.docker.com/desktop/setup/install/windows-install/">Windows</a></li>

<li><a href="https://docs.docker.com/desktop/setup/install/linux/">Linux</a></li>

<h3 class="doxsection"><a class="anchor" id="autotoc_md131"></a>

Docker Desktop GUI</h3>

<li>Search for the <a href="https://hub.docker.com/r/sbryngelson/mfc">sbryngelson/mfc</a> repository. All the MFC containers are stored here.</li>

<li>Find and pull a release tag (e.g., <span class="tt">latest-cpu</span>).<ul>

<li>Read through the <b>Tag Details</b> below to distinguish between them. Docker Desktop's left sidebar has two key tabs: <b>Images</b> stores your program copies, and <b>Containers</b> shows instances of those images. You can launch multiple containers from a single image.</li>

<li>Start a container by navigating to the <span class="tt">Images</span> tab and clicking the <span class="tt">Run</span> button.<ul>

<li>Use the <em>Exec</em> section to interact with MFC directly via terminal, the <em>Files</em> section to transfer files between your device and container, and the <em>Stats</em> section to display resource usage.</li>

<h3 class="doxsection"><a class="anchor" id="autotoc_md132"></a>

Docker CLI</h3>

<p>You can navigate Docker entirely from the command line. From a bash-like shell, pull from the <a href="https://hub.docker.com/r/sbryngelson/mfc">sbryngelson/mfc</a> repository and run the latest MFC container: </p><div class="fragment"><div class="line">docker run -it --rm --entrypoint bash sbryngelson/mfc:latest-cpu</div>

</div><!-- fragment --><p><b>Selecting OS/ARCH:</b> Docker selects the compatible architecture by default when pulling and running a container. You can manually specify your platform if something seems to go wrong, as Docker may suggest doing so. For example, <span class="tt">linux/amd64</span> handles many *nix-based x86 architectures, and <span class="tt">linux/arm64</span> handles Apple Silicon and Arm-based *nix devices. You can specify it like this: </p><div class="fragment"><div class="line">docker run -it --rm --entrypoint bash --platform linux/amd64 sbryngelson/mfc:latest-cpu</div>

</div><!-- fragment --><p><b>What's Next?</b></p>

<p>Once a container has started, the primary working directory is <span class="tt">/opt/MFC</span>, and all necessary files are located there. You can check out the usual MFC documentation, such as the <a class="el" href="examples.html" title="Example Cases">Example Cases</a>, to get familiar with running cases. Then, review the <a class="el" href="case.html" title="Case Files">Case Files</a> to write a custom case file.</p>

<h2 class="doxsection"><a class="anchor" id="autotoc_md133"></a>

Details on Running Containers</h2>

<p>Let's take a closer look at running MFC within a container. Kick off a CPU container: </p><div class="fragment"><div class="line">docker run -it --rm --entrypoint bash sbryngelson/mfc:latest-cpu</div>

</div><!-- fragment --><p> Or, start a GPU container. </p><div class="fragment"><div class="line">docker run -it --rm --gpus all --entrypoint bash sbryngelson/mfc:latest-gpu</div>

</div><!-- fragment --><p><b>Note:</b> <span class="tt">--gpus all</span> exposes the container to available GPUs, and <em>only NVIDIA GPUs are currently supported</em>. <a href="https://stackoverflow.com/questions/9727688/how-to-get-the-cuda-version">Ensure your device's CUDA version is at least 12.3</a> to avoid backward compatibility issues.</p>

<p><b>Mounting Directory</b></p>

<p>Mount a directory to <span class="tt">mnt</span> inside the container to easily transfer files between your host computer and the separate container. For example, <span class="tt">cp -r &lt;source&gt; /mnt/destination&gt;</span> moves something from your source computer to the container (reverse the order for the reverse to happen!). </p><div class="fragment"><div class="line">docker run -it --rm --entrypoint bash -v &quot;$PWD&quot;:/mnt sbryngelson/mfc:latest-cpu</div>

</div><!-- fragment --><p><b>Shared Memory</b></p>

<p>If you run a job with multiple MPI ranks, you could run into <em>MPI memory binding errors</em>. This can manifest as a failed test (launched via <span class="tt">./mfc.sh test</span>) and running cases with <span class="tt">./mfc.sh run -n X &lt;path/to/case.py&gt;</span> where <span class="tt">X &gt; 1</span>. To avoid this issue, you can increase the shared memory size (to keep MPI working): </p><div class="fragment"><div class="line">docker run -it --rm --entrypoint bash --shm-size=&lt;e.g., 4gb&gt; sbryngelson/mfc:latest-cpu</div>

</div><!-- fragment --><p> or avoid MPI altogether via <span class="tt">./mfc.sh &lt;your commands&gt; --no-mpi</span>.</p>

<h3 class="doxsection"><a class="anchor" id="autotoc_md134"></a>

Portability</h3>

<p>On the source machine, pull and save the image: </p><div class="fragment"><div class="line">docker pull sbryngelson/mfc:latest-cpu</div>

<div class="line">docker save -o mfc:latest-cpu.tar sbryngelson/mfc:latest-cpu</div>

</div><!-- fragment --><p> On the target machine, load and run the image: </p><div class="fragment"><div class="line">docker load -i mfc:latest-cpu.tar</div>

<div class="line">docker run -it --rm mfc:latest-cpu</div>

</div><!-- fragment --><h2 class="doxsection"><a class="anchor" id="autotoc_md135"></a>

Using Supercomputers/Clusters via Apptainer/Singularity</h2>

<h3 class="doxsection"><a class="anchor" id="autotoc_md136"></a>

Interactive Shell</h3>

<div class="fragment"><div class="line">apptainer shell --nv --fakeroot --writable-tmpfs --bind &quot;$PWD&quot;:/mnt docker://sbryngelson/mfc:latest-gpu</div>

<div class="line">Apptainer&gt;cd /opt/MFC</div>

</div><!-- fragment --><p> or </p><div class="fragment"><div class="line">apptainer exec --nv --fakeroot --writable-tmpfs --bind &quot;$PWD&quot;:/mnt docker://sbryngelson/mfc:latest-gpu bash -c &quot;cd /opt/MFC &amp;&amp; bash&quot;</div>

</div><!-- fragment --><p> To run MFC on CPUs, omit <span class="tt">--nv</span> and use the <span class="tt">mfc:latest-cpu</span> container image.</p>

<h3 class="doxsection"><a class="anchor" id="autotoc_md137"></a>

For Portability</h3>

<p>On the source machine, pull and translate the image into <span class="tt">.sif</span> format: </p><div class="fragment"><div class="line">apptainer build mfc:latest-gpu.sif docker://sbryngelson/mfc:latest-gpu</div>

</div><!-- fragment --><p> On the target machine, load and start an interactive shell: </p><div class="fragment"><div class="line">apptainer shell --nv --fakeroot --writable-tmpfs --bind &quot;$PWD&quot;:/mnt mfc:latest-gpu.sif</div>

</div><!-- fragment --><h3 class="doxsection"><a class="anchor" id="autotoc_md138"></a>

Slurm Job</h3>

<p>Below is an example Slurm batch job script. Refer to your machine's user guide for instructions on properly loading and using Apptainer. </p><div class="fragment"><div class="line">#!/bin/bash</div>

<div class="line">#SBATCH --job-name=mfc-sim</div>

<div class="line">#SBATCH --nodes=2</div>

<div class="line">#SBATCH --ntasks-per-node=12</div>

<div class="line">#SBATCH --time=06:00:00</div>

<div class="line">#SBATCH --partition=</div>

<div class="line">#SBATCH --output=mfc-sim-%j.out</div>

<div class="line">#SBATCH --error=mfc-sim-%j.err</div>

<div class="line"> </div>

<div class="line">cd $SLURM_SUBMIT_DIR</div>

<div class="line"> </div>

<div class="line"># Define container image</div>

<div class="line">CONTAINER=&quot;mfc:latest-gpu.sif&quot;</div>

<div class="line"> </div>

<div class="line">apptainer exec --nv --fakeroot --writable-tmpfs \</div>

<div class="line">--bind &quot;$PWD&quot;:/mnt \</div>

<div class="line"> $CONTAINER \</div>

<div class="line"> bash -c &quot;cd /opt/MFC &amp;&amp; ./mfc.sh run sim/case.py -- -c &lt;computer&gt;&quot;</div>

</div><!-- fragment --><p>In the above,</p><ul>

<li>The <span class="tt">/sim</span> directory should have all the simulation files, including the case setup (<span class="tt">case.py</span>).</li>

<li>The <span class="tt">--nv --fakeroot --writable-tmpfs</span> set of flags are needed to<ul>

<li>Grant access to the host system's NVIDIA GPUs and its CUDA libraries.</li>

<li>Enable root-like permissions inside the container without actual root access.</li>

<li>Allow temporary write access to the container filesystem.</li>

<h2 class="doxsection"><a class="anchor" id="autotoc_md139"></a>

Tag Details</h2>

<h3 class="doxsection"><a class="anchor" id="autotoc_md140"></a>

Base Images</h3>

<li>CPU images (v4.3.0-latest releases) are built on <b>Ubuntu 22.04</b>.</li>

<li>GPU images (v4.3.0-latest releases) are built on <b>NVHPC SDK 23.11 (CUDA 12.3) &amp; Ubuntu 22.04</b>.</li>

<h3 class="doxsection"><a class="anchor" id="autotoc_md141"></a>

Tag Structure</h3>

<li><b><span class="tt">vx.x.x</span></b> - Official MFC release versions (recommended: use <span class="tt">latest</span> release)</li>

<li><b><span class="tt">cpu/gpu</span></b> - Build configurations for CPU or GPU acceleration.</li>

<li><b><span class="tt">ubuntu-xx.xx</span></b> - Base Ubuntu version (standard = <span class="tt">amd64</span>, <span class="tt">-arm</span> = <span class="tt">arm64</span>)</li>

<h3 class="doxsection"><a class="anchor" id="autotoc_md142"></a>

Example Tags</h3>

<div class="fragment"><div class="line">mfc:latest-xxx # Latest version (amd64 &amp; arm64)</div>

<div class="line">mfc:vx.x.x-cpu # CPU version (amd64 &amp; arm64)</div>

<div class="line">mfc:vx.x.x-gpu # GPU version (amd64 &amp; arm64)</div>

<div class="line">mfc:vx.x.x-xxx-ubuntu-xx.xx # amd64 natively-supported version</div>

<div class="line">mfc:vx.x.x-xxx-ubuntu-xx.xx-arm # arm64 natively-supported version</div>

</div><!-- fragment --><h3 class="doxsection"><a class="anchor" id="autotoc_md143"></a>

Architecture Support</h3>

<p>You can specify your architecture with <span class="tt">--platform &lt;os&gt;/&lt;arch&gt;</span>, typically either <span class="tt">linux/amd64</span> or <span class="tt">linux/arm64</span>. If you are 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. </p><div class="fragment"><div class="line">linux/amd64</div>

<div class="line">linux/amd64/v2</div>

<div class="line">linux/amd64/v3</div>

<div class="line">linux/arm64</div>

<div class="line">linux/riscv64</div>

<div class="line">linux/ppc64le</div>

<div class="line">linux/s390x</div>

<div class="line">linux/386</div>

<div class="line">linux/mips64le</div>

<div class="line">linux/mips64</div>

<div class="line">linux/loong64</div>

<div class="line">linux/arm/v7</div>

<div class="line">linux/arm/v6</div>

</div><!-- fragment --><div style="text-align:center; font-size:0.75rem; color:#888; padding:16px 0 0;">Page last updated: 2026-10-10</div> </div></div><!-- contents -->

<div id="page-nav" class="page-nav-panel">

<div id="page-nav-resize-handle"></div>

<div id="page-nav-tree">

<div id="page-nav-contents">

<div id="nav-path" class="navpath">

<ul></ul>