Changes between Version 9 and Version 10 of Tutorials

Show
Ignore:
Timestamp:
06/10/13 15:25:04 (12 years ago)
Author:
jorisborgdorff
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • Tutorials

    v9 v10  
    2727== Full MUSCLE tutorial == 
    2828 
    29 <h1 id="user_account">User account</h1> 
    30  
    31 <p>A user account on the grass machine (or locally) can be provided to anyone 
    32 that wants to execute the tutorial.</p> 
    33  
    34 <p>For more information, please contact <a href="&#x6D;&#x61;&#105;&#108;&#116;&#111;:&#106;&#46;&#98;&#111;&#x72;&#x67;&#x64;&#x6F;&#114;&#102;&#x66;&#64;&#117;&#118;&#97;&#x2E;&#x6E;&#108;">&#106;&#46;&#98;&#111;&#x72;&#x67;&#x64;&#x6F;&#114;&#102;&#x66;&#64;&#117;&#118;&#97;&#x2E;&#x6E;&#108;</a>.</p> 
    35  
    36 <h1 id="part_1_installing_and_testing">Part 1: installing and testing</h1> 
    37  
    38 <p>If you have a Windows machine, first log in to a Linux or Mac OS X machine.</p> 
    39  
    40 <ol> 
    41 <li><p>Follow the <a href="http://apps.man.poznan.pl/trac/muscle/wiki/Installation" title="MUSCLE 2 installation">MUSCLE installation page</a>.</p></li> 
    42 <li><p>To add MUSCLE to the path and set a few environment variables, run the 
    43 following (don&#8217;t forget the dot at the start!):</p> 
    44  
    45 <pre><code>. [MUSCLE_DIR]/etc/muscle.profile 
    46 </code></pre></li> 
    47 <li><p>Now you can run <code>muscle2</code>. We will show its functionality with an example 
    48 model that is packaged with MUSCLE. First go to the unzipped MUSCLE folder, 
    49 and try to read <code>src/cxa/SimpleSubmodelExample.cxa.rb</code> and see what it does. 
    50 To show the submodels that the example contains, run:</p> 
    51  
    52 <pre><code>cd .. 
    53 muscle2 --cxa src/cxa/SimpleSubmodelExample.cxa.rb 
    54 </code></pre> 
    55  
    56 <p>This example has a writer submodel <code>w</code> and a reader submodel <code>r</code>. The 
    57 writer sends data to the reader, and the reader prints that data to screen.</p> 
    58  
    59 <p>You can run the simple example by specifying that the current MUSCLE command 
    60 will run the Simulation Manager with the <code>--main</code> flag or its shorthand <code>-m</code>, 
    61 and specifying all submodels that should run in this command:</p> 
    62  
    63 <pre><code>muscle2 -mc src/cxa/SimpleSubmodelExample.cxa.rb w r 
    64 </code></pre> 
    65  
    66 <p>Usually, if you want to run all the submodels instances with the current MUSCLE 
    67 command, specify the <code>--allinstances</code> or its shorthand <code>-a</code>:</p> 
    68  
    69 <pre><code>muscle2 -amc src/cxa/SimpleSubmodelExample.cxa.rb 
    70 </code></pre> 
    71  
    72 <p>So what do we observe? MUSCLE detects that it should start the Simulation 
    73 Manager and a Simulation. It first starts the manager, which shows its 
    74 TCP/IP address. Then the Simulation starts and it executes the submodel 
    75 instances <code>w</code> and <code>r</code>. These start their respective conduits, and start 
    76 &#8216;computing&#8217;.</p> 
    77  
    78 <p>On local machines, these commands are sufficient to run any MUSCLE model. 
    79 You can try the other examples in the <code>src/cxa</code> directory, just run</p> 
    80  
    81 <pre><code>muscle2 -amc src/cxa/[...].cxa.rb 
    82 </code></pre></li> 
    83 <li><p>Scientific applications that are started remotely generally do not 
    84 have a direct feedback to a user interface, but we will run one that does. 
    85 This is why we logged in with the -X flag of SSH in step 2.</p> 
    86  
    87 <pre><code>muscle2 -amc src/cxa/LaplaceExample.cxa.rb 
    88 </code></pre> 
    89  
    90 <p>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.</p></li> 
    97 <li><p>Take a look at all the options by running</p> 
    98  
    99 <pre><code>muscle2 
    100 </code></pre></li> 
    101 </ol> 
    102  
    103 <h1 id="part_2_distributed_execution">Part 2: distributed execution</h1> 
    104  
    105 <p>In this part we will do an inter-process and an inter-machine run of MUSCLE.</p> 
    106  
    107 <ol> 
    108 <li><p>Open a second terminal, and log in to another machine, or try it on the same machine. 
    109 When logged in do</p> 
    110  
    111 <pre><code>. [MUSCLE_DIR]/etc/muscle.profile 
    112 </code></pre> 
    113  
    114 <p>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:</p> 
    115  
    116 <pre><code>muscle2 -mc src/cxa/SimpleSubmodelExample.cxa.rb w 
    117 </code></pre> 
    118  
    119 <p>So what do you observe?</p> 
    120  
    121 <p>One of the most important messages is <code>Started the connection handler, listening on [IPADDRESS:PORT]</code>. 
    122 Copy the IP address and port number. 
    123 In the second terminal, start the reading submodel r, and at the end put the <code>-M</code> or <code>--manager</code> flag 
    124 with the IP address and port:</p> 
    125  
    126 <pre><code>muscle2 -c src/cxa/SimpleSubmodelExample.cxa.rb r -M [IPADDRESS:PORT] 
    127 </code></pre> 
    128  
    129 <p>What happens in both terminals?</p></li> 
    130 <li><p>To isolate the output from the Simulation Manager, we can run it separately.</p> 
    131  
    132 <p>In the first terminal window, start the Simulation Manager:</p> 
    133  
    134 <pre><code>muscle2 -mc src/cxa/SimpleSubmodelExample.cxa.rb 
    135 </code></pre> 
    136  
    137 <p>In the second terminal, start the submodels. Again, replace the port number 
    138 with the one that is printed by the Simulation Manager.</p> 
    139  
    140 <pre><code>muscle2 -ac src/cxa/SimpleSubmodelExample.cxa.rb -M [IPADDRESS:PORT] 
    141 </code></pre> 
    142  
    143 <p>What happens in both terminals?</p></li> 
    144 <li><p>To do distributed computing, also install MUSCLE on another node</p> 
    145  
    146 <pre><code>ssh user@node2 
    147 [INSTALL MUSCLE...] 
    148 . MUSCLE_DIR/etc/muscle.profile 
    149 </code></pre> 
    150  
    151 <p>And go to the source directory of MUSCLE. We will perform the same experiment, 
    152 but now on different hosts. So on the first node, for instance run only <code>w</code></p> 
    153  
    154 <pre><code>muscle2 -mc src/cxa/SimpleSubmodelExample.cxa.rb w 
    155 </code></pre> 
    156  
    157 <p>On the other node, we now also need to specify which host and port the other 
    158 MUSCLE instance is running on</p> 
    159  
    160 <pre><code>muscle -c src/cxa/SimpleSubmodelExample.cxa.rb -M [IPADDRESS:PORT] r 
    161 </code></pre> 
    162  
    163 <p>What is the output in node one? And on the other?</p></li> 
    164 </ol> 
    165  
    166 <p><strong>Related:</strong> inter-cluster executions can be done with the <code>--intercluster</code> tag, 
    167 with which the MUSCLE transport overlay (MTO) is used. We will not be doing this 
    168 directly here. In the <a href="http://apps.man.poznan.pl/trac/muscle/wiki/MTO" title="MTO documentation">MTO documentation</a> this is explained more thoroughly.</p> 
    169  
    170 <h1 id="part_3_the_power_of_coupling">Part 3: The power of coupling</h1> 
    171  
    172 <p>First, download an extension of the LaplaceExample that was shown in item 1.4.</p> 
    173  
    174 <pre><code>wget http://apps.man.poznan.pl/trac/muscle/raw-attachment/wiki/Tutorials/laplace.zip 
    175 unzip laplace.zip 
    176 cd laplace 
    177 ant 
    178 </code></pre> 
    179  
    180 <p>The source of the submodels can be found in <code>src/laplace</code>. This example code 
    181 shows how the same code can be reused in different scenarios:</p> 
    182  
    183 <ul> 
    184 <li>Coupling as in example 1.4 - run <code>muscle2 -amc laplace.cxa.rb</code></li> 
    185 <li>Doing some simple transformation with filters after sending the data - <code>muscle2 -amc laplaceFilter.cxa.rb</code></li> 
    186 <li>Setting one boundary explicitly using terminals - <code>muscle2 -amc laplaceTerminal.cxa.rb</code></li> 
    187 <li>Using a periodic boundary condition - <code>muscle2 -amc laplacePeriodic.cxa.rb</code></li> 
    188 <li>Doing domain decomposition using mappers - <code>muscle2 -amc laplaceMapper.cxa.rb</code></li> 
    189 </ul> 
    190  
    191 <p>Their coupling is shown in the following diagrams:</p> 
    192  
    193 <p><img src="http://apps.man.poznan.pl/trac/muscle/raw-attachment/wiki/Tutorials/scenarios.png" alt="Scenarios" title="" /></p> 
    194  
    195 <ol> 
    196 <li>Try the different scenarios and see what the differences are between the configuration files.</li> 
    197 <li>Modify the configuration files to get different geometries or transformations. For example (pick one): 
    198 <ul> 
    199 <li>add a submodel instance so that you get a coupling between West - Middle - East;</li> 
    200 <li>change the filters and see how it affects the computations (see <a href="http://apps.man.poznan.pl/trac/muscle/wiki/Configuration#Filters" title="MUSCLE 2 Filter documentation">Filter documentation</a>); or</li> 
    201 <li>modify the file <code>src/laplace/filter/InvertFilter</code> to do something additional (see <a href="http://apps.man.poznan.pl/trac/muscle/wiki/Java%20API#Filters" title="MUSCLE 2 Java filter documentation">Java filter documentation</a>)</li> 
    202 <li>modify the file <code>src/laplace/terminal/DoubleArraySource.java</code> to do something additional, such as computing a function instead of sending a fixed number (see <a href="http://apps.man.poznan.pl/trac/muscle/wiki/Java%20API#Terminals" title="MUSCLE 2 Java terminal documentation">Java terminal documentation</a>)</li> 
    203 </ul></li> 
    204 </ol> 
    205  
    206 <h1 id="part_4_a_diagram_of_your_tightly_coupled_model">Part 4: a diagram of your tightly coupled model</h1> 
    207  
    208 <p>To apply this programming paradigm to your own multiscale model, you can apply 
    209 the methodology as presented on day 1.</p> 
    210  
    211 <ol> 
    212 <li>Identify the processes in your problem, and their scales. Draw them on the same diagram, taking time as a x-axis, and space as the y-axis. Each process should have a granularity (step size), which is the lower bound for the rectangle, and a problem size (total size), which is the upper bound for the rectangle.</li> 
    213 <li>Draw arrows between interacting processes. Now your scale separation map is more or less complete.</li> 
    214 <li>When you think about implementation of that scale separation map, could you use any of the coupling types shown in part 3? Would it be tightly or loosely coupled? </li> 
    215 <li>Work out coupling diagram of your own application.</li> 
    216 </ol> 
    217  
    218 <h1 id="part_5_modifying_the_simple_example_optional">Part 5: modifying the simple example (optional)</h1> 
    219  
    220 <p>To start on using MUSCLE for your own applications, you can start by modifying 
    221 the examples. Depending on the programming language of your application, you can 
    222 start with (<a href="http://apps.man.poznan.pl/trac/muscle/wiki/Java%20API" title="MUSCLE 2 Java documentation">Java documentation</a>) the files in <code>src/java/examples/simplesubmodel</code> or with 
    223 (<a href="http://apps.man.poznan.pl/trac/muscle/wiki/C%2B%2B%20API" title="MUSCLE 2 C/C++ documentation">C++/C documentation</a>) <code>src/cpp/examples/simplecpp</code> or (<a href="http://apps.man.poznan.pl/trac/muscle/wiki/Fortran%20API" title="MUSCLE 2 Fortran documentation">Fortran documentation</a>) <code>src/cpp/examples/simplefortran</code>. 
    224 The last two only contain the Sender (the submodel w) of the simple example.</p> 
    225  
    226 <ol> 
    227 <li><p>Modify src/java/examples/simplesubmodel/ConsoleWriter.java so that it sends a 
    228 message back to Sender.java; modify Sender.java to receive this message. In 
    229 this example, call both the sending and the receiving port &#8220;messages&#8221;, for 
    230 example. Test your implementation by running</p> 
    231  
    232 <pre><code>cd build 
    233 ./build.sh $MUSCLE_HOME 
    234 cd .. 
    235 muscle2 -amc src/cxa/SimpleSubmodelExample.cxa.rb 
    236 </code></pre> 
    237  
    238 <p><strong>Spoiler:</strong></p> 
    239  
    240 <ul> 
    241 <li><p>In ConsoleWriter.java</p> 
    242  
    243 <ul> 
    244 <li>create the method <code>protected void intermediateObservation()</code>      </li> 
    245 <li><p>send some data over it in <code>execute()</code> by adding</p> 
    246  
    247 <pre><code>double[] msg = {1.0, 0.0, 1.0}; 
    248 out("messages").send(msg); 
    249 </code></pre></li> 
    250 </ul></li> 
    251 <li><p>In Sender.java</p> 
    252  
    253 <ul> 
    254 <li>Create the method <code>protected void solvingStep()</code></li> 
    255 <li><p>Receive the data</p> 
    256  
    257 <pre><code>double[] msg = (double[])in("messages").receive(); 
    258 </code></pre></li> 
    259 <li><p>Print the data with </p> 
    260  
    261 <pre><code>for (double d : msg) { 
    262      log("Message from ConsoleWriter: " + d); 
    263 } 
    264 </code></pre></li> 
    265 </ul></li> 
    266 <li><p>In the configuration file <code>src/cxa/SimpleSubmodelExample.cxa.rb</code></p> 
    267  
    268 <ul> 
    269 <li><p>Append the lines</p> 
    270  
    271 <pre><code>cs.attach('r' =&gt; 'w') { 
    272     tie('messages', 'messages') 
    273 } 
    274 </code></pre></li> 
    275 <li><p>Since the names of the ports are equal (<code>messages</code>), you can also use the abbreviated form:</p> 
    276  
    277 <pre><code>cs.attach('r' =&gt; 'w') { 
    278     tie('messages') 
    279 } 
    280 </code></pre></li> 
    281 </ul></li> 
    282 <li>Build it and execute</li> 
    283 </ul></li> 
    284 <li><p>Modify <code>src/cpp/examples/simplecpp/Sender.cpp</code> to receive a message from ConsoleWriter</p> 
    285  
    286 <pre><code>cd build 
    287 ./build.sh $HOME/muscle 
    288 muscle2 -amc ../src/cxa/NativeExample2.cxa.rb 
    289 </code></pre> 
    290  
    291 <p><strong>Spoiler:</strong></p> 
    292  
    293 <ul> 
    294 <li><p>In Sender.cpp</p> 
    295  
    296 <ul> 
    297 <li><p>Receive some data after sending by coding in the <code>main()</code> function</p> 
    298  
    299 <pre><code>size_t sz; 
    300 double* msg = (double *) 
    301     muscle::env::receive("messages", (void *)0, sz, MUSCLE_DOUBLE); 
    302 </code></pre></li> 
    303 <li><p>Print the data with </p> 
    304  
    305 <pre><code>for (size_t j = 0; j &lt; sz; j++) { 
    306     logger::info("Message from ConsoleWriter: %f", msg[j]); 
    307 } 
    308 </code></pre></li> 
    309 <li><p>Free the data with</p> 
    310  
    311 <pre><code>muscle::env::free_data(msg, MUSCLE_DOUBLE); 
    312 </code></pre></li> 
    313 </ul></li> 
    314 <li><p>In the configuration file <code>src/cxa/NativeExample2.cxa.rb</code></p> 
    315  
    316 <ul> 
    317 <li><p>Change the line</p> 
    318  
    319 <pre><code>cxa.add_kernel('r', 'examples.simplejava.ConsoleWriter') 
    320 </code></pre> 
    321  
    322 <p>to</p> 
    323  
    324 <pre><code>cxa.add_kernel('r', 'examples.simplesubmodel.ConsoleWriter') 
    325 </code></pre></li> 
    326 <li><p>Append the lines</p> 
    327  
    328 <pre><code>cs.attach('r' =&gt; 'w') { 
    329     tie('messages') 
    330 } 
    331 </code></pre></li> 
    332 </ul></li> 
    333 </ul></li> 
    334 </ol> 
    335  
    336 <p>If you would prefer to use the free-form API of MUSCLE, take a look at the 
    337 SimpleExample, this doesn&#8217;t implement the different formal operators of MML, but just an <code>execute()</code> method.</p> 
    33829 
    33930For MAPPER partners, visit the [[MAPPER tutorial]].