# Model coupling collaborative document
## a.k.a. The digital ginger twins show

This document: https://tinyurl.com/2022-11-01-model-coupling

Setup (episode 3 and 4): https://esciencecenter-digital-skills.github.io/model-coupling-workshop/index.html

The lesson: https://esciencecenter-digital-skills.github.io/model-coupling-workshop

9:00 Start (Lourens)
9:05 Introduction (Robin)
9:30 MMSF Theory (Lourens)
10:15 Break
10:30 Connect a model to MUSCLE3 (Jaro)
11:30 Break
11:45 Run a coupled simulation (Jaro and Lourens)
12:30 End

## Roll call + fancy nickname for this workshop
- Jaro - The digital...
- Lourens - ...ginger twins
- Stefan
- Makeda (Candace Moore)
- Francesco
- Djura
- Yang
- Suvayu
- Meiert
- Sarah
- Bart

## Episode 1
### Challenge 1:
EXERCISE: BREAKING IT DOWN
Think of another system you might want to simulate. Can you think of how to break it down into two or more computational submodels? Most importantly, consider what information would be passed from one model to the other.

- *Name: Answer*
- Djura: Yesterday I heard someone talking about exposomics (I think) which is about the interaction with the human body and everything in the environment must be a lot of models needed there
- Meiert: evolution of accretion disks from the radiative dominated to the GR advection dominated domain. The outer disk is dominated by gas-flow physics in the newtoninan limit. The inner by GR driven advection. The mass flow through the boundary must be passed to the GR submodel, the radiation output from the inner accretion disk, which heats the outer, must be passed back. The inner disk evolves on timescales OOM shhorter than the outer.
-
- Makeda: human brain
- Yang: simulation of ship and water, the interaction between fluid and solid structure should be addressed by the forcing between each other, and the deformation of water body and structures.
- Francesco: chemical systems, where you want to describe a part of the system at higher level of theory (atomistically) and the environment at lower level (continuum). E.g.: solute + solvent.
- Stefan: System biology, simulate cell, submodels: membrane, nucleus, mitochonria, reactions
- Suvayu: I have always wondered how to simulate a marketplace. The approach there could be to have separate "models" for the marketplace, and different entities interacting (buyers & sellers). And the data that they exchange is inventory, willingness to buy (or maybe funds available), and revenue/profit per transaction. However I have never found a way to model the game theory aspect of it, e.g. how does a seller respond to another sellers actions (e.g. discounts), or how to model asymmetry of information, e.g. the marketplace knows about every participant, but participants don't have a way to counter.
- Sarah: modeling plant activities: leaf processes, root processes, hydraulic and photosynthetic processes.

## Episode 2

### Challenge 1:

(Copy-paste the table template and add your own submodels)

*Name*
| Submodel | Domain |
| --- | --- |
| | |
| | |

*Djura*
| Submodel | Domain |
| --- | --- |
| airplane | the physical airplane for the duration of the flight |
| air | the airflow in some region around the airplane (adjacent to the airplane)for the duration of the flight |
|molecular level (maybe there's some tearing to be modeled|I guess same temporal domain as the rest? same space as the fysical airplane |

*Suvayu* (public transport network for a city)
| Submodel | Domain |
| --- | --- |
| infrastructure (state of operation) | discrete changes in space & time, mostly static |
| service (metro, bus, tram) | running duration, route |
| commuters | departure time, desired time of arrival, start and end points |

*Francesco*
| Submodel | Domain in space |
| --- | --- |
| Solute | Closed volume around a molecule |
| Solvent | Outside the solute region |

Domain in time: consider equilibrium conditions

*Meiert*
| Submodel | Domain in space |
| --- | --- |
| outer radiative, classic HD |Space around SMBH at galaxy center, outer accretion disk till last stable orbit |
| inner disk, GR advection dominated, GR MHD |Space around SMBH at galaxy center, from last stable orbit to Event Horizon |
| --- | --- |
|Submodel | Domain in time |
| --- | --- |
| | overlapping, arbitrary, till equilibrium |
| |overlapping,, arbitrary, till equilibrium |
| | |

*Yang*
| Submodel | Domain |
| --- | --- |
| ship | structual dynamic system of a solid body, adjacent to water domain and air domain and the free interface between water and air |
| water | fuild dynamic field |
| air | fuild dynamic field |
| air-water interface | fuild dynamic field with interaction between two fluid fields with different features |

*Stefan*
| Submodel | Domain |
| --- | --- |
| Molecular dynamics | femto second |
| Membrane transport | milli second |

*Sarah*
model: real-time predictions of vegetation health
| Submodel | Domain |
| --- | --- |
| satellite data | time(month to day)-space(km to m) |
| plant process | time(hour to minute)-space (m to cm) |
| atmospheric process | time(hour to minute)-space (km to m) |
| antropologic process | time(day to hour)-space (km to m) |

### Challenge 2:

(Copy-paste the table template and add your own submodels, or copy-paste from above and add a column)

| Submodel | Domain | Scale |
| --- | --- | --- |
| | | |
| | | |

*Djura*
| Submodel | Domain | Scale |
| --- | --- |---|
| airplane | the physical airplane for the duration of the flight | centimeters, millimeters?, size is the size of the airplane |
| air | the airflow in some region around the airplane (adjacent to the airplane)for the duration of the flight | Maybe centimeters, millimeters? size of the selected region around the airplane |
|molecular level (maybe there's some tearing to be modeled|I guess same temporal domain as the rest? same space as the fysical airplane | molecular scale, still encompasses the whole plane (potentially) |

*Suvayu* (public transport network for a city)
| Submodel | Domain | Scale |
| --- | --- | -- |
| infrastructure | spans the whole city | kms |
| infrastructure | lifetime of tracks, stations, etc | years |
| service | route/a path along the city/infrastructure | kms|
| service | trip duration/$\Delta t$ | HH:MM |
| commuters | a person | m/cm |
| commuters | trip duration/$\Delta t$ | HH:MM (similar to service) |

*Stefan*
| Submodel | Scale | Domain |
| --- | --- | --- |
| Molecular dynamics | femto second | ligand-protein-complex inside membrane |
| Membrane transport | milli second | membrane of a cell|

*Francesco*
| Submodel | Domain in space | Scale |
| --- | --- | --- |
| Solute | Closed volume around a molecule | Angstroms / nanometer |
| Solvent | Outside the solute region | Nanometers |

*Meiert*
| Submodel | Domain in space | spatial scale |
| --- | --- | --- |
| outer radiative, classic HD |Space around SMBH at galaxy center, outer accretion disk till last stable orbit | kpc scale, pc resolution |
| inner disk, GR advection dominated, GR MHD |Space around SMBH at galaxy center, from last stable orbit to Event Horizon | pc scale, millipc resolution |
| --- | --- | --- |
|Submodel | Domain in time | scale in time |
| --- | --- | --- |
| | overlapping, arbitrary, till equilibrium |10 - 1000 Myr, @~Myr |
| |overlapping,, arbitrary, till equilibrium | 100/1000 yr - Myr, @~100yr |
| | | |

*Yang*
| Submodel | Domain | Scale |
| --- | --- | --- |
| ship | structual dynamic system of a solid body, adjacent to water domain and air domain and the free interface between water and air | in minutes and meters |
| water | fuild dynamic field | in minutes and meters |
| air | fuild dynamic field |in minutes and meters |
| air-water interface | fuild dynamic field with interaction between two fluid fields with different features | in minutes and meters |

*Makeda*
| Submodel | Domain | Scale |
| --- | --- | --- |
| neuronal electrical activity | brain |seconds? |
| axonal activity | | |

*Sarah*
model: real-time predictions of vegetation health
| Submodel | Domain | Scale |
| --- | --- | --- |
| satellite data | time-space(global) |time(month to day)-space(km to m)|
| plant process | time-space |time(hour to minute)-space (m to cm)|
| atmospheric process | time-space |time(hour to minute)-space (km to m)|
| antropologic process | time-space|time(day to hour)-space (km to m)|

**The Scale Separation Map.** The box in the center depicts the scale of a given process or model, the dashed boxes show possible other scales and the corresponding relationships.

**Submodel Execution Loop (SEL)**

**Coupling Templates**

**Coupling Templates in gMMSL**

## Episode 3

### Challenge 1:

In the previous episode we have discussed the Submodel Execution Loop (SEL) and the various operators that are associated with it. In the code of the reaction function, can you recognize the beginning and end of the four operators (finit, Oi, S and Of ) plus the state update loop in this submodel? Mark these by placing the following 10 comments in the code:

# begin F_INIT
# end F_INIT
# begin O_I
# end O_I
# begin S
# end S
# begin state_update_loop
# end state_update_loop
# begin O_F
# end O_F

### Challenge: Port names

Which ports do we need on the reaction submodel to communicate with the outside world? What should they be called? Which operators should they be associated with?
- Djura: O_F: U (final state), initial state is `initial_state`

- Meiert: {F_init: 'inital_concentration_distribution', O_F: 'final_concentration_distribution'
- Stefan: {F_INIT: 'initial_concentration', O_F:'final_concentration'}

### Challenge 2: Creating an instance and adding a loop

Add the following to our reaction model code:

- a libmuscle.Instance object with the appropriate operator-port dictionary
- the reuse loop

### Challenge 3: Getting settings

In our example, several settings have been hard-coded into the model:

- the total simulation time to run this sub-model, t_max
- the time step to use, dt
- and the model parameter, k

Change the code such that we request these settings from the MUSCLE manager.

### Challenge 4: Receiving the initial state and keeping track of time

Where previously we had received initial_state from the function call, we now want to get it through a libmuscle message. Add statements to receive a message on the initial_state port and store the data and timestamp attributes in an appropriate place.

Also make sure the state update loop tracks global simulation time (corrected by the received timestamp).

### Challenge 5: Send back the result

In the Of operator of your model construct a message and replace the return statement with a call to libmuscle.Instance.send() to send the final state to the outside world.

## Episode 4

### Challenge 1:

What is different between the reaction model we saw previously and the diffusion model in `diffusion.py`? Beyond the model itself being different, obviously :-)

### Challenge 2: Complete the yMMSL file

Open the file reaction_diffusion.ymmsl. In it, you’ll find an incomplete yMMSL description of the coupled simulation, as shown below. Your challenge? Complete it!

## Feedback

### How was the difficulty level of the course?
- just right +1

### How was the quality of the course?
- good, although it takes more time than planned +1

### Is anything missing?
- more challenges (exercises) or examples

### Any other comments?
- In carpentries workshops we usually don't show the lesson material directly on the screen, maybe a powerpoint (or a browser tab with just the relevant picture) would be nicer
- This workshop was awesome!
- it would be nice to edit ymmsl file in editor like Visual Studio Code with syntax highlighting and validation like missing keys

## BUGS
- not working on Windows or WSL(or at least Makeda WSL)
- On mac, I had to have the main program within `if __name__ == "__main__":` - probably due to the different behaviour in forking/spawning threads.
- see Multiprocessing section here: https://carpentries-incubator.github.io/lesson-parallel-python/04b-threads-and-processes/index.html, it links to the relevant part in the Python docs