CMake 3.10 or newer (if using clang with libc++, use 3.18+)
Boost 1.67 or newer
ZeroMQ 4.2 or newer (if ZeroMQ support is needed)
MPI-2 implementation (if MPI support is needed)
Some basics on using the macOS Terminal (or any Unix/Linux shell) will be useful to fully understand this guide. Articles and tutorials you may find useful include:
Note: Keep in mind that your cmake version should be newer than the boost version. If you have an older cmake, you may want an older boost version. Alternatively, you can choose to upgrade your version of cmake.
To set up your environment:
(if needed) Install git on your system for easy access to the HELICS source. Download from git-scm. This installs the command line which is described here. GUI’s interfaces such as SourceTree are another option.
(if desired) Many required libraries are easiest installed using the homebrew package manager. These directions assume this approach, so unless you prefer to track these libraries and dependencies down yourself, install it if you don’t have it yet. As an alternative package manager, you can use vcpkg – it is slower because it builds all dependencies for source, but instead of following step below you could either run
-DCMAKE_TOOLCHAIN_FILE=[path to vcpkg]/scripts/buildsystems/vcpkg.cmakeas shown in the vcpkg getting started instructions, or by setting the environment variable
VCPKG_ROOT=[path to vcpkg]prior to running
(if needed) Setup a command-line compile environment
a) Install a C++11 compiler (C++14 preferred). e.g.
clangfrom the Xcode command line tools. These can be installed from the command line in Terminal by typing
xcode-select --installand following the on-screen prompts. b) Install cmake with
brew install cmake. Alternately, a DMG file is available for cmake from their website.
Install most dependencies using homebrew.
brew install boost brew install zeromq brew install cmake
Make sure cmake and git are available in the Command Prompt with
which gitIf they aren’t, add them to the system PATH variable.
Getting and building from source:
git cloneto check out a copy of HELICS.
Create a build folder. Run cmake and give it the path that HELICS was checked out into.
git clone https://github.com/GMLC-TDC/HELICS cd HELICS mkdir build cd build
Compile and Install¶
There are a number of different options and approaches at this point depending on your needs, in particular with respect to programming language support.
Note: For any of these options, if you want to install in a custom location, you can add the following CMake argument:
-DCMAKE_INSTALL_PREFIX=/path/to/install/folder/. There are also many other options, and you can check them out by running
ccmake . in the
Keep in mind running HELICS commands like
helics_app will not work from just any old random folder with a custom install folder.
You will either need to run them from inside the
bin subfolder of your custom install, or provide a more complete path to the command.
To run HELICS commands from any folder, you must add the
bin subfolder of your custom install to the
PATH environment variable. See the
first link in the Useful Resources section for details.
Basic Install (without language bindings)¶
Run the following:
ccmake . # optional, to change install path or other configuration settings
Building HELICS with MATLAB support¶
To install HELICS with MATLAB support, you will need to add run cmake with the
The important thing to note is that the MATLAB binaries are in the PATH.
mex must be available in the PATH.
Note: To check if
mex is in the PATH, type
which mex and see if it returns a PATH to the
If it does not, you should install MATLAB and add the path to all the MATLAB binaries to your PATH.
git clone https://github.com/GMLC-TDC/HELICS
cmake -DHELICS_BUILD_MATLAB_INTERFACE=ON -DCMAKE_INSTALL_PREFIX=$HOME/local/helics-main/ ..
Building HELICS MATLAB support manually¶
If you have changed the C-interface and want to regenerate the SWIG MATLAB bindings, you will need to use a custom version of SWIG to build the MATLAB interface. To do that, you can follow the following instructions.
Install SWIG with MATLAB
./configure --prefix=$HOME/local/swig_install; make; make install;
Ensure that SWIG and MATLAB are in the PATH
The below generates the MATLAB interface using SWIG.
swig -I../src/helics/shared_api_library -outdir ./matlab -matlab ./helics.i
mv helics_wrap.cxx matlab/helicsMEX.cxx
You can copy these files into the respective
HELICS/interfaces/matlab/ folder and run the cmake command above.
Alternatively, you wish to build the MATLAB interface without using CMake, and you can do the following.
mex -I../src/helics/shared_api_library ./matlab/helics_wrap.cxx -lhelicsSharedLib -L/path/to/helics_install/lib/helics/
mv helicsMEX.* matlab/
You will need HELICS installed correctly before the above can be run successfully.
Building HELICS using gcc¶
Firstly, you’ll need gcc. You can
brew install gcc. Depending on the version of gcc you’ll need to modify the following instructions slightly. These instructions are for
First you will need to build boost using gcc from source. Download the latest version of boost from the boost.org website. In the following example we are doing to use boost v1.69.0 Keep in mind that your cmake version should be newer than the boost version, so if you have an older cmake you may want an older boost version. Alternatively, you can choose to upgrade your version of cmake as well.
Unzip the folder
boost_1_69_0 to any location, for example Downloads.
$ cd ~/Downloads/boost_1_69_0
$ ./bootstrap.sh --prefix=/ --prefix=$HOME/local/boost-gcc-1.69.0
project-config.jam and changes the lines as follows:
# Compiler configuration. This definition will be used unless
# you already have defined some toolsets in your user-config.jam
# if ! darwin in [ feature.values <toolset> ]
# using darwin ;
# project : default-build <toolset>darwin ;
using gcc : 8.2 : /usr/local/bin/g++-8 ;
$ ./b2 install
$ # OR
$ ./bjam cxxflags='-fPIC' cflags='-fPIC' -a link=static install # For static linking
This will install boost in the
Next, you will need to build HELICS and tell it what the
$ cmake -DCMAKE_INSTALL_PREFIX="$HOME/local/helics-gcc-X.X.X/" -DBOOST_ROOT="$HOME/local/boost-gcc-1.69.0" -DCMAKE_C_COMPILER=/usr/local/Cellar/gcc/8.2.0/bin/gcc-8 -DCMAKE_CXX_COMPILER=/usr/local/Cellar/gcc/8.2.0/bin/g++-8 ../
$ make clean; make -j 4; make install
Basic test (without language bindings)¶
A quick test is to double check the versions of the HELICS player and recorder:
$ helics_player --version
$ helics_recorder --version
Testing HELICS with MATLAB support¶
To run the MATLAB HELICS extension, one would have to load the
helicsSharedLib in the MATLAB file.
This is run by the
helicsStartup function in the generated MATLAB files.
You can test this by opening MATLAB from the terminal or using the icon.
/Applications/MATLAB_R2017b.app/bin/matlab -nodesktop -nosplash -nojvm
Note: See Helics issue #763, if your installation doesn’t point the dylib to the correct location.
You can run the following in two separate windows to test an example from the following repository:
git clone https://github.com/GMLC-TDC/HELICS-examples
Run the following in one MATLAB instance
matlab -nodesktop -nosplash
Run the following in a separate MATLAB instance.
matlab -nodesktop -nosplash