• For more information, please check the documentation.
• Video introduction
• To refer MUSEN please use Dosta et al., 2020.
• New versions and updates.

MUSEN should install and work on all latest versions of Windows or Linux (Ubuntu or Red Head). Requires Visual C++ Redistributable for Visual Studio 2019 to run on Windows.

A fully functional version can be compiled and built with Microsoft Visual Studio 2019.

• Microsoft Visual Studio 2019
• Qt 5.15.2 msvc2019_64
• Qt Visual Studio Tools for Visual Studio 2019
• CUDA 11.2
• Git
• CMake
• (optional) MATLAB R2019a

1. Download and install all requirements on your computer.

   1.1. Microsoft Visual Studio: select "Desktop Development with C++" when choosing what components to install.

   1.2. Qt: You will need to create a free Qt-account to run installation. When selecting components, choose Qt → Qt 5.15.2 → MSVC 2019 64-bit.

   1.3. CUDA: Download the specified version of CUDA and install the configuration proposed by the setup utility.

   1.4. Use the last available version of CMake and select the option "Add to system path" if available during installation.

   1.5. Use the last available version of Git.

2. Setup Qt Visual Studio Tools extension to point to the installed Qt libraries. In Visual Studio 2019, go to Extensions → Qt VS Tools → Qt Options → Add → ... → Navigate in the Qt installation directory to X:/path/to/Qt/5.15.2/msvc2019_64 → OK.

3. Prepare third-party statically linked libraries: zlib, protobuf. To do this, navigate to X:/path/to/msolids/MUSEN/ExternalLibraries/ and execute files RunZLibCompile.bat and RunProtobufCompile.bat. They will download and build all the required libraries by executing files CompileZLib.ps1, CompileProtobuf.ps1.

4. Open X:/path/to/msolids/MUSEN/MUSEN/musen.sln file with Visual Studio and build the solution.

A fully functional version can be compiled and built in WSL.

1. Enable the Windows Subsystem for Linux. Open PowerShell and run:

wsl --install

Additional information here.

2. Install Ubuntu

wsl --install -d Ubuntu-22.04

3. Launch the installed distribution and follow the instructions for initial setup.

4. Login to your distribution and update it by running:

sudo apt update
sudo apt upgrade

5. Install all required tools and libraries, as described in Build on Linux.

6. Compile MUSEN either with Visual Studio (step 6.a) or directly in Ubuntu (step 6.b)

   6.a Open .../musen/musen.sln file with Visual Studio 2019. In Solution Explorer under Installers folder select LinuxBuildWSL project, then from the main menu navigate to (Project → Properties → Configuration Properties → Linux Build Settings) and select MUSEN versions that you want to build. Run building project LinuxBuildWSL (Build → Build Selection).

   6.b Compile MUSEN as described in Build on Linux.

7. The built executables will be placed in ...musen/Installers/Installers/.

A fully functional version can be compiled and built with cmake and gcc.

• gcc-7.5, g++-7.5
• cmake 3.0.0
• protobuf 3.0.0
• qt 5.9.5
• cuda 9.1 The versions of CUDA and C++ compiler must be compatible. See compatibility list e.g. here.

Tested on Ubuntu 18.04, 20.04, 22.04.

1. Change the current working directory to the desired location and download the MUSEN code:

cd /path/to/desired/location/
git clone --depth 1 https://github.com/msolids/musen.git
cd musen

2. Install required tools and libraries.

sudo apt install build-essential cmake libprotobuf-dev protobuf-compiler libqt5opengl5-dev

3. Install CUDA

sudo apt install nvidia-cuda-toolkit

or in case of compatibility issues (usually on Ubuntu 22.04), using official installation guide or running the script for Ubuntu:

./scripts/install_cuda.sh
exec bash

4. Build MUSEN

mkdir install
mkdir build
cd build
cmake .. -DCMAKE_INSTALL_PREFIX=../install
cmake --build . --parallel $(nproc)
make install

5. Built executables can be found in

cd ../install

• CMusen - command-line version of MUSEN
• Databases - agglomerates, geometries and materials databases
• Documentation - manuals
• ExternalLibraries - external libraries used in MUSEN on Windows (zlib and protobuf)
• GeneralFunctions - main functions and types used in MUSEN
• Installers - scripts and data needed to build installers on Windows
• Models - contact models (particle-particle, particle-wall, solid bonds, etc.)
• Modules\BondsGenerator - generate bonds between particles
• Modules\ContactAnalyzer - functions for contacts detection
• Modules\FileManager - set of functions to convert, merge or modify .mdem files with simulation results
• Modules\GeneralSources - general components
• Modules\Geometries - set of classes and functions to work with geometrical objects
• Modules\ObjectsGenerator - dynamic particles or agglomerates generator
• Modules\PackageGenerator - generate packing of particles prior simulation
• Modules\ResultsAnalyzer - analyzer of simulation results (export necessary data to csv files)
• Modules\ScriptInterface - analyze input scripts for command-line version
• Modules\SimplifiedScene - simplified entity generated from SystemStructure and which is used during simulation
• Modules\SimResultsStorage - low-level functions for data handling (load and save data)
• Modules\Simulator - CPU and GPU simulators
• Modules\SystemStructure - main entity which stores the information about whole scene
• MusenGUI - graphical version of MUSEN
• QTDialog - Qt-based dialogs for graphical user interface
• Version - version information

• CUDA 11.2 – Nvidia Corporation – NVIDIA License
• Inno Setup 6.1.2 – Jordan Russell – Modified BSD License
• Protobuf 3.14.0 – Google Inc. – BSD License
• Qt 5.15.2 – The Qt Company – LGPLv3 License
• Visual Studio Community 2019 – Microsoft Corporation – Microsoft Software License Terms
• zlib v1.2.11 – Jean-loup Gailly and Mark Adler – zlib License