Merge pull request #720 from molpopgen/more_demes_docs

Add more documentation re: demes.

doc/_toc.yml

@@ -70,6 +70,7 @@
 
 - part: Technical details
   chapters:
+  - file: technical/demes
   - file: technical/genetic_values
   - file: technical/writingplugins
 

doc/pages/demographic_models.md

@@ -16,6 +16,7 @@
 
 ```{eval-rst}
 .. autoclass:: fwdpy11.demographic_models.DemographicModelDetails
+   :members:
 ```
 
 ```{eval-rst}

doc/short_vignettes/demes_vignette.md

@@ -91,3 +91,28 @@ print(model.asblack())
 ```
 
 Again, it is simpler to build up the demography using `demes` than it is using the `fwdpy11` objects directly.
+
+## Initializing populations
+
+A model specified using `demes` contains enough information to initialize instances of {class}`fwdpy11.DiploidPopulation`.
+We recommend that you use this information so that the initial deme size(s) in your simulation is correct!
+
+To see how this works, let's revisit the Gutenkunst model from above.
+The value returned contains the initial size of each deme in the model:
+
+```{code-cell}
+model = fwdpy11.discrete_demography.from_demes("gutenkunst_ooa.yml")
+
+print(model.metadata['initial_sizes'])
+```
+
+Given that, a sorted list comprehension does the job:
+
+```{code-cell}
+initial_sizes= [model.metadata['initial_sizes'][i] for i in sorted(model.metadata['initial_sizes'].keys())]
+pop = fwdpy11.DiploidPopulation(initial_sizes, 1000.)
+print(pop.deme_sizes())
+```
+
+The reason to go through the sorting step is to get the right initial sizes *in the right order* for "rootless" `demes` graphs.
+A rootless model is one with more than one ancestral deme in the ancient past.

doc/technical/demes.md

@@ -0,0 +1,16 @@
+(demes_details)=
+
+# Details of `demes` integration
+
+This page gives various technical details regarding `fwdpy11` treats [`demes`](https://popsim-consortium.github.io/demes-docs/main/) models.
+See {ref}`the vignette <demes_vignette>` for an overview.
+
+## Implementation of mass migration events (a.k.a. pulse migrations)
+
+The low-level discrete demography `API` provides {class}`fwdpy11.MassMigration` to implement single-generation bulk movements of lineages.
+See {ref}`here <massmigrations>` for details.
+
+For models generated with `demes`, we instead use a single-generation change to the migration matrix.
+It turns out that this method greatly simplifies the implementation of {func}`fwdpy11.discrete_demography.from_demes`.
+
+While biologically and mathematically equivalent, these two approaches would give different results for the same random number seed.