Installation ============ This document will walk you through the installation process of CFDEM®coupling. First Aspherix® needs to be installed using its installer. OpenFOAM® and CFDEM®coupling are then installed. Finally, basic test cases are run to verify the successful installation. As prerequisites OpenFOAM-8 and cmake >= 3.10 need to be installed. On Ubuntu 18.04+ cmake is installed during the OpenFOAM® installation with an appropriate version. .. note:: All steps described in this article are also available as video tutorials on the `Aspherix website `_. .. contents:: :local: :depth: 1 .. _install_asx: Install Aspherix® ----------------- Before installing CFDEM®coupling, it is necessary that Aspherix® is propertly installed on your system. For more information regarding Aspherix®, please visit the `official website `_. You receive details of the Aspherix® installation together with the Aspherix® installer as part of the provided documentation. The default installation location of Aspherix® on your system is $HOME/DCS-Computing. You can test your Aspherix® installation by typing in your console: .. parsed-literal:: aspherix Which should lead to the output *Aspherix (Version ...) Checkout of asx_solver OK.* ---------- .. _install_of: Install OpenFOAM® ----------------- The easiest way to install :ref:`OpenFOAM® ` on your system is by using the package manager, as it is described in the next paragraphs. In case this is not an option for you, you can find some optional installation information in the following page: .. toctree:: :maxdepth: 1 additionalInstall As a prerequisite for the OpenFOAM® installation you need to download and install additional software (see the `OpenFOAM webpage `_ for more details), which you get for Ubuntu 18.04 by executing in the terminal the following command: .. parsed-literal:: sudo apt-get install build-essential flex bison git-core cmake zlib1g-dev libboost-system-dev libboost-thread-dev libopenmpi-dev openmpi-bin gnuplot libreadline-dev libncurses-dev libxt-dev For many Ubuntu systems there are packages including OpenFOAM® and Paraview® provided by OpenFOAM.org (find complete instructions for `Ubuntu `_), which can easily be installed using the "apt" package manager. Basically the ``dl.openfoam.org`` repository must be added once to the list of software repositories. This is done with the terminal command: .. parsed-literal:: sudo sh -c "wget -O - http://dl.openfoam.org/gpg.key | apt-key add -" sudo add-apt-repository http://dl.openfoam.org/ubuntu Then OpenFOAM® is installed using the terminal commands: .. parsed-literal:: sudo apt-get update sudo apt-get -y install openfoam8 Finally you need to "enable" the installed package by adding some lines to your ``.bashrc`` file. Open the .bashrc file by typing: .. parsed-literal:: gedit ~/.bashrc Then add the following line to the end of the file and save the changes. .. parsed-literal:: source /opt/openfoam8/etc/bashrc For testing your installation, please open a new terminal window (!) and test that the ``simpleFoam`` application is found. Type into your terminal .. parsed-literal:: simpleFoam -help and execute it. You should get a “Usage” message printed to screen. .. note:: The current version of CFDEM®coupling compiles only with OpenFOAM® in version 8. ---------- .. _install_swak: Install swak4FOAM (optional) ---------------------------- swak4FOAM is a library of tools which open functionality otherwise only available by implementing new models. It is used in some test cases, mostly for post processing. To run these test cases without swak4FOAM, remove the related calls which are usually found in the ``functions`` subDict in ``controlDict``. To install swak4FOAM go to your OpenFOAM folder and run .. parsed-literal:: # clone repo into swak4Foam ub folder git clone https://github.com/Unofficial-Extend-Project-Mirror/openfoam-extend-swak4Foam-dev.git swak4Foam # go to cloned folder cd swak4Foam # checkout version compatible to OpenFOAM-8 git checkout 0f570f524c0e3be44155cdf0f7623c5403f234d3 # build ./AllwmakeAll All dependencies and package requirements should already be installed from the package installation during the OpenFOAM installation process. .. note:: If encountering compilation problems with swak4FOAM, try first to run the compilation on a single core by running ``export WM_NCOMPPROCS=1`` before invoking ``./AllwmakeAll``. ---------- .. _install_cfdem: Install CFDEM®coupling ---------------------- You should have received a zip archive named "CFDEMcoupling-BASIC" containing CFDEM®coupling. Please, unzip it into the folder ``$HOME/DCS-Computing``. Alternatively, you may have received access to a repository containing a custom version of CFDEMcoupling. In this case, please clone the repository into ``$HOME/DCS-Computing``. As a second step, you need to set some :doc:`environment variables ` in ``~/.bashrc`` (if you use c-shell, manipulate ``~/.cshrc`` accordingly). Open your ``$HOME/.bashrc`` file and add the following block to the end of the file. The following example assumes that you are using the "CFDEMcoupling-BASIC" version. In other cases you need to change the ``CFDEM_VERSION`` environment variable in the example below or modify other entries if necessary. .. parsed-literal:: #================================================# #- CFDEMcoupling SETUP export CFDEM_VERSION=BASIC export CFDEM_PROJECT_DIR=$HOME/DCS-Computing/CFDEMcoupling-$CFDEM_VERSION export CFDEM_PROJECT_USER_DIR=$HOME/DCS-Computing/$LOGNAME-$CFDEM_VERSION export CFDEM_bashrc=$CFDEM_PROJECT_DIR/src/lagrangian/cfdemParticle/etc/bashrc export CFDEM_ASX_INSTALL_DIR=$HOME/DCS-Computing/Aspherix-6.0.0 . $CFDEM_bashrc #================================================# Then open a new terminal so that above changes to your .bashrc become active and test your setup by typing: .. parsed-literal:: cfdemSysTest .. note:: Many useful :doc:`aliases ` are set with sourcing of the CFDEMcoupling bashrc, e.g. ``cfdemEtc`` . Make use of them! .. note:: Please note the output of the number of threads per core and the recommendation for the CFD-DEM :doc:`hyperthreading setting `. .. note:: On some systems, as RHEL and CentOS the MPICXX library is needed additionally within the system linker paths. Please add CFDEM_ADD_LIBS+=-lmpicxx CFDEM_ADD_LIBS+=-L/path/to/lmpicxx to src/lagrangian/cfdemParticle/etc/addLibs_universal/additionalLibs_solver. In addition to `the requirements stated above for OpenFOAM <_install_of>`_, CFDEMcoupling requires ``cmake`` to build. To compile CFDEM®coupling open a new terminal and run .. parsed-literal:: cfdemCompCFDEM It compiles the CFDEM®coupling libraries, CFDEM®coupling solvers and CFDEM®coupling utilities. The compilation will stop, if build errors occur. The compilation is automatically logged and the logs can be found in: .. parsed-literal:: $CFDEM_SRC_DIR/lagrangian/cfdemParticle/etc/log In case questions concerning the installation arise, please feel free to contact `DCS Computing `_. .. note:: Here we assume you have already installed Aspherix® at the default location ``$HOME/DCS-Computing``, and we assume you have :ref:`installed OpenFOAM® `. Further we assume you are using the CFDEM®coupling version ``CFDEMcoupling-BASIC``, otherwise please change the commands according to your CFDEM®coupling version. .. note:: Some tutorials rely on `swak4Foam `_ for additional postprocessing steps. ---------- .. _setup_paraview_macro: Setup Paraview Macro -------------------- To facilitate data loading a paraview macro is available to split loaded OpenFOAM / CFDEMcoupling data into separate blocks for internal field, patches, and --if present -- particles. .. note:: The macro is automatically installed during compilation. This means that you need to perform the steps described below only if you want to use the Macro on a system (or for a user) where no CFDEMcoupling is compiled. To use this macro copy it from its location to the Paraview Macro folder: .. parsed-literal:: cp -r $CFDEM_ETC_DIR/paraview/CFDEMcoupling* / where the ``pv_macro_dir`` is: .. parsed-literal:: - on Linux: $HOME/.config/ParaView/Macros' - on Windows %userprofile%\\AppData\\Roaming\\ParaView\\Macros On Linux (assuming the above location of the Paraview config folder) you can also use: .. parsed-literal:: cfdemInstallParaviewMacro After loading CFDEMcoupling simulation results you can run the ``CFDEMcoupling`` macro to split up the multiblock data, see Figure 1. .. figure:: img/paraview_macro.png :align: center Figure 1: CFDEMcoupling results split using the paraview macro. .. note:: Select **all** blocks when loading the data. ---------- .. _test_installation: Test the installation --------------------- A simple way to test your installation is by running a tutorial case. In order to run a single tutorial it is recommended to use the *Allrun.sh* scripts in the tutorial directories. They execute the simulation and provide some basic output (e.g., comparison of simulation output with an analytic solution). Now we describe briefly how to run a simple test case, settlingTest, which models the settling velocity of a single sphere. Open a terminal and navigate to the tutorial folder: .. parsed-literal:: cfdemTut cd cfdemSolverPiso/settlingTest Run the simulation by executing the "Allrun.sh" script in the terminal: .. parsed-literal:: ./Allrun.sh This will trigger Aspherix® to start the DEM simulation and CFDEM®coupling to start a coupled CFD-DEM simulation. Both simulations will communicate via socket and exchange the necessary data, e.g. particle position and velocity is communicated from DEM to CFD and the drag force is communicated from DEM to CFD. When the simulation is finished, a plot of the particle settling velocity pops up. The simulation result is compared to the analytical solution. You can visualize the simulation data using, e.g. Paraview. .. image:: img/cfdemSolverPiso_settlingTest.png :align: center In above plot the particle velocity (settling velocity) is ploted over time in red. The black line gives the analytical solution for the settling velocity using the Stokes drag law. Therefore, a slight offset between red and black line is to be expected. You can run all the tutorial cases sequentially by executing the alias cfdemTestTUT. For running pure Aspherix® cases, you can use the aliases .. parsed-literal:: cfdemAspherix inputScriptName cfdemAspherixPar inputScriptName nOfProcs In the :doc:`tutorials section ` you find more details on setting up and running a tutorials. .. note:: If you want to run your own cases, it is recommended to first copy the tutorial case to ``$CFDEM_PROJECT_USER_DIR/run`` which is automatically being generated. E.g., copy one of the tutorial cases there, and adapt it to your needs before running. This helps you keeping the tutorial in its original clean and working state. ---------- .. _install_helyx: Install Helyx®OS (optional) --------------------------- If you are interested in using a GUI based workflow for setting up your coupled CFD-DEM cases we recommend having a look into :ref:`Helyx® `-OS provided by `Engys `_. .. note:: This is to be considered only a first "proof of concept" of combining CFDEM®coupling and Helyx®OS, which is planned to be streamlined in the future. You can find detailed installation instructions for Helyx®OS `here `_. Basically it boils down to downloading the installer from this `link `_. Then you need to change the permissions of the file by typing to the terminal .. parsed-literal:: chmod 755 HELYX-OS-2.4.0-linux-x86_64.bin And finally you need to execute the installer in a terminal by typing .. parsed-literal:: ./HELYX-OS-2.4.0-linux-x86_64.bin .. note:: It is not required to install GUI + Kernel as you can use the OpenFOAM® version installed as described :ref:`above `. So please select only the components HELYX-OS-GUI. During installation the destination folder is being queried. As a default your user home directory is a good starting point. Simply type "echo $HOME" in a terminal to see the path. For a simple start of Helyx®OS we recommend to add to your ~/.bashrc (right above the definition of CFDEM_VERSION) the path of your Helyx®OS installation (you can find the correct path by looking for the file HELYX-OS.sh): .. parsed-literal:: export CFDEM_HELYXOS_DIR=$HOME/Engys/HELYX-OS/v2.4.0 In order to check your environment variables you can use the command .. parsed-literal:: cfdemSysTest , which will show your settings and if they are complete and correct. After defining CFDEM_HELYXOS_DIR you can start Helyx®OS by typing to your terminal: .. parsed-literal:: cfdemHelyxOS After the first start you will have to define the paths to your OpenFOAM® installation. Please add .. parsed-literal:: /opt/openfoam6 to ``Edit/Preferences/Core Folder``. ---------- .. _install_on_windows: Install OpenFOAM on Windows --------------------------- You can run OpenFOAM® and CFDEM®coupling natively on Windows unsing the Windows sub-system for Linux (WSL). 1. To prepare your Windows system, check that you have updated your Windows 10 to at least version 2004, e.g. displayed in *Settings -> System -> Info -> Windows specifications*. If you do not have this version installed, run the update from *Settings -> Update & Security -> Windows Update*. .. note:: You can force the update of Windows 10 to version 2004 as described in `this manual `_. 2. Activate WSL by opening the PowerShell as Administrator via the start menu and execute the command: .. parsed-literal:: Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux When prompred choose to restart Windows. 3. When rebooted, open a new PowerShell terminal with Administrator privileges and execute: .. parsed-literal:: Enable-WindowsOptionalFeature -Online -FeatureName VirtualMachinePlatform Again, when prompred choose to restart Windows. 4. After the second reboot, start a new PowerShell terminal with Administrator privileges and to switch from WSL1 to the newer version WSL2, execute: .. parsed-literal:: wsl --set-default-version 2 Now, WSL2 is set up and we proceed by installing a Ubuntu virtual machine which will be used by WSL. 5. Start by opening the Microsoft Store and search for ``Ubuntu 18.04``. Click *Install*. This will download the system image and may take some time depending on your internet connection. 6. Start Ubuntu 18.04 from the start menu. This step will set up Ubuntu. In the process you must choose a username and a password for that user. These do not need to be identical with your Windows credentials. 7. Within the Ubuntu system run the following commands to update the package repository and install required tools: .. parsed-literal:: sudo apt-get update sudo apt-get install build-essential sudo apt-get install nautilus gedit sudo apt-get install xfce4 8. Open your bashrc (e.g. using ``nano``) .. parsed-literal:: nano .bashrc and add the line .. parsed-literal:: export DISPLAY=$(cat /etc/resolv.conf | grep nameserver | awk '{print $2}'):0 at the file end. Save the changes. If using nano, this is done using ``Ctrl + o`` followed by ``Ctrl + x``. 9. Create links to acces the Windows file system more easily: .. parsed-literal:: ln -s /mnt/c/Users/yourUserName/Downloads winDownloads ln -s /mnt/c/Users/yourUserName/Documents winDocuments 10. Close the terminal. 11. Install `Paraview on Windows `_ 12. To run graphical programs on the Linux machine you need to additionally install an Xserver on your Windows. Fir this purpose we recommend `VcXsrv `_. After installing VcXsrv, start it using the application Xlaunch. .. note:: When doing so make sure to activate the checkbox "Disable access control". 13. Restart the ubuntu terminal. In the terminal type .. parsed-literal:: startxfce4 & to start the graphical user interface. Now, you are ready to proceed with the normal installation of :ref:`OpenFOAM ` and :ref:`CFDEMcoupling ` as described above within the just set up Ubuntu sub-system. .. note:: After the installation of Aspherix-GUI you need to change the path of the Paraview installation to point to the one installed in Windows. ---------- .. _footnotes: **Footnotes:** OPENFOAM® is a registered trade mark of OpenCFD Ltd, producer and distributor of the OpenFOAM software via https://www.openfoam.com. HELYX® is a registered trade mark of Engys Limited, producer and distributor of the Helyx software via https://engys.com. .. _github: http://github.com/ .. _gitHelp: http://help.github.com/linux-set-up-git .. _gitCFDEM: http://github.com/CFDEMproject .. _gitscm: http://git-scm.com/downloads .. _compOF: https://github.com/CFDEMproject/CFDEMcoupling-PUBLIC/blob/master/src/lagrangian/cfdemParticle/cfdTools/versionInfo.H .. _bashrc: https://github.com/CFDEMproject/CFDEMcoupling-PUBLIC/blob/master/src/lagrangian/cfdemParticle/etc/bashrc .. _ParaViewlink: https://www.paraview.org/ .. _lig: https://www.aspherix-dem.com .. _asxTut: http://www.aspherix-dem.com/tutorials-linux .. _dcs: http://www.dcs-computing.com