Installation

The recent bundle of MUSCLE can be downloaded from the  Downloads section. The bundled package contains the source code, documentation and precompiled Java archives (jar).

The offered version of MUSCLE in several places extends and improve the  package provided by Jan Hegewald. We can list here the following elements:

  • simplified installation procedure (some dependencies are already included in the bundle),
  • added support for generation of OTF trace logs,
  • implemented Port Range traversing technique for cross-cluster execution.

Dependencies

The core functionality of the MUSCLE is written in Java. To be able to integrate native code with the MUSCLE, there is also a native part which is written in C++. Bootstrapping and platform independent configuration is done with a highly flexible setup mechanism written in Ruby.

In order to use the MUSCLE, you need a recent Java runtime. You can obtain it at either  http://www.java.com/en/download/index.jsp (Sun-Java) or  http://openjdk.java.net/ (Open-JDK).

A Ruby installation can be downloaded from:  http://www.ruby-lang.org/en/downloads/. The MUSCLE does currently not work with Ruby 1.9.1 or newer.

General Instructions

If the dependencies are in place, you are ready to use MUSCLE. In general no compilation is required! Extract the download, e.g.

$ unzip muscle-1.0.1.zip

Change your working directory to the the MUSCLE directory:

$ cd muscle-1.0.1

See if MUSCLE is working correctly:

$ ./src/ruby/muscle.rb --version

In case you plan to use MUSCLE with native code, you will have to compile the native library part of MUSCLE using a C++ compiler (such as g++). The build script belonging to MUSCLE also has a target to build the native libraries. This requires a C++ compiler and CMake ( http://www.cmake.org/) to be available. You can also use your favourite IDE/build system instead.

What’s in the bundle?

The MUSCLE download bundle contains the following items:

  • build - This directory contains the compiled Java bytecode and C++ libraries.
  • build.rb - The build script. It can compile the java sources, build jar archives build the native shared libraries.
  • CMakeLists.txt - The configuration file for cmake. Only needed if the native libraries are to be built. This file is used by the build.rb, you do not have to call cmake manually.
  • doc - The documentation files.
  • OTF - The configuration and helper scripts for OTF trace logger.
  • src - This directory contains the MUSCLE source code.
  • thirdparty - The MUSCLE will automatically load third-party libraries which are in this directory.

Installation example - Scientific Linux 5.6

Note: Some part of the presented installation procedure requires to be invoked by root.

  1. Check if proper version of ruby is already installed in the system, otherwise install it:
    ruby --version
    -bash: ruby: command not found
    
    yum install ruby
    ...
    ruby --version
    ruby 1.8.5 (2006-08-25) [x86_64-linux]
    
  1. Ensure if you have a c++ compiler available on your system. If you have not, install this:
    yum install gcc-c++
    
  1. Check if cmake is available, otherwise install cmake:
    yum install cmake
    
    Note: you may need to add the reference to the repositorium with extra packages. To do this you need to create the file 'epel.repo' in the /etc/yum.repos.d directory. The content of the file may look as follows:
    [epel]
    name=Extra Packages for Enterprise Linux 5 - $basearch 
    
    #baseurl=http://download.fedoraproject.org/pub/epel/5/$basearch
    mirrorlist=http://mirrors.fedoraproject.org/mirrorlist?repo=epel-5&arch=$basearch
    failovermethod=priority
    enabled=1
    gpgcheck=0
    
  1. Check if recent Java SE Runtime Environment (JRE) or Java SE Development Kit (JDK) are present in your system. As the precompiled MUSCLE package is already included at build/muscle.jar you may not need to compile the Java sources and JRE should be sufficient. Hovewer, if you want to recompile the Java part of the MUSCLE (recommended), a recent Java compiler is also required.
    yum install jdk
    
  1. Set required environment variables, e.g.
    export JAVA_HOME=/usr/java/jdk1.6.0_26
    export PATH=$JAVA_HOME/bin:$PATH
    
  1. Download the muscle bundle from  Downloads section, e.g.
    wget http://apps.man.poznan.pl/trac/muscle/downloads/muscle-1.0.1.zip
    
  1. Extract the package:
    unzip muscle-1.0.1.zip
    
  1. Recompile entire MUSCLE:
    cd muscle-1.0.1
    ./build.rb all
    
  1. See if the MUSCLE is working:
    ./src/ruby/muscle.rb --version
    

Sample execution

There are some examples which belong to the MUSCLE bundle. Example code for kernels can be found in the directories java/examples and cpp/examples. There are also prepared configurations for coupled examples CxA (MUSCLE simulations), which can be found in the cxa directory.

Hello World

Sender

At java/examples/simplejava/Sender we provide a minimalist kernel written in Java, which sends data (an array of double).

Receiver

At java/examples/simplejava/ConsoleWriter we provide a simple kernel written in Java. It receives data (an array of double) and prints its content to the standard output.

CxA (coupling schema)

The configuration cxa/SimpleExample.cxa.rb configures a minimal CxA which couples the java/examples/simplejava/Sender and java/examples/simplejava/ConsoleWriter kernels.

Execution

To run the simmulation defined in cxa/SimpleExample.cxa.rb use the following command:

./src/ruby/muscle.rb --cxa_file src/cxa/SimpleExample.cxa.rb --main plumber w r --autoquit

Further reading

For more information how to install and run MUSCLE see doc/muscle_developers_guide.pdf included in the MUSCLE bundle. For more information how to install and run MUSCLE see doc/muscle_developers_guide.pdf.