Return values of simulation functions

[AtiyahElsheikh]

continuing #2

Summary:

doX!(*)

to return named tuple as outputs, i.e.

output1 = ... , output2 = ... , etc.

Particularly useful would be to return the indices of a concerned sub-population, e.g.

deads = .. , indexInPeople = ...

Here indexInPeople gives the indices of deads in a given population.

[AtiyahElsheikh]

The caller can retain a particular output easily, e.g.

function doDeaths(...) 
   ...
   return (deads = .. , deadsind = ...) 
end

The caller

(; deadsind) = doDeaths(model, allParameters(model))

[AtiyahElsheikh]

Functions s.a. doDeaths and doBirths create arrays of references every iteration. Avoiding this seems to significantly improve the memory usage and performance.

Therefore it is desired to allow function calls that don't return any output and performs the desired operation in place. This is realized by additional traits type NoReturn or WithReturn, .e.g. the default behavior of dodeaths:

dodeaths!(model, time) = 
    dodeaths!(model, time, AlivePopulation(), NoReturn())

Alternatively the function call

dodeaths!(model, time, AlivePopulation(), WithReturn())

returns outputs.

It is also thinkable to allow outputs to be placed in the first argument. This is can be done when needed.

[AtiyahElsheikh]

instead of traits, the API looks now as follows:

• x! (e.g. death!()) returns true or false
• dox!(model, time, ret=) or dox!(model,time, popfeature,ret=)

the third argument, popfeature, is related to #21

ret can take one of the following values:

• nothing : no return is done
• an integer (say of value v) : v + number of dox occurrences is returned
• a vector of Person[] : vector of persons that have been subject to x are returned. Here the same vector can be used to ensure less storage usage. This vector of person will be emptied as the beginning of the dox operation
• a named tuple of people and indices to also return the indices of people in the target subpopulation that were subject to dox!