%% Generated by Sphinx. \def\sphinxdocclass{report} \documentclass[letterpaper,10pt,english]{sphinxmanual} \ifdefined\pdfpxdimen \let\sphinxpxdimen\pdfpxdimen\else\newdimen\sphinxpxdimen \fi \sphinxpxdimen=.75bp\relax \ifdefined\pdfimageresolution \pdfimageresolution= \numexpr \dimexpr1in\relax/\sphinxpxdimen\relax \fi %% let collapsible pdf bookmarks panel have high depth per default \PassOptionsToPackage{bookmarksdepth=5}{hyperref} \PassOptionsToPackage{warn}{textcomp} \usepackage[utf8]{inputenc} \ifdefined\DeclareUnicodeCharacter % support both utf8 and utf8x syntaxes \ifdefined\DeclareUnicodeCharacterAsOptional \def\sphinxDUC#1{\DeclareUnicodeCharacter{"#1}} \else \let\sphinxDUC\DeclareUnicodeCharacter \fi \sphinxDUC{00A0}{\nobreakspace} \sphinxDUC{2500}{\sphinxunichar{2500}} \sphinxDUC{2502}{\sphinxunichar{2502}} \sphinxDUC{2514}{\sphinxunichar{2514}} \sphinxDUC{251C}{\sphinxunichar{251C}} \sphinxDUC{2572}{\textbackslash} \fi \usepackage{cmap} \usepackage[T1]{fontenc} \usepackage{amsmath,amssymb,amstext} \usepackage{babel} \usepackage{tgtermes} \usepackage{tgheros} \renewcommand{\ttdefault}{txtt} \usepackage[Bjarne]{fncychap} \usepackage{sphinx} \fvset{fontsize=auto} \usepackage{geometry} % Include hyperref last. \usepackage{hyperref} % Fix anchor placement for figures with captions. \usepackage{hypcap}% it must be loaded after hyperref. % Set up styles of URL: it should be placed after hyperref. \urlstyle{same} \usepackage{sphinxmessages} \setcounter{tocdepth}{1} \title{User Manual for Maxwell-TD and Docker} \date{Jun 17, 2024} \release{1.0} \author{ACEM group} \newcommand{\sphinxlogo}{\vbox{}} \renewcommand{\releasename}{Release} \makeindex \begin{document} \ifdefined\shorthandoff \ifnum\catcode`\=\string=\active\shorthandoff{=}\fi \ifnum\catcode`\"=\active\shorthandoff{"}\fi \fi \pagestyle{empty} \sphinxmaketitle \pagestyle{plain} \sphinxtableofcontents \pagestyle{normal} \phantomsection\label{\detokenize{index::doc}} \chapter{Maxwell-TD and Docker} \section{Introduction to Docker} Docker is a powerful platform designed for developing, shipping, and running applications using containerization technology. Containers are standardized units that package software and its dependencies, enabling applications to run consistently across various environments. This approach offers several advantages over traditional methods of software deployment and management. \subsection{Key Benefits of Docker} \begin{enumerate} \item \textbf{Portability and Consistency}: Docker containers are lightweight and isolated, ensuring that applications behave predictably regardless of the environment. This portability simplifies the deployment process and reduces compatibility issues. \item \textbf{Efficiency in Development and Deployment}: Developers can build and ship applications faster with Docker. Containers encapsulate all necessary components, including libraries and dependencies, making it easier to manage and scale applications. \item \textbf{Environment Flexibility}: Docker supports deployment across different environments, whether on-premises, in the cloud, or hybrid setups. This flexibility ensures seamless transitions between development, testing, and production environments. \end{enumerate} \subsection{Why Docker for Running Maxwell-TD?} Maxwell-TD, a Discontinuous Galerkin Time-Domain (DGTD) solver program primarily developed and tested in UNIX environments, benefits significantly from Docker on Windows. Here's why: \begin{enumerate} \item \textbf{UNIX Compatibility}: Maxwell-TD is optimized for UNIX environments, and compiling it for Windows can be challenging and time-consuming due to differing libraries and dependencies. \item \textbf{Pre-built Docker Image}: Docker allows Maxwell-TD to be packaged into a pre-built image that includes all necessary libraries and configurations for UNIX. This image can then be easily deployed and run on Windows systems using Docker Desktop and Windows Subsystem for Linux (WSL). \item \textbf{Simplified Setup}: By leveraging Docker and WSL, users can avoid the complexities of setting up a UNIX-like environment on Windows manually. Docker ensures that Maxwell-TD runs seamlessly without the need for extensive configuration or troubleshooting. \item \textbf{Consistency and Reliability}: Docker's containerization ensures that Maxwell-TD behaves consistently across different Windows machines, maintaining the integrity and reliability of the software application. \end{enumerate} In conclusion, Docker provides an efficient solution for running Maxwell-TD on Windows by encapsulating it within a container that is compatible with UNIX environments. This approach streamlines deployment, reduces setup efforts, and enhances overall compatibility and reliability of Maxwell-TD in diverse computing environments. \label{\detokenize{Manual:user-manual-windows-system}}\label{\detokenize{Manual::doc}} \section{Step\sphinxhyphen{}by\sphinxhyphen{}Step installation in Windows} \label{\detokenize{Manual:step-by-step-installation-in-windows}} \sphinxAtStartPar This guide provides comprehensive instructions for installing and configuring Docker Desktop on a Windows system. It covers activating virtualization in BIOS, installing WSL (Windows Subsystem for Linux), importing Docker images, mounting user data, and running Docker containers. Additionally, it includes tips for running Maxwell-TD. \subsection{Activate Virtualization in BIOS} \label{\detokenize{Manual:activate-virtualization-in-bios}} \sphinxAtStartPar To enable virtualization, you’ll need to access the BIOS settings during startup. Here’s how: \begin{enumerate} \sphinxsetlistlabels{\arabic}{enumi}{enumii}{}{.}% \item {} \sphinxAtStartPar Power on your computer. \item {} \sphinxAtStartPar Keep an eye on the initial boot screen. \item {} \sphinxAtStartPar When you see the screen, press the \sphinxcode{\sphinxupquote{F2 / F10 / F12 / Esc / Delete / Enter}} key to enter the BIOS settings. \end{enumerate} \begin{figure}[htbp] \centering \capstart \noindent\sphinxincludegraphics[width=900\sphinxpxdimen]{{B1}.jpg} \caption{Screen when we boot up the machine. Press \sphinxcode{\sphinxupquote{F2 / F10 / F12 / Esc / Delete / Enter}}}\label{\detokenize{Manual:id1}}\end{figure} \sphinxAtStartPar Once inside the BIOS settings: \begin{enumerate} \sphinxsetlistlabels{\arabic}{enumi}{enumii}{}{.}% \setcounter{enumi}{3} \item {} \sphinxAtStartPar Navigate through the BIOS menus using the arrow keys. Look for the section typically labeled \sphinxcode{\sphinxupquote{Advanced}}, \sphinxcode{\sphinxupquote{Advanced Settings}} or \sphinxcode{\sphinxupquote{CPU Configuration}}. \end{enumerate} \sphinxAtStartPar or \begin{enumerate} \sphinxsetlistlabels{\arabic}{enumi}{enumii}{}{.}% \setcounter{enumi}{3} \item {} \sphinxAtStartPar Alternatively, some BIOS versions allow you to search for settings. Look for a search bar or a similar feature where you can type \sphinxcode{\sphinxupquote{virtualization}} or \sphinxcode{\sphinxupquote{VT\sphinxhyphen{}x}} (for Intel processors) / \sphinxcode{\sphinxupquote{AMD\sphinxhyphen{}V}} (for AMD processors). \end{enumerate} \begin{figure}[htbp] \centering \capstart \noindent\sphinxincludegraphics[width=900\sphinxpxdimen]{{B3}.jpg} \caption{BIOS settings screen.}\label{\detokenize{Manual:id2}}\end{figure} \sphinxAtStartPar 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\sphinxhyphen{}based applications on your computer. After making the necessary changes, remember to save your settings and exit the BIOS. \begin{enumerate} \sphinxsetlistlabels{\arabic}{enumi}{enumii}{}{.}% \setcounter{enumi}{4} \item {} \sphinxAtStartPar Change the setting from \sphinxcode{\sphinxupquote{Disabled}} to \sphinxcode{\sphinxupquote{Enabled}} using the appropriate key (usually \sphinxcode{\sphinxupquote{Enter}} or the \sphinxcode{\sphinxupquote{+}} key). \item {} \sphinxAtStartPar Save changes and exit BIOS \end{enumerate} \begin{figure}[htbp] \centering \capstart \noindent\sphinxincludegraphics[width=900\sphinxpxdimen]{{B2}.jpg} \caption{Turn on Virtualization.}\label{\detokenize{Manual:id3}}\end{figure} \sphinxAtStartPar Your computer will restart with virtualization support enabled. \subsection{Install WSL} \label{\detokenize{Manual:install-wsl}} \sphinxAtStartPar Here are the simplified instructions for installing Windows Subsystem for Linux (WSL) and verifying its installation: \sphinxAtStartPar \sphinxstylestrong{Installing Windows Subsystem for Linux (WSL)} \begin{enumerate} \sphinxsetlistlabels{\arabic}{enumi}{enumii}{}{.}% \item {} \sphinxAtStartPar \sphinxstylestrong{Open PowerShell as Administrator} \item {} \sphinxAtStartPar \sphinxstylestrong{Install WSL:} Run the following command to install WSL: \sphinxcode{\sphinxupquote{wsl \sphinxhyphen{}\sphinxhyphen{}install}}. Follow any prompts or confirmations that appear during the installation process. \item {} \sphinxAtStartPar \sphinxstylestrong{Wait for Installation to Complete:} Allow the installation process to finish. This may take some time depending on your internet speed. \end{enumerate} \begin{figure}[htbp] \centering \capstart \noindent\sphinxincludegraphics[width=1200\sphinxpxdimen]{{W3}.png} \caption{Install Windows Subsystem for Linux (WSL)}\label{\detokenize{Manual:id4}}\end{figure} \begin{enumerate} \sphinxsetlistlabels{\arabic}{enumi}{enumii}{}{.}% \setcounter{enumi}{3} \item {} \sphinxAtStartPar \sphinxstylestrong{Check WSL Version:} Run the following command to check the installed WSL versions and their respective distributions: \sphinxcode{\sphinxupquote{wsl \sphinxhyphen{}l \sphinxhyphen{}v}} This command lists all installed Linux distributions and their associated WSL versions (\sphinxtitleref{1} or \sphinxtitleref{2}). \end{enumerate} \begin{figure}[htbp] \centering \capstart \noindent\sphinxincludegraphics[width=1200\sphinxpxdimen]{{W4}.png} \caption{Check if WSL is properly installed}\label{\detokenize{Manual:id5}}\end{figure} \sphinxAtStartPar Following these steps ensures that you install Windows Subsystem for Linux (WSL) and confirm its proper installation on your Windows system. \subsection{Install Docker Desktop in Windows} \label{\detokenize{Manual:install-docker-desktop-in-windows}}\begin{enumerate} \sphinxsetlistlabels{\arabic}{enumi}{enumii}{}{.}% \item {} \sphinxAtStartPar Download Docker Desktop from \sphinxhref{https://www.docker.com/get-started/}{Docker’s official website} (\sphinxurl{https://www.docker.com/get-started/}). \end{enumerate} \begin{figure}[htbp] \centering \capstart \noindent\sphinxincludegraphics[width=1200\sphinxpxdimen]{{W5}.png} \caption{Download Docker Desktop online}\label{\detokenize{Manual:id6}}\end{figure} \begin{enumerate} \sphinxsetlistlabels{\arabic}{enumi}{enumii}{}{.}% \setcounter{enumi}{1} \item {} \sphinxAtStartPar Once downloaded, locate the installer file (e.g., \sphinxcode{\sphinxupquote{DockerDesktopInstaller.exe}}) and double\sphinxhyphen{}click to launch it. \item {} \sphinxAtStartPar 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. \end{enumerate} \begin{figure}[htbp] \centering \capstart \noindent\sphinxincludegraphics[width=1200\sphinxpxdimen]{{W6}.png} \caption{Docker Desktop Installer}\label{\detokenize{Manual:id7}}\end{figure} \begin{figure}[htbp] \centering \capstart \noindent\sphinxincludegraphics[width=1200\sphinxpxdimen]{{W7}.png} \caption{Installing Docker Desktop}\label{\detokenize{Manual:id8}}\end{figure} \begin{figure}[htbp] \centering \capstart \noindent\sphinxincludegraphics[width=1200\sphinxpxdimen]{{W8}.png} \caption{Finish installing Docker Desktop}\label{\detokenize{Manual:id9}}\end{figure} \begin{enumerate} \sphinxsetlistlabels{\arabic}{enumi}{enumii}{}{.}% \setcounter{enumi}{3} \item {} \sphinxAtStartPar After installation, a Docker Desktop shortcut will appear on your desktop. The necessary components to run Maxwell\sphinxhyphen{}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). %\end{enumerate} \begin{figure}[htbp] \centering \capstart \noindent\sphinxincludegraphics[width=200\sphinxpxdimen]{{W9}.png} \caption{All the data/folders/apps needed to run Maxwell\sphinxhyphen{}TD Docker image}\label{\detokenize{Manual:id10}}\end{figure} %\begin{enumerate} \sphinxsetlistlabels{\arabic}{enumi}{enumii}{}{.}% \setcounter{enumi}{4} \item {} \sphinxAtStartPar Launch Docker Desktop by double\sphinxhyphen{}clicking the Docker Desktop shortcut on your desktop. \item {} \sphinxAtStartPar Upon first launch, Docker Desktop may prompt you to accept terms and conditions. Agree to proceed with using the application. %\end{enumerate} \begin{figure}[htbp] \centering \capstart \noindent\sphinxincludegraphics[width=900\sphinxpxdimen]{{W10}.png} \caption{Accept the terms and conditions}\label{\detokenize{Manual:id11}}\end{figure} %\begin{enumerate} \sphinxsetlistlabels{\arabic}{enumi}{enumii}{}{.}% \setcounter{enumi}{6} \item {} \sphinxAtStartPar You can continue without logging into Docker Desktop if prompted, and optionally skip any survey presented during initial setup. \end{enumerate} \begin{figure}[htbp] \centering \capstart \noindent\sphinxincludegraphics[width=900\sphinxpxdimen]{{W11}.png} \caption{Continue without logging in}\label{\detokenize{Manual:id12}}\end{figure} \begin{figure}[htbp] \centering \capstart \noindent\sphinxincludegraphics[width=900\sphinxpxdimen]{{W12}.png} \caption{Skip Survey}\label{\detokenize{Manual:id13}}\end{figure} \sphinxAtStartPar Currently, the local repository in Docker Desktop is empty. To proceed, we must upload the compiled image for Maxwell\sphinxhyphen{}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. \begin{figure}[htbp] \centering \capstart \noindent\sphinxincludegraphics[width=900\sphinxpxdimen]{{W13}.png} \caption{Image local Repository}\label{\detokenize{Manual:id14}}\end{figure} \newpage \subsection{Import Docker Image} \label{\detokenize{Manual:import-docker-image}} \sphinxAtStartPar 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. \sphinxAtStartPar In the designated working folder, you will find a zipped Docker image file and an “examples” folder containing user\sphinxhyphen{}defined data. \begin{figure}[htbp] \centering \capstart \noindent\sphinxincludegraphics[width=600\sphinxpxdimen]{{W14}.png} \caption{Location of Maxwell\sphinxhyphen{}TD Docker Image (Zipped)}\label{\detokenize{Manual:id15}}\end{figure} \sphinxAtStartPar To load the Docker image, execute the command \sphinxcode{\sphinxupquote{docker load \sphinxhyphen{}\sphinxhyphen{}input \textless{}PATH to zipped docker image\textgreater{}}}. This process will take some time, and you can verify its completion by using \sphinxcode{\sphinxupquote{docker images}} in the console. \begin{figure}[htbp] \centering \capstart \noindent\sphinxincludegraphics[width=1200\sphinxpxdimen]{{W16}.png} \caption{Load and check Docker Image}\label{\detokenize{Manual:id16}}\end{figure} \sphinxAtStartPar The loaded Docker image will also be visible both in Docker Desktop. \begin{figure}[htbp] \centering \capstart \noindent\sphinxincludegraphics[width=1200\sphinxpxdimen]{{W17}.png} \caption{Loaded Docker Image can be seen in Docker Desktop}\label{\detokenize{Manual:id17}}\end{figure} \subsection{Mounting User data and running Docker image} \label{\detokenize{Manual:mounting-user-data-and-running-docker-image}} \sphinxAtStartPar 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 \sphinxcode{\sphinxupquote{runDocker.ps1}} that can be executed in the console terminal. \sphinxAtStartPar To run the script and start the Docker image, follow these steps: \begin{enumerate} \sphinxsetlistlabels{\arabic}{enumi}{enumii}{}{.}% \item {} \sphinxAtStartPar \sphinxstylestrong{Open PowerShell as Administrator} \item {} \sphinxAtStartPar \sphinxstylestrong{Navigate to Script Directory:} Use the \sphinxcode{\sphinxupquote{cd}} command to navigate to the directory where \sphinxcode{\sphinxupquote{runDocker.ps1}} is located. \item {} \begin{description} \sphinxlineitem{\sphinxstylestrong{Execute the Script:}}\begin{itemize} \item {} \sphinxAtStartPar Run the script by typing \sphinxcode{\sphinxupquote{.\textbackslash{}runDocker.ps1}} and press \sphinxcode{\sphinxupquote{Enter}}. \item {} \sphinxAtStartPar The script will mount the folder containing user\sphinxhyphen{}defined data into the Docker Server environment. \end{itemize} \end{description} \end{enumerate} \begin{sphinxadmonition}{note}{Note:}\begin{itemize} \item {} \sphinxAtStartPar 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. \item {} \sphinxAtStartPar Treat the Docker image as a saved state of a customized environment. \end{itemize} \end{sphinxadmonition} \begin{figure}[htbp] \centering \capstart \noindent\sphinxincludegraphics[width=1200\sphinxpxdimen]{{W18}.png} \caption{Use PowerShell Script to run Docker Image}\label{\detokenize{Manual:id18}}\end{figure} \sphinxAtStartPar 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. \begin{itemize} \item {} \sphinxAtStartPar \sphinxstylestrong{\$imageName}: \end{itemize} \sphinxAtStartPar This variable defines the name of the Docker image that you want to run. In this case, it is set to \sphinxcode{\sphinxupquote{maxwell\_td\_image}}. Users should not change this variable if they intend to run Maxwell\sphinxhyphen{}TD. \begin{itemize} \item {} \sphinxAtStartPar \sphinxstylestrong{\$containerName}: \end{itemize} \sphinxAtStartPar 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. \begin{itemize} \item {} \sphinxAtStartPar \sphinxstylestrong{\$hostVolumePath}: \end{itemize} \sphinxAtStartPar 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. \begin{itemize} \item {} \sphinxAtStartPar \sphinxstylestrong{\$containerVolumePath}: \end{itemize} \sphinxAtStartPar This variable defines the path within the Docker container (running on Linux environment) where the host volume (\sphinxstylestrong{\$hostVolumePath}) will be mounted. In this script, it is set to \sphinxcode{\sphinxupquote{/dgtd/model/}}. It is recommended that users do not change this variable unless necessary, to ensure compatibility with the Docker image’s expected mount point. \begin{figure}[htbp] \centering \capstart \noindent\sphinxincludegraphics[width=1200\sphinxpxdimen]{{W20}.png} \caption{User\sphinxhyphen{}defined parameters to change location of User data}\label{\detokenize{Manual:id19}}\end{figure} \sphinxAtStartPar 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 \sphinxcode{\sphinxupquote{docker run \sphinxhyphen{}\sphinxhyphen{}rm \sphinxhyphen{}\sphinxhyphen{}gpus all \sphinxhyphen{}it \sphinxhyphen{}\sphinxhyphen{}name \$\{containerName\} \sphinxhyphen{}v \$\{hostVolumePath\}:\$\{containerVolumePath\} \$\{imageName\}}}. \begin{description} \sphinxlineitem{\sphinxstylestrong{Explanation of Docker Command Flags}}\begin{itemize} \item {} \sphinxAtStartPar \sphinxcode{\sphinxupquote{docker run}}: This command starts a new Docker container. \item {} \sphinxAtStartPar \sphinxcode{\sphinxupquote{\sphinxhyphen{}\sphinxhyphen{}rm}}: Automatically removes the container when it exits. Useful for temporary containers. \item {} \sphinxAtStartPar \sphinxcode{\sphinxupquote{\sphinxhyphen{}\sphinxhyphen{}gpus all}}: Enables access to all GPUs in the container. \item {} \sphinxAtStartPar \sphinxcode{\sphinxupquote{\sphinxhyphen{}it}}: Allocates a pseudo\sphinxhyphen{}TTY and keeps stdin open. Allows interactive terminal access. \item {} \sphinxAtStartPar \sphinxcode{\sphinxupquote{\sphinxhyphen{}\sphinxhyphen{}name \$\{containerName\}}}: Assigns a name to the container instance based on the value stored in the \sphinxcode{\sphinxupquote{\$containerName}} variable. \item {} \sphinxAtStartPar \sphinxcode{\sphinxupquote{\sphinxhyphen{}v \$\{hostVolumePath\}:\$\{containerVolumePath\}}}: Mounts a volume from the host machine (Windows) into the Docker container. \sphinxcode{\sphinxupquote{\$\{hostVolumePath\}}} is the path on the host system, and \sphinxcode{\sphinxupquote{\$\{containerVolumePath\}}} is the path inside the container where the volume will be mounted. \item {} \sphinxAtStartPar \sphinxcode{\sphinxupquote{\$\{imageName\}}}: Specifies the Docker image to use for creating the container. \end{itemize} \sphinxlineitem{\sphinxstylestrong{Additional Information}}\begin{itemize} \item {} \sphinxAtStartPar The \sphinxcode{\sphinxupquote{\sphinxhyphen{}\sphinxhyphen{}rm}} flag ensures that the container is automatically removed after it stops running, helping to manage resources efficiently. \item {} \sphinxAtStartPar \sphinxcode{\sphinxupquote{\sphinxhyphen{}\sphinxhyphen{}gpus all}} allows the Docker container to access all available GPUs on the host machine, which is crucial for applications that require GPU acceleration. \item {} \sphinxAtStartPar \sphinxcode{\sphinxupquote{\sphinxhyphen{}it}} enables interactive mode with a terminal session, which is useful for interacting directly with the container if needed. \end{itemize} \end{description} \sphinxAtStartPar This Docker command, when executed within the PowerShell script, sets up and runs the Docker container named \sphinxcode{\sphinxupquote{\$\{containerName\}}} with GPU support, mounts necessary volumes, and utilizes the specified Docker image \sphinxcode{\sphinxupquote{\$\{imageName\}}} for the Maxwell\sphinxhyphen{}TD application. Adjust \sphinxcode{\sphinxupquote{\$\{containerName\}}}, \sphinxcode{\sphinxupquote{\$\{hostVolumePath\}}}, \sphinxcode{\sphinxupquote{\$\{containerVolumePath\}}}, and \sphinxcode{\sphinxupquote{\$\{imageName\}}} as per your specific environment and requirements. \begin{figure}[htbp] \centering \capstart \noindent\sphinxincludegraphics[width=1200\sphinxpxdimen]{{W21}.png} \caption{Commands to run Docker image}\label{\detokenize{Manual:id20}}\end{figure} \begin{sphinxadmonition}{note}{Note:} \sphinxAtStartPar When opening a Windows text file in a Unix environment, extra \sphinxcode{\sphinxupquote{\textbackslash{}r}} characters at the end of each line can cause errors such as \sphinxcode{\sphinxupquote{/bin/bash\textasciicircum{}M: bad interpreter: No such file or directory}}. This is because Unix\sphinxhyphen{}based systems expect lines to end with \sphinxcode{\sphinxupquote{\textbackslash{}n}} (newline) instead of \sphinxcode{\sphinxupquote{\textbackslash{}r\textbackslash{}n}} (carriage return followed by newline) used in Windows. \sphinxAtStartPar To fix this issue, you can convert the line endings from Windows format to Unix format using utilities like \sphinxcode{\sphinxupquote{dos2unix}}, which removes the extra \sphinxcode{\sphinxupquote{\textbackslash{}r}} characters. Alternatively, you can use the included function \sphinxcode{\sphinxupquote{Remove\sphinxhyphen{}CarriageReturns}} in \sphinxcode{\sphinxupquote{runDocker.ps1}} to process the files. Once corrected, your script should execute correctly within Docker or any Unix\sphinxhyphen{}based environment without encountering interpreter errors. \end{sphinxadmonition} \begin{figure}[htbp] \centering \capstart \noindent\sphinxincludegraphics[width=1200\sphinxpxdimen]{{W19}.png} \caption{Miscellaneous function to treat textfiles from Windows System (Optional)}\label{\detokenize{Manual:id21}}\end{figure} \sphinxAtStartPar To run the script, navigate to the directory where \sphinxcode{\sphinxupquote{runDocker.ps1}} is located and execute \sphinxcode{\sphinxupquote{./runDocker.ps1}}. The script will display the CUDA toolkit version and open a BASH shell in the Docker container with \sphinxcode{\sphinxupquote{maxwell\_td\_image}}. This environment simulates a Linux environment. \begin{figure}[htbp] \centering \capstart \noindent\sphinxincludegraphics[width=1200\sphinxpxdimen]{{W27}.png} \caption{Running PowerShell Script}\label{\detokenize{Manual:id22}}\end{figure} \subsection{How to use Maxwell\sphinxhyphen{}TD} \label{\detokenize{Manual:how-to-use-maxwell-td}} \sphinxAtStartPar Upon starting the Docker container, you will be in the \sphinxcode{\sphinxupquote{/dgtd/}} directory, where the Discontinuous Galerkin Time\sphinxhyphen{}Domain (DGTD) code is located. The compiled code can be found in the \sphinxcode{\sphinxupquote{/dgtd/build/}} directory, with the executables named \sphinxcode{\sphinxupquote{maxwelltd\_CUDA\_LTS\_DOUBLEpre\_FLOATpro}} and \sphinxcode{\sphinxupquote{maxwelltd\_CUDA\_LTS\_DOUBLEpre\_FLOATpro\sphinxhyphen{}}}. User data, mounted from the Windows filesystem, is available in the \sphinxcode{\sphinxupquote{/dgtd/model/}} directory. Before running the simulation, the compiled executable must be copied to the simulation folder (\sphinxcode{\sphinxupquote{/dgtd/model/MaxwellTD\_data/}}). This can be done by executing the following command: \begin{sphinxVerbatim}[commandchars=\\\{\}] cp /dgtd/build/maxwelltd\PYGZus{}CUDA\PYGZus{}LTS\PYGZus{}DOUBLEpre\PYGZus{}FLOATpro* /dgtd/model/MaxwellTD\PYGZus{}data/ \end{sphinxVerbatim} \begin{figure}[htbp] \centering \capstart \noindent\sphinxincludegraphics[width=1200\sphinxpxdimen]{{W29}.png} \caption{Local Directory in Docker Image}\label{\detokenize{Manual:id23}}\end{figure} \sphinxAtStartPar Simulation files for the MaxwellTD model are located in the directory \sphinxcode{\sphinxupquote{/dgtd/model/MaxwellTD\_data}}. Additionally, we have included CST reference data for the same simulation model in the folder \sphinxcode{\sphinxupquote{CST\_data}}. A Python script named \sphinxcode{\sphinxupquote{compare\_maxwelltd\_CST.py}} has been provided to facilitate extraction and comparison of data between the DGTD simulation and CST data. \begin{figure}[htbp] \centering \capstart \noindent\sphinxincludegraphics[width=1200\sphinxpxdimen]{{W31a}.png} \caption{Simulation folder}\label{\detokenize{Manual:id24}}\end{figure} \sphinxAtStartPar To run the DGTD simulation, we can navigate to \sphinxcode{\sphinxupquote{/dgtd/model/MaxwellTD\_data/}} and run the shell script \sphinxcode{\sphinxupquote{CUDA\_LTS\_RUN.sh}}. \begin{sphinxVerbatim}[commandchars=\\\{\}] ./CUDA\PYGZus{}LTS\PYGZus{}RUN.sh \end{sphinxVerbatim} \begin{figure}[htbp] \centering \capstart \noindent\sphinxincludegraphics[width=1200\sphinxpxdimen]{{W45}.png} \caption{Running Simulation script}\label{\detokenize{Manual:id25}}\end{figure} \sphinxAtStartPar This will initiate the DGTD simulation. \begin{figure}[htbp] \centering \capstart \noindent\sphinxincludegraphics[width=1200\sphinxpxdimen]{{W46}.png} \caption{Simulating running}\label{\detokenize{Manual:id26}}\end{figure} \begin{figure}[htbp] \centering \capstart \noindent\sphinxincludegraphics[width=1200\sphinxpxdimen]{{W47}.png} \caption{End of simulation}\label{\detokenize{Manual:id27}}\end{figure} \sphinxAtStartPar Following the completion of the simulation, you can execute the Python script \sphinxcode{\sphinxupquote{compare\_maxwelltd\_CST.py}} to compare the results with those obtained from the CST simulation. \begin{sphinxVerbatim}[commandchars=\\\{\}] python3 compare\PYGZus{}maxwelltd\PYGZus{}CST.py \end{sphinxVerbatim} \begin{figure}[htbp] \centering \capstart \noindent\sphinxincludegraphics[width=1200\sphinxpxdimen]{{W49}.png} \caption{Running post\sphinxhyphen{}processing PYTHON script}\label{\detokenize{Manual:id28}}\end{figure} \chapter{Common issues} \label{\detokenize{Manual:common-issues}} \section{Incompatible GPU drivers/toolkit} \label{\detokenize{Manual:incompatible-gpu-drivers-toolkit}} \sphinxAtStartPar It’s essential to verify that your Windows device has the correct CUDA toolkit installed to run Maxwell\sphinxhyphen{}TD. You can check the CUDA toolkit version by using ‘nvidia\sphinxhyphen{}smi’ in the console terminal. The minimum required version to run Maxwell\sphinxhyphen{}TD is CUDA toolkit 12.4. \begin{figure}[htbp] \centering \capstart \noindent\sphinxincludegraphics[width=1200\sphinxpxdimen]{{W22}.png} \caption{Check CUDA toolkit version}\label{\detokenize{Manual:id29}}\end{figure} \sphinxAtStartPar If you need to update your CUDA toolkit, you can visit the \sphinxhref{https://developer.nvidia.com/cuda-toolkit}{NVIDIA website} (\sphinxurl{https://developer.nvidia.com/cuda-toolkit}). 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. \begin{figure}[htbp] \centering \capstart \noindent\sphinxincludegraphics[width=1200\sphinxpxdimen]{{W23}.png} \caption{NVIDIA website to download CUDA toolkit}\label{\detokenize{Manual:id30}}\end{figure} \begin{figure}[htbp] \centering \capstart \noindent\sphinxincludegraphics[width=1200\sphinxpxdimen]{{W24}.png} \caption{NVIDIA CUDA toolkit download}\label{\detokenize{Manual:id31}}\end{figure} \begin{figure}[htbp] \centering \capstart \noindent\sphinxincludegraphics[width=1200\sphinxpxdimen]{{W25}.png} \caption{NVIDIA CUDA toolkit (Latest version)}\label{\detokenize{Manual:id32}}\end{figure} \begin{figure}[htbp] \centering \capstart \noindent\sphinxincludegraphics[width=1200\sphinxpxdimen]{{W26}.png} \caption{NVIDIA CUDA toolkit (Earlier versions)}\label{\detokenize{Manual:id33}}\end{figure} \sphinxAtStartPar 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\sphinxhyphen{}TD and other CUDA\sphinxhyphen{}dependent applications can function correctly. \section{Windows Version} \label{\detokenize{Manual:windows-version}} \sphinxAtStartPar Make sure your Windows 10 or 11 system meets the following requirements: \begin{itemize} \item {} \sphinxAtStartPar \sphinxstylestrong{WSL Version:} Ensure WSL version 1.1.3.0 or newer. \item {} \sphinxAtStartPar \sphinxstylestrong{Windows 11:} 64\sphinxhyphen{}bit Home or Pro version 21H2 or later, or Enterprise or Education version 21H2 or later. \item {} \sphinxAtStartPar \sphinxstylestrong{Windows 10:} 64\sphinxhyphen{}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. \end{itemize} \begin{sphinxadmonition}{note}{Note:}\begin{itemize} \item {} \sphinxAtStartPar 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. \item {} \sphinxAtStartPar 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. \end{itemize} \end{sphinxadmonition} \section{Sufficient Memory to upload image} \label{\detokenize{Manual:sufficient-memory-to-upload-image}} \sphinxAtStartPar 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. \begin{figure}[htbp] \centering \capstart \noindent\sphinxincludegraphics[width=1200\sphinxpxdimen]{{W42}.png} \caption{View all containers or image on Docker Desktop}\label{\detokenize{Manual:id34}}\end{figure} \sphinxAtStartPar Users can remove any unwanted images or containers using the ‘delete’ button. \begin{figure}[htbp] \centering \capstart \noindent\sphinxincludegraphics[width=1200\sphinxpxdimen]{{W43}.png} \caption{Delete if not needed to free up space}\label{\detokenize{Manual:id35}}\end{figure} \sphinxAtStartPar If necessary, resort to command\sphinxhyphen{}line operations to reclaim system resources. Execute these commands in a PowerShell console with administrative privileges. \begin{sphinxVerbatim}[commandchars=\\\{\}] \PYG{c+c1}{\PYGZsh{} Purging All Unused or Dangling Resources} docker system prune \PYG{c+c1}{\PYGZsh{} Remove stopped containers and all unused images} docker system prune \PYGZhy{}a \PYG{c+c1}{\PYGZsh{} Removing Docker Images} \PYG{c+c1}{\PYGZsh{}\PYGZsh{} Remove Specific Images} \PYG{c+c1}{\PYGZsh{} List all images (including intermediate layers)} docker images \PYGZhy{}a \PYG{c+c1}{\PYGZsh{} Remove specific image(s) using their ID or tag} docker rmi \PYGZlt{}image\PYGZus{}id\PYGZus{}or\PYGZus{}name\PYGZgt{} \PYG{c+c1}{\PYGZsh{}\PYGZsh{} Remove Dangling Images} \PYG{c+c1}{\PYGZsh{} List dangling images} docker images \PYGZhy{}f \PYG{n+nv}{dangling}\PYG{o}{=}\PYG{n+nb}{true} \PYG{c+c1}{\PYGZsh{} Remove dangling images} docker image prune \PYG{c+c1}{\PYGZsh{}\PYGZsh{} Remove Images Matching a Pattern} \PYG{c+c1}{\PYGZsh{} List images matching a pattern (using grep)} docker images \PYGZhy{}a \PYG{p}{|} grep \PYG{l+s+s2}{\PYGZdq{}pattern\PYGZdq{}} \PYG{c+c1}{\PYGZsh{} Remove images matching a pattern using awk and xargs} docker images \PYGZhy{}a \PYG{p}{|} grep \PYG{l+s+s2}{\PYGZdq{}pattern\PYGZdq{}} \PYG{p}{|} awk \PYG{l+s+s1}{\PYGZsq{}\PYGZob{}print \PYGZdl{}1\PYGZdq{}:\PYGZdq{}\PYGZdl{}2\PYGZcb{}\PYGZsq{}} \PYG{p}{|} xargs docker rmi \PYG{c+c1}{\PYGZsh{}\PYGZsh{} Remove All Images} \PYG{c+c1}{\PYGZsh{} Remove all Docker images} docker rmi \PYG{k}{\PYGZdl{}(}docker images \PYGZhy{}a \PYGZhy{}q\PYG{k}{)} \PYG{c+c1}{\PYGZsh{} Removing Containers} \PYG{c+c1}{\PYGZsh{}\PYGZsh{} Remove Specific Containers} \PYG{c+c1}{\PYGZsh{} List all containers (including stopped ones)} docker ps \PYGZhy{}a \PYG{c+c1}{\PYGZsh{} Remove specific container(s)} docker rm \PYGZlt{}container\PYGZus{}id\PYGZus{}or\PYGZus{}name\PYGZgt{} \PYG{c+c1}{\PYGZsh{}\PYGZsh{} Remove All Exited Containers} \PYG{c+c1}{\PYGZsh{} List all exited containers} docker ps \PYGZhy{}a \PYGZhy{}f \PYG{n+nv}{status}\PYG{o}{=}exited \PYG{c+c1}{\PYGZsh{} Remove all exited containers} docker rm \PYG{k}{\PYGZdl{}(}docker ps \PYGZhy{}a \PYGZhy{}f \PYG{n+nv}{status}\PYG{o}{=}exited \PYGZhy{}q\PYG{k}{)} \PYG{c+c1}{\PYGZsh{}\PYGZsh{} Remove Containers Matching a Pattern} \PYG{c+c1}{\PYGZsh{} List containers matching a pattern (using grep)} docker ps \PYGZhy{}a \PYG{p}{|} grep \PYG{l+s+s2}{\PYGZdq{}pattern\PYGZdq{}} \PYG{c+c1}{\PYGZsh{} Remove containers matching a pattern using awk and xargs} docker ps \PYGZhy{}a \PYG{p}{|} grep \PYG{l+s+s2}{\PYGZdq{}pattern\PYGZdq{}} \PYG{p}{|} awk \PYG{l+s+s1}{\PYGZsq{}\PYGZob{}print \PYGZdl{}1\PYGZcb{}\PYGZsq{}} \PYG{p}{|} xargs docker rm \PYG{c+c1}{\PYGZsh{}\PYGZsh{} Stop and Remove All Containers} \PYG{c+c1}{\PYGZsh{} Stop all containers} docker stop \PYG{k}{\PYGZdl{}(}docker ps \PYGZhy{}a \PYGZhy{}q\PYG{k}{)} \PYG{c+c1}{\PYGZsh{} Remove all containers} docker rm \PYG{k}{\PYGZdl{}(}docker ps \PYGZhy{}a \PYGZhy{}q\PYG{k}{)} \end{sphinxVerbatim} \section{BIOS settings} \label{\detokenize{Manual:bios-settings}} \sphinxAtStartPar 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. \section{Change Simulation Parameters} \label{\detokenize{Manual:change-simulation-parameters}} \sphinxAtStartPar To modify simulation parameters, you can edit the \sphinxcode{\sphinxupquote{CUDA\_LTS\_RUN.sh}} 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. \begin{sphinxVerbatim}[commandchars=\\\{\}] \PYG{n+nb}{echo} \PYG{l+s+s2}{\PYGZdq{}===========\PYGZdq{}} \PYG{n+nb}{echo} \PYG{l+s+s2}{\PYGZdq{}EXECUTABLE\PYGZdq{}} \PYG{n+nv}{EXE}\PYG{o}{=}\PYG{l+s+s2}{\PYGZdq{}./maxwelltd\PYGZus{}CUDA\PYGZus{}LTS\PYGZus{}DOUBLEpre\PYGZus{}FLOATpro\PYGZdq{}} \PYG{n+nb}{echo} \PYG{n+nv}{\PYGZdl{}EXE} \PYG{n+nb}{echo} \PYG{l+s+s2}{\PYGZdq{}FileName\PYGZdq{}} \PYG{n+nb}{echo} \PYG{l+s+s2}{\PYGZdq{}===========\PYGZdq{}} \PYG{c+c1}{\PYGZsh{} 0. [EXE]} \PYG{c+c1}{\PYGZsh{} 1. Filename: Simulation Filename} \PYG{c+c1}{\PYGZsh{} 2. Freq: Central Modulation Frequency (MHz)} \PYG{c+c1}{\PYGZsh{} 3. Planewave Waveform (Excitation Type): (0)Time Harmonic (1)Gauss (2)Neumann (3) Modulated Gauss;} \PYG{c+c1}{\PYGZsh{} 4. Port Waveform (0) Time Harmonic Pulse (1) Gaussian Pulse} \PYG{c+c1}{\PYGZsh{} 5. Tdelay: Delay of excitation pulse (sec)} \PYG{c+c1}{\PYGZsh{} 6. Tau: Width of pulse (sec)} \PYG{c+c1}{\PYGZsh{} 7. FinalTime: Termination Time (sec)} \PYG{c+c1}{\PYGZsh{} 8. Gamma (Penalty) \PYGZhy{}\PYGZhy{}\PYGZgt{} 1 upwind , 0 central} \PYG{c+c1}{\PYGZsh{} 9. VTU \PYGZhy{}\PYGZhy{}\PYGZgt{} 0 (YES), 1 (NO)} \PYG{c+c1}{\PYGZsh{}10. Surface Field Output BC Surfaces \PYGZhy{}\PYGZhy{}\PYGZgt{} (0) Off (1) PEC only (2) FieldPlane only (3) FieldPlane and PEC} \PYG{c+c1}{\PYGZsh{}11. Surface Output Types \PYGZhy{}\PYGZhy{}\PYGZgt{} (0) Field (1) Current (2) Field and Current} \PYG{c+c1}{\PYGZsh{}12. Poly order \PYGZhy{}\PYGZhy{}\PYGZgt{} (1) First Order (2) Second Order} \PYG{c+c1}{\PYGZsh{}13. Free Space Comparison(Analytical): (0) True and (1) False} \PYG{c+c1}{\PYGZsh{}14. SAMPLINGRATE : parameter of Pade approximation} \PYG{c+c1}{\PYGZsh{}15. PADE : (0) Pade mode is Off (2) Pade mode is on} \PYG{n+nv}{FILENAME}\PYG{o}{=}cylinder\PYGZus{}cr1.75 \PYG{n+nv}{FREQ}\PYG{o}{=}\PYG{l+m}{2650} \PYG{n+nv}{PLANEWAVEFLAG}\PYG{o}{=}\PYG{l+m}{1} \PYG{n+nv}{PORTFLAG}\PYG{o}{=}\PYG{l+m}{1} \PYG{n+nv}{TD}\PYG{o}{=}\PYG{l+m}{2}.5e\PYGZhy{}9 \PYG{n+nv}{TAU}\PYG{o}{=}\PYG{l+m}{2}.5e\PYGZhy{}10 \PYG{n+nv}{FINALTIME}\PYG{o}{=}25e\PYGZhy{}8 \PYG{n+nv}{GAMMA}\PYG{o}{=}\PYG{l+m}{0}.025 \PYG{n+nv}{VTU}\PYG{o}{=}\PYG{l+m}{1} \PYG{n+nv}{SURFFIELDOUTBCSURFS}\PYG{o}{=}\PYG{l+m}{0} \PYG{n+nv}{SURFOUTTYPES}\PYG{o}{=}\PYG{l+m}{0} \PYG{n+nv}{POLYORDER}\PYG{o}{=}\PYG{l+m}{2} \PYG{n+nv}{ANALYTICAL}\PYG{o}{=}\PYG{l+m}{1} \PYG{n+nv}{SAMPLINGRATE}\PYG{o}{=}\PYG{l+m}{12}.5 \PYG{n+nv}{PADE}\PYG{o}{=}\PYG{l+m}{2} rm *.log rm *.vtu rm AnalyticalIncidentField* rm Probes\PYGZus{}* rm *.TD* rm \PYGZhy{}r ./TimeDomainVoltages \PYG{n+nv}{\PYGZdl{}EXE} \PYG{n+nv}{\PYGZdl{}FILENAME} \PYG{n+nv}{\PYGZdl{}FREQ} \PYG{n+nv}{\PYGZdl{}PLANEWAVEFLAG} \PYG{n+nv}{\PYGZdl{}PORTFLAG} \PYG{n+nv}{\PYGZdl{}TD} \PYG{n+nv}{\PYGZdl{}TAU} \PYG{n+nv}{\PYGZdl{}FINALTIME} \PYG{n+nv}{\PYGZdl{}GAMMA} \PYG{n+nv}{\PYGZdl{}VTU} \PYG{n+nv}{\PYGZdl{}SURFFIELDOUTBCSURFS} \PYG{n+nv}{\PYGZdl{}SURFOUTTYPES} \PYG{n+nv}{\PYGZdl{}POLYORDER} \PYG{n+nv}{\PYGZdl{}ANALYTICAL} \PYG{n+nv}{\PYGZdl{}SAMPLINGRATE} \PYG{n+nv}{\PYGZdl{}PADE} \PYG{p}{|} tee \PYGZhy{}a compute.log rm \PYGZhy{}r ./VTU\PYGZus{}LTS mkdir ./VTU\PYGZus{}LTS mv *.vtu ./VTU\PYGZus{}LTS rm \PYGZhy{}r ./PROBES mkdir ./PROBES mv *.csv ./PROBES mv *.TD* ./PROBES mv *.log ./PROBES \end{sphinxVerbatim} \renewcommand{\indexname}{Index} \printindex \end{document}