[[PageOutline]]

= Documentation =

The MUSCLE library contains the API and configuration necessary to implement a multiscale model. Neither depends on the hardware that the model will executed on, whether that is local, distributed, or through a job scheduler. When using the Java API, the principle is write once, use everywhere. For C/C++ code, recompilation might be necessary depending on the operating system and hardware, but if the submodel code is standards-compliant, this should not pose a problem.

The MUSCLE runtime environment is then able to run the multiscale model on different resources. The actual runtime location only depends on the command-line arguments given to MUSCLE, not on the implementation of the submodels.

For getting started, see the [[Installation|Installation section]].

== The MUSCLE library ==

The MUSCLE library contains the means to write a submodel and couple it to other submodels. The design is such that submodels do not have to know with which other submodels they communicate, and the coupling is fixed later during configuration phase. The Java API is the most extensive, while the C++ and Fortran API provide the basic needed functionality. Also for performance reasons it may make sense to use the Java API.

* [[Java API|Java]]
* [[C++ API|C/C++]]
* [[Fortran API|Fortran]]
* [[Python API|Python]]
* [[MATLAB API|MATLAB]]

Configuration is done with a Ruby file with some MUSCLE-specific commands, here the coupling can be specified.

* [[Configuration|MUSCLE configuration file]]

To compile the model code, MUSCLE should be added to compile path.

* [[Compiling]]

=== Example code ===

The MUSCLE 2 package contains a lot of examples, showing its diverse functionalities. First of all, a few basic mappers are implemented in the directory {{{src/java/muscle/core/kernels}}}, filters in {{{src/java/muscle/core/conduit/filter}}} and terminals in {{{src/java/muscle/core/conduit/terminal}}}. For an overview of examples of complete but basic models, see:

* [[List of examples]]

A real world example of the astrophysics model Piernik is also available:

* [[Piernik]]

== The MUSCLE runtime environment ==

The runtime environment is managed by the muscle2 command-line program. It can be directly called, or through services such as QCG-Broker.

* [[Command-line execution]]

For the executing MUSCLE on multiple sites, a separate daemon is used for forwarding messages across administrative domains:

* [[MTO|Muscle Transport Overlay (MTO)]]

== Related tools and services ==

The `QCG-Computing` stack and `GridSpace` are external software products that support MUSCLE.

 * [[QCG-SimpleClient|QCG-SimpleClient (Command-line, single cluster)]]
 * [[QCG-Icon|QCG-Icon (Desktop application, single cluster)]]
 * [[QCG-AdvancedClient|QCG-AdvancedClient (Command-line, single and cross-cluster)]]
 * [[Toolchain|MaMe, MAD, GridSpace, QCG  Toolchain (Web application, single and cross-cluster)]]