From c5c966720d91b6e1bea797ca3c29c23126773e1e Mon Sep 17 00:00:00 2001 From: rzommers Date: Mon, 2 Dec 2024 17:26:21 -0500 Subject: [PATCH 01/42] Create .readthedocs.yaml --- .readthedocs.yaml | 14 ++++++++++++++ 1 file changed, 14 insertions(+) create mode 100644 .readthedocs.yaml diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 00000000..3cbb61e9 --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,14 @@ +version: "2" + +build: + os: "ubuntu-22.04" + tools: + python: "3.10" + +python: + install: + - requirements: rtd/docs/requirements.txt + +sphinx: + configuration: rtd/docs/source/conf.py + fail_on_warning: false From 291a7d9a9303b346ec9f435865df10df1be18f85 Mon Sep 17 00:00:00 2001 From: rzommers Date: Mon, 2 Dec 2024 17:27:15 -0500 Subject: [PATCH 02/42] Update .readthedocs.yaml Fixed path --- .readthedocs.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 3cbb61e9..3c72076d 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -7,8 +7,8 @@ build: python: install: - - requirements: rtd/docs/requirements.txt + - requirements: rtd/requirements.txt sphinx: - configuration: rtd/docs/source/conf.py + configuration: rtd/source/conf.py fail_on_warning: false From 76ccd6d850598f4af5e926e561d74a588b5d6673 Mon Sep 17 00:00:00 2001 From: rzommers Date: Mon, 2 Dec 2024 17:27:58 -0500 Subject: [PATCH 03/42] Create Makefile --- rtd/Makefile | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) create mode 100644 rtd/Makefile diff --git a/rtd/Makefile b/rtd/Makefile new file mode 100644 index 00000000..d0c3cbf1 --- /dev/null +++ b/rtd/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) From 289eadd936f18dc643a306a0ff4e14f744eb8399 Mon Sep 17 00:00:00 2001 From: rzommers Date: Mon, 2 Dec 2024 17:28:21 -0500 Subject: [PATCH 04/42] Create make.bat --- rtd/make.bat | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) create mode 100644 rtd/make.bat diff --git a/rtd/make.bat b/rtd/make.bat new file mode 100644 index 00000000..9534b018 --- /dev/null +++ b/rtd/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=build + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd From 70266ac0c4295eb53396b2ebf9748bc3241fdf67 Mon Sep 17 00:00:00 2001 From: rzommers Date: Mon, 2 Dec 2024 17:28:44 -0500 Subject: [PATCH 05/42] Create requirements.txt --- rtd/requirements.txt | 4 ++++ 1 file changed, 4 insertions(+) create mode 100644 rtd/requirements.txt diff --git a/rtd/requirements.txt b/rtd/requirements.txt new file mode 100644 index 00000000..22131894 --- /dev/null +++ b/rtd/requirements.txt @@ -0,0 +1,4 @@ +sphinx==8.1.3 +sphinx-rtd-theme==3.0.1 +markdown-it-py==3.0.0 +myst-parser==4.0.0 From 8a261345ad7e5033899bf07ceb14f5eb0916932f Mon Sep 17 00:00:00 2001 From: rzommers Date: Mon, 2 Dec 2024 17:29:12 -0500 Subject: [PATCH 06/42] Create conf.py --- rtd/source/conf.py | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) create mode 100644 rtd/source/conf.py diff --git a/rtd/source/conf.py b/rtd/source/conf.py new file mode 100644 index 00000000..3655b091 --- /dev/null +++ b/rtd/source/conf.py @@ -0,0 +1,36 @@ +# Configuration file for the Sphinx documentation builder. + +# -- Project information + +project = 'Test-rtd' +copyright = 'TBA' +author = 'TBA' + +release = '0.1' +version = '0.1.0' + +# -- General configuration + +extensions = [ + 'sphinx.ext.duration', + 'sphinx.ext.doctest', + 'sphinx.ext.autodoc', + 'sphinx.ext.autosummary', + 'sphinx.ext.intersphinx', + "myst_parser", +] + +intersphinx_mapping = { + 'python': ('https://docs.python.org/3/', None), + 'sphinx': ('https://www.sphinx-doc.org/en/master/', None), +} +intersphinx_disabled_domains = ['std'] + +templates_path = ['_templates'] + +# -- Options for HTML output + +html_theme = 'sphinx_rtd_theme' + +# -- Options for EPUB output +epub_show_urls = 'footnote' From b7c7e6c8c9fd41d509b614d7d154cd32fea37feb Mon Sep 17 00:00:00 2001 From: rzommers Date: Mon, 2 Dec 2024 17:29:43 -0500 Subject: [PATCH 07/42] Create index.md --- rtd/source/index.md | 262 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 262 insertions(+) create mode 100644 rtd/source/index.md diff --git a/rtd/source/index.md b/rtd/source/index.md new file mode 100644 index 00000000..0064e5e6 --- /dev/null +++ b/rtd/source/index.md @@ -0,0 +1,262 @@ +# User Guide for MISO + +This guide explains in a step-by-step approach the recommended way to install the MISO software library. + +## Windows Subsystem for Linux (WSL) + +A Linux OS must be used to access the provided tools. If you are already running on a Linux OS (Ubuntu, Fedora, etc.), skip this step, and continue with installing OpenMPI and System Packages. If you are running on a Windows OS, one available option to access this content is by using a Linux simulator, for example, WSL. Note that the code blocks in this guide assume that Ubuntu is being used, so certain steps may be different on other platforms. + +[Installation Process] + +## OpenMPI and System Packages + +OpenMPI is a software package that is an implementation of the Message Passing Interface (MPI) standard that is required for a parallel build of MFEM. Alternatives exist, such as MPICH, but OpenMPI is the recommended MPI implementation. MPI is required for MISO. + +In addition to MISO, it is highly recommended to install gcc, which is a collection of compilers, and cmake, which is a build system generator. Alternatives exist for both of these installations, but this guide will use these choices. + +To download these packages, you must be on an administrator account. Use the following lines of code in the terminal to download the packages: + +``` +sudo apt install gcc +sudo apt install cmake +sudo apt install git +sudo apt-get install openmpi-bin openmpi-doc libopenmpi-dev +``` + +[Add info on connecting openmpi on WSL] + +## MFEM Prerequisites + +Two dependencies are required in order to build the MFEM library, used for finite element discretization: HYPRE and METIS. + +### HYPRE + +To download the HYPRE package, follow the below steps: +1. Go to [HYPRE GitHub](https://github.com/hypre-space/hypre) +2. Download version 2.28.0 (this is NOT the current version; go to the "Releases" section to see past versions) +3. Unzip the folder and extract it to [path_to_motor_folder]/Dependencies +4. Additional information can be found in the README.md and INSTALL.md files for configuration and installation + +Enter the terminal and navigate to the motor folder. Use the following lines of code to configure and install HYPRE. + +``` +cd Dependencies/hypre/src +./configure +cd cmbuild +cmake .. -DCMAKE_POSITION_INDEPENDENT_CODE=ON -DHYPRE_INSTALL_PREFIX="[path_to_motor_folder]/Installations/hypre" -DHYPRE_ENABLE_SHARED=ON +make install +cd ../../.. +export PATH=$PATH:[path_to_motor_folder]/Installations/hypre +``` + +Note that EVERY "export" statement must be repeated upon each PC reboot, if MISO needs to be used. + +### METIS + +The official METIS website can be unreliable, so its recommended to use the GitHub page linked from MFEM that has some relevant versions for using with MFEM. + +To download the METIS package, follow the below steps: +1. Go to [Metis-MFEM GitHub](https://github.com/mfem/tpls) +2. Download the default package +3. Unzip the folder and enter it +4. Unzip the metis-5.1.0 folder and extract it to [path_to_motor_folder]/Dependencies + +Enter the terminal and navigate to the motor folder. Use the following lines of code to configure and install METIS. + +``` +cd Dependencies/metis +make config shared=1 cc=gcc prefix=[path_to_motor_folder]/Installations/metis +make -j 4 +make install +cd ../.. +export PATH=$PATH:[path_to_motor_folder]/Installations/metis +``` + +## PUMI (additional mesh tool) + +PUMI is a library that is optional for standalone MFEM, but is required for certain MISO tests. This project uses the CORE package, which is a modification of PUMI and serves the same purpose. EngineeringSketchPad (ESP) is a dependency for CORE, and OpenCASCADE is in turn a requirement for ESP. + +### OpenCASCADE + +[Specific folder, check for alternatives] +[Figure out how to attach file to RTD] +[Alternative: possibility of downloading directly from site?] + +### ESP + +Enter the terminal and navigate to the motor folder. Use the following lines of code to download, configure, and install ESP. + +``` +cd Dependencies +git clone https://github.com/tuckerbabcock/EngSketchPad.git +cd EngSketchPad +git checkout 8a5ca2bd6fbed747d371eb926e8a24d0cfcda087 +cd config +./makeEnv /[path_to_motor_folder]/Installations/OpenCASCADE +cd .. +source ESPenv.sh +cd src +make +cd ../../.. +``` + +In addition to every "export" statement, the following command must be repeated upon each PC reboot, if MISO needs to be used: + +``` +source [path_to_motor_folder]/Dependencies/EngSketchPad/ESPenv.sh +``` + +### CORE (PUMI) + +A configuration file is highly recommended to be used with cmake to more specifically configure the build of CORE. This file can be made using the "cat" command in the terminal, or made using a text editor. The "cat" command can be used in the following way: + +``` +cat >> config_core.sh +# Write line-by-line code for the file +# Use CTRL-Z to stop command +``` + +The below file name and code block are recommended for this configuration file. + +#### config_core.sh + +``` +cmake .. \ + -DCMAKE_C_COMPILER="MPICC" \ + -DCMAKE_CXX_COMPILER="MPICXX" \ + -DCMAKE_INSTALL_PREFIX="/[path_to_motor_folder]/Installations/core" \ + -DBUILD_SHARED_LIBS=ON \ + -DSCOREC_CXX_OPTIMIZE=ON \ + -DSCOREC_CXX_SYMBOLS=ON \ + -DSCOREC_CXX_WARNINGS=OFF \ + -DSCOREC_EXTRA_CXX_FLAGS="-Wextra -Wall" \ + -DENABLE_ZOLTAN=OFF \ + -DENABLE_EGADS=ON \ + -DPUMI_USE_EGADSLITE=OFF \ + -DIS_TESTING=OFF \ +``` + +#### Terminal Code + +``` +cd Dependencies +git clone https://github.com/tuckerbabcock/core.git +cd core +git checkout egads-dev +mkdir build +cd build +# make config_core.sh (see above) or move file into build folder +source config_core.sh +make -j 4 +make install +cd ../../.. +export PATH=$PATH:/[path_to_motor_folder]/Installations/core +``` + +## Building MFEM + +Once HYPRE, METIS, and CORE have been successfully installed, MFEM can now be built. For more information on the package, see the [MFEM Website](https://mfem.org/building/). You can also go to their [GitHub](https://github.com/mfem/mfem) and inspect the README.md and INSTALL.md files. + +A configuration file is highly recommended to be used with cmake to more specifically configure the build of MFEM. + +#### config_mfem.sh + +``` +cmake .. \ + -DCMAKE_CXX_COMPILER="MPICXX" \ + -DCMAKE_BUILD_TYPE=Debug \ + -DCMAKE_INSTALL_PREFIX="/[path_to_motor_folder]/Installations/mfem" \ + -DBUILD_SHARED_LIBS=ON \ + -DMFEM_DEBUG=ON \ + -DMFEM_USE_MPI=ON \ + -DMFEM_USE_METIS=ON \ + -DMFEM_USE_METIS_5=ON \ + -DMFEM_USE_PUMI=ON \ + -DPUMI_DIR="/[path_to_motor_folder]/Installations/core" \ + -DMFEM_ENABLE_EXAMPLES=OFF \ + -DMFEM_ENABLE_MINIAPPS=OFF \ +``` + +#### Terminal Code + +``` +cd Dependencies +git clone https://github.com/mfem/mfem.git +cd mfem +git checkout odl +mkdir build +cd build +# make config_mfem.sh (see above) or move file into build folder +source config_mfem.sh +make -j 4 +make install +make examples -j 4 +make test +cd ../../.. +export PATH=$PATH:/[path_to_motor_folder]/Installations/mfem +``` + +It is not required to run the "make examples" and "make test" commands. If you decide to run the tests, a number of them should fail, as they are only built when the "MFEM_ENABLE_MINIAPPS" option is enabled. These modules are not used by MISO and lengthen the installation process, so it is not recommended to build them. + +## MISO + +MISO is the main library used to make finite element simulations, and is based on MFEM. One additional dependency, ADEPT, used for automatic differentiation, is required before the build process can begin. + +### ADEPT + +To download the ADEPT package, follow the below steps: +1. Go to [ADEPT Website](https://www.met.reading.ac.uk/clouds/adept/download.html) +2. Download version 2.1 (this is NOT the most recent version; version 2.1.1 may be compatible but has not been tested) +3. Unzip the folder and extract it to [path_to_motor_folder]/Dependencies + +Enter the terminal and navigate to the motor folder. Use the following lines of code to configure and install ADEPT. + +``` +cd Dependencies/adept +./configure --prefix="/[path_to_motor_folder]/Installations/adept +make +make install +cd ../.. +export PATH=$PATH:/[path_to_motor_folder]/Installations/adept +``` + +### Building MISO + +Once MFEM and ADEPT have been successfully installed, MISO can now be built. For more information on the package, go to the [GitHub](https://github.com/OptimalDesignLab/MISO) and inspect the README.md file. + +A configuration file is highly recommended to be used with cmake to more specifically configure the build of MISO. + +#### config_miso.sh + +``` +cmake .. \ + -DCMAKE_C_COMPILER="MPICC" \ + -DCMAKE_CXX_COMPILER="MPICXX" \ + -DCMAKE_BUILD_TYPE=Debug \ + -DMFEM_DIR="/[path_to_motor_folder]/Dependencies/mfem" \ + -DAdept_ROOT="/[path_to_motor_folder]/Installations/adept" \ + -DPUMI_DIR="/[path_to_motor_folder]/Installations/core" \ + -DBUILD_SHARED_LIBS=OFF \ + -DBUILD_TESTING=ON \ + -DCMAKE_EXPORT_COMPILE_COMMANDS=ON \ +``` + +#### Terminal Code + +``` +git clone https://github.com/OptimalDesignLab/MISO.git +cd MISO +git checkout dev +mkdir build +cd build +# make config_miso.sh (see above) or move file into build folder +source config_miso.sh +make -j 4 +make install +make tests +cd ../.. +``` + +The "make tests" command is expected to take a long time to complete. If any of the 57 tests results in a failure, it is most likely a problem with a dependency. It is also possible that you are running an outdated version of MISO, which may be rectified by navigating to the MISO folder and running the "git submodule update" command + +At this point, MISO has been fully installed and may be used for projects. From 266a7cc3c79823807b2298c85e0b2566111ac835 Mon Sep 17 00:00:00 2001 From: rzommers Date: Tue, 3 Dec 2024 11:47:50 -0500 Subject: [PATCH 08/42] Update conf.py Corrected project title --- rtd/source/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rtd/source/conf.py b/rtd/source/conf.py index 3655b091..9d02c579 100644 --- a/rtd/source/conf.py +++ b/rtd/source/conf.py @@ -2,7 +2,7 @@ # -- Project information -project = 'Test-rtd' +project = 'MISO Setup' copyright = 'TBA' author = 'TBA' From cdca34dd940bd19fac45cddee9d9bb683552a9c9 Mon Sep 17 00:00:00 2001 From: rzommers Date: Tue, 3 Dec 2024 15:24:56 -0500 Subject: [PATCH 09/42] Update index.md Updated WSL and OpenMPI information --- rtd/source/index.md | 60 +++++++++++++++++++++++++++++++++++++-------- 1 file changed, 50 insertions(+), 10 deletions(-) diff --git a/rtd/source/index.md b/rtd/source/index.md index 0064e5e6..733e7a22 100644 --- a/rtd/source/index.md +++ b/rtd/source/index.md @@ -6,13 +6,36 @@ This guide explains in a step-by-step approach the recommended way to install th A Linux OS must be used to access the provided tools. If you are already running on a Linux OS (Ubuntu, Fedora, etc.), skip this step, and continue with installing OpenMPI and System Packages. If you are running on a Windows OS, one available option to access this content is by using a Linux simulator, for example, WSL. Note that the code blocks in this guide assume that Ubuntu is being used, so certain steps may be different on other platforms. -[Installation Process] +To install WSL, enter the terminal (on Windows, you can use "windows_key + r" and type in "cmd" to the prompt to open the terminal) and enter the following line of code: + +``` +wsl --install +``` + +Accept all permissions on the popups and allow WSL to be installed. Once finished, you will be asked to enter a username and password. This will be your Linux administrator account, and the password will be needed to be used for all "sudo" commands to install required system packages. + +Start up a new Ubuntu (Linux) terminal by selecting the dropdown arrow and choosing "Ubuntu". The default directory is "/home/[username]". From this point, use the command: + +``` +mkdir motor +``` + +to create a folder for all downloads. Below is a list of basic Linux commands to navigate between folders: + +``` +explorer.exe . # open file explorer +ls # display folders and files within current directory +cd [folder] # enter a folder within the current directory +cd .. # exit current directory to its container folder +cd # navigate to /home/[username] +cd / # navigate to / +``` ## OpenMPI and System Packages OpenMPI is a software package that is an implementation of the Message Passing Interface (MPI) standard that is required for a parallel build of MFEM. Alternatives exist, such as MPICH, but OpenMPI is the recommended MPI implementation. MPI is required for MISO. -In addition to MISO, it is highly recommended to install gcc, which is a collection of compilers, and cmake, which is a build system generator. Alternatives exist for both of these installations, but this guide will use these choices. +In addition to MISO, it is highly recommended to install gcc, which is a collection of compilers, and cmake, which is a build system generator. Alternatives exist for both of these installations, but this guide will use these choices. git and build-essential are mandatory packages, and while build-essential may be installed by default, you should confirm its presence before proceeding. To download these packages, you must be on an administrator account. Use the following lines of code in the terminal to download the packages: @@ -20,10 +43,24 @@ To download these packages, you must be on an administrator account. Use the fol sudo apt install gcc sudo apt install cmake sudo apt install git -sudo apt-get install openmpi-bin openmpi-doc libopenmpi-dev +sudo apt install build-essential +sudo apt install openmpi-bin openmpi-doc libopenmpi-dev +``` + +For OpenMPI (or any MPI package) to be used, it must be able to be found on the PC's path. To confirm that OpenMPI has been successfully installed and can be used, enter the terminal and use the following lines of code: + +``` +which mpicc +which mpicxx ``` -[Add info on connecting openmpi on WSL] +After each command, a directory should be listed that holds these particular executables. If these files can not be found, then they need to be added to your path. Enter the file explorer and search for "mpicc". The file, along with mpicxx and others, should be in a "bin" directory". Add this directory as a Path variable by using the following code: + +``` +export PATH=$PATH:[path_to_mpi_container_directory] +``` + +This command MUST be repeated whenever a new command prompt is opened, as an export statement is not permanent. Every export command throughout this process must be repeated when that particular installation needs to be used. ## MFEM Prerequisites @@ -35,17 +72,20 @@ To download the HYPRE package, follow the below steps: 1. Go to [HYPRE GitHub](https://github.com/hypre-space/hypre) 2. Download version 2.28.0 (this is NOT the current version; go to the "Releases" section to see past versions) 3. Unzip the folder and extract it to [path_to_motor_folder]/Dependencies + Note that the default browser download is to Windows. Drag and drop the extracted files in file explorer to copy them from Windows over to Linux 4. Additional information can be found in the README.md and INSTALL.md files for configuration and installation Enter the terminal and navigate to the motor folder. Use the following lines of code to configure and install HYPRE. ``` -cd Dependencies/hypre/src +cd Dependencies/hypre-2.28.0/src./ ./configure + # If this comes back as an error, use the following line of code then repeat ./configure + chmod +x configure cd cmbuild cmake .. -DCMAKE_POSITION_INDEPENDENT_CODE=ON -DHYPRE_INSTALL_PREFIX="[path_to_motor_folder]/Installations/hypre" -DHYPRE_ENABLE_SHARED=ON make install -cd ../../.. +cd ../../../.. export PATH=$PATH:[path_to_motor_folder]/Installations/hypre ``` @@ -64,7 +104,7 @@ To download the METIS package, follow the below steps: Enter the terminal and navigate to the motor folder. Use the following lines of code to configure and install METIS. ``` -cd Dependencies/metis +cd Dependencies/metis-5.1.0 make config shared=1 cc=gcc prefix=[path_to_motor_folder]/Installations/metis make -j 4 make install @@ -133,7 +173,7 @@ cmake .. \ -DENABLE_ZOLTAN=OFF \ -DENABLE_EGADS=ON \ -DPUMI_USE_EGADSLITE=OFF \ - -DIS_TESTING=OFF \ + -DIS_TESTING=OFF ``` #### Terminal Code @@ -174,7 +214,7 @@ cmake .. \ -DMFEM_USE_PUMI=ON \ -DPUMI_DIR="/[path_to_motor_folder]/Installations/core" \ -DMFEM_ENABLE_EXAMPLES=OFF \ - -DMFEM_ENABLE_MINIAPPS=OFF \ + -DMFEM_ENABLE_MINIAPPS=OFF ``` #### Terminal Code @@ -238,7 +278,7 @@ cmake .. \ -DPUMI_DIR="/[path_to_motor_folder]/Installations/core" \ -DBUILD_SHARED_LIBS=OFF \ -DBUILD_TESTING=ON \ - -DCMAKE_EXPORT_COMPILE_COMMANDS=ON \ + -DCMAKE_EXPORT_COMPILE_COMMANDS=ON ``` #### Terminal Code From 4cd4398022adc02487078f98d620629cca136936 Mon Sep 17 00:00:00 2001 From: rzommers Date: Mon, 16 Dec 2024 14:52:45 -0500 Subject: [PATCH 10/42] Update index.md Edited for clarity --- rtd/source/index.md | 40 ++++++++++++++++++++++++++++------------ 1 file changed, 28 insertions(+), 12 deletions(-) diff --git a/rtd/source/index.md b/rtd/source/index.md index 733e7a22..ddda2df2 100644 --- a/rtd/source/index.md +++ b/rtd/source/index.md @@ -4,7 +4,7 @@ This guide explains in a step-by-step approach the recommended way to install th ## Windows Subsystem for Linux (WSL) -A Linux OS must be used to access the provided tools. If you are already running on a Linux OS (Ubuntu, Fedora, etc.), skip this step, and continue with installing OpenMPI and System Packages. If you are running on a Windows OS, one available option to access this content is by using a Linux simulator, for example, WSL. Note that the code blocks in this guide assume that Ubuntu is being used, so certain steps may be different on other platforms. +A Linux OS is highly recommended for this installation. If you are already running on a Linux OS (Ubuntu, Fedora, etc.), skip this step, and continue below with installing OpenMPI and System Packages. If you are running on a Windows OS, one option is to use a Linux simulator; for example, WSL. Note that the code blocks in this guide assume that Ubuntu is being used, so certain steps may be different on other platforms. To install WSL, enter the terminal (on Windows, you can use "windows_key + r" and type in "cmd" to the prompt to open the terminal) and enter the following line of code: @@ -14,13 +14,21 @@ wsl --install Accept all permissions on the popups and allow WSL to be installed. Once finished, you will be asked to enter a username and password. This will be your Linux administrator account, and the password will be needed to be used for all "sudo" commands to install required system packages. -Start up a new Ubuntu (Linux) terminal by selecting the dropdown arrow and choosing "Ubuntu". The default directory is "/home/[username]". From this point, use the command: +Start up a new Ubuntu (Linux) terminal by selecting the dropdown arrow and choosing "Ubuntu". The default directory is "/home/[username]". + +## Linux Basics + +This section is for those that have little to no previous experience working with Linux and/or with the terminal. + +To begin, use the command: ``` mkdir motor ``` -to create a folder for all downloads. Below is a list of basic Linux commands to navigate between folders: +to create a folder for all MISO-related downloads. Throughout this guide, there will be paths that refer to this folder (for example, [path_to_motor_folder]). The default path for most prompts is /home/[username], so an example [path_to_motor_folder] would be /home/[username]/motor. + +Below is a list of other basic Linux commands that will assist in navigatation between directories: ``` explorer.exe . # open file explorer @@ -31,11 +39,13 @@ cd # navigate to /home/[username] cd / # navigate to / ``` +The file explorer is best utilized by native Linux users, and doesn't interact as well with WSL. It is most often used to search for specific files, or quickly move or extract files/folders. + ## OpenMPI and System Packages -OpenMPI is a software package that is an implementation of the Message Passing Interface (MPI) standard that is required for a parallel build of MFEM. Alternatives exist, such as MPICH, but OpenMPI is the recommended MPI implementation. MPI is required for MISO. +OpenMPI is a software package that is an implementation of the Message Passing Interface (MPI) standard that is required for a parallel build of MFEM (the main dependency of MISO). Alternatives exist, such as MPICH, but OpenMPI is the recommended MPI implementation. -In addition to MISO, it is highly recommended to install gcc, which is a collection of compilers, and cmake, which is a build system generator. Alternatives exist for both of these installations, but this guide will use these choices. git and build-essential are mandatory packages, and while build-essential may be installed by default, you should confirm its presence before proceeding. +In addition to OpenMPI, it is highly recommended to install gcc, which is a collection of compilers, and cmake, which is a build system generator. Alternatives exist for both of these installations, but this guide will use these choices. git and build-essential are mandatory packages, and while build-essential may be installed by default, its presence should be confirmed before proceeding. To download these packages, you must be on an administrator account. Use the following lines of code in the terminal to download the packages: @@ -54,7 +64,7 @@ which mpicc which mpicxx ``` -After each command, a directory should be listed that holds these particular executables. If these files can not be found, then they need to be added to your path. Enter the file explorer and search for "mpicc". The file, along with mpicxx and others, should be in a "bin" directory". Add this directory as a Path variable by using the following code: +After each command, a directory should be listed that holds the executable. If these files can not be found, then they need to be added to your path. Enter the file explorer and search for "mpicc". The file, along with mpicxx and others, should be in a "bin" directory. Add this directory as a Path variable by using the following code: ``` export PATH=$PATH:[path_to_mpi_container_directory] @@ -72,7 +82,7 @@ To download the HYPRE package, follow the below steps: 1. Go to [HYPRE GitHub](https://github.com/hypre-space/hypre) 2. Download version 2.28.0 (this is NOT the current version; go to the "Releases" section to see past versions) 3. Unzip the folder and extract it to [path_to_motor_folder]/Dependencies - Note that the default browser download is to Windows. Drag and drop the extracted files in file explorer to copy them from Windows over to Linux + Note that if using WSL, the default browser download is to Windows. Drag and drop the extracted files in file explorer to copy them from Windows over to Linux 4. Additional information can be found in the README.md and INSTALL.md files for configuration and installation Enter the terminal and navigate to the motor folder. Use the following lines of code to configure and install HYPRE. @@ -80,7 +90,7 @@ Enter the terminal and navigate to the motor folder. Use the following lines of ``` cd Dependencies/hypre-2.28.0/src./ ./configure - # If this comes back as an error, use the following line of code then repeat ./configure + # If an error statement stops this command, use the following line of code then repeat ./configure chmod +x configure cd cmbuild cmake .. -DCMAKE_POSITION_INDEPENDENT_CODE=ON -DHYPRE_INSTALL_PREFIX="[path_to_motor_folder]/Installations/hypre" -DHYPRE_ENABLE_SHARED=ON @@ -89,7 +99,7 @@ cd ../../../.. export PATH=$PATH:[path_to_motor_folder]/Installations/hypre ``` -Note that EVERY "export" statement must be repeated upon each PC reboot, if MISO needs to be used. +Recall that EVERY "export" statement must be repeated upon each PC reboot, when MISO is being used. ### METIS @@ -114,7 +124,7 @@ export PATH=$PATH:[path_to_motor_folder]/Installations/metis ## PUMI (additional mesh tool) -PUMI is a library that is optional for standalone MFEM, but is required for certain MISO tests. This project uses the CORE package, which is a modification of PUMI and serves the same purpose. EngineeringSketchPad (ESP) is a dependency for CORE, and OpenCASCADE is in turn a requirement for ESP. +PUMI is a library that is optional for standalone MFEM, but is required for certain aspects of MISO. This project uses the CORE package, which is a modification of PUMI and serves the same purpose. EngineeringSketchPad (ESP) is a dependency of CORE, and OpenCASCADE is in turn a dependency of ESP. ### OpenCASCADE @@ -140,7 +150,7 @@ make cd ../../.. ``` -In addition to every "export" statement, the following command must be repeated upon each PC reboot, if MISO needs to be used: +In addition to every "export" statement, the following command must be repeated upon each PC reboot, when MISO is being used: ``` source [path_to_motor_folder]/Dependencies/EngSketchPad/ESPenv.sh @@ -178,6 +188,8 @@ cmake .. \ #### Terminal Code +Enter the terminal and navigate to the motor folder. Use the following lines of code to download, configure, and install CORE. + ``` cd Dependencies git clone https://github.com/tuckerbabcock/core.git @@ -195,7 +207,7 @@ export PATH=$PATH:/[path_to_motor_folder]/Installations/core ## Building MFEM -Once HYPRE, METIS, and CORE have been successfully installed, MFEM can now be built. For more information on the package, see the [MFEM Website](https://mfem.org/building/). You can also go to their [GitHub](https://github.com/mfem/mfem) and inspect the README.md and INSTALL.md files. +Once HYPRE, METIS, and CORE have been successfully installed, MFEM can now be built. For more information on the package, see the [MFEM Website](https://mfem.org/building/). You can also go to their [GitHub](https://github.com/mfem/mfem) and look through the README.md and INSTALL.md files. A configuration file is highly recommended to be used with cmake to more specifically configure the build of MFEM. @@ -219,6 +231,8 @@ cmake .. \ #### Terminal Code +Enter the terminal and navigate to the motor folder. Use the following lines of code to download, configure, and install MFEM. + ``` cd Dependencies git clone https://github.com/mfem/mfem.git @@ -281,6 +295,8 @@ cmake .. \ -DCMAKE_EXPORT_COMPILE_COMMANDS=ON ``` +Enter the terminal and navigate to the motor folder. Use the following lines of code to download, configure, and install MISO. + #### Terminal Code ``` From 2732cdbdc75955091ec7134cac36a8f8eed16138 Mon Sep 17 00:00:00 2001 From: rzommers Date: Mon, 16 Dec 2024 16:21:20 -0500 Subject: [PATCH 11/42] Create Further Work.md --- rtd/source/Further Work.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 rtd/source/Further Work.md diff --git a/rtd/source/Further Work.md b/rtd/source/Further Work.md new file mode 100644 index 00000000..8b137891 --- /dev/null +++ b/rtd/source/Further Work.md @@ -0,0 +1 @@ + From 7271c5f76de23c4face180fed479cbe074b0d00a Mon Sep 17 00:00:00 2001 From: rzommers Date: Mon, 16 Dec 2024 16:27:13 -0500 Subject: [PATCH 12/42] Delete rtd/source/Further Work.md --- rtd/source/Further Work.md | 1 - 1 file changed, 1 deletion(-) delete mode 100644 rtd/source/Further Work.md diff --git a/rtd/source/Further Work.md b/rtd/source/Further Work.md deleted file mode 100644 index 8b137891..00000000 --- a/rtd/source/Further Work.md +++ /dev/null @@ -1 +0,0 @@ - From 0b898674d56818e1d5d2fefed9910dc75a377394 Mon Sep 17 00:00:00 2001 From: rzommers Date: Mon, 16 Dec 2024 16:28:15 -0500 Subject: [PATCH 13/42] Create editors.md --- rtd/source/editors.md | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 rtd/source/editors.md diff --git a/rtd/source/editors.md b/rtd/source/editors.md new file mode 100644 index 00000000..2581931c --- /dev/null +++ b/rtd/source/editors.md @@ -0,0 +1,3 @@ +# Editor's Guide + +This is a test. From cbd21cbca0a7a84453c349198550f64f9a2ad66c Mon Sep 17 00:00:00 2001 From: rzommers Date: Mon, 16 Dec 2024 16:56:17 -0500 Subject: [PATCH 14/42] Update editors.md Added info --- rtd/source/editors.md | 27 ++++++++++++++++++++++++++- 1 file changed, 26 insertions(+), 1 deletion(-) diff --git a/rtd/source/editors.md b/rtd/source/editors.md index 2581931c..836a543c 100644 --- a/rtd/source/editors.md +++ b/rtd/source/editors.md @@ -1,3 +1,28 @@ # Editor's Guide -This is a test. +This page is for editors of this guide, and serves as a reference of information for adding + +Immediate things that need to be done: +1. OpenCascade - Currently have a folder to connect with GitHub, would be nice to find version on their website that is compatible. +2. MotorModel Tests - Section needs to be updated when problems are resolved + +The Readthedocs portion of this repository includes the following files/folders: +1. .readthedocs.yaml - Main file; same basic formula, doesn't need to be touched beyond what's already been done +2. rtd (folder) + 1. Makefile + 2. make.bat + 3. requirements.txt - installed packages, like markdown; extensions can be added here if desired + 4. conf.py - Configuration file; used to set project title, author(s), copyright, extensions, and themes; can be modified as project changes + 5. index.md - Markdown file, main content page + 6. editors.md - This file + +To make a new page, simply make a new GitHub file with the ending ".md". The readthedocs page should update, but this is not confirmed. + +Editing in GitHub will automatically reflect changes in Readthedocs. There may be a time delay, but no further work needs to be done. Changes to the conf.py file will take longer to reflect over. + +### Markdown Basics + +- To make titles/subtitles, use the # key before the title name. Each additional # in a row diminishes the size of the title. +- To make a code block, use ``` before and after the lines of code, each on their own line. Separate code blocks from other text by at least one empty line. +- Inspect this file's markdown code to see how bulleted and numbered lists are made. +- For additional information, check out the [Full Markdown Guide](https://www.markdownguide.org/extended-syntax/) From 33ec9285eed406e414a8fb4e66cf834ed9cc9bde Mon Sep 17 00:00:00 2001 From: rzommers Date: Tue, 17 Dec 2024 10:44:34 -0500 Subject: [PATCH 15/42] Update index.md Testing editors.md page connection --- rtd/source/index.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/rtd/source/index.md b/rtd/source/index.md index ddda2df2..dd191d26 100644 --- a/rtd/source/index.md +++ b/rtd/source/index.md @@ -2,6 +2,8 @@ This guide explains in a step-by-step approach the recommended way to install the MISO software library. +[editors](editors.md) + ## Windows Subsystem for Linux (WSL) A Linux OS is highly recommended for this installation. If you are already running on a Linux OS (Ubuntu, Fedora, etc.), skip this step, and continue below with installing OpenMPI and System Packages. If you are running on a Windows OS, one option is to use a Linux simulator; for example, WSL. Note that the code blocks in this guide assume that Ubuntu is being used, so certain steps may be different on other platforms. From d879600c994097c695baf7ff6e6602de20598853 Mon Sep 17 00:00:00 2001 From: rzommers Date: Tue, 17 Dec 2024 10:56:29 -0500 Subject: [PATCH 16/42] Update conf.py Added html_theme_options --- rtd/source/conf.py | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/rtd/source/conf.py b/rtd/source/conf.py index 9d02c579..e41c91af 100644 --- a/rtd/source/conf.py +++ b/rtd/source/conf.py @@ -32,5 +32,9 @@ html_theme = 'sphinx_rtd_theme' +html_theme_options = { + 'navigation_depth': -1, +} + # -- Options for EPUB output epub_show_urls = 'footnote' From 60e03a8f2606e015ef71c2e70aa6f8978ddfa4d6 Mon Sep 17 00:00:00 2001 From: rzommers Date: Tue, 17 Dec 2024 11:09:41 -0500 Subject: [PATCH 17/42] Update index.md --- rtd/source/index.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/rtd/source/index.md b/rtd/source/index.md index dd191d26..9788d145 100644 --- a/rtd/source/index.md +++ b/rtd/source/index.md @@ -2,8 +2,6 @@ This guide explains in a step-by-step approach the recommended way to install the MISO software library. -[editors](editors.md) - ## Windows Subsystem for Linux (WSL) A Linux OS is highly recommended for this installation. If you are already running on a Linux OS (Ubuntu, Fedora, etc.), skip this step, and continue below with installing OpenMPI and System Packages. If you are running on a Windows OS, one option is to use a Linux simulator; for example, WSL. Note that the code blocks in this guide assume that Ubuntu is being used, so certain steps may be different on other platforms. @@ -318,3 +316,9 @@ cd ../.. The "make tests" command is expected to take a long time to complete. If any of the 57 tests results in a failure, it is most likely a problem with a dependency. It is also possible that you are running an outdated version of MISO, which may be rectified by navigating to the MISO folder and running the "git submodule update" command At this point, MISO has been fully installed and may be used for projects. + +.. toctree:: +:maxdepth: 2 +:caption: Contents: + + editors From 451f143aeee36120b405ee49aa5567f80223f17d Mon Sep 17 00:00:00 2001 From: rzommers Date: Tue, 17 Dec 2024 11:30:16 -0500 Subject: [PATCH 18/42] Update index.md --- rtd/source/index.md | 6 ------ 1 file changed, 6 deletions(-) diff --git a/rtd/source/index.md b/rtd/source/index.md index 9788d145..ddda2df2 100644 --- a/rtd/source/index.md +++ b/rtd/source/index.md @@ -316,9 +316,3 @@ cd ../.. The "make tests" command is expected to take a long time to complete. If any of the 57 tests results in a failure, it is most likely a problem with a dependency. It is also possible that you are running an outdated version of MISO, which may be rectified by navigating to the MISO folder and running the "git submodule update" command At this point, MISO has been fully installed and may be used for projects. - -.. toctree:: -:maxdepth: 2 -:caption: Contents: - - editors From 3ca3cfa22e0d2013f63de108ee7ed4d01b63c7cf Mon Sep 17 00:00:00 2001 From: rzommers Date: Tue, 17 Dec 2024 11:30:41 -0500 Subject: [PATCH 19/42] Delete rtd/source/conf.py --- rtd/source/conf.py | 40 ---------------------------------------- 1 file changed, 40 deletions(-) delete mode 100644 rtd/source/conf.py diff --git a/rtd/source/conf.py b/rtd/source/conf.py deleted file mode 100644 index e41c91af..00000000 --- a/rtd/source/conf.py +++ /dev/null @@ -1,40 +0,0 @@ -# Configuration file for the Sphinx documentation builder. - -# -- Project information - -project = 'MISO Setup' -copyright = 'TBA' -author = 'TBA' - -release = '0.1' -version = '0.1.0' - -# -- General configuration - -extensions = [ - 'sphinx.ext.duration', - 'sphinx.ext.doctest', - 'sphinx.ext.autodoc', - 'sphinx.ext.autosummary', - 'sphinx.ext.intersphinx', - "myst_parser", -] - -intersphinx_mapping = { - 'python': ('https://docs.python.org/3/', None), - 'sphinx': ('https://www.sphinx-doc.org/en/master/', None), -} -intersphinx_disabled_domains = ['std'] - -templates_path = ['_templates'] - -# -- Options for HTML output - -html_theme = 'sphinx_rtd_theme' - -html_theme_options = { - 'navigation_depth': -1, -} - -# -- Options for EPUB output -epub_show_urls = 'footnote' From 09c72186fae251b6cd1b10327fa218a42de45c8e Mon Sep 17 00:00:00 2001 From: rzommers Date: Tue, 17 Dec 2024 11:30:56 -0500 Subject: [PATCH 20/42] Delete rtd/Makefile --- rtd/Makefile | 20 -------------------- 1 file changed, 20 deletions(-) delete mode 100644 rtd/Makefile diff --git a/rtd/Makefile b/rtd/Makefile deleted file mode 100644 index d0c3cbf1..00000000 --- a/rtd/Makefile +++ /dev/null @@ -1,20 +0,0 @@ -# Minimal makefile for Sphinx documentation -# - -# You can set these variables from the command line, and also -# from the environment for the first two. -SPHINXOPTS ?= -SPHINXBUILD ?= sphinx-build -SOURCEDIR = source -BUILDDIR = build - -# Put it first so that "make" without argument is like "make help". -help: - @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) - -.PHONY: help Makefile - -# Catch-all target: route all unknown targets to Sphinx using the new -# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). -%: Makefile - @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) From fc4f87828f98514cb09532d7b9d58220657f1951 Mon Sep 17 00:00:00 2001 From: rzommers Date: Tue, 17 Dec 2024 11:31:04 -0500 Subject: [PATCH 21/42] Delete rtd/make.bat --- rtd/make.bat | 35 ----------------------------------- 1 file changed, 35 deletions(-) delete mode 100644 rtd/make.bat diff --git a/rtd/make.bat b/rtd/make.bat deleted file mode 100644 index 9534b018..00000000 --- a/rtd/make.bat +++ /dev/null @@ -1,35 +0,0 @@ -@ECHO OFF - -pushd %~dp0 - -REM Command file for Sphinx documentation - -if "%SPHINXBUILD%" == "" ( - set SPHINXBUILD=sphinx-build -) -set SOURCEDIR=source -set BUILDDIR=build - -if "%1" == "" goto help - -%SPHINXBUILD% >NUL 2>NUL -if errorlevel 9009 ( - echo. - echo.The 'sphinx-build' command was not found. Make sure you have Sphinx - echo.installed, then set the SPHINXBUILD environment variable to point - echo.to the full path of the 'sphinx-build' executable. Alternatively you - echo.may add the Sphinx directory to PATH. - echo. - echo.If you don't have Sphinx installed, grab it from - echo.http://sphinx-doc.org/ - exit /b 1 -) - -%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% -goto end - -:help -%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% - -:end -popd From 748bdc39ad91d18ba785365cbe53ac5327290ab5 Mon Sep 17 00:00:00 2001 From: rzommers Date: Tue, 17 Dec 2024 11:31:27 -0500 Subject: [PATCH 22/42] Rename rtd/source/editors.md to rtd/editors.md --- rtd/{source => }/editors.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename rtd/{source => }/editors.md (100%) diff --git a/rtd/source/editors.md b/rtd/editors.md similarity index 100% rename from rtd/source/editors.md rename to rtd/editors.md From 156c185dc485b5e72bd30036f5e024503bdc63a1 Mon Sep 17 00:00:00 2001 From: rzommers Date: Tue, 17 Dec 2024 11:31:45 -0500 Subject: [PATCH 23/42] Rename rtd/source/index.md to rtd/index.md --- rtd/{source => }/index.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename rtd/{source => }/index.md (100%) diff --git a/rtd/source/index.md b/rtd/index.md similarity index 100% rename from rtd/source/index.md rename to rtd/index.md From d4d4ab49d643239663c0d705f2c501a0672a136b Mon Sep 17 00:00:00 2001 From: rzommers Date: Tue, 17 Dec 2024 11:32:12 -0500 Subject: [PATCH 24/42] Update requirements.txt --- rtd/requirements.txt | 70 +++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 66 insertions(+), 4 deletions(-) diff --git a/rtd/requirements.txt b/rtd/requirements.txt index 22131894..f6cb652b 100644 --- a/rtd/requirements.txt +++ b/rtd/requirements.txt @@ -1,4 +1,66 @@ -sphinx==8.1.3 -sphinx-rtd-theme==3.0.1 -markdown-it-py==3.0.0 -myst-parser==4.0.0 +# +# This file is autogenerated by pip-compile with python 3.10 +# To update, run: +# +# pip-compile docs/requirements.in +# +click==8.1.3 + # via mkdocs +ghp-import==2.1.0 + # via mkdocs +griffe==0.22.0 + # via mkdocstrings-python +importlib-metadata==4.12.0 + # via mkdocs +jinja2==3.1.2 + # via + # mkdocs + # mkdocstrings +markdown==3.3.7 + # via + # markdown-include + # mkdocs + # mkdocs-autorefs + # mkdocstrings + # pymdown-extensions +markdown-include==0.6.0 + # via -r docs/requirements.in +markupsafe==2.1.1 + # via + # jinja2 + # mkdocstrings +mergedeep==1.3.4 + # via mkdocs +mkdocs==1.3.0 + # via + # -r docs/requirements.in + # mkdocs-autorefs + # mkdocstrings +mkdocs-autorefs==0.4.1 + # via mkdocstrings +mkdocstrings[python]==0.19.0 + # via + # -r docs/requirements.in + # mkdocstrings-python +mkdocstrings-python==0.7.1 + # via mkdocstrings +packaging==21.3 + # via mkdocs +pymdown-extensions==9.5 + # via mkdocstrings +pyparsing==3.0.9 + # via packaging +python-dateutil==2.8.2 + # via ghp-import +pyyaml==6.0 + # via + # mkdocs + # pyyaml-env-tag +pyyaml-env-tag==0.1 + # via mkdocs +six==1.16.0 + # via python-dateutil +watchdog==2.1.9 + # via mkdocs +zipp==3.8.0 + # via importlib-metadata From 3eb46bc0d6f1ee54a23c60edaa49cf7ff9135db7 Mon Sep 17 00:00:00 2001 From: rzommers Date: Tue, 17 Dec 2024 11:32:49 -0500 Subject: [PATCH 25/42] Create requirements.in --- rtd/requirements.in | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 rtd/requirements.in diff --git a/rtd/requirements.in b/rtd/requirements.in new file mode 100644 index 00000000..bec300ca --- /dev/null +++ b/rtd/requirements.in @@ -0,0 +1,3 @@ +mkdocs +mkdocstrings[python] +markdown-include From 3256adb94b5d82a5aaa42a2c5beb57252d70b221 Mon Sep 17 00:00:00 2001 From: rzommers Date: Tue, 17 Dec 2024 11:33:49 -0500 Subject: [PATCH 26/42] Create mkdocs.yml --- rtd/mkdocs.yml | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) create mode 100644 rtd/mkdocs.yml diff --git a/rtd/mkdocs.yml b/rtd/mkdocs.yml new file mode 100644 index 00000000..d6ee970e --- /dev/null +++ b/rtd/mkdocs.yml @@ -0,0 +1,16 @@ +site_name: MISO Installation +theme: + name: readthedocs + highlightjs: true +plugins: + - search + - mkdocstrings: + handlers: + # See: https://mkdocstrings.github.io/python/usage/ + python: + options: + docstring_style: sphinx +markdown_extensions: + - markdown_include.include: + base_path: . + - admonition From 9ca888d29e2b0c6a77bbb45c6599ec6cc234a0ef Mon Sep 17 00:00:00 2001 From: rzommers Date: Tue, 17 Dec 2024 11:34:34 -0500 Subject: [PATCH 27/42] Update .readthedocs.yaml --- .readthedocs.yaml | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 3c72076d..a6cbdfe7 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -9,6 +9,5 @@ python: install: - requirements: rtd/requirements.txt -sphinx: - configuration: rtd/source/conf.py - fail_on_warning: false +mkdocs: + configuration: rtd/mkdocs.yml From 01156c38c6b27a138556aa006b7b8ac9977935e9 Mon Sep 17 00:00:00 2001 From: rzommers Date: Tue, 17 Dec 2024 11:37:22 -0500 Subject: [PATCH 28/42] Rename rtd/editors.md to rtd/docs/editors.md --- rtd/{ => docs}/editors.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename rtd/{ => docs}/editors.md (100%) diff --git a/rtd/editors.md b/rtd/docs/editors.md similarity index 100% rename from rtd/editors.md rename to rtd/docs/editors.md From c6e5975294d1fe47f4180db65db0fc1fb5f9079c Mon Sep 17 00:00:00 2001 From: rzommers Date: Tue, 17 Dec 2024 11:37:43 -0500 Subject: [PATCH 29/42] Rename rtd/index.md to rtd/docs/index.md --- rtd/{ => docs}/index.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename rtd/{ => docs}/index.md (100%) diff --git a/rtd/index.md b/rtd/docs/index.md similarity index 100% rename from rtd/index.md rename to rtd/docs/index.md From a4663a5b1678458d1107dae8c5f1b49cfcaf37a0 Mon Sep 17 00:00:00 2001 From: rzommers Date: Tue, 17 Dec 2024 11:37:56 -0500 Subject: [PATCH 30/42] Rename rtd/requirements.in to rtd/docs/requirements.in --- rtd/{ => docs}/requirements.in | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename rtd/{ => docs}/requirements.in (100%) diff --git a/rtd/requirements.in b/rtd/docs/requirements.in similarity index 100% rename from rtd/requirements.in rename to rtd/docs/requirements.in From 91e61a1c9072af7da3e300675269bb252f525e94 Mon Sep 17 00:00:00 2001 From: rzommers Date: Tue, 17 Dec 2024 11:38:08 -0500 Subject: [PATCH 31/42] Rename rtd/requirements.txt to rtd/docs/requirements.txt --- rtd/{ => docs}/requirements.txt | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename rtd/{ => docs}/requirements.txt (100%) diff --git a/rtd/requirements.txt b/rtd/docs/requirements.txt similarity index 100% rename from rtd/requirements.txt rename to rtd/docs/requirements.txt From 9d67e6989397dba85c1c9eaa7bc2428bc4fb2fd6 Mon Sep 17 00:00:00 2001 From: rzommers Date: Tue, 17 Dec 2024 11:38:24 -0500 Subject: [PATCH 32/42] Update .readthedocs.yaml --- .readthedocs.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index a6cbdfe7..dc2a5260 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -7,7 +7,7 @@ build: python: install: - - requirements: rtd/requirements.txt + - requirements: rtd/docs/requirements.txt mkdocs: configuration: rtd/mkdocs.yml From 1c653019ae335d7cbcb3ec85733c1042eab09a2f Mon Sep 17 00:00:00 2001 From: rzommers Date: Tue, 17 Dec 2024 12:11:38 -0500 Subject: [PATCH 33/42] Update index.md --- rtd/docs/index.md | 33 ++++++++++++++++++++++----------- 1 file changed, 22 insertions(+), 11 deletions(-) diff --git a/rtd/docs/index.md b/rtd/docs/index.md index ddda2df2..c41ade0f 100644 --- a/rtd/docs/index.md +++ b/rtd/docs/index.md @@ -64,6 +64,8 @@ which mpicc which mpicxx ``` +These executables are used to compile and link MPI programs. + After each command, a directory should be listed that holds the executable. If these files can not be found, then they need to be added to your path. Enter the file explorer and search for "mpicc". The file, along with mpicxx and others, should be in a "bin" directory. Add this directory as a Path variable by using the following code: ``` @@ -107,7 +109,7 @@ The official METIS website can be unreliable, so its recommended to use the GitH To download the METIS package, follow the below steps: 1. Go to [Metis-MFEM GitHub](https://github.com/mfem/tpls) -2. Download the default package +2. Download METIS 5.1.0 (or the tpls wrapper that includes multiple versions) 3. Unzip the folder and enter it 4. Unzip the metis-5.1.0 folder and extract it to [path_to_motor_folder]/Dependencies @@ -128,9 +130,14 @@ PUMI is a library that is optional for standalone MFEM, but is required for cert ### OpenCASCADE -[Specific folder, check for alternatives] -[Figure out how to attach file to RTD] -[Alternative: possibility of downloading directly from site?] +Enter the terminal and navigate to the motor folder. Use the following lines of code to download OpenCascade. + +``` +cd Installations +wget -nv https://acdl.mit.edu/esp/otherOCCs/OCC741lin64.tgz +tar -xzpf OCC741lin64.tgz +cd .. +``` ### ESP @@ -142,7 +149,7 @@ git clone https://github.com/tuckerbabcock/EngSketchPad.git cd EngSketchPad git checkout 8a5ca2bd6fbed747d371eb926e8a24d0cfcda087 cd config -./makeEnv /[path_to_motor_folder]/Installations/OpenCASCADE +./makeEnv /[path_to_motor_folder]/Installations/OpenCASCADE-7.4.1 cd .. source ESPenv.sh cd src @@ -172,8 +179,8 @@ The below file name and code block are recommended for this configuration file. ``` cmake .. \ - -DCMAKE_C_COMPILER="MPICC" \ - -DCMAKE_CXX_COMPILER="MPICXX" \ + -DCMAKE_C_COMPILER="mpicc" \ + -DCMAKE_CXX_COMPILER="mpicxx" \ -DCMAKE_INSTALL_PREFIX="/[path_to_motor_folder]/Installations/core" \ -DBUILD_SHARED_LIBS=ON \ -DSCOREC_CXX_OPTIMIZE=ON \ @@ -195,6 +202,7 @@ cd Dependencies git clone https://github.com/tuckerbabcock/core.git cd core git checkout egads-dev +git submodule update --init --recursive mkdir build cd build # make config_core.sh (see above) or move file into build folder @@ -215,7 +223,8 @@ A configuration file is highly recommended to be used with cmake to more specifi ``` cmake .. \ - -DCMAKE_CXX_COMPILER="MPICXX" \ + -DCMAKE_C_COMPILER="mpicc" \ + -DCMAKE_CXX_COMPILER="mpicxx" \ -DCMAKE_BUILD_TYPE=Debug \ -DCMAKE_INSTALL_PREFIX="/[path_to_motor_folder]/Installations/mfem" \ -DBUILD_SHARED_LIBS=ON \ @@ -267,7 +276,7 @@ Enter the terminal and navigate to the motor folder. Use the following lines of ``` cd Dependencies/adept -./configure --prefix="/[path_to_motor_folder]/Installations/adept +./configure --prefix="/[path_to_motor_folder]/Installations/adept" make make install cd ../.. @@ -284,15 +293,17 @@ A configuration file is highly recommended to be used with cmake to more specifi ``` cmake .. \ - -DCMAKE_C_COMPILER="MPICC" \ - -DCMAKE_CXX_COMPILER="MPICXX" \ + -DCMAKE_C_COMPILER="mpicc" \ + -DCMAKE_CXX_COMPILER="mpicxx" \ -DCMAKE_BUILD_TYPE=Debug \ -DMFEM_DIR="/[path_to_motor_folder]/Dependencies/mfem" \ -DAdept_ROOT="/[path_to_motor_folder]/Installations/adept" \ -DPUMI_DIR="/[path_to_motor_folder]/Installations/core" \ -DBUILD_SHARED_LIBS=OFF \ -DBUILD_TESTING=ON \ + -DBUILD_PYTHON_WRAPPER=ON \ -DCMAKE_EXPORT_COMPILE_COMMANDS=ON + -DMISO_USE_CLANG_TIDY=OFF \ ``` Enter the terminal and navigate to the motor folder. Use the following lines of code to download, configure, and install MISO. From b08c8b907c5f49e2e0966c6d39e87b30226edb92 Mon Sep 17 00:00:00 2001 From: rzommers Date: Tue, 17 Dec 2024 14:12:55 -0500 Subject: [PATCH 34/42] Update index.md Corrected various issues after following through and checking --- rtd/docs/index.md | 19 +++++++++++++------ 1 file changed, 13 insertions(+), 6 deletions(-) diff --git a/rtd/docs/index.md b/rtd/docs/index.md index c41ade0f..8377ff41 100644 --- a/rtd/docs/index.md +++ b/rtd/docs/index.md @@ -37,6 +37,8 @@ cd [folder] # enter a folder within the current directory cd .. # exit current directory to its container folder cd # navigate to /home/[username] cd / # navigate to / +rm [file] # remove a file +rm -r [folder] # remove a directory ``` The file explorer is best utilized by native Linux users, and doesn't interact as well with WSL. It is most often used to search for specific files, or quickly move or extract files/folders. @@ -55,6 +57,9 @@ sudo apt install cmake sudo apt install git sudo apt install build-essential sudo apt install openmpi-bin openmpi-doc libopenmpi-dev +sudo apt install python3 +sudo apt install python3-pip +sudo apt install python3-mpi4py ``` For OpenMPI (or any MPI package) to be used, it must be able to be found on the PC's path. To confirm that OpenMPI has been successfully installed and can be used, enter the terminal and use the following lines of code: @@ -136,6 +141,7 @@ Enter the terminal and navigate to the motor folder. Use the following lines of cd Installations wget -nv https://acdl.mit.edu/esp/otherOCCs/OCC741lin64.tgz tar -xzpf OCC741lin64.tgz +rm OCC741lin64.tgz cd .. ``` @@ -208,7 +214,7 @@ cd build # make config_core.sh (see above) or move file into build folder source config_core.sh make -j 4 -make install +sudo make install cd ../../.. export PATH=$PATH:/[path_to_motor_folder]/Installations/core ``` @@ -223,9 +229,8 @@ A configuration file is highly recommended to be used with cmake to more specifi ``` cmake .. \ - -DCMAKE_C_COMPILER="mpicc" \ -DCMAKE_CXX_COMPILER="mpicxx" \ - -DCMAKE_BUILD_TYPE=Debug \ + -DCMAKE_BUILD_TYPE=Release \ -DCMAKE_INSTALL_PREFIX="/[path_to_motor_folder]/Installations/mfem" \ -DBUILD_SHARED_LIBS=ON \ -DMFEM_DEBUG=ON \ @@ -275,8 +280,10 @@ To download the ADEPT package, follow the below steps: Enter the terminal and navigate to the motor folder. Use the following lines of code to configure and install ADEPT. ``` -cd Dependencies/adept +cd Dependencies/adept-2.1 ./configure --prefix="/[path_to_motor_folder]/Installations/adept" + # If an error statement stops this command, use the following line of code then repeat command + chmod +x configure make make install cd ../.. @@ -301,9 +308,9 @@ cmake .. \ -DPUMI_DIR="/[path_to_motor_folder]/Installations/core" \ -DBUILD_SHARED_LIBS=OFF \ -DBUILD_TESTING=ON \ - -DBUILD_PYTHON_WRAPPER=ON \ - -DCMAKE_EXPORT_COMPILE_COMMANDS=ON + -DCMAKE_EXPORT_COMPILE_COMMANDS=ON \ -DMISO_USE_CLANG_TIDY=OFF \ + -DBUILD_PYTHON_WRAPPER=ON ``` Enter the terminal and navigate to the motor folder. Use the following lines of code to download, configure, and install MISO. From d17c2c3c7ebb9a6f6791b7aa46b1a14cd749d900 Mon Sep 17 00:00:00 2001 From: rzommers Date: Tue, 17 Dec 2024 14:15:52 -0500 Subject: [PATCH 35/42] Update index.md Info on Python --- rtd/docs/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/rtd/docs/index.md b/rtd/docs/index.md index 8377ff41..71c93e2a 100644 --- a/rtd/docs/index.md +++ b/rtd/docs/index.md @@ -49,7 +49,7 @@ OpenMPI is a software package that is an implementation of the Message Passing I In addition to OpenMPI, it is highly recommended to install gcc, which is a collection of compilers, and cmake, which is a build system generator. Alternatives exist for both of these installations, but this guide will use these choices. git and build-essential are mandatory packages, and while build-essential may be installed by default, its presence should be confirmed before proceeding. -To download these packages, you must be on an administrator account. Use the following lines of code in the terminal to download the packages: +To download these packages, you must be on an administrator account. Note that this list includes three Python packages; these are only required if MISO's Python wrapper needs to be built. Use the following lines of code in the terminal to download the packages: ``` sudo apt install gcc @@ -310,7 +310,7 @@ cmake .. \ -DBUILD_TESTING=ON \ -DCMAKE_EXPORT_COMPILE_COMMANDS=ON \ -DMISO_USE_CLANG_TIDY=OFF \ - -DBUILD_PYTHON_WRAPPER=ON + -DBUILD_PYTHON_WRAPPER=ON # Only required if the Python wrapper needs to be built. If not needed, replace ON with OFF. ``` Enter the terminal and navigate to the motor folder. Use the following lines of code to download, configure, and install MISO. From 7c5c79bc293bbaf12de1ad102610017ff37af685 Mon Sep 17 00:00:00 2001 From: rzommers Date: Tue, 17 Dec 2024 14:31:45 -0500 Subject: [PATCH 36/42] Update editors.md Completed --- rtd/docs/editors.md | 29 ++++++++++++++++------------- 1 file changed, 16 insertions(+), 13 deletions(-) diff --git a/rtd/docs/editors.md b/rtd/docs/editors.md index 836a543c..28dcd045 100644 --- a/rtd/docs/editors.md +++ b/rtd/docs/editors.md @@ -1,28 +1,31 @@ # Editor's Guide -This page is for editors of this guide, and serves as a reference of information for adding +This page is for editors of this guide, and serves as a reference of information for adding new content/pages, as well as keeping track of improvements that need to be made. -Immediate things that need to be done: -1. OpenCascade - Currently have a folder to connect with GitHub, would be nice to find version on their website that is compatible. +Remaining issues that need to be resolved: +1. OpenCascade - Current solution is to download a file linked online. Better solution would be to download and install directly from the [OpenCascade Website](https://dev.opencascade.org/release). 2. MotorModel Tests - Section needs to be updated when problems are resolved +3. ESP - It is currently built in such a way that PUMI is not properly visualized, and fails the MFEM tests. A correction needs to be made and subsequent steps must be tested to confirm that the process still works properly. The Readthedocs portion of this repository includes the following files/folders: -1. .readthedocs.yaml - Main file; same basic formula, doesn't need to be touched beyond what's already been done +1. .readthedocs.yaml - Main file; points to configuration files, selects versions of Ubuntu, Python; don't change 2. rtd (folder) - 1. Makefile - 2. make.bat - 3. requirements.txt - installed packages, like markdown; extensions can be added here if desired - 4. conf.py - Configuration file; used to set project title, author(s), copyright, extensions, and themes; can be modified as project changes - 5. index.md - Markdown file, main content page - 6. editors.md - This file + 1. mkdocs.yml - Markdown configuration file; used to change project title, theme + 2. requirements.txt - Generated requirements file for RTD; don't change + 3. requirements.in - Used for individual builds; don't change + 4. index.md - Main content page; uses Markdown + 5. editors.md - This page -To make a new page, simply make a new GitHub file with the ending ".md". The readthedocs page should update, but this is not confirmed. +To make a new page, simply make a new GitHub file with the ending ".md" within. -Editing in GitHub will automatically reflect changes in Readthedocs. There may be a time delay, but no further work needs to be done. Changes to the conf.py file will take longer to reflect over. +Every GitHub commit automatically makes Readthedocs build a new document. There may be a time delay, but no further work needs to be done. + +The other website to maintain is [MotorModel Installation](https://motormodel.readthedocs.io/en/latest/), which does not have an Editor's Guide page. ### Markdown Basics -- To make titles/subtitles, use the # key before the title name. Each additional # in a row diminishes the size of the title. +- To make titles/subtitles, use the # key before the title name. Each subsequent # in a row diminishes the size of the title. - To make a code block, use ``` before and after the lines of code, each on their own line. Separate code blocks from other text by at least one empty line. +- To insert a link, write the display text in brackets, and immediately follow it (without spaces) with the embedded link in parentheses. - Inspect this file's markdown code to see how bulleted and numbered lists are made. - For additional information, check out the [Full Markdown Guide](https://www.markdownguide.org/extended-syntax/) From 4e603e658797dea73fb509ff5b9cd9841df7ad61 Mon Sep 17 00:00:00 2001 From: rzommers Date: Tue, 17 Dec 2024 15:21:41 -0500 Subject: [PATCH 37/42] Update editors.md --- rtd/docs/editors.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/rtd/docs/editors.md b/rtd/docs/editors.md index 28dcd045..b2604ed4 100644 --- a/rtd/docs/editors.md +++ b/rtd/docs/editors.md @@ -3,18 +3,18 @@ This page is for editors of this guide, and serves as a reference of information for adding new content/pages, as well as keeping track of improvements that need to be made. Remaining issues that need to be resolved: -1. OpenCascade - Current solution is to download a file linked online. Better solution would be to download and install directly from the [OpenCascade Website](https://dev.opencascade.org/release). -2. MotorModel Tests - Section needs to be updated when problems are resolved -3. ESP - It is currently built in such a way that PUMI is not properly visualized, and fails the MFEM tests. A correction needs to be made and subsequent steps must be tested to confirm that the process still works properly. +- OpenCascade - Current solution is to download a file linked online. Better solution would be to download and install directly from the [OpenCascade Website](https://dev.opencascade.org/release). +- MotorModel Tests - Section needs to be updated when problems are resolved +- ESP - It is currently built in such a way that PUMI is not properly visualized, and fails the MFEM tests. A correction needs to be made and subsequent steps must be tested to confirm that the process still works properly. The Readthedocs portion of this repository includes the following files/folders: -1. .readthedocs.yaml - Main file; points to configuration files, selects versions of Ubuntu, Python; don't change -2. rtd (folder) - 1. mkdocs.yml - Markdown configuration file; used to change project title, theme - 2. requirements.txt - Generated requirements file for RTD; don't change - 3. requirements.in - Used for individual builds; don't change - 4. index.md - Main content page; uses Markdown - 5. editors.md - This page +- .readthedocs.yaml - Main file; points to configuration files, selects versions of Ubuntu, Python; don't change +- rtd (folder) + - mkdocs.yml - Markdown configuration file; used to change project title, theme + - requirements.txt - Generated requirements file for RTD; don't change + - requirements.in - Used for individual builds; don't change + - index.md - Main content page; uses Markdown + - editors.md - This page To make a new page, simply make a new GitHub file with the ending ".md" within. @@ -27,5 +27,5 @@ The other website to maintain is [MotorModel Installation](https://motormodel.re - To make titles/subtitles, use the # key before the title name. Each subsequent # in a row diminishes the size of the title. - To make a code block, use ``` before and after the lines of code, each on their own line. Separate code blocks from other text by at least one empty line. - To insert a link, write the display text in brackets, and immediately follow it (without spaces) with the embedded link in parentheses. -- Inspect this file's markdown code to see how bulleted and numbered lists are made. +- Inspect this file's markdown code to see how bulleted lists are made. - For additional information, check out the [Full Markdown Guide](https://www.markdownguide.org/extended-syntax/) From e7cd552540ade8939c345c2472979032d370498b Mon Sep 17 00:00:00 2001 From: rzommers Date: Tue, 17 Dec 2024 15:27:51 -0500 Subject: [PATCH 38/42] Update editors.md --- rtd/docs/editors.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/rtd/docs/editors.md b/rtd/docs/editors.md index b2604ed4..eebe4844 100644 --- a/rtd/docs/editors.md +++ b/rtd/docs/editors.md @@ -3,11 +3,13 @@ This page is for editors of this guide, and serves as a reference of information for adding new content/pages, as well as keeping track of improvements that need to be made. Remaining issues that need to be resolved: -- OpenCascade - Current solution is to download a file linked online. Better solution would be to download and install directly from the [OpenCascade Website](https://dev.opencascade.org/release). -- MotorModel Tests - Section needs to be updated when problems are resolved -- ESP - It is currently built in such a way that PUMI is not properly visualized, and fails the MFEM tests. A correction needs to be made and subsequent steps must be tested to confirm that the process still works properly. + +1. OpenCascade - Current solution is to download a file linked online. Better solution would be to download and install directly from the [OpenCascade Website](https://dev.opencascade.org/release). +2. MotorModel Tests - Section needs to be updated when problems are resolved +3. ESP - It is currently built in such a way that PUMI is not properly visualized, and fails the MFEM tests. A correction needs to be made and subsequent steps must be tested to confirm that the process still works properly. The Readthedocs portion of this repository includes the following files/folders: + - .readthedocs.yaml - Main file; points to configuration files, selects versions of Ubuntu, Python; don't change - rtd (folder) - mkdocs.yml - Markdown configuration file; used to change project title, theme From a32536c54eb56411dca4f13a1b84a34de128894c Mon Sep 17 00:00:00 2001 From: rzommers Date: Tue, 17 Dec 2024 15:31:48 -0500 Subject: [PATCH 39/42] Update editors.md --- rtd/docs/editors.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/rtd/docs/editors.md b/rtd/docs/editors.md index eebe4844..ffd7694a 100644 --- a/rtd/docs/editors.md +++ b/rtd/docs/editors.md @@ -10,13 +10,13 @@ Remaining issues that need to be resolved: The Readthedocs portion of this repository includes the following files/folders: -- .readthedocs.yaml - Main file; points to configuration files, selects versions of Ubuntu, Python; don't change +1. .readthedocs.yaml - Main file; points to configuration files, selects versions of Ubuntu, Python; don't change - rtd (folder) - - mkdocs.yml - Markdown configuration file; used to change project title, theme - - requirements.txt - Generated requirements file for RTD; don't change - - requirements.in - Used for individual builds; don't change - - index.md - Main content page; uses Markdown - - editors.md - This page + 2. mkdocs.yml - Markdown configuration file; used to change project title, theme + 3. requirements.txt - Generated requirements file for RTD; don't change + 4. requirements.in - Used for individual builds; don't change + 5. index.md - Main content page; uses Markdown + 6. editors.md - This page To make a new page, simply make a new GitHub file with the ending ".md" within. From 4075610851f6674da72f9d32470e6818bb1a4aa9 Mon Sep 17 00:00:00 2001 From: rzommers Date: Tue, 17 Dec 2024 15:53:22 -0500 Subject: [PATCH 40/42] Update editors.md --- rtd/docs/editors.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/rtd/docs/editors.md b/rtd/docs/editors.md index ffd7694a..aeea502c 100644 --- a/rtd/docs/editors.md +++ b/rtd/docs/editors.md @@ -10,13 +10,13 @@ Remaining issues that need to be resolved: The Readthedocs portion of this repository includes the following files/folders: -1. .readthedocs.yaml - Main file; points to configuration files, selects versions of Ubuntu, Python; don't change +- .readthedocs.yaml - Main file; points to configuration files, selects versions of Ubuntu, Python; don't change - rtd (folder) - 2. mkdocs.yml - Markdown configuration file; used to change project title, theme - 3. requirements.txt - Generated requirements file for RTD; don't change - 4. requirements.in - Used for individual builds; don't change - 5. index.md - Main content page; uses Markdown - 6. editors.md - This page + - mkdocs.yml - Markdown configuration file; used to change project title, theme + - requirements.txt - Generated requirements file for RTD; don't change + - requirements.in - Used for individual builds; don't change + - index.md - Main content page; uses Markdown + - editors.md - This page To make a new page, simply make a new GitHub file with the ending ".md" within. From c8ee395ab97a17ae6f73d7daa3a6cc36e29fcfff Mon Sep 17 00:00:00 2001 From: rzommers Date: Sat, 21 Dec 2024 13:39:33 -0500 Subject: [PATCH 41/42] Update index.md Updated for ESP fix --- rtd/docs/index.md | 41 ++++++++++++++++++++++++++++++++++++++++- 1 file changed, 40 insertions(+), 1 deletion(-) diff --git a/rtd/docs/index.md b/rtd/docs/index.md index 71c93e2a..8d46c585 100644 --- a/rtd/docs/index.md +++ b/rtd/docs/index.md @@ -77,7 +77,22 @@ After each command, a directory should be listed that holds the executable. If t export PATH=$PATH:[path_to_mpi_container_directory] ``` -This command MUST be repeated whenever a new command prompt is opened, as an export statement is not permanent. Every export command throughout this process must be repeated when that particular installation needs to be used. +This command MUST be repeated whenever a new command prompt is opened, as an export statement is not permanent. Every export command throughout this guide must be repeated when the corresponding installation needs to be used. + +## Python Environment Setup + +A virtual environment must be made to be able to access Python libraries while in the terminal. All Python files must be kept in the same file location as the C++ dependencies. + +This step is only required if the tests that use MISO are written in Python. + +Enter the terminal and navigate to the motor folder. Use the following lines of code to create and activate a virtual Python environment. + +``` +python -m venv source /[path_to_motor_folder]/python +source /[path_to_motor_folder]/python/bin/activate +``` + +The source command must be repeated on each PC reboot, when Python is being used. ## MFEM Prerequisites @@ -218,6 +233,30 @@ sudo make install cd ../../.. export PATH=$PATH:/[path_to_motor_folder]/Installations/core ``` +### Return to ESP + +If MISO is eventually going to be used for a modeling project that requires better visualization, then ESP should be re-built before proceeding to allow PUMI to connect with CORE. First, enter the file explorer and open the file: + +``` +/[path_to_motor_folder]/Dependencies/EngSketchPad/ESPenv.sh +``` + +Within this file, there should be a line that says "#export PUMI". Replace this line with the following: + +``` +export PUMI=/[path_to_motor_folder]/Dependencies/core +``` + +Enter the terminal and navigate to the motor folder. Use the following lines of code to rebuild ESP. + +``` +cd Dependencies/EngSketchPad +source ESPenv.sh +cd src +make clean +make +cd ../../.. +``` ## Building MFEM From 7af3ac88a9b61f7648832046c6194ea413bf3751 Mon Sep 17 00:00:00 2001 From: rzommers Date: Sat, 21 Dec 2024 13:40:15 -0500 Subject: [PATCH 42/42] Update editors.md Updated for ESP fix --- rtd/docs/editors.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/rtd/docs/editors.md b/rtd/docs/editors.md index aeea502c..1d615fae 100644 --- a/rtd/docs/editors.md +++ b/rtd/docs/editors.md @@ -5,8 +5,7 @@ This page is for editors of this guide, and serves as a reference of information Remaining issues that need to be resolved: 1. OpenCascade - Current solution is to download a file linked online. Better solution would be to download and install directly from the [OpenCascade Website](https://dev.opencascade.org/release). -2. MotorModel Tests - Section needs to be updated when problems are resolved -3. ESP - It is currently built in such a way that PUMI is not properly visualized, and fails the MFEM tests. A correction needs to be made and subsequent steps must be tested to confirm that the process still works properly. +2. MotorModel Tests - Section needs to be updated when current bugs are resolved The Readthedocs portion of this repository includes the following files/folders: