TL;DR

In this section of tutorial, we run the following commands:

cd examples/poisson/
../../bin/main -i poisson.sample.yml
../../bin/main -i poisson.sample.2d.yml
../../bin/main -i poisson.sample.random.yml
../../bin/main -i poisson.sample.yml -f model_reduction/subdomain_training=individual

In order to run sample generation, we set the option main/mode to be sample_generation in the input file. In the example of examples/poisson/poisson.sample.yml,

main:
  mode: sample_generation
  use_rom: true
  solver: poisson

There are two types of sampling:

• base sample generator that samples over uniform grid points on parameter space
• random sample generator that randomly choose the parameter values over a uniform random distribution

Base sample generator

In the example of examples/poisson/poisson.sample.yml, we use base sample generator, saving snapshots in the name of poisson0,

sample_generation:
  type: base
  file_path:
    prefix: "poisson0"

Specifying the list of sampling parameters

The list of parameters to be sampled is specified in the input file under sample_generation/parameter. In the example of examples/poisson/poisson.sample.yml, we sample over one parameter:

sample_generation:
  parameters:
    - key: single_run/poisson0/k
      type: double
      sample_size: 3
      minimum: 2.0
      maximum: 3.0

For each parameter listed, base sample generator creates an 1D uniform grid space between minimum and maximum with the specified sample_size. In sample generation, base sample generator replaces the value of the input option key with a sample value, and executes a single-run. Running the main driver with this input file

cd examples/poisson/
../../bin/main -i poisson.sample.yml

executes three single-runs that solve for Poisson equation with a sample value for parameter single_run/poisson0/k.

Technically, any option within the input file can be chosen as a sampling parameter. Currently, however, we only support double and filename type of input options. The example examples/poisson/poisson.sample.2d.yml samples over global configuration files as an additional parameter:

sample_generation:
  parameters:
    - key: single_run/poisson0/k
      type: double
      sample_size: 3
      minimum: 2.0
      maximum: 3.0
    - key: mesh/component-wise/global_config
      type: filename
      sample_size: 4
      minimum: 1
      maximum: 4
      format: "config/sample.config-%02d.h5"

For filename parameter, the key input option is set to a string that follows the format with an integer index. The integer index is chosen from 1D uniform grid space of size sample_size between minimum and maximum. In this example, 4 global configuration files will be used for sampling:

• config/sample.config-01.h5
• config/sample.config-02.h5
• config/sample.config-03.h5
• config/sample.config-04.h5

If multiple $N$ sampling parameters are listed, then base sample generator creates an $N$-D uniform grid space accordingly. For the $i$-th sampling parameter with sample size $S_i$, we have the total sample size of $$S = \prod_{i=1}^N S_i.$$

Running the example input file above

../../bin/main -i poisson.sample.2d.yml

will collect $3\times4=12$ samples with different single_run/poisson0/k values and mesh/component-wise/global_config files.

Random sampling

base sample generation can suffer the curse of dimensionality with a large number of sampling parameters. Using random sample generator can set the total number of samples and pick sample values randomly from the given ranges.

The example examples/poisson/poisson.sample.random.yml shows the input for generating 5 samples over random single_run/poisson0/k values and mesh/component-wise/global_config files:

sample_generation:
  type: random
  random_sample_generator:
    number_of_samples: 5
  parameters:
    - key: single_run/poisson0/k
      type: double
      minimum: 2.0
      maximum: 3.0
    - key: mesh/component-wise/global_config
      type: filename
      minimum: 1
      maximum: 4
      format: "config/sample.config-%02d.h5"

The probability distribution of each sampling parameter is uniform within the range between minimum and maximum. To see the sampling result of random sample generator, run the following command:

../../bin/main -i poisson.sample.random.yml

Subdomain training type

Sample generators save the snapshots differently according to the subdomain training type. There are two types of subdomain training type:

• universal: the snapshots are saved per each reference component mesh. POD basis will be also trained per each component.
• individual: given the global domain, individual subdomains are considered as reference components. The snapshots are saved per each individual subdomain.

The subdomain training type is specified in the input file as model_reduction/subdomain_training:

model_reduction:
  subdomain_training: universal

All previous examples were using universal subdomain training. The resulting snapshots are saved per each reference component mesh such as below:

With individual subdomain training, the snapshots are saved per each subdomain named as dom0, dom1, .... Running the following command

../../bin/main -i poisson.sample.yml -f model_reduction/subdomain_training=individual

will return the following output:

NOTE: sample generation for individual subdomain training works only when the global domain does not change: when the global domain mesh file or global configuration file is not sampled.