Yade can be installed from packages (pre-compiled binaries) or source code. The choice depends on what you need: if you don’t plan to modify Yade itself, package installation is easier. In the contrary case, you must download and install the source code.
Pre-built packages are provided for all currently supported Debian and Ubuntu versions and available on yade-dem.org/packages .
These are “daily” versions of the packages which are being updated regularly and, hence, include all the newly added features.
To install the daily-version you need to add the repository to your /etc/apt/sources.list, add the PGP-key AA915EEB as trusted and install yadedaily:
sudo bash -c 'echo "deb http://www.yade-dem.org/packages/ xenial/" >> /etc/apt/sources.list'
wget -O - http://www.yade-dem.org/packages/yadedev_pub.gpg | sudo apt-key add -
sudo apt-get update
sudo apt-get install yadedaily
If you have another distribution, not Ubuntu Trusty (Version 14.04 LTS), be sure to use the correct name in the first line (for instance, xenial, stretch or jessie). For the list of currently supported distributions, please visit yade-dem.org/packages.
After that you can normally start Yade using the command yadedaily or yadedaily-batch. yadedaily on older distributions can have some disabled features due to older library versions, shipped with particular distribution.
The Git-repository for packaging stuff is available on GitHub. Each branch corresponds to one distribution, e.g., xenial, stretch etc. The scripts for building all of this stuff are here. It uses “pbuilder” to build packages, so all packages are built in a clean environment.
If you do not need yadedaily-package any more, just remove the corresponding line in /etc/apt/sources.list and the package itself:
sudo apt-get remove yadedaily
To remove our key from keyring, execute the following command:
sudo apt-key remove AA915EEB
Since 2011, all Ubuntu (starting from 11.10, Oneiric) and Debian (starting from Wheezy) versions have Yade in their main repositories. There are only stable releases in place. To install Yade, run the following:
sudo apt-get install yade
After that you can normally start Yade using the command yade or yade-batch.
To check, what version of Yade is included in your specific distribution, visit Ubuntu or Debian. The Debian-Backports repository is updated regularly to bring the newest Yade version to the users of stable Debians.
Daily and stable Yade versions can coexist without any conflicts, i.e., you can use yade` and yadedaily at the same time.
Installation from source code is reasonable, when you want to add or modify constitutive laws, engines, functions etc. Installing the latest trunk version allows one to use newly added features, which are not yet available in packaged versions.
If you want to install from source, you can install either a release (numbered version, which is frozen) or the current development version (updated by the developers frequently). You should download the development version (called trunk) if you want to modify the source code, as you might encounter problems that will be fixed by the developers. Release versions will not be updated (except for updates due to critical and easy-to-fix bugs), but generally they are more stable than the trunk.
We use GIT (the git command) for code management (install the git package on your system and create a GitHub account):
git clone git@github.com:yade/trunk.git
will download the whole code repository of the trunk. Check out Yade on GitHub for more details on how to collaborate using git.
Alternatively, a read-only checkout is possible via https without a GitHub account (easier if you don’t want to modify the trunk version):
git clone https://github.com/yade/trunk.git
For those behind a firewall, you can download the sources from our GitHub repository as compressed archive.
Release and trunk sources are compiled in exactly the same way. In order to get notifications about changes to the truck (i.e., commits), use watch option on GitHub.
Yade relies on a number of external software to run; they are checked before the compilation starts. Some of them are only optional. The last ones are only relevant for using the fluid coupling module (FlowEngine).
Most of the list above is very likely already packaged for your distribution. In case you are confronted with some errors concerning not available packages (e.g., package libmetis-dev is not available) it may be necessary to add yade external ppa from https://launchpad.net/~yade-users/+archive/external (see below) as well as http://www.yade-dem.org/packages (see the top of this page):
sudo add-apt-repository ppa:yade-users/external
sudo apt-get update
The following commands have to be executed in the command line of your corresponding distribution. Just copy&paste to the terminal. Note, to execute these commands you need root privileges.
Ubuntu, Debian and their derivatives:
sudo apt-get install cmake git freeglut3-dev libloki-dev \
libboost-all-dev fakeroot dpkg-dev build-essential g++ \
python-dev ipython python-matplotlib libsqlite3-dev python-numpy python-tk gnuplot \
libgts-dev python-pygraphviz libvtk6-dev python-numpy libeigen3-dev \
python-xlib python-pyqt5 pyqt5-dev-tools python-pyqt5.qtwebkit gtk2-engines-pixbuf python-argparse \
libqglviewer-dev python-imaging libjs-jquery python-sphinx python-git python-bibtex \
libxmu-dev libxi-dev libcgal-dev help2man libbz2-dev zlib1g-dev python-minieigen
Some of the packages (for example, cmake, eigen3) are mandatory, some of them are optional. Watch for notes and warnings/errors, which are shown by cmake during the configuration step. If the missing package is optional, some of Yade features will be disabled (see the messages at the end of the configuration).
Additional packages, which can become mandatory later:
sudo apt-get install python-gts
For effective usage of direct solvers in the PFV-type fluid coupling, the following libraries are recommended, together with eigen>=3.1: blas, lapack, suitesparse, and metis. All four of them are available in many different versions. Different combinations are possible and not all of them will work. The following was found to be effective on recent deb-based systems. On ubuntu 12.04, better compile openblas with USE_OPENMP=1, else yade will run on a single core:
sudo apt-get install libopenblas-dev libsuitesparse-metis-dev
Some packages listed here are relatively new and they can be absent in your distribution (for example, libmetis-dev or python-gts). They can be installed from yade-dem.org/packages or from our external PPA. If not installed the related features will be disabled automatically.
If you are using other distributions than Debian or its derivatives you should install the software packages listed above. Their names in other distributions can differ from the names of the Debian-packages.
Warning
If you have Ubuntu 14.04 Trusty, you need to add -DCMAKE_CXX_FLAGS=-frounding-math during the configuration step of compilation (see below) or to install libcgal-dev from our external PPA. Otherwise the following error occurs on AMD64 architectures:
terminate called after throwing an instance of 'CGAL::Assertion_exception'
what(): CGAL ERROR: assertion violation!
Expr: -CGAL_IA_MUL(-1.1, 10.1) != CGAL_IA_MUL(1.1, 10.1)
File: /usr/include/CGAL/Interval_nt.h
Line: 209
Explanation: Wrong rounding: did you forget the -frounding-math option if you use GCC (or -fp-model strict for Intel)?
Aborted
You should create a separate build-place-folder, where Yade will be configured and where the source code will be compiled. Here is an example for a folder structure:
myYade/ ## base directory
trunk/ ## folder for source code in which you use github
build/ ## folder in which the sources will be compiled; build-directory; use cmake here
install/ ## install folder; contains the executables
Then, inside this build-directory you should call cmake to configure the compilation process:
cmake -DCMAKE_INSTALL_PREFIX=/path/to/installfolder /path/to/sources
For the folder structure given above call the following command in the folder “build”:
cmake -DCMAKE_INSTALL_PREFIX=../install ../trunk
Additional options can be configured in the same line with the following syntax:
cmake -DOPTION1=VALUE1 -DOPTION2=VALUE2
The following options are available:
- CMAKE_INSTALL_PREFIX: path where Yade should be installed (/usr/local by default)
- LIBRARY_OUTPUT_PATH: path to install libraries (lib by default)
- DEBUG: compile in debug-mode (OFF by default)
- CMAKE_VERBOSE_MAKEFILE: output additional information during compiling (OFF by default)
- SUFFIX: suffix, added after binary-names (version number by default)
- NOSUFFIX: do not add a suffix after binary-name (OFF by default)
- YADE_VERSION: explicitly set version number (is defined from git-directory by default)
- ENABLE_GUI: enable GUI option (ON by default)
- ENABLE_CGAL: enable CGAL option (ON by default)
- ENABLE_VTK: enable VTK-export option (ON by default)
- ENABLE_OPENMP: enable OpenMP-parallelizing option (ON by default)
- ENABLE_GTS: enable GTS-option (ON by default)
- ENABLE_GL2PS: enable GL2PS-option (ON by default)
- ENABLE_LINSOLV: enable LINSOLV-option (ON by default)
- ENABLE_PFVFLOW: enable PFVFLOW-option, FlowEngine (ON by default)
- ENABLE_LBMFLOW: enable LBMFLOW-option, LBM_ENGINE (ON by default)
- ENABLE_SPH: enable SPH-option, Smoothed Particle Hydrodynamics (OFF by default)
- ENABLE_LIQMIGRATION: enable LIQMIGRATION-option, see [Mani2013] for details (OFF by default)
- ENABLE_MASK_ARBITRARY: enable MASK_ARBITRARY option (OFF by default)
- ENABLE_PROFILING: enable profiling, e.g., shows some more metrics, which can define bottlenecks of the code (OFF by default)
- runtimePREFIX: used for packaging, when install directory is not the same as runtime directory (/usr/local by default)
- CHUNKSIZE: specifiy the chunk size if you want several sources to be compiled at once. Increases compilation speed but RAM-consumption during compilation as well (1 by default)
- VECTORIZE: enables vectorization and alignment in Eigen3 library, experimental (OFF by default)
- USE_QT5: use QT5 for GUI, experimental (ON by default)
For using more extended parameters of cmake, please follow the corresponding documentation on https://cmake.org/documentation.
If cmake finishes without errors, you will see all enabled and disabled options at the end. Then start the actual compilation process with:
make
The compilation process can take a considerable amount of time, be patient. If you are using a multi-core systems you can use the parameter -j to speed-up the compilation and split the compilation onto many cores. For example, on 4-core machines it would be reasonable to set the parameter -j4. Note, Yade requires approximately 3GB RAM per core for compilation, otherwise the swap-file will be used and compilation time dramatically increases.
The installation is performed with the following command:
make install
The install command will in fact also recompile if source files have been modified. Hence there is no absolute need to type the two commands separately. You may receive make errors if you don’t have permission to write into the target folder. These errors are not critical but without writing permissions Yade won’t be installed in /usr/local/bin/.
After the compilation finished successfully, the new built can be started by navigating to /path/to/installfolder/bin and calling yade via (based on version yade-2014-02-20.git-a7048f4):
cd /path/to/installfolder/bin
./yade-2014-02-20.git-a7048f4
For building the documentation you should at first execute the command make install and then make doc to build it. The generated files will be stored in your current install directory /path/to/installfolder/share/doc/yade-your-version. Once again writing permissions are necessary for installing into /usr/local/share/doc/. To open your local documentation go into the folder html and open the file index.html with a browser.
make manpage command generates and moves manpages in a standard place. make check command executes standard test to check the functionality of the compiled program.
Yade can be compiled not only by GCC-compiler, but also by CLANG front-end for the LLVM compiler. For that you set the environment variables CC and CXX upon detecting the C and C++ compiler to use:
export CC=/usr/bin/clang
export CXX=/usr/bin/clang++
cmake -DOPTION1=VALUE1 -DOPTION2=VALUE2
Clang does not support OpenMP-parallelizing for the moment, that is why the feature will be disabled.
When spliting the compilation on many cores (make -jN), N is limited by the available cores and memory. It is possible to use more cores if remote computers are available, ditributing the compilation with ditscc (see distcc documentation for configuring slaves and master):
export CC=distcc gcc
export CXX=distcc g++
cmake [options as usual]
make -jN
In addition, and independently of distcc, caching previous compilations with ccache can speed up re-compilation:
export CC=ccache gcc
export CXX=ccache g++
cmake [options as usual]
The two tools can be combined very simply, adding to the above exports:
export CCACHE_PREFIX="distcc"
If you are not running Ubuntu nor Debian, there is a way to create a Yubuntu live-usb on any usb mass-storage device (minimum recommended size is 5GB). It is a way to make a bootable usb-key with a preinstalled minimalist operating system (Xubuntu), including Yadedaily and Paraview.
More informations about this alternative are available here (see the README file first).