Changes between Version 12 and Version 13 of Tutorials

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

--

Legend:

Unmodified
Added
Removed
Modified

  • Tutorials

    v12 v13  
    2626 
    2727== Full MUSCLE tutorial == 
    28  
    2928For more information, please contact <j.borgdorff@uva.nl>. 
    3029 
    … …  
    3332If you have a Windows machine, first log in to a Linux or Mac OS X machine. 
    3433 
    35 1. Follow the [wiki:Installation MUSCLE installation] 
    36  
    37 2. To add MUSCLE to the path and set a few environment variables, run the 
    38         following (don't forget the dot at the start!): 
    39         {{{ 
    40                 . [MUSCLE_DIR]/etc/muscle.profile 
    41         }}} 
    42  
    43 3. Now you can run `muscle2`. We will show its functionality with an example 
    44         model that is packaged with MUSCLE. First go to the unzipped MUSCLE folder, 
    45         and try to read `src/cxa/SimpleSubmodelExample.cxa.rb` and see what it does. 
    46         To show the submodels that the example contains, run: 
    47         {{{ 
    48                 cd .. 
    49                 muscle2 --cxa src/cxa/SimpleSubmodelExample.cxa.rb  
    50         }}} 
    51  
    52         This example has a writer submodel `w` and a reader submodel `r`. The 
    53         writer sends data to the reader, and the reader prints that data to screen. 
    54  
    55         You can run the simple example by specifying that the current MUSCLE command 
    56         will run the Simulation Manager with the `--main` flag or its shorthand `-m`, 
    57         and specifying all submodels that should run in this command: 
    58         {{{ 
    59                 muscle2 -mc src/cxa/SimpleSubmodelExample.cxa.rb w r 
    60         }}} 
    61          
    62         Usually, if you want to run all the submodels instances with the current MUSCLE 
    63         command, specify the `--allinstances` or its shorthand `-a`: 
    64          
    65         {{{ 
    66                 muscle2 -amc src/cxa/SimpleSubmodelExample.cxa.rb 
    67         }}} 
    68  
    69         So what do we observe? MUSCLE detects that it should start the Simulation 
    70         Manager and a Simulation. It first starts the manager, which shows its 
    71         TCP/IP address. Then the Simulation starts and it executes the submodel 
    72         instances `w` and `r`. These start their respective conduits, and start 
    73         'computing'. 
    74          
    75         On local machines, these commands are sufficient to run any MUSCLE model. 
    76         You can try the other examples in the `src/cxa` directory, just run 
    77          
    78         {{{ 
    79                 muscle2 -amc src/cxa/[...].cxa.rb 
    80         }}} 
    81  
    82 4. Scientific applications that are started remotely generally do not 
    83     have a direct feedback to a user interface, but we will run one that does. 
    84     This is why we logged in with the -X flag of SSH in step 2. 
    85          
    86         {{{ 
    87         muscle2 -amc src/cxa/LaplaceExample.cxa.rb 
    88         }}} 
    89          
    90         It will open two windows that compute temperature dissipation, that are 
    91     coupled on the boundary. Red is a +1 temparature, blue a -1 temperature, 
    92     and green a zero temperature. The initial condition, far right and far left 
    93     correspond to zero temperature, the top to a sine function and the bottom to a cosine. 
    94         Temperature is dissipated during each time step by taking the average of 
    95         the four neighboring cells. The adjacent boundary is transmitted each 
    96         iteration. 
     341. Follow the [http://apps.man.poznan.pl/trac/muscle/wiki/Installation MUSCLE installation] 
     35 
     362. 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  }}} 
     40 
     413. 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  }}} 
     65 
     664. 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. 
    9772 
    98735. Take a look at all the options by running 
    99         {{{ 
    100                 muscle2 
    101         }}} 
     74  {{{ 
     75    muscle2 
     76  }}} 
    10277 
    10378== Part 2: distributed execution == 
    … …  
    10580In this part we will do an inter-process and an inter-machine run of MUSCLE. 
    10681 
    107 1. Open a second terminal, and log in to another machine, or try it on the same machine. 
    108         When logged in do 
    109         {{{ 
    110                 . [MUSCLE_DIR]/etc/muscle.profile 
    111         }}} 
    112  
    113         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: 
    114         {{{ 
    115                 muscle2 -mc src/cxa/SimpleSubmodelExample.cxa.rb w 
    116         }}} 
    117  
    118         So what do you observe? 
    119  
    120         One of the most important messages is `Started the connection handler, listening on [IPADDRESS:PORT]`. 
    121         Copy the IP address and port number. 
    122         In the second terminal, start the reading submodel r, and at the end put the `-M` or `--manager` flag 
    123         with the IP address and port: 
    124         {{{ 
    125                 muscle2 -c src/cxa/SimpleSubmodelExample.cxa.rb r -M [IPADDRESS:PORT] 
    126         }}} 
    127  
    128         What happens in both terminals? 
     821. 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? 
    129103 
    1301042. To isolate the output from the Simulation Manager, we can run it separately. 
    131105 
    132         In the first terminal window, start the Simulation Manager: 
    133         {{{ 
    134                 muscle2 -mc src/cxa/SimpleSubmodelExample.cxa.rb 
    135         }}} 
    136  
    137         In the second terminal, start the submodels. Again, replace the port number 
    138         with the one that is printed by the Simulation Manager. 
    139         {{{ 
    140                 muscle2 -ac src/cxa/SimpleSubmodelExample.cxa.rb -M [IPADDRESS:PORT] 
    141         }}} 
    142  
    143         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? 
    144118 
    1451193. To do distributed computing, also install MUSCLE on another node 
    146         {{{ 
    147                 ssh user@node2 
    148                 [INSTALL MUSCLE...] 
    149                 . MUSCLE_DIR/etc/muscle.profile 
    150         }}} 
    151  
    152         And go to the source directory of MUSCLE. We will perform the same experiment, 
    153         but now on different hosts. So on the first node, for instance run only `w` 
    154         {{{ 
    155                 muscle2 -mc src/cxa/SimpleSubmodelExample.cxa.rb w 
    156         }}} 
    157  
    158         On the other node, we now also need to specify which host and port the other 
    159         MUSCLE instance is running on 
    160         {{{ 
    161                 muscle -c src/cxa/SimpleSubmodelExample.cxa.rb -M [IPADDRESS:PORT] r 
    162         }}} 
    163  
    164         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? 
    165139 
    166140**Related:** inter-cluster executions can be done with the `--intercluster` tag, 
    … …  
    1941681. Try the different scenarios and see what the differences are between the configuration files. 
    1951692. Modify the configuration files to get different geometries or transformations. For example (pick one): 
    196         * add a submodel instance so that you get a coupling between West - Middle - East; 
    197         * change the filters and see how it affects the computations (see [wiki:Configuration#Filters Filter documentation]); or 
    198          * modify the file `src/laplace/filter/InvertFilter` to do something additional (see [wiki:"Java API#Filters" Java filter documentation]) 
    199          * 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]) 
     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]) 
    200174 
    201175== Part 4: a diagram of your tightly coupled model == 
    … …  
    213187To start on using MUSCLE for your own applications, you can start by modifying 
    214188the examples. Depending on the programming language of your application, you can 
    215 start with ([wiki:"Java API" Java documentation]) the files in `src/java/examples/simplesubmodel` or with 
    216 ([wiki:"C++ API" C++/C documentation]) `src/cpp/examples/simplecpp` or ([wiki:"Fortran API" Fortran documentation]) `src/cpp/examples/simplefortran`. 
     189start with ([wiki:Java%20API Java documentation]) the files in `src/java/examples/simplesubmodel` or with 
     190([wiki:C%20API C++/C documentation]) `src/cpp/examples/simplecpp` or ([wiki:Fortran%20API Fortran documentation]) `src/cpp/examples/simplefortran`. 
    217191The last two only contain the Sender (the submodel w) of the simple example. 
    218192 
    2191931. Modify src/java/examples/simplesubmodel/ConsoleWriter.java so that it sends a 
    220         message back to Sender.java; modify Sender.java to receive this message. In 
    221         this example, call both the sending and the receiving port "messages", for 
    222         example. Test your implementation by running 
     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 
    223197     
    224         {{{ 
     198  {{{ 
    225199        cd build 
    226                 ./build.sh $MUSCLE_HOME 
    227                 cd .. 
    228                 muscle2 -amc src/cxa/SimpleSubmodelExample.cxa.rb 
    229         }}} 
    230  
    231         **Spoiler:** 
    232  
    233         * In ConsoleWriter.java 
    234                 * create the method `protected void intermediateObservation()`           
    235                 * send some data over it in `execute()` by adding 
    236                         {{{ 
     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      {{{ 
    237211                double[] msg = {1.0, 0.0, 1.0}; 
    238                             out("messages").send(msg); 
    239                         }}} 
    240         * In Sender.java 
    241                 * Create the method `protected void solvingStep()` 
    242                 * Receive the data 
    243                         {{{ 
    244                                 double[] msg = (double[])in("messages").receive(); 
    245                         }}} 
    246                 * Print the data with  
    247                         {{{ 
    248                                 for (double d : msg) { 
    249                                         log("Message from ConsoleWriter: " + d); 
    250                                 } 
    251                         }}} 
    252         * In the configuration file `src/cxa/SimpleSubmodelExample.cxa.rb` 
    253                 * Append the lines 
    254                         {{{ 
    255                                 cs.attach('r' => 'w') { 
    256                                         tie('messages', 'messages') 
    257                                 } 
    258                         }}} 
    259                 * Since the names of the ports are equal (`messages`), you can also use the abbreviated form: 
    260                         {{{ 
    261                                 cs.attach('r' => 'w') { 
    262                                         tie('messages') 
    263                                 } 
    264                         }}} 
    265         * Build it and execute 
     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 
    266240 
    2672412. Modify `src/cpp/examples/simplecpp/Sender.cpp` to receive a message from ConsoleWriter 
    268         {{{ 
    269                 cd build 
    270                 ./build.sh $HOME/muscle 
    271                 muscle2 -amc ../src/cxa/NativeExample2.cxa.rb 
    272         }}} 
    273  
    274         **Spoiler:** 
    275          
    276         * In Sender.cpp 
    277                 * Receive some data after sending by coding in the `main()` function 
    278                         {{{ 
    279                                 size_t sz; 
    280                                 double* msg = (double *) 
    281                                         muscle::env::receive("messages", (void *)0, sz, MUSCLE_DOUBLE); 
    282                         }}} 
    283                 * Print the data with  
    284                         {{{ 
    285                                 for (size_t j = 0; j < sz; j++) { 
    286                                         logger::info("Message from ConsoleWriter: %f", msg[j]); 
    287                                 } 
    288                         }}} 
    289                 * Free the data with 
    290                         {{{ 
    291                                 muscle::env::free_data(msg, MUSCLE_DOUBLE); 
    292                         }}} 
    293         * In the configuration file `src/cxa/NativeExample2.cxa.rb` 
    294                 * Change the line 
    295                         {{{ 
    296                                 cxa.add_kernel('r', 'examples.simplejava.ConsoleWriter') 
    297                         }}} 
    298                         to 
    299                         {{{ 
    300                                 cxa.add_kernel('r', 'examples.simplesubmodel.ConsoleWriter') 
    301                         }}} 
    302                  
    303                 * Append the lines 
    304                         {{{ 
    305                                 cs.attach('r' => 'w') { 
    306                                         tie('messages') 
    307                                 } 
    308                         }}} 
     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      }}} 
     276     
     277    * Append the lines 
     278      {{{ 
     279        cs.attach('r' => 'w') { 
     280          tie('messages') 
     281        } 
     282      }}} 
    309283 
    310284If you would prefer to use the free-form API of MUSCLE, take a look at the