Changes between Version 17 and Version 18 of Configuration

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

--

Legend:

Unmodified
Added
Removed
Modified

  • Configuration

    v17 v18  
    11= MUSCLE configuration file = 
    22 
    3 The MUSCLE configuration file, or historically, the [[http://www.complex-automata.org/|Complex Automata]] (CxA) file specifies what code will be used in a simulation, and how its coupled together. It is actually a Ruby file, so any Ruby syntax will work inside it. 
     3MUSCLE has a renewed configuration syntax, but the [wiki:Configuration2 old syntax] can still be used. The MUSCLE configuration file, or historically, the [[http://www.complex-automata.org/|Complex Automata]] (CxA) file specifies what code will be used in a simulation, and how its coupled together. It is actually a Ruby file, so any Ruby syntax will work inside it. 
    44 
    5 To use it, make a file and get the cxa object 
     5To use it, make a file add kernels to it by giving a name and a Java class that has the submodel implementation 
    66{{{ 
    7 cxa = Cxa.LAST 
    8 }}} 
    9 and then add kernels to it by giving a name and a Java class that has the submodel implementation 
    10 {{{ 
    11 cxa.add_kernel('w', 'examples.simplejava.Sender') 
    12 cxa.add_kernel('r', 'examples.simplejava.ConsoleWriter') 
     7w = Instance.new('w', 'examples.simplejava.Sender') 
     8r = Instance.new('r', 'examples.simplejava.ConsoleWriter') 
    139}}} 
    1410When using a C++ kernel without a Java interface, use the {{{muscle.core.standalone.NativeKernel}}} package. For an MPI executable, on a machine where mpiexec/mpirun can be called directly, use {{{muscle.core.standalone.MPIKernel}}}. 
    1511 
    16 To add properties, add them to the {{{env}}} hash of {{{cxa}}}: 
     12To add properties, add them to the global {{{$env}}} hash or to the instances directly: 
    1713{{{ 
    18 cxa.env["max_timesteps"] = 4 
    19 cxa.env["w:dt"] = 1 
    20 cxa.env["w:someDoubleProperty"] = 6.1 
    21 cxa.env["w:someOtherProperty"] = "this is w text" 
    22 cxa.env["r:someOtherProperty"] = "this is r text" 
    23 cxa.env["cxa_path"] = File.dirname(__FILE__) 
     14$env['max_timesteps'] = 4 
     15w['dt'] = 1 
     16w['someDoubleProperty'] = 6.1 
     17w['someOtherProperty'] = "this is w text" 
     18r['someOtherProperty'] = "this is r text" 
    2419}}} 
    2520Properties that are only meant for a single submodel are prepended with the name and a colon (e.g., {{{"submodelName:propertyName"}}}). Other properties are global and will be used by all submodels. 
    2621 
    27 The scale of the submodels can also be specified in the CxA file. For the timestep of a submodel, use {{{"submodelName:dt"}}}, for the total time it will run, {{{"submodelName:T"}}}. For the first 3 spatial dimensions, use {{{dx}}}, {{{dy}}}, {{{dz}}} as step size, and {{{X}}}, {{{Y}}}, {{{Z}}} as total size. In Java, the scale can be accessed with the {{{getScale()}}} method of a submodel. 
     22The scale of the submodels can also be specified in the CxA file. For the timestep of a submodel, use {{{"dt"}}}, for the total time it will run, {{{"T"}}}. For the first 3 spatial dimensions, use {{{dx}}}, {{{dy}}}, {{{dz}}} as step size, and {{{X}}}, {{{Y}}}, {{{Z}}} as total size. In Java, the scale can be accessed with the {{{getScale()}}} method of a submodel. 
    2823 
    29 The {{{cs}}} property of {{{cxa}}} is the connection scheme; it defines how submodels are coupled. In the example, submodel w is attached to submodel {{{r}}} by tying the conduit entrance {{{dataOut}}} of {{{w}}} to the conduit exit {{{dataIn}}} of {{{r}}}. It also ties conduit entrance {{{otherOut}}} of {{{w}}} to {{{other}}} of {{{r}}}. 
     24In the example, submodel w is attached to submodel {{{r}}} by tying the conduit entrance {{{dataOut}}} of {{{w}}} to the conduit exit {{{dataIn}}} of {{{r}}}. It also ties conduit entrance {{{otherOut}}} of {{{w}}} to {{{other}}} of {{{r}}}. 
    3025 
    3126{{{ 
    32 cs = cxa.cs 
    33  
    34 cs.attach('w' => 'r') { 
    35         tie('dataOut', 'dataIn') 
    36         tie('otherOut', 'other') 
    37 } 
     27w.couple(r, {'dataOut' => 'dataIn', 'otherOut' => 'other'}) 
    3828}}} 
    3929If the conduit entrance and exit have the same name, the second argument of {{{tie}}} is optional. 
    … …  
    4333For native executables that uses the MUSCLE API, the following parameters may be set: {{{"submodelName:command"}}} to set the path to the executable; and {{{"submodelName:args"}}} to give additional command-line parameters to the executable. Suppose my executable is somewhere in my home {{{bin}}} directory, this could be 
    4434{{{ 
    45 cxa.env["subA:command"] = ENV['HOME'] + "/bin/subA" 
    46 cxa.env["subA:args"] = "paramA paramB" 
     35subA["command"] = ENV['HOME'] + "/bin/subA" 
     36subA["args"] = "paramA paramB" 
    4737}}} 
    4838 
    49 For MPI code, two additional parameters should be set: {{{"submodelName:mpiexec_command"}}} with the name or the path the the mpiexec/mpirun executable; and {{{"submodelName:mpiexec_args"}}} which are the arguments, like "-np 2", etc. 
     39For MPI code, two additional parameters should be set: {{{"mpiexec_command"}}} with the name or the path the the mpiexec/mpirun executable; and {{{"mpiexec_args"}}} which are the arguments, like "-np 2", etc. 
    5040 
    5141 
    … …  
    5444If a conduit filter should be applied to a conduit, these can be added as a list as the last argument of {{{tie()}}}: 
    5545{{{ 
    56 cs.attach('w' => 'r') { 
    57         tie('dataOut', 'dataIn',['muscle.core.conduit.filter.MultiplyDoubleFilter_0.5']) 
    58 } 
     46w.couple(r, {'dataOut' => 'dataIn'}, ['muscle.core.conduit.filter.MultiplyDoubleFilter_0.5']) 
    5947}}} 
    6048In the example, the MUSCLE filter {{{MultiplyDoubleFilter}}} is applied, which multiplies each double with a value, in this case 0.5. For user defined filters, one double argument may be given, separated from the class name by an underscore. MUSCLE supplies some filters in package {{{muscle.core.conduit.filter}}}: 
    … …  
    8068For convenience, the MUSCLE filters may be referred to by their name instead of their class: 
    8169{{{ 
    82 cs.attach('w' => 'r') { 
    83         tie('dataOut', 'dataIn',['multiply_0.5','console']) 
    84 } 
     70w.couple(r, {'dataOut' => 'dataIn'}, ['multiply_0.5','console']) 
    8571}}} 
    8672 
    87 By default, the conduit filters get applied at the receiving submodel. If a filter should be applied at the sending submodel or if filters should be applied at both locations, the {{{tie}}} function takes an additional argument, so that the first list of filters is applied at the sending side and the second list of filters is applied at the receiving side. 
     73By default, the conduit filters get applied at the receiving submodel. If a filter should be applied at the sending submodel or if filters should be applied at both locations, the {{{couple}}} function takes an additional argument, so that the first list of filters is applied at the sending side and the second list of filters is applied at the receiving side. 
    8874The following fragment multiplies the data with a constant on the sending side, and prints it on the receiving side: 
    8975{{{ 
    90 cs.attach('w' => 'r') { 
    91         tie('dataOut', 'dataIn',['multiply_0.5'],['console']) 
    92 } 
     76w.couple(r, {'dataOut' => 'dataIn'}, ['multiply_0.5'], ['console']) 
    9377}}} 
    9478 
    9579And the following fragment compresses data on the sending side and uncompresses it on the receiving side: 
    9680{{{ 
    97 cs.attach('w' => 'r') { 
    98         tie('dataOut', 'dataIn',['serialize','compress'],['decompress','deserialize']) 
    99 } 
     81w.couple(r, {'dataOut' => 'dataIn'}, ['serialize','compress'], ['decompress','deserialize']) 
    10082}}} 
    10183 
    10284For large data sets it may increase performance to split the data into multiple chunks before compressing. In the following configuration, it gets sent in separate chunks and compressing is done in a separate thread from sending: 
    10385{{{ 
    104 cs.attach('w' => 'r') { 
    105         tie('dataOut', 'dataIn',['serialize','chunk_16','compress','thread'],['decompress','dechunk_16','deserialize']) 
    106 } 
     86w.couple(r, {'dataOut' => 'dataIn'}, ['serialize','chunk_16','compress','thread'], ['decompress','dechunk_16','deserialize']) 
    10787}}} 
    10888 
    … …  
    11292 
    11393{{{ 
    114 cxa.add_terminal('readA', 'muscle.core.conduit.terminal.DoubleFileSource') 
    115 cxa['readA:filename'] = "/path/to/some.file" 
    116 cxa['readA:suffix'] = 'dat' 
    117 cxa['readA:relative'] = false 
    118 cxa['readA:delimiter'] = ',' 
     94readA = Terminal.new('readA', 'muscle.core.conduit.terminal.DoubleFileSource') 
     95readA['filename'] = "/path/to/some.file" 
     96readA['suffix'] = 'dat' 
     97readA['relative'] = false 
     98readA['delimiter'] = ',' 
    11999 
    120 cs.attach('readA' => 'r') { 
    121     tie('dataIn') 
    122 } 
     100readA.couple(r, 'dataIn') 
    123101}}} 
    124102Here, we're reading the file {{{/path/to/some.file.dat}}}, and the path is not relative to the runtime path of MUSCLE. The doubles in that file are delimited by commas. Finally, a terminal port takes any name of the receiving or sending end, so only one value is given to tie. For the moment, it is not possible to apply filters to terminals. 
    125103 
    126104[[Documentation|<< Back to Documentation]] 
    127  
    128 [[Configuration2|New configuration format]]