# Generating a Tessellation from Statistical Cell Properties

Statistical morphological properties for the cells can be specified as input, using option `-morpho`

. In this case, instead of a Voronoi tessellation, Neper generates a Laguerre tessellation (which can represent any tessellation comprised of convex cells, and therefore does not involve particular limitations) by optimizing the attributes of its seeds until the specified input is reached [CMAME2018].

Note

To reproduce *exactly* the images below, add the following line to your `$HOME/.neperrc`

file (or to a local configuration file to be loaded with `--rcfile`

):

```
neper -V -imagesize 800:400
```

## Using the Built-in `graingrowth`

Option `-morpho`

includes the `graingrowth`

(or `gg`

, for short) properties, which corresponds to those of an experimental polycrystal subjected to grain growth. Both the cell size distribution and the cell sphericity distribution (how close are the cells from a sphere) are defined [CMAME2018].

A 100-cell tessellation with grain-growth properties can be generated using the Tessellation Module (-T) as follows:

```
$ neper -T -n 100 -morpho gg
```

This produces a Tessellation File (.tess) named `n100-id1.tess`

.

The tessellation can be visualized using the Visualization Module (-V):

```
$ neper -V n100-id1.tess -print img1
```

This produces a PNG file named `img1.png`

.

## Specifying Custom Properties

Statistical properties other than those of `gg`

can be specified. `gg`

actually is an alias for `diameq:lognormal(1,0.35),1-sphericity:lognormal(0.145,0.03)`

, where `diameq::lognormal(1,0.35)`

specifies a lognormal distribution of the (normalized) cell equivalent diameters of average 1 and standard deviation 0.35, and `1-sphericity:lognormal(0.145,0.03)`

corresponds to a lognormal distribution of the cell “1-sphericities” of average 0.145 and standard deviation 0.03. It is therefore possible to use this longer argument and change the numerical values. For example, to get nearly equal-size cells (small standard deviation of the cell size lognormal distribution), one may use:

```
$ neper -T -n 100 -morpho "diameq:lognormal(1,0.05),1-sphericity:lognormal(0.145,0.03)"
```

The tessellation can be visualized as before:

```
$ neper -V n100-id1.tess -print img2
```

Of course, it is also possible to change the sphericity distribution, for instance to get less spherical grains (smaller average of the sphericity distribution):

```
$ neper -T -n 100 -morpho "diameq:lognormal(1,0.05),1-sphericity:lognormal(0.245,0.03)"
```

The tessellation can be visualized as before:

```
$ neper -V n100-id1.tess -print img3
```

Note

See Statistical Distributions for a list of possible distributions and other possible inputs.

Important

Although it is not strictly needed, distributions for both the sizes (e.g. `diameq`

) and the shapes of the cells should be specified. Generating a tessellation from only a cell size distribution can lead to unrealistically small cell sphericities.

## Specifying an Absolute Cell Size Distribution

It is possible to get Neper to consider the cell size distribution as a distribution of absolute values by using `-n`

`from_morpho`

(instead of an actual number of cells). Neper determines the number of cells from the cell size distribution and the domain size. An example is:

```
$ neper -T -n from_morpho -morpho "diameq:lognormal(0.2,0.06),1-sphericity:lognormal(0.145,0.03)" -o mytess
```

Note

Option `-o`

is used to set the output file name. The default file name is `n<n>-id<id>.tess`

and, in this case, would be the odd `nfrom_morpho-id1.tess`

.

The tessellation contains 184 cells and can be visualized as before:

```
$ neper -V mytess.tess -print img4
```

## Specifying an Experimental Cell Size Distribution

Experimental or, more generally, numerical distributions defined from a file can be specified by using option `-morpho`

`<property>:custom(<file_name>)`

(instead of analytical distributions).

Consider a cell-size (`diameq`

) distribution defined from a file, `mydistrib`

, that contains:

```
0.2 10.0
0.3 20.0
0.4 5.0
```

i.e., 10 cells have a `diameq`

equal to 0.2, 20 cells have a `diameq`

equal to 0.3, and 5 cells have a `diameq`

equal to 0.4 (for a tessellation comprising 35 cells). The numbers on the right column are actually only considered relative to each other.

Note

In contrast to analytical distributions, numerical distributions do not need to be normalized to 1.

As for an analytical distribution, if

`-morpho`

`from_morpho`

is used, Neper determines the number of cells from the cell size distribution and the domain size.

The corresponding tessellation can be generated as follows:

```
$ neper -T -n from_morpho \
-morpho "diameq:custom(mydistrib),1-sphericity:lognormal(0.145,0.03)" \
-statcell diameq \
-o mytess
```

where option `-statcell`

is used to output the cell equivalent diameters to file `mytess.stcell`

.

The tessellation can be visualized by coloring the cells from their equivalent diameters using options `-datacellcol`

and `-datacellscale`

:

```
$ neper -V mytess.tess \
-datacellcol "real:file(mytess.stcell)" \
-datacellscale 0.15:0.20:0.25:0.30:0.35:0.40:0.45 \
-datacellscaletitle "Cell size (mm)" \
-print img5
```

This produces a PNG file named `img5.png`

for the tessellation and a PNG file named `img5-scale3.png`

for the scale bar.

To include the scale bar to the image, ImageMagick can be used:

```
$ convert img5.png img5-scale3.png -gravity East -composite img5.png
```

## Speeding up Tessellation

When statistical properties (or other properties) are specified as input, Neper employs an interative approach, and so tessellation generation is longer than for a standard Voronoi tessellation. Even though the tessellation generation remains relatively fast, to speed up the tessellation process, a first way is through multithreading, as a performace increase is expected up about 16 threads. A second way is to modify the termination criterion, which is controlled by option `-morphooptistop`

and set to `val=1e-5`

by default, which is relatively low. The value can be increased, or another criterion can be used.