Summary¶
The summary module.
The summary files are a set of snapshot of simulated values such as rates, volume totals, and timestamps.
#include <ecl3/summary.h>
The summary format consists of two parts:
A specification file (.SMSPEC) that describes the data layout
A series of simulation steps in either a unified file (.UNSMRY) or separated by step (.Snnnn) where nnnn are consecutive numbers between 0000 and 9999
Briefly, the unified summary .UNSMRY is just a concatenated set of .Snnnn files.
In the summary file, data is recorded as report steps. In the non-unified case, every .Snnnn file is a single report step. Any report step can have one more timesteps, called ministeps. In documentation, these report-ministep pairs will be denoted as report.mini, i.e. (1.2) describes ministep 2 at report step 1. Report steps starts at 1, ministeps start at 0, but only ministeps are actually recorded in the file.
The specification is list of keywords with metadata describing how to interpret the data in the summary files. It essentially describes a matrix - consider a simulation with 2 wells, with summary for Well water cut (WWCT) and Well oil production rate (WOPR):
Step |
WWCT:W1 |
WWCT:W2 |
WOPR:W1 |
WOPR:W2 |
1.0 |
0.2 |
0.4 |
1000.4 |
7231.8 |
1.1 |
0.2 |
0.4 |
1020.1 |
4231.8 |
2.0 |
0.3 |
0.3 |
1220.1 |
4231.7 |
2.1 |
0.3 |
0.3 |
1220.1 |
2967.1 |
The DIMENS keyword in the specification file specifies the paramter NLIST, which are the number of columns in this matrix. For this example, NLIST = 4, as step is derived from reportstep+ministep. The column headers (WWCT:W1) in this example are constructed from the KEYWORDS and WGNAMES keywords in the specification file, where WGNAME[n] corresponds to KEYWORD[n].
In fact, most parameter in the specification file are index based. Consider the three keywords KEYWORDS, WGNAMES, and UNITS in a specification file:
KEYWORDS: [WWPR, WWPR, WOPR]
WGNAMES: [W1, W2, W1]
UNITS: [SM3/DAY, SM3/DAY, SM3/DAY]
Formatted as a matrix:
WWPR | WWPR | WOPR W1 | W2 | W1 SM3/DAY | SM3/DAY | SM3/DAY
ministep 1.0: [5.2, 1.3, 4.2]
Means that the Well water production rate (WWPR) for the well W1 is 5.2 SM3/DAY at report step 1.0, i.e. the columns of the stacked keywords all describe the same sample.
Every report step starts with a SEQHDR keyword, followed by pairs of MINISTEP-PARAMS keywords. The PARAMS should be NLIST long.
Enums
Functions
-
const char **
ecl3_smspec_keywords
(void)¶ Known .SMSPEC keywords.
Obtain a list of the known keywords in the summary specification (.SMSPEC) file.
This centralises the known keywords. The intended use case is for users to be able to figure out if all keywords in a file are known summary specification keywords. All strings are NULL terminated.
The list is terminated by a NULL.
-
const char *
ecl3_unit_system_name
(int)¶ INTEHEAD unit system name.
The INTEHEAD (optional) keyword specifies the unit system and the simulation program used to produce a summary. It is an array with two values:
INTEHEAD = [ecl3_unit_systems, ecl3_simulator_identifiers]
The functions ecl3_unit_system_name and ecl3_simulatorid_name map between an identifier and the corresponding NULL-terminated string name.
-
const char *
ecl3_simulatorid_name
(int)¶
-
int
ecl3_params_identifies
(const char *id, const char *keyword)¶ Check if a parameter is needed to uniquely identify column.
The params_* functions are named as such because they deal with the identifiers for vectors provided with the PARAMS keyword in the summary files.
Most keywords require additional data in order to uniquely identify what the corresponding vector means. Well-related keywords (WOPR, WWCT etc) all depend on a corresponding WGNAMES entry, whereas FIELD related keywords are already completely specified.
This function implements the ruleset, and can be used to determine if a vector depend on a data type to be fully specified.
To make matters worse, summary specifications often contain columns whose values are all garbage. These are identified by a rubbish entry in any of the additional specifiers. That means the otherwise valid keyword “WWCT ” contains all garbage, because the corresponding WGNAMES entry is “:+:+:+:+” or blank.
When a vector is partially identified by the given id, the number of identifiers required to uniquely identify the vector is returned. For example, a WOPR entry is identified by WOPR + well name, and ecl3_params_identifies(“WOPR “, “WGNAMES “) return 1. Completions are identified by well name and NUMS, so both (“WGNAME “, “COFR “) and (“NUMS “, “COFR “) return 2. This is to support iterating over possible identifiers and terminate when the vector is fully specified.
Consider this example, with NLIST = 5, i.e. there are 5 vectors per ministep:
KEYWORD
WGNAME
WWCT
WELL1
WWCT
WELL2
WWCT
:+:+:+:+
WOPR
WELL1
WOPR
WELL1
All PARAMS will have 5 values, but only 4 will be sensical:
KEYWORD
WGNAME
WWCT
WELL1
WWCT
WELL2
WOPR
WELL1
WOPR
WELL1
This function is intended as a predicate to check whether or not a sample should be included in reports, computation or other data structures, or if the vector is nonsensical.
The function ecl3_params_partial_identifiers return a list of identifiers that might make ecl3_params_iodentified_by return non-zero. For maximum future compatibility for arbitrary input, consider this example:
Notes
This function currently implements what is expected from eclipse. Intersect and petrel sometimes use the NAMES for varchar well names, rather than WGNAMES. This function is (currently) not aware, and will say that only WGNAMES will add to specification.
Examples
Print all the params a keyword depends on:
const char* keyword = "WOPR "; const char** id = ecl3_params_partial_identifiers(); while (*id) { if (ecl3_params_identifies(*id, keyword)) printf("%s depends on %s\n", *id, keyword); ++id; }
A selected truth table:
Function
id
keyword
outcome
ecl3_params_identifies
WGNAMES
WWCT
true
ecl3_params_identifies
WGNAMES
GOPR
true
ecl3_params_identifies
NUMS
GOPR
false
ecl3_params_identifies
WGNAMES
YEARS
false
- Return
zero if the id is not required, otherwise the number of identifiers needed to uniquely identify the vector
- Parameters
id
: identifier category, e.g. WGNAMES, NUMSkeyword
: e.g. WWCT, YEARS
-
const char **
ecl3_params_partial_identifiers
(void)¶ Ids that partially identifies keywords.
Returns a list of keyword that will partially specialise at least one vector, i.e. can make ecl3_params_identifies return non-zero.
The list is terminated by a NULL.
Examples
Print all keywords that partially identifies a vector:
const char** id = ecl3_params_partial_identifiers(); while (*id) { puts(*id); ++id; }