Changes between Version 17 and Version 18 of Tutorials

Show
Ignore:
Timestamp:
09/12/13 11:13:51 (11 years ago)
Author:
jorisborgdorff
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • Tutorials

    v17 v18  
    22 
    33There are some [[Documentation#Examplecode|examples provided]] within the MUSCLE bundle. Example code for kernels can be found in the directories {{{src/java/examples}}} and {{{src/cpp/examples}}}. There are also prepared configurations for coupled examples CxA (MUSCLE simulations), which can be found in the {{{src/cxa}}} directory. 
    4  
    5 === Running {{{SimpleExample}}} === 
    6  
    7  Sender:: 
    8    In {{{src/java/examples/simplejava/Sender.java}}} we provide a minimalist kernel written in Java, which sends data (an array of double). 
    9  
    10  Receiver:: 
    11    In {{{src/java/examples/simplejava/ConsoleWriter.java}}} we provide a simple kernel written in Java. It receives data (an array of double) and prints its content to the standard output. 
    12  
    13  CxA (coupling schema):: 
    14    The configuration {{{src/cxa/SimpleExample.cxa.rb}}} configures a minimal CxA which couples the {{{examples.simplejava.Sender}}} and {{{examples.simplejava.ConsoleWriter}}} kernels. 
    15  
    16  Execution:: 
    17    To run the simulation defined in src/cxa/SimpleExample.cxa.rb use the following command: 
    18    {{{ 
    19    muscle2 --cxa src/cxa/SimpleExample.cxa.rb --main --allkernels 
    20    }}} 
    21    or in shorthand notation 
    22    {{{ 
    23    muscle2 -c src/cxa/SimpleExample.cxa.rb -am 
    24    }}} 
    25    It will first start the Simulation Manager, of which one per simulation is necessary, and then the local manager, which manages the kernels that are started with one {{{muscle2}}} invocation. 
    264 
    275== Full MUSCLE tutorial == 
    … …  
    3513 
    36142. To add MUSCLE to the path and set a few environment variables, run the following (don't forget the dot at the start!): 
    37 {{{ 
    38  . [MUSCLE_DIR]/etc/muscle.profile 
    39 }}} 
     15  {{{ 
     16   . [MUSCLE_DIR]/etc/muscle.profile 
     17  }}} 
    4018 
    41193. Now you can run `muscle2`. We will show its functionality with an example model that is packaged with MUSCLE. First go to the unzipped MUSCLE folder, and try to read `src/cxa/SimpleSubmodelExample.cxa.rb` and see what it does. To show the submodels that the example contains, run: 
    42 {{{ 
    43  cd .. 
    44  muscle2 --cxa src/cxa/SimpleSubmodelExample.cxa.rb  
    45 }}} 
    46  
    47 This example has a writer submodel `w` and a reader submodel `r`. The writer sends data to the reader, and the reader prints that data to screen. 
    48  
    49 You can run the simple example by specifying that the current MUSCLE command will run the Simulation Manager with the `--main` flag or its shorthand `-m`, and specifying all submodels that should run in this command: 
    50 {{{ 
     20  {{{ 
     21   cd .. 
     22   muscle2 --cxa src/cxa/SimpleSubmodelExample.cxa.rb  
     23  }}} 
     24 
     25  This example has a writer submodel `w` and a reader submodel `r`. The writer sends data to the reader, and the reader prints that data to screen. 
     26 
     27  You can run the simple example by specifying that the current MUSCLE command will run the Simulation Manager with the `--main` flag or its shorthand `-m`, and specifying all submodels that should run in this command: 
     28  {{{ 
    5129 muscle2 -mc src/cxa/SimpleSubmodelExample.cxa.rb w r 
    52 }}} 
    53  
    54 Usually, if you want to run all the submodels instances with the current MUSCLE command, specify the `--allinstances` or its shorthand `-a`: 
    55 {{{ 
    56  muscle2 -amc src/cxa/SimpleSubmodelExample.cxa.rb 
    57 }}} 
    58  
    59 So what do we observe? MUSCLE detects that it should start the Simulation Manager and a Simulation. It first starts the manager, which shows its TCP/IP address. Then the Simulation starts and it executes the submodel instances `w` and `r`. These start their respective conduits, and start 'computing'. 
    60  
    61 On local machines, these commands are sufficient to run any MUSCLE model. You can try the other examples in the `src/cxa` directory, just run 
    62 {{{ 
    63  muscle2 -amc src/cxa/[...].cxa.rb 
    64 }}} 
     30  }}} 
     31 
     32  Usually, if you want to run all the submodels instances with the current MUSCLE command, specify the `--allinstances` or its shorthand `-a`: 
     33  {{{ 
     34  muscle2 -amc src/cxa/SimpleSubmodelExample.cxa.rb 
     35  }}} 
     36 
     37  So what do we observe? MUSCLE detects that it should start the Simulation Manager and a Simulation. It first starts the manager, which shows its TCP/IP address. Then the Simulation starts and it executes the submodel instances `w` and `r`. These start their respective conduits, and start 'computing'. 
     38 
     39  On local machines, these commands are sufficient to run any MUSCLE model. You can try the other examples in the `src/cxa` directory, just run 
     40  {{{ 
     41  muscle2 -amc src/cxa/[...].cxa.rb 
     42  }}} 
    6543 
    66444. Scientific applications that are started remotely generally do not have a direct feedback to a user interface, but we will run one that does. This is why we logged in with the -X flag of SSH in step 2. 
    67 {{{ 
     45  {{{ 
    6846  muscle2 -amc src/cxa/LaplaceExample.cxa.rb 
    69 }}} 
    70  
    71 It will open two windows that compute temperature dissipation, that are coupled on the boundary. Red is a +1 temparature, blue a -1 temperature, and green a zero temperature. The initial condition, far right and far left correspond to zero temperature, the top to a sine function and the bottom to a cosine. Temperature is dissipated during each time step by taking the average of the four neighboring cells. The adjacent boundary is transmitted each iteration. 
     47  }}} 
     48 
     49  It will open two windows that compute temperature dissipation, that are coupled on the boundary. Red is a +1 temparature, blue a -1 temperature, and green a zero temperature. The initial condition, far right and far left correspond to zero temperature, the top to a sine function and the bottom to a cosine. Temperature is dissipated during each time step by taking the average of the four neighboring cells. The adjacent boundary is transmitted each iteration. 
    7250 
    73515. Take a look at all the options by running 
    74 {{{ 
     52  {{{ 
    7553 muscle2 
    76 }}} 
     54  }}} 
    7755 
    7856== Part 2: distributed execution == 
    … …  
    8159 
    82601. Open a second terminal, and log in to another machine, or try it on the same machine. When logged in do 
    83 {{{ 
    84  . [MUSCLE_DIR]/etc/muscle.profile 
    85 }}} 
    86  
    87 Then go to the unzipped MUSCLE directory. Now we can run muscle on the same site. In the first terminal window, start the main MUSCLE with the writing submodel w. This is done by typing: 
    88 {{{ 
    89  muscle2 -mc src/cxa/SimpleSubmodelExample.cxa.rb w 
    90 }}} 
    91  
    92 So what do you observe? 
    93  
    94 One of the most important messages is `Started the connection handler, listening on [IPADDRESS:PORT]`. 
    95 Copy the IP address and port number. 
    96 In the second terminal, start the reading submodel r, and at the end put the `-M` or `--manager` flag 
    97 with the IP address and port: 
    98 {{{ 
    99  muscle2 -c src/cxa/SimpleSubmodelExample.cxa.rb r -M [IPADDRESS:PORT] 
    100 }}} 
    101  
    102 What happens in both terminals? 
     61  {{{ 
     62   . [MUSCLE_DIR]/etc/muscle.profile 
     63  }}} 
     64 
     65  Then go to the unzipped MUSCLE directory. Now we can run muscle on the same site. In the first terminal window, start the main MUSCLE with the writing submodel w. This is done by typing: 
     66  {{{ 
     67   muscle2 -mc src/cxa/SimpleSubmodelExample.cxa.rb w 
     68  }}} 
     69 
     70  So what do you observe? 
     71 
     72  One of the most important messages is `Started the connection handler, listening on [IPADDRESS:PORT]`. 
     73  Copy the IP address and port number.  
     74  In the second terminal, start the reading submodel r, and at the end put the `-M` or `--manager` flag 
     75  with the IP address and port: 
     76  {{{ 
     77   muscle2 -c src/cxa/SimpleSubmodelExample.cxa.rb r -M [IPADDRESS:PORT] 
     78  }}} 
     79 
     80  What happens in both terminals? 
    10381 
    104822. To isolate the output from the Simulation Manager, we can run it separately. 
    10583 
    106 In the first terminal window, start the Simulation Manager: 
    107 {{{ 
    108  muscle2 -mc src/cxa/SimpleSubmodelExample.cxa.rb 
    109 }}} 
    110  
    111 In the second terminal, start the submodels. Again, replace the port number 
    112 with the one that is printed by the Simulation Manager. 
    113 {{{ 
    114  muscle2 -ac src/cxa/SimpleSubmodelExample.cxa.rb -M [IPADDRESS:PORT] 
    115 }}} 
    116  
    117 What happens in both terminals? 
     84  In the first terminal window, start the Simulation Manager: 
     85  {{{ 
     86   muscle2 -mc src/cxa/SimpleSubmodelExample.cxa.rb 
     87  }}} 
     88 
     89  In the second terminal, start the submodels. Again, replace the port number 
     90  with the one that is printed by the Simulation Manager. 
     91  {{{ 
     92   muscle2 -ac src/cxa/SimpleSubmodelExample.cxa.rb -M [IPADDRESS:PORT] 
     93  }}} 
     94 
     95  What happens in both terminals? 
    11896 
    119973. To do distributed computing, also install MUSCLE on another node 
    120 {{{ 
    121  ssh user@node2 
    122  [INSTALL MUSCLE...] 
    123  . MUSCLE_DIR/etc/muscle.profile 
    124 }}} 
    125  
    126 And go to the source directory of MUSCLE. We will perform the same experiment, 
    127 but now on different hosts. So on the first node, for instance run only `w` 
    128 {{{ 
    129  muscle2 -mc src/cxa/SimpleSubmodelExample.cxa.rb w 
    130 }}} 
    131  
    132 On the other node, we now also need to specify which host and port the other 
    133 MUSCLE instance is running on 
    134 {{{ 
    135  muscle -c src/cxa/SimpleSubmodelExample.cxa.rb -M [IPADDRESS:PORT] r 
    136 }}} 
    137  
    138 What is the output in node one? And on the other? 
     98  {{{ 
     99  ssh user@node2 
     100  [INSTALL MUSCLE...] 
     101  . MUSCLE_DIR/etc/muscle.profile 
     102  }}} 
     103 
     104  And go to the source directory of MUSCLE. We will perform the same experiment, 
     105  but now on different hosts. So on the first node, for instance run only `w` 
     106  {{{ 
     107  muscle2 -mc src/cxa/SimpleSubmodelExample.cxa.rb w 
     108  }}} 
     109 
     110  On the other node, we now also need to specify which host and port the other 
     111  MUSCLE instance is running on 
     112  {{{ 
     113   muscle -c src/cxa/SimpleSubmodelExample.cxa.rb -M [IPADDRESS:PORT] r 
     114  }}} 
     115 
     116  What is the output in node one? And on the other? 
    139117 
    140118**Related:** inter-cluster executions can be done with the `--intercluster` tag, 
    … …  
    1681461. Try the different scenarios and see what the differences are between the configuration files. 
    1691472. Modify the configuration files to get different geometries or transformations. For example (pick one): 
    170  * add a submodel instance so that you get a coupling between West - Middle - East; 
    171  * change the filters and see how it affects the computations (see [wiki:Configuration#Filters Filter documentation]); or 
    172  * modify the file `src/laplace/filter/InvertFilter` to do something additional (see [wiki:"Java API#Filters" Java filter documentation]) 
    173  * modify the file `src/laplace/terminal/DoubleArraySource.java` to do something additional, such as computing a function instead of sending a fixed number (see [Java terminal documentation][javaterminal]) 
     148  * add a submodel instance so that you get a coupling between West - Middle - East; 
     149  * change the filters and see how it affects the computations (see [wiki:Configuration#Filters Filter documentation]); or 
     150  * modify the file `src/laplace/filter/InvertFilter` to do something additional (see [wiki:"Java API#Filters" Java filter documentation]) 
     151  * modify the file `src/laplace/terminal/DoubleArraySource.java` to do something additional, such as computing a function instead of sending a fixed number (see [wiki:"Java API#Terminals"  Java terminal documentation]) 
    174152 
    175153== Part 4: a diagram of your tightly coupled model == 
    … …  
    192170 
    1931711. Modify `src/java/examples/simplesubmodel/ConsoleWriter.java` so that it sends a 
    194 message back to Sender.java; modify Sender.java to receive this message. In 
    195 this example, call both the sending and the receiving port "messages", for 
    196 example. Test your implementation by running 
     172  message back to Sender.java; modify Sender.java to receive this message. In 
     173  this example, call both the sending and the receiving port "messages", for 
     174  example. Test your implementation by running 
    197175  
    198 {{{ 
    199    cd build 
    200  ./build.sh $MUSCLE_HOME 
    201  cd .. 
    202  muscle2 -amc src/cxa/SimpleSubmodelExample.cxa.rb 
    203 }}} 
     176  {{{ 
     177    cd build 
     178  ./build.sh $MUSCLE_HOME 
     179   cd .. 
     180   muscle2 -amc src/cxa/SimpleSubmodelExample.cxa.rb 
     181  }}} 
    204182 
    205183**Spoiler:** 
    206184 
    207185* In `ConsoleWriter.java` 
    208  * create the method `protected void intermediateObservation()`   
    209  * send some data over it in `execute()` by adding 
    210   {{{ 
     186  * create the method `protected void intermediateObservation()`   
     187  * send some data over it in `execute()` by adding 
     188    {{{ 
    211189       double[] msg = {1.0, 0.0, 1.0}; 
    212     out("messages").send(msg); 
    213   }}} 
     190      out("messages").send(msg); 
     191    }}} 
    214192* In `Sender.java` 
    215  * Create the method `protected void solvingStep()` 
    216  * Receive the data 
    217   {{{ 
     193  * Create the method `protected void solvingStep()` 
     194  * Receive the data 
     195   {{{ 
    218196   double[] msg = (double[])in("messages").receive(); 
    219   }}} 
    220  * Print the data with  
    221   {{{ 
     197   }}} 
     198  * Print the data with  
     199   {{{ 
    222200   for (double d : msg) { 
    223201     log("Message from ConsoleWriter: " + d); 
    224202   } 
    225   }}} 
     203   }}} 
    226204* In the configuration file `src/cxa/SimpleSubmodelExample.cxa.rb` 
    227  * Append the lines 
    228   {{{ 
    229    r.couple(w, {'messages' => 'messages'}) 
    230   }}} 
    231  * Since the names of the ports are equal (`messages`), you can also use the abbreviated form: 
    232   {{{ 
    233    r.couple(w, 'messages') 
    234   }}} 
     205  * Append the lines 
     206    {{{ 
     207    r.couple(w, {'messages' => 'messages'}) 
     208    }}} 
     209  * Since the names of the ports are equal (`messages`), you can also use the abbreviated form: 
     210    {{{ 
     211    r.couple(w, 'messages') 
     212    }}} 
    235213* Build it and execute 
    236214 
    2372152. Modify `src/cpp/examples/simplecpp/Sender.cpp` to receive a message from ConsoleWriter 
    238 {{{ 
    239  cd build 
    240  ./build.sh $HOME/muscle 
    241  muscle2 -amc ../src/cxa/NativeExample2.cxa.rb 
    242 }}} 
     216  {{{ 
     217  cd build 
     218  ./build.sh $HOME/muscle 
     219  muscle2 -amc ../src/cxa/NativeExample2.cxa.rb 
     220  }}} 
    243221 
    244222**Spoiler:** 
    245223 
    246224* In Sender.cpp 
    247  * Receive some data after sending by coding in the `main()` function 
     225  * Receive some data after sending by coding in the `main()` function 
    248226  {{{ 
    249227   size_t sz; 
    … …  
    251229    muscle::env::receive("messages", (void *)0, sz, MUSCLE_DOUBLE); 
    252230  }}} 
    253  * Print the data with  
     231  * Print the data with  
    254232  {{{ 
    255233   for (size_t j = 0; j < sz; j++) { 
    … …  
    257235   } 
    258236  }}} 
    259  * Free the data with 
     237  * Free the data with 
    260238  {{{ 
    261239   muscle::env::free_data(msg, MUSCLE_DOUBLE); 
    262240  }}} 
    263241* In the configuration file `src/cxa/NativeExample2.cxa.rb` 
    264  * Change the line 
     242  * Change the line 
    265243  {{{ 
    266244   r = Instance.new('r', 'examples.simplejava.ConsoleWriter') 
    … …  
    279257SimpleExample, this doesn't implement the different formal operators of MML, but just an `execute()` method. 
    280258 
     259=== Running {{{SimpleExample}}} === 
     260 
     261 Sender:: 
     262   In {{{src/java/examples/simplejava/Sender.java}}} we provide a minimalist kernel written in Java, which sends data (an array of double). 
     263 
     264 Receiver:: 
     265   In {{{src/java/examples/simplejava/ConsoleWriter.java}}} we provide a simple kernel written in Java. It receives data (an array of double) and prints its content to the standard output. 
     266 
     267 CxA (coupling schema):: 
     268   The configuration {{{src/cxa/SimpleExample.cxa.rb}}} configures a minimal CxA which couples the {{{examples.simplejava.Sender}}} and {{{examples.simplejava.ConsoleWriter}}} kernels. 
     269 
     270 Execution:: 
     271   To run the simulation defined in src/cxa/SimpleExample.cxa.rb use the following command: 
     272   {{{ 
     273   muscle2 --cxa src/cxa/SimpleExample.cxa.rb --main --allkernels 
     274   }}} 
     275   or in shorthand notation 
     276   {{{ 
     277   muscle2 -c src/cxa/SimpleExample.cxa.rb -am 
     278   }}} 
     279   It will first start the Simulation Manager, of which one per simulation is necessary, and then the local manager, which manages the kernels that are started with one {{{muscle2}}} invocation. 
     280 
    281281For MAPPER partners, visit the [[MAPPER tutorial]]. 
    282 For MAPPER partners, visit the [[MAPPER tutorial]].