diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 00000000..dc2a5260 --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,13 @@ +version: "2" + +build: + os: "ubuntu-22.04" + tools: + python: "3.10" + +python: + install: + - requirements: rtd/docs/requirements.txt + +mkdocs: + configuration: rtd/mkdocs.yml diff --git a/rtd/docs/editors.md b/rtd/docs/editors.md new file mode 100644 index 00000000..1d615fae --- /dev/null +++ b/rtd/docs/editors.md @@ -0,0 +1,32 @@ +# Editor's Guide + +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 current bugs are 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 +- 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. + +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 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 lists are made. +- For additional information, check out the [Full Markdown Guide](https://www.markdownguide.org/extended-syntax/) diff --git a/rtd/docs/index.md b/rtd/docs/index.md new file mode 100644 index 00000000..8d46c585 --- /dev/null +++ b/rtd/docs/index.md @@ -0,0 +1,375 @@ +# 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 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: + +``` +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]". + +## 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 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 +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 / +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. + +## 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 (the main dependency of MISO). Alternatives exist, such as MPICH, but OpenMPI is the recommended MPI implementation. + +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. 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 +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: + +``` +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: + +``` +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 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 + +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 + 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. + +``` +cd Dependencies/hypre-2.28.0/src./ +./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 +make install +cd ../../../.. +export PATH=$PATH:[path_to_motor_folder]/Installations/hypre +``` + +Recall that EVERY "export" statement must be repeated upon each PC reboot, when MISO is being 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 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 + +Enter the terminal and navigate to the motor folder. Use the following lines of code to configure and install 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 +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 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 + +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 +rm OCC741lin64.tgz +cd .. +``` + +### 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-7.4.1 +cd .. +source ESPenv.sh +cd src +make +cd ../../.. +``` + +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 +``` + +### 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 + +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 +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 +source config_core.sh +make -j 4 +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 + +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. + +#### config_mfem.sh + +``` +cmake .. \ + -DCMAKE_CXX_COMPILER="mpicxx" \ + -DCMAKE_BUILD_TYPE=Release \ + -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 + +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 +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-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 ../.. +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 \ + -DMISO_USE_CLANG_TIDY=OFF \ + -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. + +#### 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. diff --git a/rtd/docs/requirements.in b/rtd/docs/requirements.in new file mode 100644 index 00000000..bec300ca --- /dev/null +++ b/rtd/docs/requirements.in @@ -0,0 +1,3 @@ +mkdocs +mkdocstrings[python] +markdown-include diff --git a/rtd/docs/requirements.txt b/rtd/docs/requirements.txt new file mode 100644 index 00000000..f6cb652b --- /dev/null +++ b/rtd/docs/requirements.txt @@ -0,0 +1,66 @@ +# +# 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 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