HELICS with language bindings support

HELICS with Python

pip install helics should work for most use cases.

For developers and special use cases, the HELICS Python module code can be found in the PyHELICS repository.

HELICS with Java

To install HELICS with Java support, you will need to add HELICS_BUILD_JAVA_INTERFACE=ON.

HELICS with MATLAB

To install HELICS with MATLAB support, you will need to add HELICS_BUILD_MATLAB_INTERFACE=ON.

git clone https://github.com/GMLC-TDC/HELICS
cd HELICS
mkdir build
cd build
cmake -DHELICS_BUILD_MATLAB_INTERFACE=ON -DCMAKE_INSTALL_PREFIX=/Users/$(whoami)/local/helics-develop/ ..
make -j8
make install

On windows using visual studio the command line cmake would look like

cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX="C:\local\helics-develop" -DENABLE_SWIG=OFF -DHELICS_BUILD_MATLAB_INTERFACE=ON -G "Visual Studio 16 2019 Win64" ..

cmake --build . --config Release --target INSTALL

Cmake will search for the MATLAB executable and execute a mex command inside MATLAB to build the interface. For this operation to succeed MATLAB must be available and mex must be setup to use an appropriate C compiler. The setup is only required once for each MATLAB installation and does not need to repeated unless the compiler changes. From within MATLAB run

>>mex -setup

and follow the prompted instructions.

Reconstructing the files requires a specific version of SWIG with MATLAB support. If swig is not used then adding -DENABLE_SWIG=OFF to the cmake command will bypass swig and use the included interface files directly. If any modifications to the C library were made then swig must be used to regenerate the files appropriately, otherwise the existing files can be used. The CMAKE scripts will detect if the swig is the appropriate version and act accordingly.

Add the install directory path to the MATLAB files to your PATH. This can be the system path, or the MATLAB path through the addpath command or the graphical equivalent

>> addpath('path/to/helics/install/matlab')

Now in MATLAB, run the following:

helicsStartup
display(helics.helicsGetVersion())

The helics Startup usually isn’t required on Windows systems. Alternatively, you can load the HELICS library manually, depending on which operating system you use.

loadlibrary(GetFullPath('path/to/helics/install/libhelics.dylib'));
loadlibrary(GetFullPath('path/to/helics/install/libhelics.so'));
loadlibrary(GetFullPath('C:\path\to\helics\install\libhelics.dll'));

display(helics.helicsGetVersion())

This should print the version number of HELICS.

Optional

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=/Users/$USER/local/swig_install; make; make install;

  • Ensure that SWIG and MATLAB are in the PATH or specify them through the cmake-gui or ccmake. Then make sure swig is enabled and the Matlab files will be generated by SWIG and compiled through MATLAB.

Alternatively, you wish to build the MATLAB interface without using CMake, and you can do the following.

cd ~/GitRepos/GMLC-TDC/HELICS/swig/
mex -I../src/helics/shared_api_library ./matlab/helics_wrap.cxx -lhelics -L/path/to/helics_install/lib/helics/
mv helicsMEX.* matlab/

The above instructions will have to be modified slightly to support Windows, CMAKE is the recommended process for creating the MATLAB interface.

HELICS with Octave

To install HELICS with Octave support, you will need to add HELICS_BUILD_OCTAVE_INTERFACE=ON. Swig is required to build the Octave interface from source; it can be installed via package managers such as apt on Ubuntu or chocolatey on Windows, Octave can also be installed in this manner.

git clone https://github.com/GMLC-TDC/HELICS
cd HELICS
mkdir build
cd build
cmake -DHELICS_BUILD_OCTAVE_INTERFACE=ON -DCMAKE_INSTALL_PREFIX=/Users/$(whoami)/local/helics-develop/ ..
make -j8
make install

add the octave folder in the install directory to the octave path

>>helics
>> helicsGetVersion()
ans = 3.x.x (20XX-XX-XX)

Notes

Octave 4.2 will require swig 3.0.12, Octave 4.4 and 5.0 and higher will require swig 4.0 or higher. The Octave interface has built and run smoothly on Linux systems and on the Windows system with Octave 5.0 installed through Chocolatey. There is a regular CI test that builds and tests the interface on Octave 4.2.