Prepare the YAML configuration file

Prepare the YAML configuration file#

Prepare the control vector#

The response-functions mode will run one simulation per element in the control vector. This means that for each tracer in the control vector, there will be one simulation per horizontal dimension per vertical dimension per time dimension, these dimensions being respectively determined by the hresol, vresol and tresol arguments described in the control vector plugin documentation page.

Thus, in order to have a reasonable total computation time, the control vector must have a small enough size. A typical variational inversion control vector with a per pixel horizontal resolution might be way too large for the response-functions mode.

See Doing a dry run to determine the size of the control vector with the response-functions mode.

Note

It is advised to use the observation operator plugin autoflush (and optionally force-full-flush) input argument to limit the drive space usage of the simulations.

For response functions, a per region horizontal resolution is typically used. Here is a very simple example:

Show/Hide Example

datavect:
  plugin:
  name: standard
  version: std

components:
  ...
  flux:
    parameters:
      AAA:
        plugin:
          type: flux
          name: ...
          version: ...
        ...
        err: 1
        tresol: 1MS
        vresol: column
        hresol: regions
        regions_infos:
            dir: /path/to/directory
            file: region_mask.nc

Common options for the response-functions mode#

Run mode#

Response functions can either be run in forward (fwd) or tangent-linear (tl) mode. This can be specified with the run_mode input argument.

Note

Running the response functions in forward mode usually does not make sense as the models are non-linear.

Period length#

By default, the response functions simulation window is the time period corresponding to their control vector element.

As a control vector element can affect simulated values at observation point past its time period, the simulation window can be extended with the spin_down input argument.

Note

Response functions involving multiple independent species with different lifetimes can be run in separated PyCIF simulations with different spin_down input argument in the response-functions mode. The results of the simulations can then be combined afterwards.

Alternatively all response function simulation windows can be set to the full length of the main simulation window (defined by datei and datef in the YAML configuration file) with the full_period input argument.

Job submitting#

The response functions simulations are independent PyCIF jobs.

Warning

Depending on the platform plugin used, these jobs can be automatically submitted on the platform scheduler. Please use the job_batch_size input argument to avoid submitting hundreds or thousands jobs simultaneously.

Batch sampling#

The response functions can be grouped by simulation window by using batch sampling with the compatible models. This can significantly reduce the computation time and computation resources needed to compute the response functions. The use_batch_sampling input argument enables this behavior.

Select outputs#

By default, the response-functions mode will only dump the observation vector and the \(\mathbf{H}\) matrix. Other outputs can be dumped by setting some input arguments to true`:

  • dump_obsvect_decompostion: dumps the \(\mathbf{H}\) matrix decomposition per control vector parameter, in order to get the contribution of each control vector element to each observation vector element.

  • analytical_inversion: In addition to performing an analytical inversions, dumps the \(\mathbf{B}\) and \(\mathbf{R}\) matrices, and the \(\mathbf{x}^b\) and \(\mathbf{y}\) vectors.

When the dump_sparse_arrays input is set to true, matrices are converted to sparse matrices before dumping, saving a lot of disk space.

Note

Sparse matrices contained in NetCDF files can be converted back to dense matrices with the function pycif.utils.sparse_array.to_dense_dataset.

example:

import xarray as xr
from pycif.utils.sparse_array import to_dense_dataset

with xr.open_dataset("/.../h_matrix.nc") as sparse_ds:
    dense_ds = to_dense_dataset(sparse_ds)

Advanced options for the response-functions mode#

Using approximated model operator#

Some models such as LMDZ have options to approximate the model operator. To use an approximated model operator with the response-functions mode, the use_model_approximation input argument must be set to true.

Multiple species with different lifetimes#

  • ignore_tracers option

  • reload H option