Skip to content

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.

matrix
The matrix specifies the operations to apply. These are compound operations which are expanded to fill a matrix of all possible combinations. This generates the Cartesian product of all operations. By specifying a different sampler, a subset of this hypercube can be efficiently sampled.
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
The create subroutine takes as a template directory. This can be a directory with a finished run, or one just stored by JAMS (but not yet started). Duqtools uses the input IDS machine (db) name, user, shot, run number from e.g. jetto.in to find the data to modify for the UQ runs.
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.

Example

duqtools.yaml
create:
  data:
    db: jet
    run_in_start_at: 7000
    run_out_start_at: 8000
  matrix:
  - ids: profiles_1d/0/t_i_average
    operator: multiply
    values:
    - 1.1
    - 1.2
    - 1.3
  - bounds: symmetric
    distribution: normal
    ids: profiles_1d/0/t_i_average
    n_samples: 5
  sampler:
    method: latin-hypercube
    n_samples: 3
  template: /pfs/work/docs/jetto/runs/duqtools_template

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: jet
  run_in_start_at: 7000
  run_out_start_at: 8000

IDS operations

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.
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.

Error bound sampling

This operation samples data between the given error bounds.

Takes the IDS data from the specified path. The value is taken as the mean, and the upper and lower error bounds are specified by the _error_upper and _error_lower suffix.

Data are sampled from a normal distribution around the mean.

If the lower error bound is absent, assume a symmetric distribution.

distribution
Sample from given distribution. Currently normal is the only option.
bounds
Specify symmetric or asymmetric sampling. Use auto to choose asymmetric if the lower bounds are defined, else symmetric. The bounds are defiend by $IDS_error_upper and $IDS_error_lower in the data specification. Symmetric sampling sampling when both the lower and upper error bounds are present, takes the average of the two.
ids
IDS Path of the data to modify. core_profiles is implied.
n_samples
Number of samples to get.

Example:

duqtools.yaml
ids: profiles_1d/0/q
sampling: normal
bounds: symmetric
n_samples: 5

Note

Note that the example above adds 5 (n_samples) entries to the matrix. This is independent from the hypercube sampling above.