<liclass="toctree-l2"><aclass="reference internal"href="desktop.html#difference-between-images-and-containers">Difference between images and containers</a></li>
<liclass="toctree-l2"><aclass="reference internal"href="desktop.html#installation-in-windows">Installation in Windows</a></li>
<liclass="toctree-l2"><aclass="reference internal"href="desktop.html#enable-virtualization-for-windows-machine">Enable Virtualization for Windows Machine</a></li>
<liclass="toctree-l2"><aclass="reference internal"href="#mounting-user-data-and-running-docker-image">Mounting User data and running Docker image</a></li>
<liclass="toctree-l2"><aclass="reference internal"href="#how-to-use-maxwell-td">How to use Maxwell-TD</a></li>
<p>Welcome to the user manual for setting up and using Docker on a Windows system. This guide will provide comprehensive instructions to help you install and configure Docker Desktop on Windows, activate virtualization in BIOS, install WSL (Windows Subsystem for Linux), import Docker images, mount user data, and run Docker containers. Additionally, it includes pointers and tips to address common questions and issues that users may encounter.</p>
<p>To enable virtualization, you’ll need to access the BIOS settings during startup. Here’s how:</p>
<olclass="arabic simple">
<li><p>Power on your computer.</p></li>
<li><p>Keep an eye on the initial boot screen.</p></li>
<li><p>When you see the screen, press the <codeclass="docutils literal notranslate"><spanclass="pre">F2</span><spanclass="pre">/</span><spanclass="pre">F10</span><spanclass="pre">/</span><spanclass="pre">F12</span><spanclass="pre">/</span><spanclass="pre">Esc</span><spanclass="pre">/</span><spanclass="pre">Delete</span><spanclass="pre">/</span><spanclass="pre">Enter</span></code> key to enter the BIOS settings.</p></li>
<p><spanclass="caption-text">Screen when we boot up the machine. Press <codeclass="docutils literal notranslate"><spanclass="pre">F2</span><spanclass="pre">/</span><spanclass="pre">F10</span><spanclass="pre">/</span><spanclass="pre">F12</span><spanclass="pre">/</span><spanclass="pre">Esc</span><spanclass="pre">/</span><spanclass="pre">Delete</span><spanclass="pre">/</span><spanclass="pre">Enter</span></code></span><aclass="headerlink"href="#id1"title="Link to this image"></a></p>
<li><p>Navigate through the BIOS menus using the arrow keys. Look for the section typically labeled <codeclass="docutils literal notranslate"><spanclass="pre">Advanced</span></code>, <codeclass="docutils literal notranslate"><spanclass="pre">Advanced</span><spanclass="pre">Settings</span></code> or <codeclass="docutils literal notranslate"><spanclass="pre">CPU</span><spanclass="pre">Configuration</span></code>.</p></li>
</ol>
<p>or</p>
<olclass="arabic simple"start="4">
<li><p>Alternatively, some BIOS versions allow you to search for settings. Look for a search bar or a similar feature where you can type <codeclass="docutils literal notranslate"><spanclass="pre">virtualization</span></code> or <codeclass="docutils literal notranslate"><spanclass="pre">VT-x</span></code> (for Intel processors) / <codeclass="docutils literal notranslate"><spanclass="pre">AMD-V</span></code> (for AMD processors).</p></li>
<p>Once you locate the virtualization options within these sections, you can proceed to enable them. This step is crucial for utilizing virtualization features such as running virtual machines or other virtualization-based applications on your computer. After making the necessary changes, remember to save your settings and exit the BIOS.</p>
<olclass="arabic simple"start="5">
<li><p>Change the setting from <codeclass="docutils literal notranslate"><spanclass="pre">Disabled</span></code> to <codeclass="docutils literal notranslate"><spanclass="pre">Enabled</span></code> using the appropriate key (usually <codeclass="docutils literal notranslate"><spanclass="pre">Enter</span></code> or the <codeclass="docutils literal notranslate"><spanclass="pre">+</span></code> key).</p></li>
<p>Here are the simplified instructions for installing Windows Subsystem for Linux (WSL) and verifying its installation:</p>
<p><strong>Installing Windows Subsystem for Linux (WSL)</strong></p>
<olclass="arabic simple">
<li><p><strong>Open PowerShell as Administrator</strong></p></li>
<li><p><strong>Install WSL:</strong>
Run the following command to install WSL: <codeclass="docutils literal notranslate"><spanclass="pre">wsl</span><spanclass="pre">--install</span></code>.
Follow any prompts or confirmations that appear during the installation process.</p></li>
<li><p><strong>Wait for Installation to Complete:</strong>
Allow the installation process to finish. This may take some time depending on your internet speed.</p></li>
Run the following command to check the installed WSL versions and their respective distributions: <codeclass="docutils literal notranslate"><spanclass="pre">wsl</span><spanclass="pre">-l</span><spanclass="pre">-v</span></code>
This command lists all installed Linux distributions and their associated WSL versions (<cite>1</cite> or <cite>2</cite>).</p></li>
<li><p>Download Docker Desktop from <aclass="reference external"href="https://www.docker.com/get-started/">Docker’s official website</a> (<aclass="reference external"href="https://www.docker.com/get-started/">https://www.docker.com/get-started/</a>).</p></li>
<li><p>Once downloaded, locate the installer file (e.g., <codeclass="docutils literal notranslate"><spanclass="pre">DockerDesktopInstaller.exe</span></code>) and double-click to launch it.</p></li>
<li><p>Follow the prompts provided by the Docker Desktop installer to complete the installation process. This may involve accepting terms and conditions and choosing installation preferences.</p></li>
<li><p>After installation, a Docker Desktop shortcut will appear on your desktop. The necessary components to run Maxwell-TD Docker images include Docker Desktop itself, Windows PowerShell for running CLI commands, and a designated working folder containing Docker images and user data (e.g., geometry information).</p></li>
<p><spanclass="caption-text">All the data/folders/apps needed to run Maxwell-TD Docker image</span><aclass="headerlink"href="#id10"title="Link to this image"></a></p>
<p>Currently, the local repository in Docker Desktop is empty. To proceed, we must upload the compiled image for Maxwell-TD. This requires using the PowerShell console, as the GUI does not support managing local Docker images directly and defaults to searching online repositories for Docker images.</p>
<p>Next, we need to mount the zipped Docker image onto the Windows system. Since this action cannot be performed using the Docker Desktop GUI, we’ll need to use the console terminal instead.</p>
<p>In the designated working folder, you will find a zipped Docker image file and an “examples” folder containing user-defined data.</p>
<p>To load the Docker image, execute the command <codeclass="docutils literal notranslate"><spanclass="pre">docker</span><spanclass="pre">load</span><spanclass="pre">--input</span><spanclass="pre"><PATH</span><spanclass="pre">to</span><spanclass="pre">zipped</span><spanclass="pre">docker</span><spanclass="pre">image></span></code>. This process will take some time, and you can verify its completion by using <codeclass="docutils literal notranslate"><spanclass="pre">docker</span><spanclass="pre">images</span></code> in the console.</p>
<p><spanclass="caption-text">Loaded Docker Image can be seen in Docker Desktop</span><aclass="headerlink"href="#id17"title="Link to this image"></a></p>
<h2>Mounting User data and running Docker image<aclass="headerlink"href="#mounting-user-data-and-running-docker-image"title="Link to this heading"></a></h2>
<p>Finally, we are ready to run the Docker image. You can use a PowerShell script with administrative privileges to execute the Docker image. We have prepared a script file named <codeclass="docutils literal notranslate"><spanclass="pre">runDocker.ps1</span></code> that can be executed in the console terminal.</p>
<p>To run the script and start the Docker image, follow these steps:</p>
<olclass="arabic simple">
<li><p><strong>Open PowerShell as Administrator</strong></p></li>
<li><p><strong>Navigate to Script Directory:</strong>
Use the <codeclass="docutils literal notranslate"><spanclass="pre">cd</span></code> command to navigate to the directory where <codeclass="docutils literal notranslate"><spanclass="pre">runDocker.ps1</span></code> is located.</p></li>
<li><dlclass="simple">
<dt><strong>Execute the Script:</strong></dt><dd><ulclass="simple">
<li><p>Run the script by typing <codeclass="docutils literal notranslate"><spanclass="pre">.\runDocker.ps1</span></code> and press <codeclass="docutils literal notranslate"><spanclass="pre">Enter</span></code>.</p></li>
<li><p>The script will mount the folder containing user-defined data into the Docker Server environment.</p></li>
</ul>
</dd>
</dl>
</li>
</ol>
<divclass="admonition note">
<pclass="admonition-title">Note</p>
<ulclass="simple">
<li><p>When running the Docker image, any data saved onto the mounted filesystem will persist. However, other modifications, such as custom installations of packages, will be temporary and will disappear after you exit the Docker session.</p></li>
<li><p>Treat the Docker image as a saved state of a customized environment.</p></li>
<p>Let’s break down the lines in the PowerShell script to understand the necessary steps for running the Docker image. This will clarify what is needed for execution.</p>
<ulclass="simple">
<li><p><strong>$imageName</strong>:</p></li>
</ul>
<p>This variable defines the name of the Docker image that you want to run. In this case, it is set to <codeclass="docutils literal notranslate"><spanclass="pre">maxwell_td_image</span></code>. Users should not change this variable if they intend to run Maxwell-TD.</p>
<ulclass="simple">
<li><p><strong>$containerName</strong>:</p></li>
</ul>
<p>This variable specifies the name of the container that will run the Docker image. You can run multiple containers from the same image concurrently, so each running instance needs a unique name. Users can customize this variable to suit their naming conventions.</p>
<ulclass="simple">
<li><p><strong>$hostVolumePath</strong>:</p></li>
</ul>
<p>This variable holds the path to the working folder on the Windows system. This folder contains essential files such as geometry files for simulation models and scripts for setting simulation parameters. Users must update this path to point to their specific working folder.</p>
<p>This variable defines the path within the Docker container (running on Linux environment) where the host volume (<strong>$hostVolumePath</strong>) will be mounted. In this script, it is set to <codeclass="docutils literal notranslate"><spanclass="pre">/dgtd/model/</span></code>. It is recommended that users do not change this variable unless necessary, to ensure compatibility with the Docker image’s expected mount point.</p>
<p><spanclass="caption-text">User-defined parameters to change location of User data</span><aclass="headerlink"href="#id19"title="Link to this image"></a></p>
<p>Next, the script proceeds to execute several commands to display the paths and names. It also checks the CUDA version installed on the Windows device. Afterward, it runs the Docker command <codeclass="docutils literal notranslate"><spanclass="pre">docker</span><spanclass="pre">run</span><spanclass="pre">--rm</span><spanclass="pre">--gpus</span><spanclass="pre">all</span><spanclass="pre">-it</span><spanclass="pre">--name</span><spanclass="pre">${containerName}</span><spanclass="pre">-v</span><spanclass="pre">${hostVolumePath}:${containerVolumePath}</span><spanclass="pre">${imageName}</span></code>.</p>
<dlclass="simple">
<dt><strong>Explanation of Docker Command Flags</strong></dt><dd><ulclass="simple">
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">docker</span><spanclass="pre">run</span></code>: This command starts a new Docker container.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">--rm</span></code>: Automatically removes the container when it exits. Useful for temporary containers.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">--gpus</span><spanclass="pre">all</span></code>: Enables access to all GPUs in the container.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">-it</span></code>: Allocates a pseudo-TTY and keeps stdin open. Allows interactive terminal access.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">--name</span><spanclass="pre">${containerName}</span></code>: Assigns a name to the container instance based on the value stored in the <codeclass="docutils literal notranslate"><spanclass="pre">$containerName</span></code> variable.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">-v</span><spanclass="pre">${hostVolumePath}:${containerVolumePath}</span></code>: Mounts a volume from the host machine (Windows) into the Docker container. <codeclass="docutils literal notranslate"><spanclass="pre">${hostVolumePath}</span></code> is the path on the host system, and <codeclass="docutils literal notranslate"><spanclass="pre">${containerVolumePath}</span></code> is the path inside the container where the volume will be mounted.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">${imageName}</span></code>: Specifies the Docker image to use for creating the container.</p></li>
<li><p>The <codeclass="docutils literal notranslate"><spanclass="pre">--rm</span></code> flag ensures that the container is automatically removed after it stops running, helping to manage resources efficiently.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">--gpus</span><spanclass="pre">all</span></code> allows the Docker container to access all available GPUs on the host machine, which is crucial for applications that require GPU acceleration.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">-it</span></code> enables interactive mode with a terminal session, which is useful for interacting directly with the container if needed.</p></li>
</ul>
</dd>
</dl>
<p>This Docker command, when executed within the PowerShell script, sets up and runs the Docker container named <codeclass="docutils literal notranslate"><spanclass="pre">${containerName}</span></code> with GPU support, mounts necessary volumes, and utilizes the specified Docker image <codeclass="docutils literal notranslate"><spanclass="pre">${imageName}</span></code> for the Maxwell-TD application. Adjust <codeclass="docutils literal notranslate"><spanclass="pre">${containerName}</span></code>, <codeclass="docutils literal notranslate"><spanclass="pre">${hostVolumePath}</span></code>, <codeclass="docutils literal notranslate"><spanclass="pre">${containerVolumePath}</span></code>, and <codeclass="docutils literal notranslate"><spanclass="pre">${imageName}</span></code> as per your specific environment and requirements.</p>
<p>When opening a Windows text file in a Unix environment, extra <codeclass="docutils literal notranslate"><spanclass="pre">\r</span></code> characters at the end of each line can cause errors such as <codeclass="docutils literal notranslate"><spanclass="pre">/bin/bash^M:</span><spanclass="pre">bad</span><spanclass="pre">interpreter:</span><spanclass="pre">No</span><spanclass="pre">such</span><spanclass="pre">file</span><spanclass="pre">or</span><spanclass="pre">directory</span></code>. This is because Unix-based systems expect lines to end with <codeclass="docutils literal notranslate"><spanclass="pre">\n</span></code> (newline) instead of <codeclass="docutils literal notranslate"><spanclass="pre">\r\n</span></code> (carriage return followed by newline) used in Windows.</p>
<p>To fix this issue, you can convert the line endings from Windows format to Unix format using utilities like <codeclass="docutils literal notranslate"><spanclass="pre">dos2unix</span></code>, which removes the extra <codeclass="docutils literal notranslate"><spanclass="pre">\r</span></code> characters. Alternatively, you can use the included function <codeclass="docutils literal notranslate"><spanclass="pre">Remove-CarriageReturns</span></code> in <codeclass="docutils literal notranslate"><spanclass="pre">runDocker.ps1</span></code> to process the files. Once corrected, your script should execute correctly within Docker or any Unix-based environment without encountering interpreter errors.</p>
<p><spanclass="caption-text">Miscellaneous function to treat textfiles from Windows System (Optional)</span><aclass="headerlink"href="#id21"title="Link to this image"></a></p>
<p>To run the script, navigate to the directory where <codeclass="docutils literal notranslate"><spanclass="pre">runDocker.ps1</span></code> is located and execute <codeclass="docutils literal notranslate"><spanclass="pre">./runDocker.ps1</span></code>. The script will display the CUDA toolkit version and open a BASH shell in the Docker container with <codeclass="docutils literal notranslate"><spanclass="pre">maxwell_td_image</span></code>. This environment simulates a Linux environment.</p>
<p>Upon starting the Docker container, you will be in the <codeclass="docutils literal notranslate"><spanclass="pre">/dgtd/</span></code> directory, where the Discontinuous Galerkin Time-Domain (DGTD) code is located. The compiled code can be found in the <codeclass="docutils literal notranslate"><spanclass="pre">/dgtd/build/</span></code> directory, with the executables named <codeclass="docutils literal notranslate"><spanclass="pre">maxwelltd_CUDA_LTS_DOUBLEpre_FLOATpro</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">maxwelltd_CUDA_LTS_DOUBLEpre_FLOATpro-</span></code>. User data, mounted from the Windows filesystem, is available in the <codeclass="docutils literal notranslate"><spanclass="pre">/dgtd/model/</span></code> directory. Before running the simulation, the compiled executable must be copied to the simulation folder (<codeclass="docutils literal notranslate"><spanclass="pre">/dgtd/model/MaxwellTD_data/</span></code>). This can be done by executing the following command:</p>
<p>Simulation files for the MaxwellTD model are located in the directory <codeclass="docutils literal notranslate"><spanclass="pre">/dgtd/model/MaxwellTD_data</span></code>. Additionally, we have included CST reference data for the same simulation model in the folder <codeclass="docutils literal notranslate"><spanclass="pre">CST_data</span></code>. A Python script named <codeclass="docutils literal notranslate"><spanclass="pre">compare_maxwelltd_CST.py</span></code> has been provided to facilitate extraction and comparison of data between the DGTD simulation and CST data.</p>
<p>To run the DGTD simulation, we can navigate to <codeclass="docutils literal notranslate"><spanclass="pre">/dgtd/model/MaxwellTD_data/</span></code> and run the shell script <codeclass="docutils literal notranslate"><spanclass="pre">CUDA_LTS_RUN.sh</span></code>.</p>
<p>Following the completion of the simulation, you can execute the Python script <codeclass="docutils literal notranslate"><spanclass="pre">compare_maxwelltd_CST.py</span></code> to compare the results with those obtained from the CST simulation.</p>
<p>It’s essential to verify that your Windows device has the correct CUDA toolkit installed to run Maxwell-TD. You can check the CUDA toolkit version by using ‘nvidia-smi’ in the console terminal. The minimum required version to run Maxwell-TD is CUDA toolkit 12.4.</p>
<p>If you need to update your CUDA toolkit, you can visit the <aclass="reference external"href="https://developer.nvidia.com/cuda-toolkit">NVIDIA website</a> (<aclass="reference external"href="https://developer.nvidia.com/cuda-toolkit">https://developer.nvidia.com/cuda-toolkit</a>). Click on ‘NVIDIA CUDA Toolkit Download’ to access the latest version. Alternatively, if you require an earlier version, you can navigate to ‘Archive of Previous CUDA Releases’ on the NVIDIA website to find the specific CUDA toolkit version you need.</p>
<p>Follow the download and installation instructions provided on the NVIDIA website to update or install the CUDA toolkit on your Windows device. This ensures that Maxwell-TD and other CUDA-dependent applications can function correctly.</p>
<p>Make sure your Windows 10 or 11 system meets the following requirements:</p>
<ulclass="simple">
<li><p><strong>WSL Version:</strong> Ensure WSL version 1.1.3.0 or newer.</p></li>
<li><p><strong>Windows 11:</strong> 64-bit Home or Pro version 21H2 or later, or Enterprise or Education version 21H2 or later.</p></li>
<li><p><strong>Windows 10:</strong> 64-bit Home or Pro version 22H2 (build 19045) or later, or Enterprise or Education version 22H2 (build 19045) or later. The minimum supported version is Home or Pro 21H2 (build 19044) or later, or Enterprise or Education 21H2 (build 19044) or later.</p></li>
</ul>
<divclass="admonition note">
<pclass="admonition-title">Note</p>
<ulclass="simple">
<li><p>Docker Desktop on Windows is supported only on versions of Windows that are still actively serviced by Microsoft. It is not compatible with Windows Server versions like Windows Server 2019 or Windows Server 2022.</p></li>
<li><p>Containers and images created with Docker Desktop are shared across all user accounts on the same machine, as they use a common VM for building and running containers. However, sharing containers and images between user accounts is not supported when using the Docker Desktop WSL 2 backend.</p></li>
<p>Make sure your system has adequate storage space for the image. The current image requires 10GB for storage while zipped. Once extracted, it occupies an additional 10GB on your system, although it remains hidden from regular users. You can view these hidden images and containers using Docker Desktop.</p>
<p>If necessary, resort to command-line operations to reclaim system resources. Execute these commands in a PowerShell console with administrative privileges.</p>
<divclass="highlight-bash notranslate"><divclass="highlight"><pre><span></span><spanclass="c1"># Purging All Unused or Dangling Resources</span>
<p>To enable Docker server virtualization on Windows, it’s crucial to ensure that virtualization is enabled in your computer’s BIOS settings. This setting can only be modified by restarting your machine and accessing the BIOS configuration. Virtualization support in BIOS allows Windows to utilize Docker server features effectively. It’s a necessary step to ensure Docker containers run efficiently on your system.</p>
<p>To modify simulation parameters, you can edit the <codeclass="docutils literal notranslate"><spanclass="pre">CUDA_LTS_RUN.sh</span></code> shell script. This script contains flags or variables that control various aspects of the DGTD simulation. The script includes comments or descriptions to explain the variables’ or flags’ purpose.</p>
