Changes between Version 2 and Version 3 of Java API

Show
Ignore:
Timestamp:
09/04/12 13:22:01 (13 years ago)
Author:
jorisborgdorff
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • Java API

    v2 v3  
    33== About the API == 
    44 
    5 The Multiscale Modeling Language (MML) defines several computational elements. The names of these elements are: 
    6 * conduit; 
    7 * submodel; 
    8 * mapper; 
    9 * filter; and 
    10 * terminal. 
     5There are two ways to exploit the MUSCLE API: either by using these defined by the Multiscale Modeling Language, or by writing free-form code, where all orchestration and deadlock detection is your own responsibility. The former gives code that is easy to read and to debug, while the latter makes it possible to optimally exploit any parallelism in the model. This page section is split in two parts, one for each approach. With care, it is also possible to combine these approaches in a model, choosing the more appropriate form per submodel. 
    116 
    12 These elements are all supported in the MUSCLE API. 
     7The computational elements that the Multiscale Modeling Language (MML) defines are: 
     8* the conduit, for sending messages; 
     9* submodel, for modeling phenomena at certain scales; 
     10* mapper, for dimensionless mappings of data; 
     11* filter, for time and datatype filtering; and 
     12* terminal, for terminating empty conduits. 
    1313 
    14 There are two ways to exploit the MUSCLE API: either by using these constructs, or by writing free-form code, where all orchestration and deadlock detection is your own responsibility. The former gives code that is easy to read and to debug, while the latter makes it possible to optimally exploit any parallelism in the model. This page section is split in two parts, one for each approach. With care, it is also possible to combine these approaches in a model, choosing the more appropriate form per submodel. 
    15  
    16 In both cases, conduits are defined the same, and parameters are passed in the same way. 
     14These elements are all supported in the MUSCLE API. Conduits and parameters are used the same in MML-based or free-form code. 
    1715 
    1816=== Conduits === 
    … …  
    5654Timestamp time = obsA.getTimestamp(); 
    5755}}} 
     56If receive is called and the submodel on the other end has stopped, a MUSCLEConduitExhaustedException is thrown. To prevent this, it is possible to first call exitA.hasNext(), which is also blocking but returns a boolean. 
     57 
     58If a lot of conduit exits are used and the order in which they are received is not important, it is possible to loop over multiple conduits and call the ready() method. This is non-blocking, and it will return true when hasNext() will return an answer without blocking. 
    5859 
    5960A ConduitEntrance has several different send functions. The most basic send(data) sends the data and deduces the timestamp at which the data is sent, by adding delta T of the timescale to the previous timestamp. If the instance is dimensionless, or if required, you can explicitly set the timestamp of the data, and the timestamp at which you send the next message with send(data, time, nextTime): 
    … …  
    6970}}} 
    7071 
    71 Although the entrance is automatically closed once the instance is finished, it is also possible to close the conduit earlier. 
     72Although the entrance is automatically closed once the instance is finished, it is also possible to close the conduit earlier with the close() method, if it is not going to be used again. 
    7273 
    7374=== Parameters === 
    … …  
    110111} 
    111112}}} 
    112 Step by step, a submodel can be restarted any number of times depending on the couplings, this is what the outer loop does. Next, each time a submodel is run, it has an initialization phase where it determines the initial state and what the simulation time of this initial state should be. Then it enters a while loop while some end condition is not met. Each iteration it sends some observation of the state, and it computes the next state. When the end condition is met, it is possible to do some cleaning and to send a final observation. At the end of the submodel it decides whether it should restart. 
     113Reading this code step by step, a submodel can be restarted any number of times depending on the couplings, this is what the outer loop does. Next, each time a submodel is started, it has an initialization phase where it determines the initial state and what the simulation time of this initial state should be. Then it enters a while loop while some end condition is not met. Each iteration it sends some observation of the state, and it computes the next state. When the end condition is met, it is possible to do some cleaning and to send a final observation. At the end of the submodel it decides whether it should restart. 
    113114 
    114 In MUSCLE, endCondition is implemented as the willStop() method, which looks at all the messages sent and received and the message with the highest simulation time is compared with the total time in the timescale of the submodel, with parameter "submodelName:T". 
     115In MUSCLE, endCondition is implemented as the willStop() method, which looks at all the messages sent and received and the message with the highest simulation time is compared with the total time in the timescale of the submodel, with parameter "submodelName:T". Restart submodel returns false by default, but could depend on whether one of the conduits will receive more messages. 
    115116 
    116117== MUSCLE free-form API ==