Changes between Version 13 and Version 14 of Tutorials

Show
Ignore:
Timestamp:
06/10/13 16:10:49 (12 years ago)
Author:
jorisborgdorff
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • Tutorials

    v13 v14  
    3535 
    36362. 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   }}} 
     37 {{{ 
     38  . [MUSCLE_DIR]/etc/muscle.profile 
     39 }}} 
    4040 
    41413. 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   {{{ 
    51     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   }}} 
     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 {{{ 
     51  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 }}} 
    6565 
    66664. 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   {{{ 
    68       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. 
     67 {{{ 
     68   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. 
    7272 
    73735. Take a look at all the options by running 
    74   {{{ 
    75     muscle2 
    76   }}} 
     74 {{{ 
     75  muscle2 
     76 }}} 
    7777 
    7878== Part 2: distributed execution == 
    … …  
    8181 
    82821. 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? 
     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? 
    103103 
    1041042. To isolate the output from the Simulation Manager, we can run it separately. 
    105105 
    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? 
     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? 
    118118 
    1191193. 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? 
     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? 
    139139 
    140140**Related:** inter-cluster executions can be done with the `--intercluster` tag, 
    … …  
    147147First, download an extension of the LaplaceExample that was shown in item 1.4. 
    148148{{{ 
    149     wget http://apps.man.poznan.pl/trac/muscle/raw-attachment/wiki/Tutorials/laplace.zip 
    150     unzip laplace.zip 
    151     cd laplace 
    152     ant 
     149  wget http://apps.man.poznan.pl/trac/muscle/raw-attachment/wiki/Tutorials/laplace.zip 
     150  unzip laplace.zip 
     151  cd laplace 
     152  ant 
    153153}}} 
    154154 
    … …  
    1681681. Try the different scenarios and see what the differences are between the configuration files. 
    1691692. 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%20API#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]) 
     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%20API#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]) 
    174174 
    175175== Part 4: a diagram of your tightly coupled model == 
    … …  
    192192 
    1931931. 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 
    197      
    198   {{{ 
    199         cd build 
    200     ./build.sh $MUSCLE_HOME 
    201     cd .. 
    202     muscle2 -amc src/cxa/SimpleSubmodelExample.cxa.rb 
    203   }}} 
    204  
    205   **Spoiler:** 
    206  
    207   * In ConsoleWriter.java 
    208     * create the method `protected void intermediateObservation()`     
    209     * send some data over it in `execute()` by adding 
    210       {{{ 
    211                 double[] msg = {1.0, 0.0, 1.0}; 
    212           out("messages").send(msg); 
    213       }}} 
    214   * In Sender.java 
    215     * Create the method `protected void solvingStep()` 
    216     * Receive the data 
    217       {{{ 
    218         double[] msg = (double[])in("messages").receive(); 
    219       }}} 
    220     * Print the data with  
    221       {{{ 
    222         for (double d : msg) { 
    223            log("Message from ConsoleWriter: " + d); 
    224         } 
    225       }}} 
    226   * In the configuration file `src/cxa/SimpleSubmodelExample.cxa.rb` 
    227     * Append the lines 
    228       {{{ 
    229         cs.attach('r' => 'w') { 
    230           tie('messages', 'messages') 
    231         } 
    232       }}} 
    233     * Since the names of the ports are equal (`messages`), you can also use the abbreviated form: 
    234       {{{ 
    235         cs.attach('r' => 'w') { 
    236           tie('messages') 
    237         } 
    238       }}} 
    239   * Build it and execute 
     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 
     197   
     198 {{{ 
     199    cd build 
     200  ./build.sh $MUSCLE_HOME 
     201  cd .. 
     202  muscle2 -amc src/cxa/SimpleSubmodelExample.cxa.rb 
     203 }}} 
     204 
     205 **Spoiler:** 
     206 
     207 * In ConsoleWriter.java 
     208  * create the method `protected void intermediateObservation()`   
     209  * send some data over it in `execute()` by adding 
     210   {{{ 
     211        double[] msg = {1.0, 0.0, 1.0}; 
     212     out("messages").send(msg); 
     213   }}} 
     214 * In Sender.java 
     215  * Create the method `protected void solvingStep()` 
     216  * Receive the data 
     217   {{{ 
     218    double[] msg = (double[])in("messages").receive(); 
     219   }}} 
     220  * Print the data with  
     221   {{{ 
     222    for (double d : msg) { 
     223      log("Message from ConsoleWriter: " + d); 
     224    } 
     225   }}} 
     226 * In the configuration file `src/cxa/SimpleSubmodelExample.cxa.rb` 
     227  * Append the lines 
     228   {{{ 
     229    cs.attach('r' => 'w') { 
     230     tie('messages', 'messages') 
     231    } 
     232   }}} 
     233  * Since the names of the ports are equal (`messages`), you can also use the abbreviated form: 
     234   {{{ 
     235    cs.attach('r' => 'w') { 
     236     tie('messages') 
     237    } 
     238   }}} 
     239 * Build it and execute 
    240240 
    2412412. Modify `src/cpp/examples/simplecpp/Sender.cpp` to receive a message from ConsoleWriter 
    242   {{{ 
    243     cd build 
    244     ./build.sh $HOME/muscle 
    245     muscle2 -amc ../src/cxa/NativeExample2.cxa.rb 
    246   }}} 
    247  
    248   **Spoiler:** 
     242 {{{ 
     243  cd build 
     244  ./build.sh $HOME/muscle 
     245  muscle2 -amc ../src/cxa/NativeExample2.cxa.rb 
     246 }}} 
     247 
     248 **Spoiler:** 
     249  
     250 * In Sender.cpp 
     251  * Receive some data after sending by coding in the `main()` function 
     252   {{{ 
     253    size_t sz; 
     254    double* msg = (double *) 
     255     muscle::env::receive("messages", (void *)0, sz, MUSCLE_DOUBLE); 
     256   }}} 
     257  * Print the data with  
     258   {{{ 
     259    for (size_t j = 0; j < sz; j++) { 
     260     logger::info("Message from ConsoleWriter: %f", msg[j]); 
     261    } 
     262   }}} 
     263  * Free the data with 
     264   {{{ 
     265    muscle::env::free_data(msg, MUSCLE_DOUBLE); 
     266   }}} 
     267 * In the configuration file `src/cxa/NativeExample2.cxa.rb` 
     268  * Change the line 
     269   {{{ 
     270    cxa.add_kernel('r', 'examples.simplejava.ConsoleWriter') 
     271   }}} 
     272   to 
     273   {{{ 
     274    cxa.add_kernel('r', 'examples.simplesubmodel.ConsoleWriter') 
     275   }}} 
    249276   
    250   * In Sender.cpp 
    251     * Receive some data after sending by coding in the `main()` function 
    252       {{{ 
    253         size_t sz; 
    254         double* msg = (double *) 
    255           muscle::env::receive("messages", (void *)0, sz, MUSCLE_DOUBLE); 
    256       }}} 
    257     * Print the data with  
    258       {{{ 
    259         for (size_t j = 0; j < sz; j++) { 
    260           logger::info("Message from ConsoleWriter: %f", msg[j]); 
    261         } 
    262       }}} 
    263     * Free the data with 
    264       {{{ 
    265         muscle::env::free_data(msg, MUSCLE_DOUBLE); 
    266       }}} 
    267   * In the configuration file `src/cxa/NativeExample2.cxa.rb` 
    268     * Change the line 
    269       {{{ 
    270         cxa.add_kernel('r', 'examples.simplejava.ConsoleWriter') 
    271       }}} 
    272       to 
    273       {{{ 
    274         cxa.add_kernel('r', 'examples.simplesubmodel.ConsoleWriter') 
    275       }}} 
    276      
    277     * Append the lines 
    278       {{{ 
    279         cs.attach('r' => 'w') { 
    280           tie('messages') 
    281         } 
    282       }}} 
     277  * Append the lines 
     278   {{{ 
     279    cs.attach('r' => 'w') { 
     280     tie('messages') 
     281    } 
     282   }}} 
    283283 
    284284If you would prefer to use the free-form API of MUSCLE, take a look at the