User guide: Simulation

[AVHopp]

The user guide for simulations needs to be written.

[Scienfitz]

this has priority as its currently empty

[AVHopp]

@AdrianSosic the original plan was that you write this guide. Do we stick with that plan or should we adjust?

[AdrianSosic]

No it's fine, can write it, but would want to refactor the remaining open issues in the file first. Can plan this as my next PR. Because otherwise, there is the chance that the guide would need to be readjusted right after, which is a step that can be saved.

[AdrianSosic]

Hi @AVHopp and @Scienfitz, I'm currently working on the simulation module to get it ready for the doc page. One thing that I want to get straight is to turn it into a subpackage with clear folder structure and name space, like for the other subpackages that we already have. Therefore, a few things that we should align on:

In its current version, the package will surface three public methods that will also be described on the docs page. In our old code, these are called simulate_experiment, simulate_scenarios and simulate_transfer_learning, which is not yet ideal for the following reasons:

• According to our nomenclature, an "experiment" really just corresponds to one single parameter configuration, but simulate_experiment runs an entire campaign loop.
• simulate_scenarios logically does the same as simulate_experiment but for different conditions. The names should probably reflect that.

So possible options are:

1. simulate_scenario, simulate_scenarios, simulate_transfer_learning
2. simulate_campaign, simulate_campaigns, simulate_transfer_learning
3. same as 1 but with "run_"
4. same as 2 but with "run_"
5. Your ideas

Perhaps one reason why "scenario" could be more appropriate than "campaign" is because you not only specify a campaign as input but also other configurations, such as Monte Carlo runs etc. But maybe that's just me overthinking...

What are your opinions?

[AVHopp]

Agree that stuff should be renamed.
In general, I'd go with 2 as simulate is the more suitable word and campaign is a word that is already well-known in the context of BayBE, so people will know what to expect here. Regarding your overthinking: We actually still simulate a campaign, so the name of the function is correct. We only provide specific configurations on how to simulate the campaign.
I would however rather have something like simulate_single_campaign and simulate_multiple_campaign, as the two names are just too similar in my opinion.

[Scienfitz]

both 1 and 2 have a small disadvantage as they invite typos

But other than that I'm kind of indifferent to either 1 or 2. Maybe the point Alex makes can also be a disadvantage? Some who reads simulate_campaign might think it genreates me a random valid Campaign object (like in hypothesis)

Not a fan of "run..." anymore

[AdrianSosic]

Ok, then it's clear we take "simulate_". And with that, "simulate_campaign" seems sufficiently clear and crisp to me. Also, the third would then become "simulate_transfer_learning". About the middle one, I'm no longer sure. Now that I see the names and thought about it for a while, using the same word might actually be a bit misleading since its not only offers the possibilities to simulate multiple campaigns instead of just one, but also has many more other options... 🤔 I'll do the one change now and push the PR so that we can start the review. If we then still feel that the other names needs to be changed, I can add one more commit at the end.

[Scienfitz]

closing as PR for detailed discussion is open