Forward model

In the context of uncertainty estimation and data assimilation, a forward model refers to a predictive model that simulates how a system evolves over time given certain inputs or initial conditions. The model is called “forward” because it predicts the future state of the system based on the current state and a set of input parameters. The predictive model may include pre-processing and post-processing steps in addition to the physics simulator itself. In ERT, we think of a forward model as a sequence of jobs such as making directories, copying files, executing simulators etc.

Consider a scenario in reservoir management. Here, a forward model might encompass reservoir modeling software like RMS, a fluid simulator like Eclipse or Flow, and custom jobs like relative permeability interpolation and water saturation calculation.

To add a job to the forward model, use the FORWARD_MODEL keyword. Each FORWARD_MODEL keyword instructs ERT to run a specific executable. You can build a series of jobs by listing multiple FORWARD_MODEL keywords.

You can find all pre-configured jobs to define your forward models here. These jobs form the building blocks for your custom forward models in ERT.

Configuring your own jobs

ERT imposes no restrictions on the programming language used to write a job. The only requirement is that it should be an executable that can be run. Consequently, it is possible to create a program or script performing any desired function, and then have ERT run it as one of the jobs in the FORWARD_MODEL.

However, for ERT to recognize a job, it must be installed. All predefined jobs are already installed and may be invoked by using the FORWARD_MODEL keyword in the configuration file. If you need to include a custom job, it must first be installed using INSTALL_JOB, as follows:

INSTALL_JOB JOB_NAME JOB_CONFIG

In this command, JOB_NAME is a name of your choice that you can later use in the ERT configuration file to call upon the job. JOB_CONFIG is a file that specifies the location of the executable and provides rules for the behavior of any arguments.

By installing your own jobs in this way, you can extend the capabilities of ERT to meet your specific needs and scenarios.

EXECUTABLE  path/to/program

STDERR      prog.stderr      -- Name of stderr file (defaults to
                             -- name_of_file.stderr.<job_nr>)
STDOUT      prog.stdout      -- Name of stdout file (defaults to
                             -- name_of_file.stdout.<job_nr>)
ARGLIST     <ARG0> <ARG1>    -- A list of arguments to pass on to the
                             --  executable
REQUIRED    <ARG0> <ARG1>    -- A list of arguments required to be passed
                             -- on to the executable

Note

When configuring ARGLIST for FORWARD_MODEL jobs it is not suitable to use --some-option for named options as it treated as a comment by the configuration compiler. Single letter options, i.e. -s are needed.

Invoking the job is then done by including it in the ert config:

FORWARD_MODEL JOB_NAME(<ARG0>=3, <ARG1>="something")

Note that the following behaviour provides identical results:

DEFINE <ARG0> 3
FORWARD_MODEL JOB_NAME(<ARG1>="something")

see example Creating a script to define the forward model

Pre-configured forward models

Simulators

Reservoir

ECLIPSE100

No description

Category
simulators.reservoir
Source package
ert
Examples

The version, number of cpu, and whether or not to ignore errors and whether or not to produce YOUR_CASE_NAME.h5 output files can be configured in the configuration file when adding the job, as such:

FORWARD_MODEL ECLIPSE100(<ECLBASE>, <VERSION>=xxxx, <OPTS>={"--ignore-errors", "--summary-conversion"})

The OPTS argument is optional and can be removed, fully or partially. In absence of --ignore-errors eclipse will fail on errors. Adding the flag --ignore-errors will result in eclipse ignoring errors.

And in absence of --summary-conversions eclipse will run without producing YOUR_CASE_NAME.h5 output files. Add flag --summary-conversions to produce YOUR_CASE_NAME.h5 output files.

ECLIPSE300

No description

Category
simulators.reservoir
Source package
ert
Examples

The version, number of cpu and whether or not to ignore errors can be configured in the configuration file when adding the job, as such:

FORWARD_MODEL ECLIPSE300(<ECLBASE>, <VERSION>=xxxx, <OPTS>="--ignore-errors")

The OPTS argument is optional and can be removed, thus running eclipse without ignoring errors

FLOW

Forward model for OPM Flow simulator

Category
simulators.reservoir
Source package
ert
Examples
FORWARD_MODEL FLOW(<ECLBASE>, <VERSION>=xxx, <OPTS>="--ignore-errors")

The OPTS argument is optional and can be removed. :code>`ECLBASE` can also be defaulted. Multiple options can be supplied by separating them with a space.

ERT will be able to run the flow simulator if there is a binary named flow or the wrapper flowrun in the users $PATH environment variable.

If flowrun is found, it will take precedence, and then it will be possible to select the version of flow to use by setting <VERSION>. Available versions are verified towards what flowrun --report-versions returns.

Utility

File_system

CAREFUL_COPY_FILE

The CAREFUL_COPY_FILE job will copy a file. If the <TO> argument has a directory component, that directory will be created. This is an extension of the normal cp command which will not create directories in this way. This job superseded an older version called CAREFULL_COPY and should be used instead.

Category
utility.file_system
Source package
ert
Examples
FORWARD_MODEL CAREFUL_COPY_FILE(<FROM>=file1, <TO>=path/to/directory/file1)
COPY_DIRECTORY

The job copies the directory <FROM> to the target <TO>. If <TO> points to a non-existing directory structure, it will be created first. If the <TO> folder already exist it creates a new directory within the existing one. E.g. COPY_DIRECTORY (<FROM>=foo, <TO>=bar) creates bar/foo if the directory bar already exists. If bar does not exist it becomes a copy of foo.

Category
utility.file_system
Source package
ert
Examples
FORWARD_MODEL COPY_DIRECTORY(<FROM>=dir1, <TO>=path/to/directory/dir1)
COPY_FILE

Copies file from <FROM> to <TO>. If no directory is specified in <TO>, the file will be copied to RUNPATH. If the <TO> argument includes a directory component, that directory will be created. Unlike the standard cp command, this job will automatically create any missing directories in the destination path.

Category
utility.file_system
Source package
ert
Examples
FORWARD_MODEL COPY_FILE(<FROM>=file1, <TO>=path/to/directory/file1)
DELETE_DIRECTORY

The DELETE_DIRECTORY job will recursively remove a directory and all the files in the directory. Like the DELETE_FILE job it will only delete files and directories which are owned by the current user. If one delete operation fails the job will continue, but unless all delete calls succeed (parts of) the directory structure will remain.

Warning

If the directory to delete is a symlink to a directory, it will only delete the link and not the directory. However, if you add a trailing slash to the directory name (the symlink), then the link itself is kept, but the directory it links to will be removed.

Category
utility.file_system
Source package
ert
Examples
FORWARD_MODEL DELETE_DIRECTORY(<DIRECTORY>=path/to/directory)
DELETE_FILE

The DELETE_FILE job will only remove files which are owned by the current user, even if file system permissions would have allowed the delete operation to proceed. The DELETE_FILE will not delete a directory, and if presented with a symbolic link it will only delete the link, and not the target.

Category
utility.file_system
Source package
ert
Examples
FORWARD_MODEL DELETE_FILE(<FILES>="path/file path/file2 path/fileN")
MAKE_DIRECTORY

Will create the directory <DIRECTORY>, with all sub directories.

Category
utility.file_system
Source package
ert
Examples
FORWARD_MODEL MAKE_DIRECTORY(<DIRECTORY>=path/to/new_directory)
MOVE_FILE

The MOVE_FILE job will move file to target directory. If file already exists, this job will move file to the target directory and then replace the existing file.

Category
utility.file_system
Source package
ert
Examples
FORWARD_MODEL MOVE_FILE(<FROM>=file/to/move,<TO>=to/new/path)
MOVE_DIRECTORY

The MOVE_DIRECTORY job will move a directory. If the target directory already exists, it will be replaced.

Category
utility.file_system
Source package
ert
Examples
FORWARD_MODEL MOVE_DIRECTORY(<FROM>=dir/to/move,<TO>=to/new/path)
TEMPLATE_RENDER

Loads the data from each file (some/path/filename.xxx) in INPUT_FILES and exposes it as the variable filename. It then loads the Jinja2 template TEMPLATE_FILE and dumps the rendered result to OUTPUT.

Category
utility.file_system
Source package
ert
Examples

Given an input file my_input.json:

{
    "my_variable": "my_value"
}

And a template file tmpl.jinja:

This is written in my file together with {{my_input.my_variable}}

This job will produce an output file:

This is written in my file together with my_value

By invoking the FORWARD_MODEL as such:

FORWARD_MODEL TEMPLATE_RENDER(<INPUT_FILES>=my_input.json, <TEMPLATE_FILE>=tmpl.jinja, <OUTPUT_FILE>=output_file)