Specification requirements and structure

[jeromekelleher]

I'm struggling to find a way to get all of the different components of this specification, their properties, requirements and interpretations down in a single document. Perhaps writing down what the audiences and requirements actually are will help.

Audiences

Who will read this specification, and what do they need from it.

Simulation method developers

They need

• understand the precise semantics of the population genetics models (e.g., do migrations happen at the end of a generation or start, etc)
• understand the types and interpretations of all the values in the MDM. (.e.g. that time intervals are half-open)
• understand the distinction between the HDM and MDM, and what a parser does for them

(Let's let "simulation methods" stand for any downstream program that consumes Demes as input.)

Inference methods developers

The need

• understand the population genetics models
• understand the HDM data model, and how values can be omitted, defaults are used, etc.
• understand how to write "good" models using the HDM (i.e., what are recommendations for using defaults?)

People wishing to read and write models themselves

I guess these are the same needs as inference methods developers?

Is there anyone else?

Document structure

We need some sort of document structure that will allow these audiences to find the content they want easily.

Very much open to ideas and input here!

[grahamgower]

Maybe it could be structured as producers, parsers, and consumers? Producers are: (1) people that write models, and (2) inference methods. Parsers are the translation software that converts a HDM to the MDM. Consumers are software that works with fully-resolved models, or some API that exposes fully-resolved models (like users of the demes-python demes.Graph API).

I think that to fully understand how a given YAML file will be interpreted by simulation software, model writers probably need to grok each of these (although some details won't be so important to them).

EDIT: Perhaps framing it from a user-contract point of view would be useful? I.e. describe what the user (a model writer, intending to simulate their model) can expect at each of these three stages, and then a compliant parser must fullfill that contract.