@@ -189,6 +189,38 @@ interpret these fields, e.g. to extract the component and port name parts.
189189Note that the format allows specifying a slot here, but this is currently not
190190supported and illegal in MUSCLE3.
191191
192+ Multicast conduits
193+ ^^^^^^^^^^^^^^^^^^
194+
195+ In yMMSL you can specify that an output port is connected to multiple input
196+ ports. When a message is sent on the output port, it is copied and delivered to
197+ all connected input ports. This is called multicast and is expressed as
198+ follows:
199+
200+ .. code-block :: yaml
201+ :caption : Specifying multicast in yMMSL
202+
203+ conduits :
204+ sender.port :
205+ - receiver1.port
206+ - receiver2.port
207+
208+
209+ sender:
210+
211+ .. code-block :: python
212+ :caption: Multicast conduits in python code
213+
214+ from pathlib import Path
215+ import ymmsl
216+
217+ config = ymmsl.load(Path(' multicast.ymmsl'
218+
219+ conduits = config.model.conduits
220+ print (len (conduits)) # output: 2
221+ print (conduits[0 ]) # output: Conduit(sender.port -> receiver1.port)
222+ print (conduits[1 ]) # output: Conduit(sender.port -> receiver2.port)
223+
192224
193225--------
194226
@@ -330,6 +362,44 @@ Finally, if you need to do something complicated, you can write an inline script
330362to start the implementation. This currently only works for non-MPI programs
331363however.
332364
365+ Keeps state for next use
366+ ````````````````````````
367+
368+ Implementations may indicate if they carry state between reuses. This is
369+ currently only used for `checkpoints `_, but might see further
370+ use in the future (e.g. for load balancers). There are three possible values
371+ an implementation may indicate.
372+
373+ Necessary
374+ This implementation remembers state between consecutive iterations of the
375+ reuse loop. That state is required for the proper execution of the
376+ implementation.
377+
378+ This is the default value when not specified.
379+
380+ **Example: ** A micro model simulating an enclosed volume, where every reuse
381+ the boundary conditions are updated by the connected macro model. This micro
382+ model must keep track of the state inside the simulated volume between
383+ iterations of the reuse loop.
384+
385+ No
386+ This implementation has no state between consecutive iterations of the reuse
387+ loop.
388+
389+ **Example: ** A data converter that receives on an ``F_INIT `` port, transforms
390+ the data and outputs it on an ``O_F `` port. The transformation is only
391+ dependent on the information of the ``F_INIT `` message.
392+
393+ Helpful
394+ This implementation remembers state between consecutive iterations of the
395+ reuse loop. However, this state is not required for proper execution.
396+
397+ **Example: ** A simulation of a fluid in a pipe with obstacles. The simulation
398+ converges much faster when starting from the solution of the previous
399+ iteration. However, the same solution can still be found when starting from
400+ scratch.
401+
402+
333403Resources
334404---------
335405
@@ -404,6 +474,72 @@ Computing section in the MUSCLE3 documentation
404474<https://muscle3.readthedocs.io/en/latest/distributed_execution.html#high-performance-computing> `_.
405475
406476
477+ Checkpoints
478+ -----------
479+
480+ In yMMSL you can specify if you expect the workflow to create checkpoints. Note
481+ that all implementations in your workflow must support checkpointing, MUSCLE3
482+ will generate an error for you otherwise. See the `documentation for MUSCLE3
483+ <https://muscle3.readthedocs.io/en/latest/> `_ on checkpointing for details on
484+ enabling checkpointing for an implementation.
485+
486+ Checkpoint triggers
487+ ```````````````````
488+
489+ In yMMSL you have three possible checkpoint triggers:
490+
491+ ``at_end ``
492+ Create a checkpoint just before the instance shuts down. This can be a useful
493+ checkpoint if you intend to resume the workflow at some later point, e.g.
494+ when you wish to simulate a longer time span. This trigger is either on or
495+ off, specified with a boolean ``true `` or ``false `` (default) in the
496+ configuration.
497+
498+ ``simulation_time ``
499+ Create checkpoints based on the passed simulation time. This can only work
500+ properly if there is a shared concept of simulated time in the workflow.
501+
502+ ``wallclock_time ``
503+ Create checkpoints based on the passed wall clock time (also called `elapsed
504+ real time <https://en.wikipedia.org/wiki/Elapsed_real_time> `_). This method
505+ is not perfect and may result in missed checkpoints in certain coupling
506+ scenarios. See the MUSCLE3 documentation for a discussion of the limitations.
507+
508+ When you use any of the time-based triggers, you must also specify at what
509+ moments a checkpoint is expected. MUSCLE3 will then snapshot as soon as
510+ possible **after ** reaching the specified times. You may indicate specific
511+ moments with ``at ``-rules, but can also create repetitive checkpoints.
512+
513+ .. code-block :: yaml
514+ :caption : Example checkpoint definition
515+
516+ checkpoints :
517+ at_end : true
518+ simulation_time :
519+ - at : [1.2, 1.4]
520+ - every : 1
521+ wallclock_time :
522+ - every : 60
523+ stop : 600
524+ - every : 600
525+ start : 600
526+ stop : 3600
527+ - every : 1800
528+ start : 3600
529+
530+
531+ create checkpoints:
532+
533+ - At the end: ``at_end: true ``.
534+ - Every second of passed simulated time (``t=0,1,2,... ``), and additionally at
535+ ``t=1.2 `` and ``t=1.4 ``.
536+ - Every minute of real elapsed time, for the first 10 minutes; then every 10
537+ minutes for the remainder of the first hour; then every 30 minutes until the
538+ end.
539+
540+ See the API documentation for :py:class: `~ymmsl.CheckpointRangeRule ` for more
541+ details on the behaviour of the repetitive checkpoints.
542+
407543Examples
408544--------
409545
0 commit comments