Objective & Context

The goal here is to set up a fully functional Sim-Diasca installation, and to be able to test it and to develop with it, for example so that the implementation of new simulation cases and models can be directly experimented.

In the context of this public version, the installation will be performed:

• either from an archive (ex: Sim-Diasca-x.y.z.tar.bz2), supposedly already transmitted (typically after a request made through the contact form available at the official Sim-Diasca website (pointing, at the time of this writing, to this actual page)
• or from its official public repository

The operating system is supposed here to be GNU/Linux [3] (32 or, most probably, 64 bits):

(see the credits section about the comic strips)

Root access is not necessary, but recommended so that any lacking prerequisite can be installed directly and with little effort:

Some space on disk will be needed. 300 megabytes should be enough for the full Sim-Diasca install by itself, but, depending on your use, generated data (e.g. frames for simulation videos, plots of simulation results) could need a lot more additional space.

Finally, in all cases, i.e. even in the context of simulations to be run on a single machine (rather than in a distributed mode), the network configuration (on all hosts involved) must be adequate (notably so that any switch to a distributed mode of operation is as painless as possible).

Basic System-wide Network Settings

domain localdomain
nameserver xx.xx.xx.xx
[...]

127.0.0.1 localhost.localdomain localhost
::1       localhost
127.0.1.1 hurricane.localdomain hurricane
[...]

domain foobar.org
nameserver xx.xx.xx.xx
[...]

127.0.0.1 localhost.localdomain localhost
127.0.1.1 hurricane.foobar.org hurricane
[...]

$ erl -name my_test

Erlang/OTP 23 [erts-11.1.4] [source] [64-bit] [smp:8:8] [...]

Eshell V11.1.4  (abort with ^G)
(my_test@hurricane.foobar.org)1>

Software Prerequisites

This installation procedure is quite detailed and takes into account different cases. Applying it should not be too difficult or time-consuming, and anyway it just needs to be done once; upgrading the Sim-Diasca version will then be transparent afterwards.

Some best-effort support is generally available by email (see contact address at the top of this document), should an issue be encountered.

We preferred to list below the widest possible range of tools here. This includes:

• the UNIX basics (e.g. grep, awk, sed, etc.); your distribution is expected to provide them out of the box
• the software of which the simulation engine itself is composed (e.g. the Erlang runtime, the various intermediate layers)
• the third-party tools that most simulators may trigger for their own purpose (e.g. LogMX to monitor and browse simulation traces, gnuplot to render plots - one should ensure that its PNG support is enabled, possibly thanks to libgd - or graphviz to render graphs)
• the other tools that, depending on the use cases, may be relied upon in order to post-process or make use of the simulation results (e.g. mplayer, to display generated videos)
• finally, the toolchain that can be used to build the simulation engine and its dependencies (e.g. to recreate the Sim-Diasca trace parser based on LogMX)

$ sudo apt-get install bzip2 coreutils build-essential \
  libncurses5-dev openssl libssl-dev libwxgtk3.2-dev   \
  libgl1-mesa-dev libglu1-mesa-dev libpng16-16         \
  python3-docutils eog evince gnuplot-x11              \
  geeqie graphviz uuid-runtime mplayer ant             \
  default-jre texlive python3

Preparing the Sim-Diasca sources

The sources of Sim-Diasca can be obtained either from a Git repository (recommended approach) or from an archive file. Both cases are detailed below.

Installation From the Sim-Diasca Public Git Repository

Unless you have access to the EDF-internal Sim-Diasca Git repository (which should then be preferred, as it contains more content, and is by design more recent), you can clone the public Git repository (which should be fine as well [8]), at the following location: https://github.com/Olivier-Boudeville-EDF/Sim-Diasca.

[8]	Please tell us (typically thanks to the e-mail address at the top of this document) if ever the current public version seems to date back a bit too much, as we do not always update the public version once an internal one has been released.

It can thus be obtained, typically from a GNU/Linux host, thanks to:

$ git clone https://github.com/Olivier-Boudeville-EDF/Sim-Diasca

Then a right branch or tag shall be selected, knowing that versions bear annotated tags now labelled as: sim-diasca-x.y.z-version.

The master branch is the main one, and contains the latest public version of Sim-Diasca that has been released, so most people will happily stick to this master branch.

Note

The public repository is not the actual one that is used to develop Sim-Diasca, yet pull requests or any interaction may be based on it; if appropriate, we will take care of any integration that would be useful, and such improvements are to benefit to the community as a whole, in the next public versions to be released afterwards.

Installation From a Sim-Diasca Archive

You should have been given a Sim-Diasca archive, probably corresponding to a stable version (e.g. Sim-Diasca-a.b.c.tar.xz, like in Sim-Diasca-2.2.11.tar.xz) or a release candidate version, in the form of Sim-Diasca-a.b.c-rcd.tar.xz (like in Sim-Diasca-2.2.11-rc3.tar.xz). In 2015 we stopped using Semantic Versioning to switch back to the plain old versioning scheme.

In a directory on which you have read/write access and enough space left, extract that Sim-Diasca archive, using a proper tar incantation:

For example:

$ tar xvf Sim-Diasca-a.b.c.tar.xz

This should create a root directory named Sim-Diasca-a.b.c which contains all the relevant sources, including various top-level directories (myriad, wooper, traces, sim-diasca, etc.).

From now on, non-absolute paths (e.g. mock-simulators/soda-test/...) must be understood as being relative to this root directory.

Installing Erlang

Sim-Diasca is essentially written in Erlang, thus as soon as it will have to run on a given host, it will require a proper Erlang environment to be available on this host beforehand.

This means that all the computing hosts that may be used in the context of a distributed simulation must have access to such an Erlang environment, with compatible versions. There are various ways of ensuring it, including the cases where:

• an appropriate Erlang environment is already built-in on the host operating system
• the hosts have access to some shared infrastructure (e.g. a distributed filesystem, like NFS) - it is generally the case with HPC clusters
• a dedicated installation is performed on each of them

Although older versions of Erlang were supported (initially starting from R12B-5, released on November 5, 2008), API and typing changes require now using Erlang versions that are considerably more recent. One may preferably rely on the latest stable version available, as it is both more robust and efficient, and this is the one that is used by the developers of the engine. This version was usually in the form RxBy, like R16B, and now is named typically as OTP 23.2 at the time of this writing. As the engine relies on some features introduced in OTP 23.0, this version, or more recent, shall be used.

Erlang will then be preferably built from sources, rather than be installed thanks to the package manager of the distribution at hand, in order to benefit from an unmodified cutting-edge stable version that additionally will be built with the finely-tuned configuration deemed the most appropriate in a Sim-Diasca context [9].

$ sudo apt-get install g++ make libncurses5-dev libssl-dev libwxgtk3.2-dev \
  libgl1-mesa-dev libglu1-mesa-dev libpng16-16

For such an installation from sources, in the myriad/conf directory of the Sim-Diasca codebase a script named install-erlang.sh is provided [10].

If you have a direct connection to the Internet, it can automatically download the Erlang sources, and then build and install them appropriately; otherwise, typically if being behind a proxy, one may download first by oneself the relevant archives (namely OTP x.y Source File and OTP x.y HTML Documentation File) from here.

You can then either run the installation script "as is" (with or without a prefix being specified as parameter) or, if preferred, modify its settings appropriately beforehand, or just get inspiration from it instead and then install Erlang directly from the shell.

install-erlang.sh --help will provide more usage information, notably on whether it should be run as root or not, installed in a prefixed directory or in the system tree, with a selection of options (e.g. to prevent any attempt of downloading said archives), etc.

From a well-chosen, separate directory (e.g. ~/Software/Erlang, to avoid mixing the sources of Erlang with the ones of Sim-Diasca), one could run [11] for example:

$DIR/myriad/conf/install-erlang.sh

or, if a specific installation prefix is to be used:

$DIR/myriad/conf/install-erlang.sh /opt/my-tools-repository

In all cases, you should end up with an installed version of the latest stable source of Erlang.

Sim-Diasca developers could prefer installing automatically this version, along with its associated documentation, in an ad hoc software repository (e.g. ~/Software/Erlang/), where successive versions of the tools would be installed over time (it is quite convenient to switch versions).

The simplest and recommended approach is to run the installation script directly from such any software repository of choice (not located within the Sim-Diasca codebase), and to add the --doc-install option in order to obtain the documentation as well, like in:

$ mkdir -p ~/Software/Erlang
$ cd ~/Software/Erlang
$ $DIR/myriad/conf/install-erlang.sh --doc-install

Let's call V the Erlang version number selected by the script (e.g. V=23.2).

The actual installation directory will then be:

• if no prefix was specified (recommended case):
  • if the install script is run as root (not recommended), Erlang will be directly installed in /usr/local
  • otherwise (recommended): in ~/Software/Erlang/Erlang-$V
• if a prefix PREFIX was specified, installation will be done in PREFIX/Erlang/Erlang-$V

To allow for any later recompilation (e.g. should some options be changed), if no prefix was specified and if the installation script is not run as root, the Erlang build tree (otp_src_x.y) is not removed after the installation. Should the current directory (whence the user ran the installation script) be located within the build tree of any part of Sim-Diasca, the corresponding otp_src_x.y directory must be removed by the user, so that the Erlang BEAM files cannot be mixed up with the ones of that layer. In other cases, one may or may not prefer removing the OTP build tree or even the Erlang archives (typically otp_*_x.y.tar.gz).

If intending to make any actual development in the future (e.g. writing a specialized simulator, adding models or operating on the Sim-Diasca code itself), one should add the --generate-plt option to the install-erlang.sh command-line. It will pre-process Erlang files to generate a PLT file that will be later reused by the Dialyzer tool for code analysis. Please refer to the Using Type Specifications With Sim-Diasca section of the Sim-Diasca Developer Guide for further information.

Running the installation script should create, in the target installation directory, two corresponding sub-directories, Erlang-$V and Erlang-$V-documentation, containing respectively the Erlang runtime and its corresponding documentation, if it was selected.

Additionally, in this installation directory two symbolic links (Erlang-current-install and Erlang-current-documentation) will also be automatically created or updated, to point to these newly installed directories, so that one can register in one's settings files (e.g. ~/.bashrc) appropriate paths referring to these links: further Erlang updates will then not require the user to update his settings, while prior installed versions will remain available through the use of their full path.

So one may end up with a directory layout like:

$ tree -L 1 -d ~/Software/Erlang/
/home/dalton/Software/Erlang/
|-- Erlang-R14B
|-- Erlang-R14B-documentation
|-- Erlang-R16B
|-- Erlang-R16B-documentation
|-- Erlang-23.2
|-- Erlang-23.2-documentation
|-- Erlang-current-documentation -> Erlang-23.2-documentation
`-- Erlang-current-install -> Erlang-23.2

In the general case (i.e. unless run as root with no prefix specified), the new Erlang environment will be installed in a prefix, thus probably it will not be readily available from the shell. As a consequence one should ensure that the Erlang compiler (erlc) and the corresponding interpreter (erl) [13] can be found directly from the PATH (both are in the same directory).

For example, directly from a bash shell:

$ export PATH=~/Software/Erlang/Erlang-current-install/bin:$PATH
$ cd ~
$ type erl
erl is /home/dalton/Software/Erlang/Erlang-current-install/bin/erl

Setting also the relevant path, one time for all (rather than on a single short-lived terminal) in the shell configuration of the user (e.g. ~/.bashrc) is mandatory for further uses as well; as a consequence, please add the relevant export in the configuration file of your shell of choice.

Finally, two simple tests allow to ensure that Erlang can run flawlessly in this new environment. The first one allows to check that we are using the expected version and that it can indeed be run (you have to enter CTRL-C twice to close the Erlang shell afterwards):

$ cd
$ type erl
erl is /home/dalton/Software/Erlang/Erlang-current-install/bin/erl
$ erl
Erlang/OTP 23 [erts-11.1.4] [source] [64-bit] [smp:8:8] [ds:8:8:10] [async-threads:10] [hipe] [kernel-poll:false]

Eshell v11.1.4  (abort with ^G)

Second test allows to check that your network configuration allows to run a networked Erlang virtual machine with long names (enter again CTRL-C twice to exit):

$ erl -name this_is_a_test
Erlang/OTP 23 [erts-11.1.4] [source] [64-bit] [smp:8:8] [ds:8:8:10] [async-threads:10] [hipe] [kernel-poll:false]

Eshell V11.1.4  (abort with ^G)
(this_is_a_test@foo.bar.org )1>

Refer to the Name Resolving section should this test fail.

Installing LogMX

LogMX is the default tool used here to monitor the distributed simulation traces (refer to the Ceylan-Traces website for more information on that layer).

Using this proprietary tool is fully optional: adding the command-line option CMD_LINE_OPT="--batch" will disable its automatic launching by the engine. As, however, we believe that being able to easily inspect the simulation traces is essential in order to make the best use of the engine, we recommend to install this tool.

Although its purpose is only to allow to supervise the Sim-Diasca traces, its installation requires quite a lot of explanations, especially to deal with the case where the Sim-Diasca parser for LogMX has to be rebuilt from its sources (this is generally not needed, though).

A prerequisite to running LogMX is to have the Java SE Runtime Environment installed on the user host, preferably the (free software) OpenJDK version.

For example, Java 7 could suffice for LogMX:

$ java -version
java version "1.7.0_111"
OpenJDK Runtime Environment (IcedTea 2.6.7) (Arch Linux build 7.u111_2.6.7-1-x86_64)
OpenJDK 64-Bit Server VM (build 24.111-b01, mixed mode)

Otherwise the Sun (Oracle) version could be used, like in:

$ java -version
java version "1.6.0_10"
Java(TM) SE Runtime Environment (build 1.6.0_10-b33)
Java HotSpot(TM) Client VM (build 11.0-b15, mixed mode, sharing)

If not available, either the package manager of the distribution [14] or this link for the Sun version should be used.

Note that if only the Java SE Runtime Environment (i.e. the JRE) is installed (instead of the Java SE Development Kit, i.e. the JDK), then Java code can be executed indeed, but not generated.

However both cases should work, since using a recent JRE should spare the rebuilding of the Sim-Diasca parser (and hence the use of the JDK).

$ mkdir -p ~/Software/LogMX
$ cd ~/Software/LogMX
$ cp ~/LogMX_vx.y.z.zip .
$ unzip LogMX_vx.y.z.zip

Setting Up LogMX

Configuration Files

Sim-Diasca provides, in the traces/conf/logmx directory, the following configuration files:

• logmx.properties
• managers.properties
• parsers.properties

They should be copied in the LogMX config directory. These files should overwrite the default LogMX ones. For example:

$ for f in logmx.properties managers.properties parsers.properties; do \
/bin/cp traces/conf/logmx/$f ~/Software/LogMX/LogMX_vx.y.z/config ;    \
done

Note

If you purchased the LogMX professional version, copy the license.properties file that you obtained in the LogMX config directory instead of the supplied one (and of course keep the other properties-related files).

The LogMX script must then be set to executable:

$ chmod +x ~/Software/LogMX/LogMX_vx.y.z/logmx.sh

Identically to Erlang, the LogMX script must be found from the path. For example, with a bash shell:

$ export PATH=~/Software/LogMX/LogMX_vx.y.z:$PATH
$ cd ~
$ type logmx.sh
logmx.sh is /home/dalton/Software/LogMX/LogMX_vx.y.z/logmx.sh

Setting also the relevant path in the shell configuration (e.g. ~/.bashrc) is recommended for further uses.

A best practise for that is to install all custom software in a base directory (e.g. ~/Software/), with a sub-directory for each tool (e.g. ~/Software/LogMX/). Then all successive versions of that tool could be installed here (e.g. ~/Software/LogMX/LogMX_v7.3.0/).

Finally, a symbolic link pointing to the latest current version could be defined when installing a new version of that tool (e.g. cd ~/Software/LogMX/; ln -sf LogMX_v7.3.0 LogMX-current-install).

That way, one just has to specify in one's shell configuration:

export PATH=~/Software/LogMX/LogMX-current-install:$PATH

This is thus done once for all, it will not have to be updated when upgrading LogMX.

LogMX should then be run "as is", to ensure that it has a chance to run later, when the Sim-Diasca parser will be plugged-in:

$ logmx.sh

After up to a few seconds, a LogMX window should successfully pop up. Then close that window.

Note

On some LogMX versions, running this logmx.sh script will output a line on the console complaining about a startup.conf file being not found, or printing [: 86: 1: unexpected operator and [: 86: 0: unexpected operator.

A simple solution is to edit logmx.sh and replace the STARTUP_CONF_FILE="startup.conf" line (around line 35) by STARTUP_CONF_FILE=/dev/null.

Setting Up the Sim-Diasca Trace Parser

Due to Java, this is probably the trickiest (optional, yet recommended) part of a Sim-Diasca install.

Using The Prebuilt Sim-Diasca Parser

In the traces/conf/logmx directory, there is a prebuilt Java class, CeylanTraceParser.class, a generic parser we developed for Sim-Diasca and other tools.

If the Java environment installed on the host is recent enough (which is very likely), then that class file will be directly usable, without further need of recompiling it.

Best option is to try to use it directly, and to rebuild the parser only if this fails.

That file should just be copied to the right location:

$ CLASS_DIR=~/Software/LogMX/LogMX_vx.y.z/parsers/classes/ceylan/parser
$ mkdir -p $CLASS_DIR
$ cp traces/conf/logmx/CeylanTraceParser.class $CLASS_DIR

Checking That The Sim-Diasca Parser Works Properly

To do so, just test, from the root of the sources, whether LogMX and the Sim-Diasca parser are correctly integrated, with a sample of Sim-Diasca traces:

$ logmx.sh traces/conf/logmx/TraceSample.txt

You can skip next section if you see something like:

Otherwise, an error like Error while instantiating parser must have been reported: your Java environment is most probably not appropriate (too old?), and, if you are not able to upgrade the Java interpreter that you are using, then unfortunately the parser will have to be rebuilt with all the Java bells and whistles, as explained in the next section (usually this issue does not occur, and one can thus jump directly to the Checking Which Tools Sim-Diasca Will Use section).

Building The Sim-Diasca Trace Parser

The Java SE Development Kit (i.e. the JDK) and Ant are needed here.

They can be installed either thanks to the distribution, for example:

$ sudo apt-get install openjdk-8-jdk ant
   - or -
$ sudo apt-get install sun-java8-jdk ant

or they can be retrieved from their respective official sites (1, 2), if not directly built and installed from sources (for Ant).

Then the Sim-Diasca parser source file should be placed at the right location in the LogMX tree, and built:

$ PARSER_SRC_DIR=~/Software/LogMX/LogMX_vx.y.z/parsers/src/ceylan/parser
$ mkdir -p $PARSER_SRC_DIR
$ cp traces/conf/logmx/CeylanTraceParser.java $PARSER_SRC_DIR
$ cd ~/Software/LogMX/LogMX_vx.y.z/parsers
$ ant
Buildfile: build.xml
clean:
mkoutdir:
 [mkdir] Created dir: ~/Software/LogMX/LogMX_vx.y.z/parsers/classes
build-dev:
 [javac] Compiling 1 source file to ~/Software/LogMX/LogMX_vx.y.z/parsers/classes
BUILD SUCCESSFUL
Total time: 2 seconds

This should imply that CeylanTraceParser.class has been successfully built.

Test the result like explained before, in Checking That The Sim-Diasca Parser Works Properly.

Enabling the Python binding if needed: installing ErlPort

In the context of the evaluation of a dataflow, some simulation actors may be implemented in Python, in which case the (fully-optional) Python dataflow binding shall be enabled (see the USE_PYTHON_BINDING variable in myriad/GNUmakevars.inc for that). One should skip this section if not planning to use Python-based (dataflow) actors.

$ mkdir -p ~/Software/bin
$ cd ~/Software/bin

$ ln -s ~/Software/Python/Python-3.6.3-current-install/bin/python3.6
          python-for-sim-diasca
  or
$ ln -s /usr/bin/python3 python-for-sim-diasca

export PATH=~/Software/bin:${PATH}

$ tree -L 1 ~/Software/ErlPort
/home/batman/Software/ErlPort
|-- erlport
`-- ErlPort-current-install -> erlport/

$ ERL_PORT_BASE=~/Software/ErlPort
$ mkdir -p ${ERL_PORT_BASE}
$ cd ${ERL_PORT_BASE}
# Circumvent any proxy here.
$ git clone https://github.com/hdima/erlport.git
$ ln -s erlport ErlPort-current-install
$ cd erlport
# The SHA1 we currently rely on:
$ git checkout 246b77

from inspect import getargspec

from inspect import getfullargspec

-        Type:Reason ->
-            Trace = erlang:get_stacktrace(),
-            {error, {erlang, Type, Reason, Trace}}
+        Type:Reason:StackTrace ->
+             {error, {erlang, Type, Reason, StackTrace}}

Checking Which Tools Sim-Diasca Will Use

It is mandatory to have Sim-Diasca know where the tools it needs can be found. To check which main tools would be used, run from the sim-diasca directory:

$ make info-tools
ERLANG_INTERPRETER = ~/Software/Erlang/Erlang-current-install/bin/erl
ERLANG_COMPILER = ~/Software/Erlang/Erlang-current-install/bin/erlc
LOGMX = ~/Software/LogMX/LogMX-current-install/logmx.sh

Some tools will be only used by this make system, whereas others, the majority of them (e.g. the Erlang interpreter and compiler) will be used by the simulator as well.

Therefore the path to the former ones could be set directly in the makefiles only. However it is generally more convenient that the latter ones are found directly from the shell environment, so that both the Make system and the simulator will find them with the same correct versions.

If a make-only tool is lacking, edit the GNUmakevars.inc file of the relevant package (e.g. the one of myriad, wooper, traces, sim-diasca, etc.) accordingly.

If another tool is lacking, then the shell environment should be updated. This involves updating - most preferably, once for all - the PATH environment variable.

This can be done by adding PATH=/a/path/to/a/lacking/tool:$PATH to the shell init file (e.g. ~/.bashrc) and sourcing it again (. ~/.bashrc).

Re-run make info-tools and apply changes until the make system selects the exact tool versions you want.

Building Sim-Diasca

The good news is that Sim-Diasca is written in Erlang, thus it requires to be compiled:

The bad news is that it will not take long, only up to a few minutes, as it is itself parallel on each package.

It is just a matter of running make from the Sim-Diasca source root, i.e. its base directory, which contains the myriad, wooper, traces, etc. directories.

If using a clone, go to this root typically by entering cd sim-diasca-clone. If using a file release, it will be: cd Sim-Diasca-clone.

Then:

$ make all
Building all, sequentially, in [..]/Sim-Diasca-clone
Building all, in parallel over 8 cores, from [..]/myriad
Building all in [..]/Sim-Diasca-clone/myriad/contrib
Building all in [..]/Sim-Diasca-clone/myriad/src
           Compiling module hashtable.erl
           Compiling module hashtable_test.erl
           Compiling module hashtables_comparison_test.erl
[...]
Building all, in parallel over 8 cores, from [..]/wooper
[...]
Building all, in parallel over 8 cores, from [..]/traces
[...]
Building all, in parallel over 8 cores, from [..]/sim-diasca
[...]
Building all, in parallel over 8 cores, from [..]/mock-simulators
[...]

Then you should have a version of Sim-Diasca properly built, and fully able to run, locally or not.

However, should multiple computing hosts be used, a few system-level checks shall be performed first, to ensure that the distributed mode of operation is correctly enabled - as discussed in the next section.

Just before, a note about what we believe is a rather common network misconfiguration of too many Linux computers, which may impact even local, single-host simulations [17]: one should ensure that, if FQDN hostnames are associated to IPs for the local host in /etc/hosts (e.g. 127.0.1.1 hurricane.foobar.org hurricane), their domain matches the one (if any) specified in /etc/resolv.conf.

Often one can see there domain localdomain (instead of, say, domain foobar.org), which may lead to resolve the local FQDN as hurricane.localdomain instead of hurricane.foobar.org (which may be a problem at least for the Erlang VM).

Enabling The Distributed Mode Of Operation

A key point of scalability lies in the possibility of harnessing distributed resources.

In a distributed context, Sim-Diasca must be able to make use of the computing resources available in other networked hosts.

To do so, the Sim-Diasca agents must be already running - and thus be already installed - on each of the targeted hosts before a simulation relying on them is run.

Of course, the user could log on each of these hosts, and install then launch manually the agents needed, however this process would be quite cumbersome and could not scale up. Sim-Diasca can fully perform this deployment task on the user's behalf instead (installation and execution), if proper settings are used. Then it is sufficient either to list the candidate hosts that can be used, or to run the higher-level cluster scripts that we provide (for which the amount of processing resources required has just to be specified).

One has mainly to ensure that the network is correctly configured and that, with one's account, a SSH password-less login can be performed from the current computer to all targeted remote hosts, which are expected to already have an Erlang environment directly available.

From now on, the user node will designate the Erlang node from which the user will run the simulation (e.g. the one created when issuing a command like make my_simulation_run from the user shell). That Erlang node will never take part directly to the computing. However, depending on the simulation settings, the host this node runs on may or may not be used as a computing resource, thanks to the automatic creation of another (local, simulation-dedicated) computing node.

One can also refer to the distributed cheat sheet of the Sim-Diasca Technical Manual for further guidance.

$ hostname
hurricane

$ hostname -f
hurricane.foobar.org

127.0.0.1 hurricane.foobar.org hurricane localhost.localdomain localhost

foobar@host_a.foobar.org$ ssh-keygen -t rsa
Generating public/private rsa key pair.
Enter file in which to save the key (/home/foobar/.ssh/id_rsa):
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /home/foobar/.ssh/id_rsa.
Your public key has been saved in /home/foobar/.ssh/id_rsa.pub.
The key fingerprint is: XX:XX:XX... foobar@host_a.foobar.org

foobar@host_a.foobar.org$ ssh-copy-id -i \
   ~/.ssh/id_rsa.pub host_b.foobar.org

foobar@host_a.foobar.org$ scp ~/.ssh/id_rsa.pub \
  foobar@host_b.foobar.org:/home/foobar/.ssh/id_rsa-from-host_a.pub

foobar@host_b.foobar.org$ cat /home/foobar/.ssh/id_rsa-from-host_a.pub \
   >> /home/foobar/.ssh/authorized_keys
foobar@host_b.foobar.org$ chmod 600 /home/foobar/.ssh/authorized_keys
foobar@host_b.foobar.org$ chmod 700 /home/foobar/.ssh

foobar@host_a.foobar.org$ ssh host_b.foobar.org
last login: XXX
foobar@host_b.foobar.org$

The authenticity of host 'Server (XXXXX)' can't be established. RSA key
fingerprint is YYYYY. Are you sure you want to continue connecting (yes/no)?

$ ssh -q foo.bar.org erl -eval \
   '"io:format( \"This host would use Erlang version ~s.~n\", \
   [erlang:system_info(otp_release)]), erlang:halt()."'

Eshell V7.3  (abort with ^G)
This host would use Erlang version 18.

$ epmd -kill

Testing Sim-Diasca

Several test cases that can be run to experiment with Sim-Diasca: when a class X is defined (in class_X.erl), it is recommended to add a corresponding unitary test case (in class_X_test.erl).

To run such a test, once Sim-Diasca has been successfully built, one just has to go to the directory where that test is defined, and to run make class_X_run: the Sim-Diasca Make system will take care of compiling this test if needed and run it with an appropriately-configured Erlang interpreter.

For example, if wanting to run a Sim-Diasca built-in soda-vending test:

$ cd mock-simulators/soda-test/src
$ make
$ make demo-batch

Your console should be filled by much text similar to:

$ make demo-batch

make[1]: Entering directory 'A_ROOT_DIR/mock-simulators/soda-test/src'
       Running unitary test soda_stochastic_integration_run (third form)
       from soda_stochastic_integration_test
Launching the Erlang VM in non-distributed mode.
Erlang/OTP 19 [erts-8.1] [source] [64-bit] [smp:8:8] [async-threads:128]
[hipe] [kernel-poll:true]

Eshell V8.1  (abort with ^G)

1>
Simulation instance identifier is '46672710'.
Simulation trace file is
'Soda_Stochastic_Integration_Test-by-dalton-46672710.traces';
no interactive supervision requested.

The single specified computing host is available, using corresponding
node: 'Sim-Diasca-Soda_Stochastic_Integration_Test-dalton-46672710-computing-node@foobar.org'.

Use cookie '315bf70c-b6f1-4ff2-be23-f85832c08c31' to connect to the
nodes (user or computing ones).

[...]

[Trace Aggregator] Aggregator deleted.
End of case soda_stochastic_integration_test
(case finished, interpreter halted)
make[1]: Leaving directory 'A_ROOT_DIR/mock-simulators/soda-test/src'

Congratulations, a full simulation case just ran successfully!

One may then go one step further and test also a non-batch, more graphical mode of operation by running:

$ make demo

Three windows should pop up [21]:

• a first Geeqie/Gqview window, displaying the two simulation results (two time series) as graphs (plots), representing the number over time of cans available in each of the two soda vending machines
• a second Geeqie/Gqview window, displaying the measures aggregated by the performance tracker (resource consumption, number of instance per node, etc.), if this service is enabled (true by default)
• a LogMX console, for the supervision of the distributed simulation traces (if traces are enabled, which is true by default)

When not useful any more, all windows can be safely closed. The end of the simulation session occurs when the trace supervision window is closed.

Should a problem arise, please have a look at the Sim-Diasca Troubleshooting section of the Sim-Diasca Technical Manual.

To further discover how Sim-Diasca works and can be used, the next steps could be to peer in the source code of tests and of classes, before playing around and adding some toy models.

Installing Sim-Diasca

This completely optional action (that is generally not needed) allows to install all Sim-Diasca related packages (i.e. the Myriad, WOOPER, etc. packages), and Sim-Diasca itself, out of the build tree.

To do so, one just has to execute, from the top source directory (the one that contains the top-level directories like sim-diasca, wooper, etc.):

$ make install

In this case everything will be installed in the default ~/Software directory, which will be created if not existing already.

The user can specify any other installation directory instead, by defining the INSTALLATION_PREFIX variable, like in:

$ make install INSTALLATION_PREFIX=/opt/my-simulator

In all cases, under the installation directory, all Sim-Diasca related packages will be properly installed, mostly according to the Erlang recommended practices (i.e. with a hierarchy based on standard nested directories like ebin, examples, include, src, test, etc.).

Credits

Special thanks to Randall Munroe who is the author of all the comic strips that enliven this documentation, and who kindly allowed their use in this material.

See his XKCD website for all information, including for all his delightful other strips.

Please React!

If you have information more detailed or more recent than those presented in this document, if you noticed errors, neglects or points insufficiently discussed, drop us a line! (for that, follow the Support guidelines).

Support

Bugs, questions, remarks, patches, requests for enhancements, etc. regarding the installation procedure are to be reported to the project interface (typically issues) or directly at the email address mentioned at the beginning of this document.

Ending Word

We hope that the installation went smooth!

Now is maybe a good time to run some examples found in the mock-simulators tree (located at the root of the Sim-Diasca clone) - typically a soda-test?