Create

The create subcommand creates the UQ run files.

To run the command:

duqtools create

Check out the command-line interface for more info on how to use this command.

The `create` config

The options of the create subcommand are stored in the create key in the config.

dimensions: The dimensions specifies the dimensions of the matrix to sample from. Each dimension is a compound set of operations to apply. From this, a matrix all possible combinations is generated. Essentially, it generates the Cartesian product of all operations. By specifying a different sampler, a subset of this hypercube can be efficiently sampled.
matrix: Use dimensions instead.
sampler: For efficient UQ, it may not be necessary to sample the entire matrix or hypercube. By default, the cartesian product is taken. For more efficient sampling of the space, the following method choices are available: latin-hypercube, sobol, halton. Where n_samples gives the number of samples to extract.
template: Template directory to modify. Duqtools copies and updates the settings required for the specified system from this directory. This can be a directory with a finished run, or one just stored by JAMS (but not yet started). By default, duqtools extracts the input IMAS database entry from the settings file (e.g. jetto.in) to find the data to modify for the UQ runs.
template_data: Specify the location of the template data to modify. This overrides the location of the data specified in settings file in the template directory.
data: Where to store the in/output IDS data. The data key specifies the machine or imas db name where to store the data (db). duqtools will write the input data files for UQ start with the run number given by run_in_start_at. The data generated by the UQ runs (e.g. from jetto) will be stored starting by the run number given by run_out_start_at.

For example:

duqtools.yaml

create:
  data:
    db: test
    run_in_start_at: 7000
    run_out_start_at: 8000
  dimensions:
  - ids: profiles_1d/0/t_i_average
    operator: multiply
    scale_to_error: false
    values:
    - 1.1
    - 1.2
    - 1.3
  - ids: profiles_1d/0/electrons/temperature
    operator: multiply
    scale_to_error: false
    values:
    - 1.1
    - 1.2
    - 1.3
  sampler:
    method: latin-hypercube
    n_samples: 3
  template: /pfs/work/docs/jetto/runs/duqtools_template

Specify the template data

By default the template IMAS data to modify is extracted from the path specified in the template field.

duqtools.yaml

template: /pfs/work/stef/jetto/runs/duqtools_template

In some cases, it may be useful to re-use the same set of model settings, but with different input data. If the template_data field is specified, these data will be used instead. To do so, specify template_data with the fields below:

user: Username.
db: IMAS db/machine name.
shot: IMAS Shot number.
run: IMAS Run number.

For example:

duqtools.yaml

template: /pfs/work/g2ssmee/jetto/runs/duqtools_template
template_data:
  user: g2ssmee
  db: jet
  shot: 91234
  run: 5

Data location

Specification for the data generated by the create step.

When setting up a sequence of UQ runs, duqtools reads the source data from the template. For each individual UQ run needs, two locations must be defined. 1. The location of the input data. This is where duqtools stores the modified source data. 2. The location of the output data. The modelling software must know in advance where to store the results of the simulation.

Input data are defined by run_in_start_at, and output data by run_out_start_at. A sequence is generated starting from these numbers.

For example, with run_in_start_at: 7000 and run_out_start_at: 8000, the generated input stored at run number 7000 would correspond to output 8000, 7001 to 8001, 7002 to 8002, etc.

Note that these sequences may overlap with existing data sets. Duqtools will stop if it detects that data will be overwritten.

db: IMAS database or machine name.
run_in_start_at: The sequence of input data files start with this run number.
run_out_start_at: The sequence of output data files start with this run number.

For example:

duqtools.yaml

data:
  db: test
  run_in_start_at: 7000
  run_out_start_at: 8000

Dimensions

These instructions operate on the template model. Note that these are compound operations, so they are expanded to fill the matrix with possible entries for data modifications (depending on the sampling method).

Arithmetic operations

Apply set of arithmetic operations to IDS.

Takes the IDS data and subtracts, adds, multiplies, etc with each the given values.

operator: Which operator to apply to the data in combination with any of the given values below. This can be any of the basic numpy arithmetic operations. Available choices: add, multiply, divide, power, subtract, floor_divide, mod, and remainder. These directly map to the equivalent numpy functions, i.e. add -> np.add.
scale_to_error: If True, multiply value(s) by the error (sigma). With asymmetric errors (i.e. both lower/upper error are available), scale negative values to the lower error, and positive values to upper error.
ids: IDS Path of the data to modify. core_profiles is implied.
values: Values to use with operator on field to create sampling space.

For example:

duqtools.yaml

ids: zeff
operator: add
values: [0.01, 0.02, 0.03]

will generate 3 entries, zeff += 0.01, zeff += 0.02, and zeff += 0.03.

duqtools.yaml

ids: profiles_1d/0/t_i_average
operator: multiply
values: [1.1, 1.2, 1.3]

will generate another 3 entries, t_i_average *= 1.1, t_i_average *= 1.2, and t_i_average *= 1.3.

With these 2 entries, the parameter hypercube would consist of 9 entries total (3 for zeff times 3 for t_i_average). With the default sampler: latin-hypercube, this means 9 new data files will be written.

Note

The python equivalent is essentially np.<operator>(ids, value, out=ids) for each of the given values.

Specify value ranges

Although it is possible to specify value ranges explicitly in an operator, sometimes it may be easier to specify a range.

There are two ways to specify ranges in duqtools.

By number of samples

Generated evenly spaced numbers over a specified interval.

See the implementation of numpy.linspace for more details.

start: Start value of the sequence.
stop: End value of the sequence.
num: Number of samples to generate.

This example generates a range from 0.7 to 1.3 with 10 steps:

duqtools.yaml

ids: profiles_1d/0/t_i_average
operator: multiply
values:
  start: 0.7
  stop: 1.3
  num: 10

By stepsize

Generate evenly spaced numbers within a given interval.

See the implementation of numpy.arange for more details.

start: Start value of the sequence.
stop: End value of the sequence.
num: Number of samples to generate.

This example generates a range from 0.7 to 1.3 with steps of 0.1:

duqtools.yaml

ids: profiles_1d/0/t_i_average
operator: multiply
values:
  start: 0.7
  stop: 1.3
  step: 0.1

Sampling between error bounds

The following example takes electrons/temperature, and generates a range from \(-2\sigma\) to \(+2\sigma\) with defined steps:

duqtools.yaml

ids: profiles_1d/0/electrons/temperature
operator: add
values: [-2, -1, 0, 1, 2]
scale_to_error: True

The following example takes t_i_average, and generates a range from \(-3\sigma\) to \(+3\sigma\) with 10 equivalent steps:

duqtools.yaml

ids: profiles_1d/0/t_i_average
operator: add
values:
  start: -3
  stop: 3
  num: 10
scale_to_error: True

Note

When you specify a sigma range, make sure you use add as the operator. While the other operators are also supported, they do not make much sense in this context.

Create

The create config

Specify the template data

Data location

Dimensions

Arithmetic operations

Specify value ranges

By number of samples

By stepsize

Sampling between error bounds

The `create` config