kase file format speciﬁcation documentation · kase file format speciﬁcation documentation,...

Kase File Format SpecificationDocumentation

Release 1.0.0

[email protected]

August 08, 2014

Contents

1 Kase Format 2.1.1 1

2 Overview 3

3 Data Types 5

4 Summary of the Kase Hierarchy 74.1 Kase Study . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74.2 Kase Grids . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74.3 Kase Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84.4 Simulation Well Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84.5 Transient Sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

5 How to read this document 115.1 Classification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115.2 Presence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125.3 Time Dependency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125.4 Cross Reference System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

6 Kase Data Structure 15

7 XML Quick Reference 417.1 XML Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417.2 XML Attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417.3 XML Array . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

8 HDF5 Quick Reference 438.1 C++ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438.2 Fortran90 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438.3 C++ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438.4 Fortran90 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 448.5 C++ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 448.6 Fortran90 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

9 Elements Topology 479.1 0D Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 479.2 1D Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 479.3 2D Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 489.4 3D Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

i

10 Known Phases 49

11 Known Data Struture Types 5111.1 Wellfield . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5111.2 View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5111.3 Surface Separator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

12 Known Categories 53

13 Known Grid Roles 5513.1 For a reservoir model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5513.2 For a geological model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

14 Structured Data Arrays 5714.1 Array Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5714.2 Array Layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

ii

CHAPTER 1

Kase Format 2.1.1

This document describes the data structures and its hierarchical organization for writing and reading a kase file. Theinformation described here does not include all data present in a numerical study, but should be sufficient for definingexternal interfaces for most cases.

The kase hierarchy described here can be used to define simulation models, as an output of a pre processor, and alsothe transient results of a numerical solution, with some special data structures to represent data for reservoir modelsand simulations.

An important note is that the kase hierarchy, as defined in this document, is a definition of a set of data structuresorganization. The file format that supports this hierarchy can be of any type. This document will cover two fileformats to represent the kase hierarchy, an HDF binary file and an XML ASCII file.

1

http://hdf.ncsa.uiuc.edu/HDF5/doc/index.html

Kase File Format Specification Documentation, Release 1.0.0

Contents

• Introduction– Kase Format 2.1.1

• Overview• Data Types• Summary of the Kase Hierarchy

– Kase Study– Kase Grids– Kase Log– Simulation Well Data– Transient Sections

• How to read this document– Classification– Presence– Time Dependency– Cross Reference System

• Kase Data Structure• XML Quick Reference

– XML Group– XML Attribute– XML Array

• HDF5 Quick Reference– C++– Fortran90– C++– Fortran90– C++– Fortran90

• Elements Topology– 0D Elements– 1D Elements– 2D Elements– 3D Elements

• Known Phases• Known Data Struture Types

– Wellfield– View– Surface Separator

• Known Categories• Known Grid Roles

– For a reservoir model– For a geological model

• Structured Data Arrays– Array Size– Array Layout

2 Chapter 1. Kase Format 2.1.1

CHAPTER 2

Overview

The kase file is a hierarchical data structure that describes how to write numerical simulation data into files. Therelationship between the data can be defined in two ways: a child parent and a cross reference as described below.

The child parent relationship, which is used for:

Data association, information is associated with a specific entry.

E.g.: The “Pressure” and “Flow” grid properties are associated with the parent grid node.

GridPart_${Id}:

StaticGridFunctions: GridFunction_${Id}: name = “Pressure”

GridFunction_${Id}: name = “Flow”

Classify the types, to group a collection of a specific data type, like a set of grids.

E.g.: All children of GridParts must be a grid.

GridParts:

GridPart_${Id}: name = InnerVolume Grid part data definition

GridPart_${Id}: name = EastBoundary Grid part data definition

Define scopes, to organize the information in a consistent way. E.g.: All children of TransientInfohave a well defined transient context.

TransientInfo:

time_${time}: delta = 10.0 days

GridParts: Transient grid part information

A cross reference system, that has specific semantics to create a well defined target reference relationship.

The type?s classifiers groups, as mentioned above, are well known kase types which specify that child elements mustbe of a given type. For each type classifier we have a specific child naming rule, that consists of a prefix ending withan underscore and an integer suffix that represents an ordered index starting at 0 until the child count minus 1.

E.g.: All child of the classifier group GridParts have a GridPart_ prefix and an indexed integer suffix.

GridParts:

GridPart_0: name = InnerVolume Grid part data definition

GridPart_1: name = EastBoundary Grid part data definition

GridPart_N: name = ... Grid part data definition

3


This semantics rule creates an easy to use indexing system that allows other data structure to have a strong referenceto that element.

E.g.: A grid part can be a child grid of another one.

GridPart_N: name = ...

• parent_grid_id = 0 (attribute type: integer)

4 Chapter 2. Overview

CHAPTER 3

Data Types

The kase data structure has three major types of data:

• Classifiers: A root grouping node for a specific data type.

• Arrays: A leaf node for describing a large amount of data

• Attributes: Defining semantic information about a given group.

5


6 Chapter 3. Data Types

CHAPTER 4

Summary of the Kase Hierarchy

The tree below shows the main data structures supported by the kase hierarchy and it’s hierarchical organization.

4.1 Kase Study

It’s the tree root node that groups all information regarding a specific case. All data representation must be beneaththis node, that store global information about the case.

\Root: The standard root node.

\KaseStudy: The grouping root node for all information regarding a specific problem.

4.2 Kase Grids

\Root:

\KaseStudy:

\GridParts: classifier group for the grid parts

\GridPart_${id}: a grid part instance

\Geometry: the grid part geometry

\Topology: the grid part topology

\GridFunctions: classifier group for the grid functions

\GridFunction_${id}: a grid function instance

\Views: classifier group node for parametric grid part definition

\Zones: a domain decomposition for a grid in zones

\Zone_${id}: a zone instance, for a specific grid

\Blocks: a structured IJK block view

\Block_${id}: a block instance, for a specific grid

\Regions: a generic domain decomposition by an property range clipping.

\Region_${id}: a region instance, for a specific grid

7


\Selections: generic domain decomposition by explicitly selecting each cell in thedomain

\Selection_${id}: a selection instance, for a specific grid

\NNCs: classifier group for NNC (non-neighborhood connection)

\NNC_${id}: a NNC (non-neighborhood connection) instance

\GridFunctions: classifier group for the grid functions

\GridFunction_${id}: a transient grid function instance

4.3 Kase Log

Discrete functions data structure

\Root:

\KaseStudy:

\LogData: classifier group node for defining a set of discrete functions.

LogDataSet_${id}: a discrete log data set instance

\Log_${id}: a discrete function instance defining a data set for its image and domain.

\TransientLog: a special type of log where the domain is implicitly defines as time.

\LogImage_${id}: a discrete image instance

4.4 Simulation Well Data

A grouping node for the simulation well information

\Root:

\KaseStudy:

\WellField: classifier group node and also the well hierarchy group root

\Groups: classifier group for the well groups

\Group_${id}: a well group instance

\Wells: classifier group for the wells

\Well_${id}: a well instance

\Completions: classifier group for the well’s completions

\Completion_${id}: a completion instance

4.5 Transient Sections

It’s a tree node that groups all recurrent timesteps definitions

\Root:

\KaseStudy:

8 Chapter 4. Summary of the Kase Hierarchy


\TransientSections:: classifier group for all recurrent transient data

\Timestep_${id}: a group node for the recurrent timestep information

\GridParts: changes in the grid parts definition (transient grid function val-ues)

\Views: changes in the grid parts views

\NNCs: changes in the NNC definition (Non Neighbour Connec-tion)(transient grid function arrays)

\LogData: new discrete function log definitions

\TransientLog: log image data definition

\WellField: changes in the well field structure (parent changes, statechanges, etc.)

4.5. Transient Sections 9


10 Chapter 4. Summary of the Kase Hierarchy

CHAPTER 5

How to read this document

We use icons to identify some behavior or characteristic for each data entry in the file. Here is a list of these symbolsand its description:

5.1 Classification

Each entry in kase data structure has a generic type, like a group node an attribute. Bellow we give a description of thesegeneric types and its meaning. : group node - a classifier grouping node with a fixed label that identify/classify itschild elements.

E.g:

\GridParts: The grouping node for all grid parts defined in the simulation model

: multiple entry node - a grouping node with a label defined by an integer index. The data type is defined by itsparent, and is used by other data structures as a reference to this data. This element can have multiple definitions.

E.g.:

\GridParts:

\GridPart_${id}: A grid part with id = ${id}

: attribute - a node attribute

E.g.:

\GridParts:

\GridPart_${id}:

name: the human-readable name for the grid

: array - an array of values

E.g.:

\GridParts:

\GridPart_${id}:

\GridFunctions:

11


\GridFunction_${id}: A grid function with id = ${id}

values: an array with values for the grid function

5.2 Presence

Some data must be defined in the file and others are optional. The following icons describe the presence statement

for each data. : required - the data must be defined, its presence is mandatory. : optional - the data canbe defined, its presence is optional but recommended. Some optional attributes have a default value defined by thesentence following the item:

• DEFAULT: ${default value}

E.g.: The grid part attribute name is optional but the attribute type must be defined.

\GridParts:

\GridPart_${id}:

name: [ ] the human-readable name for the grid

type: [ ] the grid type: [unstructured, structured, reservoir]

5.3 Time Dependency

Kase data structure has some restrictions on what can be created and changed over the time. The following icons are

used to classify if the data can be defined and changed on recurrent transient sections. : static information - meansthat this entry is static. It can be defined in recurrent transient sections, but not modified.

E.g.: The grid part attribute name can be defined in the recurrent transient sections, since the GridPart_${0} group istransient, but cannot be modified oncedefined.

\GridParts: [ ]

\GridPart_0: [ ]

name: [ ] the human-readable name for the grid

: transient information - means that this entry is transient. It can be defined and modified in recurrent transientsections.

E.g.: The user can define new grid parts, and also change the ones defined.

\GridParts: [ ] \GridPart_0: [ ]

12 Chapter 5. How to read this document


5.4 Cross Reference System

: link target - the element is a target reference, and can be linked to other data structures. : link reference -the element is a reference to other data structure.

5.4. Cross Reference System 13


14 Chapter 5. How to read this document

CHAPTER 6

Kase Data Structure

\Root:

VERSION_MAJOR: [ , type: int] file major version

VERSION_MINOR: [ , type: int] file minor version

VERSION_REVISION: [ , type: int] file version revision

file_strategy: [ type: int, default: 0] an integer attribute that specifies if the data isstored in multiple files or not.

• 0 = single

• 1 = multiple

multiple_file_suffix: [ type: str, default: ”.k_”] If file_strategy is multiple, thesuffix of the transient files can be specified. The time_step_id will be appended to the suffix, so bydefault the file “file.kase” will have as transient the files “file.k_00000”, “file.k_00001”, and so on.

\KaseStudy: [ , HDF Group, XML Group]

Group node with information about the file.

data_strategy: [ , type: str, HDF Attribute, XML Attribute]

defined the strategy used to write data into the file. It can be of two types:

• “post”: optimized file data structure for post processing

• “simulator”: suited to be used for output from a simulator

appendix_of: [ , type: str, HDF Attribute, XML Attribute] defines the filename to which this kase study is appending information to

name: [ type: str, HDF Attribute, default: “”] a cultural long name for the kasestudy in this file which can be shown in user interface.

nickname: [ type: str, HDF Attribute, default: “”] a cultural short name for thekase study in this file which can be shown in user interface.

15


description: [ type: str, HDF Attribute, default: “”] a cultural descriptionfor the kase study in this file which can be shown in user interface.

software_name: [ type: str, HDF Attribute, default: “”] the name of the soft-ware that originally created this file.

software_description: [ type: str, HDF Attribute, default: “”] a short de-scription for the software that originally created this file.

vendor_name: [ type: str, HDF Attribute, default: “”] the name of the manu-facturer or vendor that created this file.

vendor_description: [ type: str, HDF Attribute, default: “”] a short de-scription of the manufacturer or vendor that created this file.

For Time Set Shift

time_set_shift_value: [ type: float, HDF Attribute] time_set_shift_unit:

[ type: str, HDF Attribute]

a pair of delta value and unit that if defined cause all time sets contained by the kase study toshifted accordingly. Used for scenarios where big kase files contain time sets with a wronginitial date, but regenerating whole file could be too expensive. This pair of option offer acheap alternative to fix files in this situation.

For Dual Porosity / Dual Permeability Models

dpdk: [ type: int, HDF Attribute, default: 0] an integer at-tribute that identifies a dual porosity / dual permeability model.

• 0: single porosity single perameability model

• 1: dual porosity single permeability model

• 2: dual porosity dual permeability model.

\Phases: [ , HDF Group, XML Group]

Definition of the simulation phases

\Phase_${id}: [ , HDF Group, XML Group]

name: [ type: str] the phase name

description: [ type: str, default: “”] the phase descrip-tion

see: Known Phases:

\Components: [ , HDF Group, XML Group]

Definition of the simulation phase components \Component_${id}:

[ , HDF Group, XML Group]

name: [ type: str, HDF Attribute] the component name

16 Chapter 6. Kase Data Structure


description: [ type: str, HDF Attribute] the compo-nent description

phase_id: [ , type: int] an integer value identifyingthe component’s phase.

\GridParts: [ HDF Group]

\GridPart_${id}: [ HDF Group] Defines a newgrid in the file. The group name must be defined by the prefix“GridPart_” and an integer suffix.

name: [ type: str, HDF Attribute] the human-readable name for the grid

description: [ type: str, HDF Attribute, default: “”]a cultural description for the grid

type: [ type: string, HDF Attribute] the grid typecan be: [”unstructured”, “structured”, “reservoir”]

grid_role: [ type: str, HDF Attribute] The gridrole is a cultural information that defines a role for this grid partin a model. For known roles by current Kase specification, seeKnown Grid Roles.

IF (grid_role == “LGR”) :

parent_grid_id: [ type: int, HDF Attribute]the parent grid_id hosting this grid

IF (dpdk == 1 or 2) :

dpdk_grid_role: [ type: str, HDF Attribute]the grid role in a Dual Porosity Dual Permeability Model aselection from: [’N/A’, ‘MATRIX’, ‘FRACTURE’]

dpdk_grid_id: [ type: int, HDF Attribute]the DPDK sibling grid_id

\Topology: [ HDF Group] Group node for all informa-tion that defines the grid topology

shared_topology_reference_id:: [ type: str, HDF Attribute]if specified, no other attributes or arrays should be specified,and the topology for this grid should be considered the sametopology specified in the referenced grid.

IF (grid_type == “unstructured” or “structured”) :

Note: Reservoir Grids are only 3 dimensional

17


dimension: [ type: int, HDF Array]defines the topological dimension. It can be:

Value Di-men-sion

unstructured struc-tured

0 0D A cloud of points Not ap-plicable

1 1D A set of polylines Apolyline

2 2D A set of surfaces of triasand quads

A surfaceof quads

3 3D A set of volumes of tetras,pyras, prisms and hexas

Avolumeof hexas

IF (grid_type == “unstructured”) :

number_of_elements: [ type: int, HDF Attribute]the total number of elements

elements_vertices: [ type: int, HDF Array]an array of integers defining all elements’ vertices. Theelements are represented one after the other by the numberof vertices and the index of each vertex, according to thesequence of vertices defined in the Elements_Topologysection.

• E.g.: “3 2 3 0 4 3 4 1 0 3 5 3 2 4 5 6 4 3“

images/elements_vertices.png

elements_positions: [ type: int, HDF Array]an array of integers, with size equal to the total numberof elements, defining the element’s initial position in theelements_vertices array.

• E.g.: “0 4 9 13”

IF (grid_type == “reservoir” or “structured”) :

IF (topological_dimension == 1) :

ni: [ , type: int, HDF Attribute]the number of cells in topological I direction

IF (topological_dimension == 1 or 2) :

nj: [ , type: int, HDF Attribute]the number of cells in topological J direction



IF (topological_dimension == 1 or 2 or 3) :

nk: [ , type: int, HDF Attribute]the number of cells in topological K direction

IF (grid_type == “reservoir”) :

number_of_active_cells: [ , type: int, default: NI*NJ*NK, HDF Attribute]the number of active cells

actnum: [ type: int, default: all active, HDF Array]an array of integers for each grid cell defining theactive cells (1 active, 0 inactive)

IF (parent_grid_id is defined) :

hostnum: [ type: int, HDF Array]an array of integers for each grid cell defining theparent cell handle.

\Geometry: [ HDF Group] Group node for all infor-mation that defines the grid geometry

shared_geometry_reference_id: [ type: int, HDF Attribute]if specified, no other attributes/arrays should be specified.This grid will share it’s geometry with the grid identified bythe given id.

basis: [ type: float, HDF Array] A floatingpoint array with the geometry basis. The elements in thearray must follow the order: origin, x, y and z axis. For athree dimensional geometry this array has twelve elements.

invert_y_axis: [ default: 0, type: int, HDF Attribute]an integer value defining if the geometry should be flipped around the Xaxis. The Y and Z axis will be inverted.

bounding_box: [ type: float, HDF Array]A floating point array with the geometry boundingbox. The elements in the array must follow the order:x min and max, y min and max and z min and max.For a three dimensional geometry this array has sixelements.

transient: [ default: 0, type: str, HDF Attribute] an in-teger value that identifies a transient geometry.

• 0 = static

• 1 = transient

quantity_unit: [ type: str, HDF Attribute]the unit for the geometry points

19


IF (grid_type == “unstructured” or“structured”) :

dimension: [ type: int, HDF Attribute]

geometric dimension:

– 1 = 1D

– 2 = 2D

– 3 = 3D

Note: Reservoir Grids are implic-itly defined as 3 dimensional


number_of_points: [ type: int, HDF Attribute]The number of points.

IF (geometric_dimension == 1):

x: [ type: float, HDF Array]The X geometry pointscoordinates with size ==number_of_points


xy: [ type: float, HDF Array]An array of float (X,Y) tuples, in this se-quence, with size = 2 *number_of_points


xyz: [ , type: float, HDF Array]An array of float (X,Y, Z) tuples, in thissequence, with size = 3* number_of_points

IF (grid_type == “structured”) :


x: [ , type: float, HDF Array]The X geometry coor-



dinates with size =NI+1.

See: Structured Data Ar-rays


xy: [ , type: float, HDF Array]An array of float (X,Y) tuples, in this se-quence, with size = 2 *(NI+1)*(NJ+1).



xyz: [ , type: float, HDF Array]An array of float (X,Y, Z) tuples, in thissequence, with size = 3 *(NI+1)*(NJ+1)*(NK+1).


IF (grid_type == “reservoir”) :

type: [ , type: int, HDF Attribute]Defines the geometry type ofa reservoir grid. The kase filesupports seven (8) differenttypes of geometry description.A integer value from 1 to 8 willdefine the reservoir geometrytype. The corresponding arraysfor each definition are listedbelow.

IF (reservoir_geometry_type== 1) :

cell_size: [ , type: float, HDF Attribute]A 1D array with the cell

21


size in X, Y and Zdirection


images/geometry_type2.jpg

The reservoir grid geom-etry type 2 can be de-scribed by two different ar-ray types.

– Delta arrays for each di-rection dx, dy or dz withsize = NI, NJ or NK

– Explicit coordinatearrays for each directionx_coord, y_coord orz_coord with size =NI+1, NJ+1 or NK+1

Delta:

dx: [ , type: float, HDF Array]A 1D array with deltavalues in topologicalI direction. The arraysize is defined by thegrid topology size in Idirection.

Or explicit:

x_coord: [ , type: float, HDF Array]A 1D array with co-ordinate values intopological I direc-tion. The array sizeis defined by the gridtopology size in Idirection plus 1.

Delta:

dy: [ , type: float, HDF Array]A 1D array with deltavalues in topologicalJ direction. The arraysize is defined by the



grid topology size in Jdirection.

Or explicit:

y_coord: [ , type: float, HDF Array]A 1D array with co-ordinate values intopological J direc-tion. The array sizeis defined by the gridtopology size in Jdirection plus 1.

Delta:

dz: [ , type: float, HDF Array]A 1D array with deltavalues in topologicalK direction. The arraysize is defined by thegrid topology size inK direction.

Or explicit:

z_coord: [ , type: float, HDF Array]A 1D array with co-ordinate values intopological K direc-tion. The array sizeis defined by the gridtopology size in Kdirection plus 1.



The X and Y coordinatesuse the same representationof type 2 geometry, withdeltas or explicity arraysdefined.

The Z coordinates are de-scribed by:

depth_top: [ , type: float, HDF Array]A 3D array with the z

23


coordinate for the topface of the grid cells.

Option 1:

depth_bottom: [ , type: float, HDF Array]A 3D array with thez coordinate for thebottom face of thegrid cells.

Option 2:

dz: [ , type: float, HDF Array]A 3D array with thecell size in Z direc-tion.

The 3D arrays layoutand size are described inStructured Data Arrays


The X and Y coordinatesuse the same representationof type 2 geometry, withdeltas or explicity arraysdefined.

Geometry of type 4 to 7have a z corner array foreach cell vertex. These ar-rays must be writen inde-pendently for each vertexusing the same sequence asfollows:

ZCORNER_${vertex}: [ , type: float, HDF Array]${vertex} will rangefrom 0 untill 7






coord: [ , type: float, HDF Array]An NJ x NI x [x, y] ar-ray with the verticalcoord lines for each J, Itopological direction.

The loop sequence must be:

loop j (0, NJ+1):

loop i (0, NI+1) x,y coordinates

zcorners: see:zcorners



coordlines: [ , type: float, HDF Array]An NJ x NI x [top,bottom] x [x, y, z]array with the verti-cal coord lines foreach J, I topologicaldirection.

The loop sequence must be:

loop j (0, NJ+1):

loop i (0, NI+1)top (x, y,z) coordi-nates

bottom (x,y, z) coor-dinates

25





xcorners: see:zcorners

ycorners: see:zcorners



The same arrays withlayout and size usedfor structured geome-tries. See: struc-tured_geometry.

\GridFunctions: [ HDF Group] Groupnode for the static and transient grid functionsassociated with the parent grid node.

\GridFunction_${id}: [ HDF Group]Defines a new grid function in the grid.The group name must be defined by thegrid function id, a unique identifier for thegrid function

name: [ type: str, HDF Attribute]the human-readable name for the gridfunction

description: [ , type: str, HDF Attribute]the human-readable short descriptionfor the grid function



location: [ type: int, HDF Attribute]grid function values topological as-sociation. It can be be:

– 0 = vertex

– 1 = edge NOT SUPPORTEDYET

– 2 = face NOT SUPPORTEDYET

– 3 = cell

– 4 = nnc USED IN NNC

transient: [ type: str, HDF Attribute]an integer value that identifies a tran-sient grid function.

– 0 = static

– 1 = transient

Limits

The minimum and maximumvalues for the values array.

limits_min [ type: numeric, default: calculated, HDF Attribute]grid function miniumvalue.

limits_max [ type: numeric, default: calculated, HDF Attribute]grid function maximumvalue.

Condition

Specifies if the grid function isassociated to a measure at sur-face or reservoir conditions.

condition [ type: numeric, default: -1, HDF Attribute]

– -1 = unknown

– 0 = surface

– 1 = reservoir

Dimension

Specifies the grid function di-mension.

dimension [ type: numeric, default: 0, HDF Attribute]

– 0 = scalar: 1 scalar foreach entry

27


– 1 = vector: N scalarsfor each entry, whereN is the geometry di-mension

– 2 = tensor: N x Nscalar matrix for eachentry, where N is thegeometry dimension

An optional way to declare thevalues for a vector or tensor gridfunction is link each componentto another grid function.

For a vector

IF (geometric_dimension== 1) :

x_component_id

[ type: nu-meric, HDF Attribute]


y_component_id



z_component_id


Quantity

The quantity is a data structure that has allinformation to define the grid function rolein the problem and also its unit of measure.

E.g. quantity_category: “poros-ity” - is a known property for a reservoirmodel, and can be defined using a category.Implicitly we can use this information toclassify this property as a volume/volumequantity type.



E.g. quantity_category: “oil pres-sure” - is a known property for a reservoirmodel, and can be defined using a category.A better way to categorize this proeprty isby defining it’s type as “pressure” and thatits associated to the “oil” phase.

quantity_unit: [ type: str, HDF Attribute]the unit for the grid function

The quantity category can be defined ex-plicitly

quantity_category: [ type: str, HDF Attribute]the category for the gridfunction

E.g.: “oil pressure”

see: Known Categories:

Or by the following attributes

quantity_type: [ type: str, HDF Attribute]the quantity type.

see: POSC Units of Mea-sure Dictionary v2.0

If associated to a phase

phase_id: [ type: int, HDF Attribute]the correspondigphase_id

If associated to a component

component_id: [ type: int, HDF Attribute]the correspondigcomponent_id

Values

IF (grid_type == “unstru-tured”) :

values: [ type: int, float, HDF Array]An 1D array withvalues for the gridfunction. Thesize of the arraydepends on thegrid_function_locationusing the follow-ing rule:

29

http://www.posc.org/refs/poscUnits20.xml

http://www.posc.org/refs/poscUnits20.xml


– vertex: size= num-ber_of_points

– cell: size= num-ber_of_elements

IF (grid_type == “reser-voir”) :

IF (location == 1):

storage_strategy: [ type: int, default: 0, HDF Attribute]an integervalue thatidentifystoragelayoutstrategy forthe gridfunctionvalues.

Twolayoutsstrate-gies aresupported:

– 0 = com-plete:all val-ues aredefined,for ac-tive andinactivevalues

– 1 =packed:only thevaluesfor theactivecells arestored.

values: [ type: int, float, HDF Array]an 1D array withvalues for the gridfunction

IF (stor-



age_strategy ==0)

see: Struc-tured DataArrays

IF (stor-age_strategy ==1)

The ar-ray sizeis the num-ber_of_active_cellsand the se-quence ofthe valuesremains thesame definedat StructuredData Arraysbut the inac-tive cells areignored.

\GridFunctions: [ HDF Group] This is a special group defining a col-lection of additional grid functions for grid parts.

It should be used when appending information to another file:

see: appendix_of attribute on KaseStudy

\GridPart_${id}: [ HDF Group] Groups all grid functionthat will be added to the grid part with grid_id

\GridFunction_${id}: [ HDF Group] Defines a newgrid function in the grid.

see: GridFunction definition

\Views: [ HDF Group] Group node for grid part view definition.

A view is a topological selection from a grid part.


\Zones: [ HDF Group] Group node for creating grid partviews as zones. A zone can only be used with structured or reser-voir grid parts, since it will define a group of K layers on a gridpart.

\Zone_${id}: [ HDF Group] Defines a newzone for a grid part.

31


name: [ type: str, HDF Attribute] the human-readable name for the zone

description: [ type: str, HDF Attribute]the human-readable short description for the zone

grid_id: [ type: int, HDF Attribute]the structured or reservoir grid_id

k_top_index: [ type: int, HDF Attribute]the K topological start index for the zone.

k_bottom_index: [ type: int, HDF Attribute]the K topological final index (inclusive) for the zone.

\Blocks: [ HDF Group] Group node for creating gridpart views as IJK blocks.

A Block can only be used with structured or reservoir grid parts,since it will define an I, J, K boundary to fit the grid part cells

\Block_${id}: [ HDF Group] Defines a new blockfor a grid part.

name: [ type: str, HDF Attribute] thehuman-readable name for the block.

description: [ type: str, HDF Attribute]the human-readable short description for the block.

grid_id: [ type: int, HDF Attribute]the structured or reservoir grid_id.

i_start_index: [ type: int, HDF Attribute]the I topological start index for the block.

j_start_index: [ type: int, HDF Attribute]the J topological start index for the block.

k_start_index: [ type: int, HDF Attribute]the J topological start index for the block.

i_end_index: [ type: int, HDF Attribute]the I topological end index for the block.

j_end_index: [ type: int, HDF Attribute]the J topological end index for the block.

k_end_index: [ type: int, HDF Attribute]the K topological end index for the block.



\Regions: [ HDF Group] Group node for creating grid part re-gions. A region can be used with any type of grid parts, since it will selecta set of cells that statisfies the region criteria.

\Region_${id}: [ HDF Group] Defines a new region for agrid part.

name: [ type: str, HDF Attribute] the human-readable name for the region

description: [ type: str, HDF Attribute] thehuman-readable short description for the region

grid_id: [ type: int, HDF Attribute] the targetgrid_id

grid_function_id: [ type: int, HDF Attribute]the target gridfunctions

value_min: [ type: float, HDF Attribute] the mini-mum property value that a cell must have.

value_max: [ type: float, HDF Attribute] the maxi-mum property value that a cell must have.

\Selections: [ HDF Group] Group node for creating a grid part se-lection. A selection is defined by explicitly indentifying each cell that ispart of it by the cell handle.

\Selection_${id}: [ HDF Group] Defines a new selection ofa grid part.

name: [ type: str, HDF Attribute] the human-readable name for the selection

description: [ type: str, HDF Attribute] thehuman-readable short description for the selection

grid_id: [ type: int, HDF Attribute] the targetgrid_id

cells: [ type: int, HDF Attribute] array with thecell handles of the selection.

IF (grid_type == “reservoir” or “structured”) : Each en-try in the array must have 3 components, the (I, J, K) coor-dinates of the selected cell.

IF (grid_type == “unstructured”) : Each entry in the arraymust be the cell handle.

33


\NNCs: [ HDF Group] Group node for additional topological connec-tivities information for the grids assembly.

\NNC_${id}: [ HDF Group] Defines a new NNC in the file.

source_grid_id: [ type: int, HDF Attribute] thesource grid_id.

source_cells: [ type: int, HDF Attribute] an arraywith the source cell handles in the the source grid.

target_grid_id: [ type: int, HDF Attribute] thetarget grid_id.

target_cells: [ type: int, HDF Attribute] an arraywith the target cell handles in the the target grid

\GridFunctions: [ HDF Group] Group node for the grid-functions associated with the NNC. Have the same data struture definedfor a grid part.

\WellField: [ HDF Group] Group node for defining the well data andits organization. Kase2 support different types of well hierarchy. The most com-mon one is used in reservoir simulation models where a real situation is modeledby groups, wells and completions in a hierarchical data structure. This group isthe root of this hierarchy.

We support basically three types of entities: Group, Well and Completion.

Important Note: This is a special well group. The well field is a well groupwith an implicit definition for its id. All references made to a group_id = 0 willbe associated with this main group.

\Groups: [ HDF Group] Group node for defining all well groupsin the model.

\Group_${id}: [ HDF Group] Defines a new group inthe file. The hdf group name must be defined by the group id, an uniqueidentifier for the log



Important Node: Unlike the other index elements, the well group hasan indexing id starting at 1. Since the id = 0 is reserved for the Well-Field.

name: [ type: str, HDF Attribute] the human-readable name for the well group.

description: [ type: str, HDF Attribute] thehuman-readable description for the well group.

parent_id: [ type: int, HDF Attribute] theparent group_id for this group.

\Wells: [ HDF Group] Group node for defining all wells in themodel.

\Well_${id}: [ HDF Group] Defines a new well in thefile. The hdf group name must be defined by an integer index.

name: [ , type: str, HDF Attribute] the human-readable name for the well.

description: [ , type: str, HDF Attribute] thehuman-readable description for the well.

parent_id: [ , type: int, HDF Attribute] theparent group_id for this well.

state: [ , type: int, HDF Attribute]

the well recurrent state, one of:

• -1 = UNKNOWN

• 0 = SHUT

• 1 = OPEN

type: [ , type: int, HDF Attribute]

the well type, one of:

• -1 = UNKNOWN

• 0 = INJECTOR

• 1 = PRODUCER

\Completions: [ HDF Group] Group node for defining well com-pletions in the model. A completion in a well field is defined by a cell handlein a grid.

\Completion_${id}: [ HDF Group] Defines a new wellin the file. The hdf group name must be defined by an integer index.

name: [ , type: str, HDF Attribute] the human-readable name for the well completion

35


DEFAULT: “${WELLNAME} - ${GRIDNAME} (${TOPO-LOGICAL_LOCATION_INDEX})”

parent_id: [ , type: int, HDF Attribute] theparent well_id for this well.

state: [ , type: int, HDF Attribute]

the completion state, one of:

• -1 = UNKNOWN

• 0 = SHUT

• 1 = OPEN

DEFAULT: 0 (shut)

attached_id: [ , type: int, HDF Attribute] thecompletion_id to which this completion is connected.

Location

There are two ways for defining a completion in a model. At least onemust be defined or both.

• Using a topological reference in a given grid

• Specifying a geometric coordinate

Topological Reference

grid_id: [ type: int, HDF Attribute]the well completion host grid_id.‘HDF Attribute‘_

location: [ type: int, HDF Attribute]the topological element association for the completion.It can be be:

• 0 = vertex

• 1 = cell


element_i: [ , type: int, HDF Attribute]the well completion I index on the host grid.

element_j: [ , type: int, HDF Attribute]the well completion J index on the host grid.

element_k: [ , type: int, HDF Attribute]the well completion K index on the host grid.


element_id: [ , type: int, HDF Attribute]the well completion cell index on the hostgrid.



Geometric Coordinates The geometric coordinates for the completioncan be explicitly defined in the file. If not defined the coordinateswill be the element center.

x: [ , type: float, HDF Attribute] the well comple-tion I index on the host grid.

IF (geometric_dimension == 2 or 3) :

y: [ , type: float, HDF Attribute] thewell completion J index on the host grid.

IF (geometric_dimension == 3) :

z: [ , type: float, HDF Attribute] thewell completion K index on the host grid.

\LogData: [ HDF Group] Group node for defining a set of discreteproperties.

\LogDataSet_${id}: [ HDF Group] Defines a new 1 (one)dimension data set that can be used to define the image or domain for dis-crete functions.

name: [ type: str, HDF Attribute] the human-readabledata set name.

description: [ type: str, HDF Attribute] the human-readable data set description

Quantity

The data set quantity description has the same data structure already definedfor a grid function: see: quantity

Array

values: [ type: array of float] The 1 (one) di-mension array with the data set values.

\Log_${id}: [ HDF Group] Defines a new discrete functionlog data. It’s a definition of a image and domain.

domain_id: [ type: int, HDF Attribute] the log-dataset_id defining the function domain.

image_id: [ type: int, HDF Attribute] the log-dataset_id defining the function image.

If associated to another data structure

owner_type: [ type: str, HDF Attribute] thedata structure type, a selection from: [”well”, “group”,“completion”, “region”, ...]

37


see: Known Data Struture Types:

owner_id: [ type: int, HDF Attribute] thecorrespondig data structure id.

owner_name: [ type: int, HDF Attribute]the correspondig data structure name. This can be usefulwhen writing transient log without a reference element in thefile.

\TransientLog: [ HDF Group] Group node for defining the discreteimage functions log data. All entries in this group have the time as the domain.In recurrent transient sections an array with values for each log can be defined.

\LogImage_${id}: [ HDF Group] Defines a new propertylog.

name: [ type: str, HDF Attribute] the human-readablename for the property log.

description: [ type: str, HDF Attribute] the human-readable description for the property log.

Quantity

The log image quantity description has the same data structure already de-fined for a grid function. See: quantity.

If associated to another data structure

owner_type: [ type: str, HDF Attribute] thedata structure type, a selection from: [”well”, “group”,“completion”, “region”, ...]

see: Known Data Struture Types:

owner_id: [ type: int, HDF Attribute] thecorrespondig data structure id [well_id, group_id, ....].

owner_name: [ type: int, HDF Attribute]the correspondig data structure name. This can be usefulwhen writing transient log without a reference element in thefile.

grid_id: [ type: int, HDF Attribute] thecorrespondig grid id.

At recurrent transient sections

The TransientLog classifier group wiil group the image values using the follow-ing arrays.

log_ids: [ type: int, HDF Attribute] defines the log ids recordedat the data array. Allows a sequence change or a reduced log.



data: [ type: array of float, HDF Attribute] This array can belinked with the log_ids array if all log properties will not be reported ata recurrent section. If the log_ids is not present is expected an array withthe number of log images defined at this point on the file.

\TransientSections: [ HDF Group] Classifier group node for the recur-rent timestep definitions. This group must be defined at the master kase file,for defining the timestep recording properties. When using multiple files eachtimestep is stored in a separate file named ${basename}_${timestepid}.kase.

initial_date: [ type: str, default: ${open date} HDF Attribute]a six elements space separated string defining the simulation initial date.The integer sequence must be: YYYY MM DD hh mm ss.

This is a cultural information to located the data in time.

• E.g.: “1990 01 01 00 00 00”

quantity_unit: [ type: str, HDF Attribute] the unit for thereported timesteps. The quantity_category is implicitly defined as “Time”.

\Timestep_${id}: [ HDF Group] A group node for all data re-ported at this timestep. All information can be defined or updated in thisgroup.

timestep: [ type: float, HDF Attribute] the ellapsedtime step since the initial date.

\Views: [ HDF Group] if defined at this timestep group cancreate a new view for a grid part or change the ones already defined.

\GridParts: [ HDF Group] if defined at this timestep groupcan create a new grid part or change the ones already defined.

\NNCs: [ HDF Group] if defined at this timestep group cancreate a new NNC or change the ones already defined.

\LogData: [ HDF Group] if defined at this timestep groupcan create a new log data.

\TransientLog: [ HDF Group] if defined at this timestepgroup can create a new log image or append values to the ones alreadydefined.

39

CHAPTER 7

XML Quick Reference

7.1 XML Group

<${GroupName}> </${GroupName}>

E.g.:

<Root><KaseStudy></KaseStudy>

</Root>

7.2 XML Attribute

<${GroupName} ${AttributeName}=”${AttributeValue}”> </${GroupName}>

E.g.:

<Root VERSION_MAJOR=”1”><KaseStudy></KaseStudy>

</Root>

7.3 XML Array

<${ArrayName} node_type=”array” size=”${ArraySize}” type=”${ArrayType}”> ${Array Values} </${Array-Name}>

The additional attribute “node_type” is mandatory, in a XML this is how we identify an array.

E.g.:

<values node_type=”array” size=”200” type=”float”>

41


1.0 2.0 3.0 ...... 198.0 199.0 200.0

</values>

42 Chapter 7. XML Quick Reference

CHAPTER 8

HDF5 Quick Reference

8.1 C++

Name: H5Gcreate

hid_t H5Gcreate( hid_t loc_id, const char \*name, size_t size_hint )hid_t H5Gcreate( hid_t loc_id, const char \*name, hid_t lcpl_id, hid_t gcpl_id, hid_t gapl_id )

8.2 Fortran90

Interface: h5gcreate_f

SUBROUTINE h5gcreate_f(loc_id, name, gr_id, hdferr, size_hint)

IMPLICIT NONEINTEGER(HID_T), INTENT(IN) :: loc_id ! File or group identifierCHARACTER(LEN=*), INTENT(IN) :: name ! Name of the group to be createdINTEGER(HID_T), INTENT(OUT) :: gr_id ! Group identifierINTEGER, INTENT(OUT) :: hdferr ! Error code

! 0 on success and -1 on failureINTEGER(SIZE_T), OPTIONAL, INTENT(IN) :: size_hint

! Number of bytes to store the names! of objects in the group.! Default value is! OBJECT_NAMELEN_DEFAULT_F

END SUBROUTINE h5gcreate_f

8.3 C++

Name: H5Acreate

hid_t H5Acreate( hid_t loc_id, const char *attr_name, hid_t type_id, hid_t space_id, hid_t acpl_id )hid_t H5Acreate( hid_t loc_id, const char *attr_name, hid_t type_id, hid_t space_id, hid_t acpl_id, hid_t aapl_id )

43

http://hdf.ncsa.uiuc.edu/HDF5/doc/RM/RM_H5G.html#Group-Create

http://hdf.ncsa.uiuc.edu/HDF5/doc/RM/RM_H5A.html#Annot-Create


8.4 Fortran90

Interface: h5acreate_f

SUBROUTINE h5acreate_f(loc_id, name, type_id, space_id, attr_id, hdferr, acpl_id, aapl_id )

IMPLICIT NONEINTEGER(HID_T), INTENT(IN) :: loc_id ! Object identifierCHARACTER(LEN=*), INTENT(IN) :: name ! Attribute nameINTEGER(HID_T), INTENT(IN) :: type_id ! Attribute datatype identifierINTEGER(HID_T), INTENT(IN) :: space_id ! Attribute dataspace identifierINTEGER(HID_T), INTENT(OUT) :: attr_id ! Attribute identifierINTEGER, INTENT(OUT) :: hdferr ! Error code:

! 0 on success and -1 on failureINTEGER(HID_T), OPTIONAL, INTENT(IN) :: acpl_id ! Attribute creation property list identifierINTEGER(HID_T), OPTIONAL, INTENT(IN) :: aapl_id ! Attribute access property list identifier

END SUBROUTINE h5acreate_f

8.5 C++

Name: H5Dcreate

Interface:

hid_t H5Dcreate( hid_t loc_id, const char *name, hid_t type_id, hid_t space_id, hid_t dcpl_id )hid_t H5Dcreate( hid_t loc_id, const char *name, hid_t dtype_id, hid_t space_id, hid_t lcpl_id, hid_t dcpl_id, hid_t dapl_id )

8.6 Fortran90

Interface: h5dcreate_f

SUBROUTINE h5dcreate_f(loc_id, name, type_id, space_id, dset_id, &hdferr, optional_id1, optional_id2, optional_id3)

IMPLICIT NONEINTEGER(HID_T), INTENT(IN) :: loc_id ! File or group identifierCHARACTER(LEN=*), INTENT(IN) :: name ! Name of the datasetINTEGER(HID_T), INTENT(IN) :: type_id ! Datatype identifierINTEGER(HID_T), INTENT(IN) :: space_id ! Dataspace identifierINTEGER(HID_T), INTENT(OUT) :: dset_id ! Dataset identifierINTEGER, INTENT(OUT) :: hdferr ! Error code

! NOTE: Optional parameters only take on a meaning depending on how many are present,! * If all three are present then the parameters follow H5Dcreate2 convention! * If only one is present then the parameters follow H5Dcreate1 convention! such that:!! lcpl_id - Link creation property list (H5Dcreate2 convention)! OR! dcpl_id - Dataset creation property list (H5Dcreate1 convention)

INTEGER(HID_T), OPTIONAL, INTENT(IN) :: optional_id1 ! lcpl_id OR dcpl_id

44 Chapter 8. HDF5 Quick Reference

http://hdf.ncsa.uiuc.edu/HDF5/doc/RM/RM_H5D.html#Dataset-Create


!! Dataset creation property list (H5Dcreate2 convention)

INTEGER(HID_T), OPTIONAL, INTENT(IN) :: optional_id2 ! dcpl_id!! Dataset access property list (H5Dcreate2 convention)

INTEGER(HID_T), OPTIONAL, INTENT(IN) :: optional_id3 ! dapl_idEND SUBROUTINE h5dcreate_f

8.6. Fortran90 45


46 Chapter 8. HDF5 Quick Reference

CHAPTER 9

Elements Topology

9.1 0D Elements

0D Elements TopologyDot

images/dot.jpg

9.2 1D Elements

1D Elements TopologyBar

47


9.3 2D Elements

2D Elements TopologyTria Quad

images/tria.jpgimages/quad.jpg

9.4 3D Elements

3D Elements TopologyTetra Pyra Prism Hexa

48 Chapter 9. Elements Topology

CHAPTER 10

Known Phases

The kase data strucuture recogninze the following phases.

• “oil”: oil phase

• “water”: water phase

• “gas”: gas phase

49


50 Chapter 10. Known Phases

CHAPTER 11

Known Data Struture Types

11.1 Wellfield

• “completion”: Completion

• “well”: Well

• “group”: Group

11.2 View

• “region”: Grid Part Region

• “zone”: Grid Part Zone

• “block”: Grid Part Block

• “selection”: Grid Part Selection

11.3 Surface Separator

• “vessel”: Surface Separator Vessel

This data type is still under development.

51


52 Chapter 11. Known Data Struture Types

CHAPTER 12

Known Categories

• “porosity”:

• “ntg”:

• “bulk volume”:

53


54 Chapter 12. Known Categories

CHAPTER 13

Known Grid Roles

13.1 For a reservoir model

In a reservoir model we can have diferent levels of grid that are related to each other. The kase structuresupport two roles in this context. A main grid that usually play the whole part of the model and a localgrid refinement on that grid.

• “MAIN”: stands for the base grid

• “LGR”: stands for a local grid refinement in a main grid region, which can cover from one cell toan IJK block

13.2 For a geological model

The kase structure support several roles in this context, that will cover the grid 2D and also 3D. Thefollowing types are supported:

• “SURFACE”

• “HORIZON”

• “FAULT”

• “SECTION”

• “BOUNDARY”

• “WELLBORE”

55


56 Chapter 13. Known Grid Roles

CHAPTER 14

Structured Data Arrays

For structured and reservoir grids the array layout and size are dependent on the dimension and size of the gridtopology.

14.1 Array Size

• Topological 1D Grids: size = NI values

• Topological 2D Grids: size = (NI * NJ) values

• Topological 3D Grids: size = (NI * NJ * NK) values

14.2 Array Layout

• Topological 1D Grids: loop in I topological direction

• Topological 2D Grids: loop in J (outer loop), loop in I (inner loop)

• Topological 3D Grids: loop in K (outer loop), loop in J, loop in I (inner loop)

Copyright (C) 2007 ESSS. All rights reserved.www.esss.com.brEngineering Simulation and Scientific Software

This file format is free to use as long as its specification is not modified or extended without the permission of ESSS.

Use of this product is governed by the License Agreement. ESSS makes no warranties, express, implied, or statutory,with respect to the product described herein and disclaims without limitation any warranties of merchantability orfitness for a particular purpose.

Last Modified: 23 April 2008

57

http://www.esss.com.br

kase file format speciﬁcation documentation · kase file format speciﬁcation documentation,...

Documents