add more to guide 102 #498

DEV_NOTE2.md

@@ -28,7 +28,48 @@ Also see https://linguaphylo.github.io/programming/2020/09/22/linguaphylo-for-de
 
 ### Generative distribution
 
-TODO:
+It is a Java interface to represent all types of generative distributions, 
+such as [probability distributions](lphy-base/src/main/java/lphy/base/distribution), tree generative distributions 
+(e.g. [Birth-death](docs/lphy/evolution/birthdeath.md), [Coalescent](docs/lphy/evolution/birthdeath.md)), 
+and [PhyloCTMC](docs/lphy/evolution/likelihood.md) generative distributions.
+
+To write your own generative distribution, you need to follow these steps:
+
+1. Design your LPhy script first, for example, `Θ ~ LogNormal(meanlog=3.0, sdlog=1.0);`.
+
+2. Create a Java class (e.g. LogNormal.java) to implement [GenerativeDistribution<T>](https://github.com/LinguaPhylo/linguaPhylo/blob/432a3edea15188c72fa12d42d0f238e9c25c1843/lphy/src/main/java/lphy/core/model/GenerativeDistribution.java). 
+
+Look at the example [LogNormal.java](https://github.com/LinguaPhylo/linguaPhylo/blob/eea9a4657669a6e9ce3f0acac494fab803df681c/lphy-base/src/main/java/lphy/base/distribution/LogNormal.java).
+A few things are required:
+
+   - Define its LPhy name by the annotation `@GeneratorInfo` for the overwritten method `RandomVariable<Double> sample()`. 
+
+     `name = "LogNormal"` will allow the parser to parse it in a LPhy code into this Java object.
+
+
+   - Define the arguments for this distribution using the annotation `@ParameterInfo` inside the constructor.
+
+     `name = "meanlog"` declares one of the arguments as "meanlog". This is also referred to as a **named argument**. 
+     Following the annotation, you need to declare the Java argument for this constructor, 
+     which must be a Value, such as `Value<Number> M`. We use `Number` so that this input can accept integer values. 
+     To make an argument optional, simply add `optional = true`.
+
+
+   - Define the data type, e.g. `LogNormal extends ParametricDistribution<Double> implements GenerativeDistribution1D<Double>`,
+     where `Double` replaces `T` and must be consistent with the returned type `RandomVariable<Double> sample()`.
+
+
+   - Implement the method `RandomVariable<...> sample()` which should sample a value from this distribution 
+     and then wrap it into `RandomVariable`.
+
+
+   - Correctly implement both methods `Map<String, Value> getParams()` and `setParam(String paramName, Value value)`, 
+     otherwise, it will fail when re-sampling values from the probabilistic graphical model represented by 
+     an LPhy script using this distribution.
+
+
+3. Register the distribution to SPI.
+
 
 ### Deterministic function