[distr201] webdoc: describe new distribution examples ()

Merging branch 'distr201'  into 'main'.

See merge request !1497

hugo/content/ex/sample/compund-particle.md

@@ -6,10 +6,11 @@ weight = 10
 ## Compound particle example
 
 In this example it is modelled a multi layer consisting of a substrate layer and an air layer.
-Cylindrical particles made of two materials are added to the air layer and their $z$ coordinate is shifted downwards in order to cross the air-substrate interface.
+Cylindrical particles made of two materials are added to the air layer
+and their $z$ coordinate is shifted downwards in order to cross the air-substrate interface.
 
 {{< galleryscg >}}
-{{< figscg src="/img/auto/scatter2d/BiMaterialCylinders.png" width="450px" caption="Intensity image">}}
+{{< figscg src="/img/auto/scatter2d/BiMaterialCylinders.png" width="450px" >}}
 {{< /galleryscg >}}
 
 {{< highlightfile file="Examples/scatter2d/BiMaterialCylinders.py" >}}

hugo/content/ex/sample/lattice-ori-distr.md

++++
+title = "Lattice orientation distribution"
+weight = 81
++++
+
+## Lattice orientation distribution example
+
+This example shows GISAS by an isotropic mixture of lattices.
+On top of a substrate, we have square lattices of cylinders.
+The lattice orientation has a uniform distribution over the full range
+form $0^\circ$ to $90^\circ$.
+
+The differently oriented lattices are incoherently summed
+using a loop over the parameter distribution samples.
+This is currently supported only under Python scripting, not in the GUI.
+
+Class references: [Layer](/ref/sample/multilayer/layer), [Distributions](/ref/other/distributions).
+
+{{< galleryscg >}}
+{{< figscg src="/img/auto/scatter2d/LatticeOrientationDistribution.png" width="450px">}}
+{{< /galleryscg >}}
+
+{{< highlightfile file="Examples/scatter2d/LatticeOrientationDistribution.py" >}}

hugo/content/ex/sample/polydispersity.md

++++
+title = "Polydispersity"
+weight = 80
++++
+
+## Polydisperse particles example
+
+This example shows GISAS by polydisperse cylinders on a substrate.
+The radii of the cylinders follow a Gaussian distribution.
+
+The uncorrelated particles are added to a layout using a loop
+over the parameter distribution samples. This is currently supported
+only under Python scripting, not in the GUI.
+
+Class references: [Layout](/ref/sample/multilayer/layout),
+[Distributions](/ref/other/distributions).
+
+{{< galleryscg >}}
+{{< figscg src="/img/auto/scatter2d/PolydisperseCylinders.png" width="450px">}}
+{{< /galleryscg >}}
+
+{{< highlightfile file="Examples/scatter2d/PolydisperseCylinders.py" >}}

hugo/content/ref/other/distributions.md

@@ -5,11 +5,41 @@ weight = 60
 
 ## Parameter distributions
 
-Currently avaliable distributions include
- -  Gate: `DistributionGate(n_samples, sigma_factor, min, max)`
- -  Lorentz: `DistributionLorentz(n_samples, hwhm_factor, min, max)`
- -  Gaussian: `DistributionGaussian(n_samples, sigma_factor, min, max)`
- -  LogNormal: `DistributionLogNormal(n_samples, sigma_factor, min, max)`
- -  Cosine: `DistributionCosine(n_samples, sigma_factor, min, max)`
-
-Usage will change soon, and shall be documented then.
\ No newline at end of file
+##### Constructors
+
+A distribution is constructed by one of the following:
+```python
+distr = ba.DistributionGate(start, stop, n_samples=25)
+distr= ba.DistributionTrapezoid(center, left, middle, right, n_samples = 25)
+distr = ba.DistributionCosine(mean, sigma, n_samples = 25)
+distr = ba.DistributionGaussian(mean, std_dev, n_samples=25, rel_samplig_width=2)
+distr = ba.DistributionLorentz(mean, hwhm, n_samples=25, rel_samplig_width=2)
+distr = ba.DistributionLogNormal(median, sigma_scale_param, n_samples=25, rel_samplig_width=2)
+```
+
+##### Usage
+
+Parameter distributions are either supplied to beam divergence or detector resolution
+classes as described there, or they are used programmatically.
+
+In programmatical usage, the function call
+```
+parsamples = distr.distributionSamples()
+```
+returns a vector of parameter samples. Each `ParameterSample` has a `value` and a `weight`.
+The sample (scattering target) model is then constructed as incoherent sum of components
+with given parameter values and weights.
+For instance, in the [PolydisperseCylinders example](/ex/scatter2d/polydisperse-cylinders),
+a layout is filled with uncorrelated particles:
+```python
+distr = ba.DistributionGaussian(10*nm, 1*nm)
+for parsample in distr.distributionSamples():
+    ff = ba.Cylinder(parsample.value, 5*nm)
+    particle = ba.Particle(material_Particle, ff)
+    layout.addParticle(particle, parsample.weight)
+```
+
+##### Examples
+
+- [PolydisperseCylinders](/ex/sample/polydispersity): layout filled with uncorrelated particles
+- [LatticeOrientationDistribution](/ex/sample/lattice-ori-distr): layer filled with uncorrelated layouts
\ No newline at end of file